@cloudbitmaps/core 0.20.0 → 0.21.0

package/dist/core/load.d.ts

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

package/dist/core/lru.d.ts

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

package/dist/core/metrics.d.ts

@@ -49,8 +49,10 @@ export type MetricEvent = {
     readonly ms: number;
 } | {
     /**
-     * One decoded-chunk cache lookup (emitted only when a cache is configured). `hit: false` means the lookup found
-     * no cached chunk. A combine or `iterate` looks up every chunk it needs when it opens its streams. A caller that
+     * One decoded-chunk cache lookup, or one chunk counted a miss without a lookup (emitted only when a cache is
+     * configured). `hit: false` means the cache did not hold the chunk. A combine or `iterate` counts every chunk it
+     * needs when it opens its streams: a lookup each, except that on a cache that holds nothing each chunk after the
+     * one a stream starts at is counted a miss without one. A caller that
      * missed while another caller's read of the same chunk was open waits on that read and adds no `storage.get`, and a
      * range carries several chunks, so the misses can outnumber the `storage.get` events; the `storage.get` count is
      * the number of requests for chunks. `materializeMany` never looks up the cache, so it emits none.

package/dist/core/order.d.ts

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

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

@@ -27,14 +27,14 @@ import type { CrbmStorageChunkSource } from './crbm-storage-source.js';
  * What a pin holds for one segment: the generation, the version identifying those exact bytes, and the pinned
  * object's fingerprint, so a read can tell that the generation it opens is still that object.
  *
- * `fingerprint` is optional so that a pin built by hand, before there was one, still compiles. Nothing checks the
- * object such a pin reads, so it cannot tell a name purged and loaded again from the segment it pinned.
- * `seg.pin()` always records it.
+ * `fingerprint` is required for a pin of a generation (`null` only when `generation` is `null`): without it a read
+ * could not tell a name purged and loaded again from the segment it pinned. `seg.pin()` always records it, and a
+ * pin of a generation without a string `version` and `fingerprint` is refused with a `ValidationError`.
  */
 export interface PinnedAt {
     readonly generation: number | null;
     readonly version: string | null;
-    readonly fingerprint?: string | null;
+    readonly fingerprint: string | null;
 }
 export declare class PinnedStorageChunkSource implements StorageChunkSource {
     private readonly inner;

package/dist/core/ports.d.ts

@@ -281,12 +281,18 @@ export interface StorageDeleteOptions {
  *   `getRange` may answer empty without reaching the backend, so it proves neither that the object exists nor
  *   that the offset lies inside it: the cloud drivers answer it empty, the memory and local-filesystem drivers
  *   throw for a missing object or an offset past the end.)
+ * - **A deleted object is missing to the next read**: once `delete(key)` has resolved, `getTail` and a non-empty `getRange`
+ *   of that key throw {@link NotFoundError} (a zero-length `getRange` is the exemption above), with no stale answer from a
+ *   cache or a replica. A rollback reads its target's footer once
+ *   after moving the pointer, in place of listing the bucket, and takes a read that succeeds as proof that the object is
+ *   there.
  * - **An out-of-range read throws {@link ValidationError}**: a range that runs past the end of the object, or a
  *   negative or non-integer offset or length. Never a clamped, short or adjacent read. A pin whose object
  *   was purged and loaded again as a smaller one asks for a range past its end, and this error is what sends it
  *   to check that the object is still the one it pinned.
  * - **`getTail` reports the object's true total size**, not the number of bytes it returned, and, where the driver has
- *   one, the object's `version` ({@link TailRead.version}) from the same response as the bytes.
+ *   one, the object's `version` ({@link TailRead.version}) from the same response as the bytes. Its length is a safe
+ *   integer, zero or less for an empty tail; any other length throws {@link ValidationError} before anything is read.
  * - **`delete` is idempotent.** Deleting an absent key is a no-op, not an error: collection passes race each
  *   other and retry. That holds with `ifVersion` too: an absent object is a no-op whatever version is given.
  * - **`delete` with `ifVersion` does what {@link StorageCaps.conditionalDelete} says.** A driver that reports `true`
@@ -299,7 +305,7 @@ export interface StorageDeleteOptions {
  *   under the key. A number can be taken again once its object is deleted, so this is what keeps a delete decided from
  *   one read, and delayed, from removing an object stored under the number since: the erasure's delete of a holder
  *   above the pointer passes the version it read when it searched that object, and a refused load's delete of an
- *   object it proved its own by a footer read passes the version of that read.
+ *   object whose footer, read once, matched what it wrote passes the version of that read.
  * - **A driver that wraps another forwards `ifVersion` and the `version` of a tail read, or reports
  *   `conditionalDelete: false`.** A wrapper that hands `delete` the key alone, and reports the inner driver's
  *   capability, makes every conditional delete through it unconditional without a word.
@@ -341,7 +347,10 @@ export interface IStorageDriver {
     getRange(key: GenKey, offset: number, length: number): Promise<Uint8Array>;
     /**
      * Speculative tail read: the last `min(maxBytes, size)` bytes + the object's **true total size**, and its `version`
-     * where the driver has one ({@link TailRead}). A missing object throws {@link NotFoundError}.
+     * where the driver has one ({@link TailRead}). `maxBytes` must be a safe integer: zero or less answers an empty tail
+     * with the size, and one past the size the whole object. Any other `maxBytes` (`NaN`, a fraction, a negative one
+     * included, an infinity of either sign, a whole number past the safe range (2^53 or more, or -2^53 or less)) throws
+     * {@link ValidationError} before anything is read. A missing object throws {@link NotFoundError}.
      */
     getTail(key: GenKey, maxBytes: number): Promise<TailRead>;
     /**
@@ -410,6 +419,12 @@ export interface ClearRegistrySummary {
      * footer stores.
      */
     readonly fingerprint: string;
+    /**
+     * The bytes from the end of the last chunk payload to the end of the object: the extension block, if any, the index and
+     * the footer. A cold open reads this many bytes from the object's end to open it in one request. An integer from 104,
+     * the footer's size, to the object's size less its 8-byte preamble, and at most 8,392,820.
+     */
+    readonly tailBytes: number;
     /** The generation's metadata, when it has any. Never the empty object. */
     readonly metadata?: GenerationMetadata;
 }
@@ -419,11 +434,24 @@ export interface SealedRegistrySummary {
     readonly generation: number;
     /**
      * Base64 of `nonce(12) ‖ ciphertext ‖ tag(16)`, sealing the cardinality as a little-endian u64, the object's size as a
-     * little-endian u64 and its footer checksum as a little-endian u32 (its fingerprint), then the metadata's canonical
-     * JSON, if any. The numbers are fixed-width, so the length reveals only the metadata's size.
+     * little-endian u64 and its footer checksum as a little-endian u32 (its fingerprint), its `tailBytes` as a
+     * little-endian u32, then the metadata's canonical JSON, if any. The numbers are fixed-width, so the length reveals only
+     * the metadata's size.
      */
     readonly sealed: string;
 }
+/**
+ * A generation a row knows it published: its number, and the checksum its object's footer stores. A rollback moves only
+ * onto a generation the row knows, and an object whose footer carries another checksum is another object under that
+ * number. The footer's checksum covers the index's checksum, which covers each chunk's, so it commits to the object's ids
+ * and shape; for a cleartext object it does not cover the extension block's bytes.
+ */
+export interface KnownGeneration {
+    /** A non-negative safe integer. */
+    readonly generation: number;
+    /** The object's footer CRC32C (the second half of its fingerprint `<size>:<crc>`), an integer from 0 to 2^32 - 1. */
+    readonly footerCrc: number;
+}
 /**
  * One lease on a generation. It names no fingerprint: a collector spares a generation by number and cannot compare an
  * object without reading it, and a purge and re-create drops the whole list with the row. A pin's own fingerprint,
@@ -481,15 +509,28 @@ export interface RegistryRecord extends SegmentRef {
      */
     readonly summary?: RegistrySummary;
     /**
-     * The generations below `currentGen` that the last publish kept as its grace window, ascending. Optional: absent
-     * means the row does not know which generations are kept, and a load then lists the bucket to collect and records
-     * them; an empty list means none are. Trusted only while every entry is below `currentGen`. A patch that moves
+     * The generations this row knows and has not decided to delete, the current one included, with each object's footer
+     * checksum: the ones it made current, in the order they were made current, oldest first and the current one last, and,
+     * when a publish over a row with no usable ledger seeds one, the ones a count by `keep` keeps in the bucket, which can
+     * include an object no load published (an orphan or a stray). An entry says the library knows the generation and its
+     * footer checksum, not that a load published it. A generation appears once,
+     * at its most recent time current (a rollback onto it moves it to the end). The entries before the last are the kept
+     * window, the generations a live lease holds, and what a rollback left; those numbered above `currentGen` are what a
+     * rollback left. In the clear on every
+     * row, an encrypted one included: a footer checksum of an encrypted object covers a random nonce and says nothing about
+     * its count, size or content, but the entries above the pointer show anyone who reads the registry that a rollback
+     * happened, and from which generation.
+     *
+     * Optional: absent means the row does not know, and a load then lists the bucket to collect. A shipped registry stores
+     * the list in the order given, at most 192 entries written and 384 read, and refuses a list that repeats a
+     * generation, one whose last entry is not the row's `currentGen`, and one whose current entry's checksum disagrees with
+     * a clear `summary`'s fingerprint. A stored list that disagrees with its row is read and not used. A patch that moves
      * `currentGen` without naming it drops it.
      */
-    readonly keptGens?: readonly number[];
+    readonly knownGens?: readonly KnownGeneration[];
     /**
      * The leases on this segment's generations: each keeps one generation out of a load's collection until it ends.
-     * Optional; absent means none. Unlike {@link keptGens} it does not follow the pointer: a patch that moves
+     * Optional; absent means none. Unlike {@link knownGens} it does not follow the pointer: a patch that moves
      * `currentGen` leaves it as it was, and only a patch that names it, or the row going away, changes it. Entries
      * past their end are ignored by every collector and pruned by the next write that names the list. A row's identity
      * is its token, so a purged and re-created segment starts with none.
@@ -510,7 +551,7 @@ export interface RegistryRecord extends SegmentRef {
     /**
      * The token of the most recent write that named a field a read resolves through: the row's create, or a compare-and-swap
      * whose patch named `currentGen`, `status`, `wrappedDeks`, `keyId` or `summary` (the resolved fields), at any value,
-     * the one the field already had included. A write that names only `leases`, `retention`, `residency` or `keptGens`
+     * the one the field already had included. A write that names only `leases`, `retention`, `residency` or `knownGens`
      * leaves it. The registry sets it; a caller never does. Compared by equality only, and never reused under one name,
      * since a token is not: a reader keys what it caches on a generation with it, so a lease or a policy write leaves a
      * warm reader's cache standing, and a write that changes the resolution never does.
@@ -532,8 +573,8 @@ export interface NewRegistryRecord {
     readonly residency?: GovernanceMeta;
     /** Must name `currentGen` when given. */
     readonly summary?: RegistrySummary;
-    /** Every entry below `currentGen`, ascending; see {@link RegistryRecord.keptGens}. */
-    readonly keptGens?: readonly number[];
+    /** In the order made current, the last entry the new row's `currentGen`; see {@link RegistryRecord.knownGens}. */
+    readonly knownGens?: readonly KnownGeneration[];
 }
 /**
  * Fields a {@link IRegistryDriver.compareAndSwap} may mutate (identity, audit, `token` and `pointerId` are
@@ -542,14 +583,14 @@ export interface NewRegistryRecord {
  * Presence-based: a field the patch does not mention is left as it was. `summary` is the one exception, because it
  * describes the current generation: a patch that moves `currentGen` and does not mention `summary` drops the old
  * one rather than keep a description of another generation. A `summary` the patch gives must name the
- * `currentGen` the row will have. `keptGens` follows the pointer the same way: a patch that moves `currentGen` and does
- * not mention it drops it, and one that gives it must name only generations below the `currentGen` the row will have.
+ * `currentGen` the row will have. `knownGens` follows the pointer the same way: a patch that moves `currentGen` and does
+ * not mention it drops it, and one that gives it must end with the `currentGen` the row will have.
  * "Moves" means changes value: a patch that names `currentGen` at the value it has keeps both.
  *
  * A patch that names a resolved field (`currentGen`, `status`, `wrappedDeks`, `keyId`, `summary`), by presence and at any
  * value, sets the row's {@link RegistryRecord.pointerId} to the token the write returns; any other patch leaves it.
  */
-export type RegistryPatch = Partial<Pick<RegistryRecord, 'currentGen' | 'wrappedDeks' | 'keyId' | 'status' | 'retention' | 'residency' | 'summary' | 'keptGens' | 'leases'>>;
+export type RegistryPatch = Partial<Pick<RegistryRecord, 'currentGen' | 'wrappedDeks' | 'keyId' | 'status' | 'retention' | 'residency' | 'summary' | 'knownGens' | 'leases'>>;
 /**
  * What a caller passes {@link IRegistryDriver.create} or {@link IRegistryDriver.compareAndSwap} besides the write itself.
  */
@@ -566,6 +607,25 @@ export interface RegistryWriteOptions {
      * settled by reading the row, never by this record. A driver that ignores the option reads the row.
      */
     readonly held?: RegistryRecord | null;
+    /**
+     * Called with the token this write carries, before the write is sent. A write sent again with a new token reports
+     * it; one that repeats the same body repeats the token already reported. The token is the one the write records:
+     * when the write lands, the row's {@link RegistryRecord.token} is it, and so is its {@link RegistryRecord.pointerId}
+     * when the write names a resolved field. A write that does not land leaves no row carrying it. A call refused before
+     * it has a token to send, on a conflict its own read finds, reports none.
+     *
+     * The token is unique to that write attempt, also against another writer racing the same version: two writers that
+     * send a write against the same row version never carry the same token, so a version counter alone is not enough.
+     * Otherwise a loser's write would pass for the winner's.
+     *
+     * It tells a writer which row writes are its own, whatever became of its request: a write that failed, or got no
+     * answer, may still have landed, and the row's `pointerId` names its writer when no later write has renewed it: it is
+     * then one of the tokens the writer was told. Only a registry that reports {@link IRegistryDriver.reportsWriteTokens}
+     * calls it; one that does not ignores it, and a writer then settles such a write by reading the object it published.
+     * A registry that wraps or extends another and overrides `create` or `compareAndSwap` passes this option through to
+     * the write it forwards, or sets the flag to `false`.
+     */
+    readonly onToken?: (token: Token) => void;
 }
 /** Capabilities a registry driver advertises; validated fail-fast at wiring time. */
 export interface RegCaps {
@@ -723,6 +783,19 @@ export declare function isStorageBackend(value: unknown): value is StorageBacken
  */
 export interface IRegistryDriver {
     capabilities(): RegCaps;
+    /**
+     * `true` when every `create` and `compareAndSwap` of this registry reports the token its write carries to
+     * {@link RegistryWriteOptions.onToken} before sending it, a resend included. A load, an erasure's rewrite and every
+     * other publish then knows whether a write that conflicted or got no answer landed by whether the row's `pointerId`
+     * is a token it was told, which names the writer and not only the bytes. Absent or `false`: the registry reports
+     * none, and such a write is settled by reading the object the publish wrote. A shipped registry says which it is.
+     *
+     * The flag may be a getter or a field. A registry that wraps or extends another and overrides `create` or
+     * `compareAndSwap` either passes `options` through to the write it forwards, or sets `reportsWriteTokens` to
+     * `false`. One that does neither reads every write of its own that landed after an error or a lost answer as not its
+     * own (`superseded`), and deletes nothing.
+     */
+    readonly reportsWriteTokens?: boolean;
     /**
      * The segment's record, or `null` if it doesn't exist (or was deleted). Throw {@link TransientError} for a fault
      * worth riding out (throttling, a 5xx, a dropped connection): a reader whose pointer refresh meets one keeps

package/dist/core/publish.d.ts

@@ -0,0 +1,207 @@
+import type { Yielder } from './cooperative.js';
+import type { Rng } from './determinism.js';
+import type { PublishedKept } from './generation-gc.js';
+import type { WrappedDek } from './crypto.js';
+import type { GenKey, IRegistryDriver, KnownGeneration, RegistryRecord, RegistrySummary, Token } from './ports.js';
+/** What a publish is told, beyond the registry and the generation key. */
+interface PublishOptions {
+    wrappedDeks?: readonly WrappedDek[];
+    expectFrom?: number;
+    expectToken?: Token;
+    /**
+     * The row `expectToken` names, as the caller read it. With it, a row whose token has moved but which differs from
+     * this one only in its leases (a reader took or released one) does not refuse the publish: it goes on against the
+     * fresh row, after a jittered wait and without the caller redoing its work, up to a bound. Any other difference
+     * refuses as ever. Without it, a moved token refuses.
+     */
+    expectRow?: RegistryRecord | null;
+    /**
+     * Fields of `expectRow` that a row may also differ in, beside its leases, without the fence refusing: a write that
+     * changed only those did not touch what the caller derived its content from. An erasure's rewrite passes `knownGens`,
+     * since another erasure's removal of generations from the ledger leaves the generation it streamed alone. A write that
+     * also renewed the row's `pointerId` still refuses.
+     */
+    expectRowIgnores?: readonly (keyof RegistryRecord)[];
+    /**
+     * Publish only while the segment still has **no registry row**.
+     *
+     * The fence for a caller whose decision rests on the row being ABSENT: every load that found no row sets it,
+     * guarded or not. `expectFrom` and `expectToken` cannot express it: both compare against a value read from a
+     * row, so when there was no row there is nothing to compare and both are simply omitted — leaving the publish a
+     * bare forward-only advance that happily lands over whatever appeared in the meantime.
+     *
+     * Without it, a guarded load into a segment that did not exist yet would judge "no row", pass its empty and
+     * `minRetained` bounds vacuously, and land an EMPTY generation over the ids a concurrent writer had just loaded,
+     * reporting `published: true`. An unguarded load would move the pointer over another first load's generation or
+     * onto a row `setRetention` made, and, where an erasure had deleted its object above that row's pointer, onto an
+     * object that is gone. Materialising into a destination that does not exist yet is the ordinary first run of a
+     * pipeline, so the `*Into` verbs reach this as often as `loadSegment` does.
+     */
+    expectAbsent?: boolean;
+    /**
+     * The generation's summary (see {@link RegistrySummary}), written by the write that moves the pointer to it. It
+     * names `key.generation`. Absent, the row is left with none for this generation.
+     */
+    summary?: RegistrySummary;
+    /**
+     * The segment's row as the caller already read it (`null`: it found none). The first attempt acts on it
+     * instead of reading the row again, which is sound because that attempt writes only under the row's own
+     * fence: its compare-and-swap carries this row's token, and with no row it creates create-only, so a row
+     * that changed or appeared since makes the write lose and the next attempt reads the row afresh. Only the
+     * idempotent "already current" answer writes nothing, so a reused row never gives it.
+     */
+    row?: RegistryRecord | null;
+    /**
+     * The object was written without encryption. Its publish is refused, with {@link KeyUnavailableError}, onto a row
+     * that carries key material: a reader of that segment opens every generation with its key, and a later
+     * `destroySegment` would attest that shredding it made a readable object unreadable. A caller decides its key
+     * from the row it read before the write, so this closes the window in which another writer creates the
+     * segment encrypted meanwhile.
+     */
+    cleartext?: boolean;
+    /**
+     * Whether the object under `key` is the one the caller wrote, and throws when it cannot tell. Asked only when a
+     * registry write failed and the row then names `key.generation`, on a registry that does not report its writes'
+     * tokens ({@link IRegistryDriver.reportsWriteTokens}; one that does settles it by the row's `pointerId` and never
+     * asks), to tell this publish's write from another writer's at the same number. Every caller that writes the object
+     * passes it. Without it, such a write that ended without an answer over a row that names `key.generation` cannot be
+     * settled: the publish throws {@link TransientError} and the caller keeps its object.
+     */
+    holdsOwnObject?: () => Promise<boolean>;
+    /**
+     * What a publish waits on before it sends a fresh compare-and-swap, after a write that ended without an answer and
+     * left the row as it was. Without a `sleep`, such a write throws at once instead of being sent again.
+     */
+    clock?: Yielder;
+    /** Spreads that wait (full jitter) so concurrent publishers do not retry together. Without it the wait is the bound. */
+    rng?: Rng;
+    /**
+     * Called once for each registry write that ended without an answer, before the row is read back. A caller whose
+     * publish then answers `false` can say that it cannot tell whether its own write landed first: the row may have
+     * held its generation for a while before another writer moved on.
+     */
+    onUnanswered?: () => void;
+    /**
+     * The clock that judges whether a lease has ended. With it, a publish over a row that holds ended leases drops
+     * them in the write that moves the pointer, which rewrites the row anyway. Without it, leases are left as they are.
+     */
+    leasesNow?: () => number;
+    /**
+     * Clear the row's leases in the write that moves the pointer: the caller's collection deletes every generation
+     * below the new pointer whatever a lease says, as a subject erasure's does.
+     */
+    clearLeases?: boolean;
+    /**
+     * How many generations below the new pointer the caller keeps. With it, the write that moves the pointer also
+     * records the window in the row (the entries of `knownGens`: the `keep` most recently current of the generations
+     * below the new one, and the ones a live lease holds), derived from the very row the write is made against, and the
+     * result names the generations the window dropped. Without it, or above the most a row collects by name, the result
+     * names no window, and a collection lists.
+     */
+    keep?: number;
+    /**
+     * The footer checksum of the object under `key` (the second half of its fingerprint), which the write that moves the
+     * pointer records in the row's `knownGens` beside the generation. It comes from the object the caller wrote or opened,
+     * the same one its `summary` describes.
+     */
+    footerCrc: number;
+    /**
+     * The window a ledger starts with, over a row that has no usable one ({@link readSeed}): the generations a count by
+     * `keep` keeps, which the write records as the ledger's entries before the new generation.
+     */
+    seed?: readonly KnownGeneration[];
+}
+/**
+ * Point a segment's registry `currentGen` at `key.generation` — the publish step that makes a freshly-written
+ * generation the authoritative latest (so registry-aware readers see it). **Forward-only and idempotent:**
+ * if the registry has no row it creates one; if it's already at/ahead of `key.generation` it's a no-op (an
+ * out-of-order/duplicate publish never regresses the pointer); otherwise it advances via compare-and-swap,
+ * retrying a few times under contention. Separated from the Storage write so callers can publish atomically
+ * after the immutable object is durable (write-then-publish).
+ *
+ * **Throws** rather than returning, in two cases, because each would otherwise create a state no reader can
+ * recover from: a `destroyed` (crypto-shredded) row, where advancing the pointer would name an object encrypted
+ * under a shredded key; and an advance carrying **new** `wrappedDeks`, which would either strand that key or make
+ * the row advertise encryption over cleartext generations. Contention that never clears throws
+ * {@link WriteConflictError} after the retries.
+ *
+ * **`expectFrom` turns forward-only into read-modify-write.** Forward-only is the right rule for a writer whose
+ * content does not depend on what was current — a load computes its ids upstream, so publishing over a newer
+ * generation loses nothing the loader knew about. It is the WRONG rule for a writer that *derived* its content
+ * from a particular generation: the erasure rewrite streams generation `from` and clears one bit, so publishing
+ * it over a newer generation silently discards whatever that generation added. Passing `expectFrom` makes the
+ * publish land only while the pointer is still exactly there, and return `false` otherwise, so the caller can
+ * report `superseded` and re-derive. The compare-and-swap itself carries the token read in the same iteration,
+ * so the check and the write see the same row.
+ *
+ * **`expectToken` fences the LINEAGE, and a derived writer needs both.** A generation number identifies a
+ * generation only within one incarnation of a name: the numbering restarts at `0` once the row is purged and
+ * the bucket empty, so a name that is retired and re-created has a *different* segment wearing the *same*
+ * `currentGen`. `expectFrom` alone matched it — and an erasure rewrite then published one incarnation's content
+ * over another's, deleted the live objects with its `keep: 0` collection, and returned `erased: true`. The row's
+ * OCC token is the identity that survives this: a shipped registry's later `create` gets a token never issued before
+ * under that name, but for a collision of probability 2^-128 per pair of incarnations, so no token is reused across them.
+ *
+ * Pass the token read alongside `expectFrom` and the publish lands only on the same row it was derived from.
+ * The check is deliberately **conservative**: the token also changes on writes that are not supersessions at
+ * all (a `setRetention`, a due-index reindex), so such a write makes a derived publish report `superseded` and
+ * the caller re-derive. That costs a re-run on a rare, unrelated write; the alternative costs a segment.
+ *
+ * **The driver sends a registry write once, and an unanswered one is reconciled by its effect.** A `create` or
+ * `compareAndSwap` that fails with {@link TransientError} (a throttle, a lost response, a timeout) may or may not
+ * have landed, and may still be in flight. The publish reads the row once more and decides from what it holds:
+ *
+ * - the pointer names `key.generation`, on the incarnation the write was made against (the row's `createdAt`), and the
+ *   write is the caller's own: the write is taken to have landed, and the publish returns `true`. A registry that
+ *   reports each write's token ({@link IRegistryDriver.reportsWriteTokens}) settles it by the row's `pointerId`, which
+ *   names the writer of the write that last set the pointer: the write is the call's own when that is the token of a
+ *   write this call sent. One that does not is settled by `holdsOwnObject` finding the caller's bytes under the number:
+ *   only the writer of a write-once object publishes its number, but a number is taken again once its object is
+ *   deleted, and a load of the same cleartext ids writes the same bytes, so another writer's identical object under
+ *   the number passes for the caller's;
+ * - the row is still the one the write was made against (the same token, or still no row): the write may land yet. The
+ *   publish then waits, on the injected clock, and sends a **new** write from the row it just read: a request of its
+ *   own, not a replay of the driver's, carrying the same version, so under the registry's fence at most one of the two
+ *   lands and the other meets a conflict, which the next read settles. At most {@link UNANSWERED_RESENDS} follow, after
+ *   a wait under 500 ms, then 1 s, then 2 s (full jitter when an `rng` is given); each is settled the same way. Still
+ *   unanswered, or with no clock to wait on, this throws the registry's own `TransientError` and writes nothing more.
+ *   A caller must not delete its object on it;
+ * - anything else: the row has moved past the state the write was conditioned on, so that write can never land, and
+ *   the publish goes on as after a lost race, from the row it just read. A pointer at `key.generation` that is not over
+ *   the caller's own object, or is on another incarnation, is a lost race too and answers `false`, never an already
+ *   current re-publish.
+ *
+ * A failed read throws `TransientError` too. The same check of the pointer runs after a {@link WriteConflictError},
+ * so a write that landed and then met itself (a registry whose client re-sent it) is not taken for a lost race.
+ * The check runs before the next attempt's `expectAbsent`, `expectToken` and `expectFrom` fences, which a write of the
+ * caller's own that landed would fail. With a registry that reports tokens it names the writer of the write that last
+ * set the pointer, so another writer's identical object under the number does not pass it; with one that does not,
+ * that object can.
+ *
+ * **A `summary` goes in the same write that moves the pointer**, so a reader that sees this generation as current
+ * sees the count and metadata that describe it, and every attempt sends the same one. It must be the shape the row's
+ * keys call for: sealed for an object written with a key, clear for one written without.
+ */
+export declare function publishGenerationKept(registry: IRegistryDriver, key: GenKey, options: PublishOptions): Promise<PublishResult>;
+/** What a publish did: whether the pointer is at the generation, and what the write recorded in the row. */
+export interface PublishResult {
+    readonly published: boolean;
+    /**
+     * What the write that moved the pointer recorded: the list, the generations the window dropped, and the new row's
+     * token. Absent when no write of this call is known to have landed (the pointer was already there, or the outcome
+     * was settled without knowing which write it was), and a collection then lists.
+     */
+    readonly kept?: PublishedKept;
+    /**
+     * A token of the row whose pointer is at the generation, when it is published: the one the write was given, or the
+     * row read that showed the pointer there. Every write of a row keeps its incarnation, so this names the incarnation
+     * the publish landed in, for the audit event.
+     */
+    readonly token?: Token;
+}
+/**
+ * {@link publishGenerationKept}'s answer to "did the pointer move", for a caller with no use for what it recorded:
+ * a publish with no `keep` leaves the row recording no list.
+ */
+export declare function publishGeneration(registry: IRegistryDriver, key: GenKey, options: PublishOptions): Promise<boolean>;
+export {};

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`.
  *