@cloudbitmaps/core 0.11.2 → 0.12.0

package/dist/core/crbm/format.d.ts

@@ -1,5 +1,5 @@
 /**
- * Frozen `.crbm` v1.0 layout constants.
+ * Frozen `.crbm` v1 layout constants (format 1.0, with its optional extension block).
  *
  * These byte widths/offsets are pinned by the golden corpus and must never change for v1 —
  * a new layout is a new format version. All multi-byte integers are little-endian (v1 fixes LE).
@@ -41,6 +41,12 @@ export declare const FOOTER_CRC_COVERAGE: 96;
 export declare const FLAG_ENCRYPTED: number;
 export declare const FLAG_INDEX_COMPRESSED: number;
 export declare const FLAG_LITTLE_ENDIAN: number;
+/**
+ * The object carries an extension block just before its index (a generation's metadata). Set only when there is
+ * something to put in it, so an object without metadata is the same bytes as before the block existed; a reader that
+ * does not know the bit refuses the object rather than reading past what it cannot see.
+ */
+export declare const FLAG_EXTENSION: number;
 /** Flag bits a v1 reader understands; any bit outside this mask is an unsupported feature. */
 export declare const KNOWN_FLAGS: number;
 /**
@@ -102,6 +108,30 @@ export declare const DEFAULT_MAX_INDEX_BYTES: number;
 export declare const DEFAULT_MAX_PAYLOAD_BYTES: number;
 /** A chunk's cardinality is in `[1, 65536]` (empty chunks are never written). */
 export declare const MAX_CHUNK_CARDINALITY = 65536;
+/**
+ * The extension block, present when the footer sets {@link FLAG_EXTENSION}: `section* ‖ u32 sectionsLength ‖ u32
+ * crc32c ‖ "CRBX"`, between the last payload and the index, so the index starts right after it. A reader finds it from
+ * `indexOffset`: the trailer is the {@link EXT_TRAILER_BYTES} bytes before the index, and the CRC32C covers the sections
+ * and the length field. Each section is `u8 type ‖ u32 length ‖ bytes`, in strictly ascending type order; a reader
+ * skips a type it does not know, so a section must be safe to ignore.
+ */
+export declare const EXT_MAGIC: Uint8Array<ArrayBuffer>;
+/** The trailer: the sections' length (u32), their CRC32C (u32) and {@link EXT_MAGIC}. */
+export declare const EXT_TRAILER_BYTES = 12;
+/** A section's header: its type (u8) and its length (u32). */
+export declare const EXT_SECTION_HEADER_BYTES = 5;
+/**
+ * Cap on the sections of one block, in bytes. A reader refuses a larger block from its trailer alone, before it reads
+ * any sections beyond what it already holds (the read that brings the index may already hold up to this much before
+ * it), and a writer of any 1.x minor keeps within it, so a later section type stays readable by this reader.
+ */
+export declare const MAX_EXT_BYTES: number;
+/**
+ * Section type 1: the generation's metadata, its canonical JSON in UTF-8. On an encrypted object the section is
+ * `nonce ‖ ciphertext ‖ tag`, sealed under the segment's key with the metadata scope of the associated data.
+ * Type 0 is not a section type: a reader refuses it.
+ */
+export declare const EXT_SECTION_METADATA = 1;
 /** Fixed width of a per-chunk CRC32C field in the index (high-entropy → not varint). */
 export declare const CRC32C_BYTES = 4;
 /**

package/dist/core/crbm/reader.d.ts

@@ -1,5 +1,6 @@
 import type { BlobReader } from '../blob.js';
 import type { CrbmCrypto } from '../crypto.js';
+import type { GenerationMetadata } from '../ports.js';
 /**
  * A parsed index as parallel typed arrays, one slot per entry, ascending by key. Typed arrays hold each field at
  * its own width with no per-entry object, so the retained heap is the arrays' byte length and nothing else.
@@ -34,7 +35,11 @@ export interface CrbmReaderOptions {
     readonly maxPayloadBytes?: number;
     /** Hard cap on the whole index region fetched/parsed from one object (default 8 MB). */
     readonly maxIndexBytes?: number;
-    /** Decryption context for an encrypted object (its DEK's AEAD + AAD builder). Required iff `FLAG_ENCRYPTED`. */
+    /**
+     * Decryption context for an encrypted object (its DEK's AEAD + AAD builder). Required iff the object's footer sets
+     * `FLAG_ENCRYPTED`: an encrypted object opened without one throws {@link ValidationError}, and an object that is
+     * not encrypted, opened with one, is refused with {@link IntegrityError}.
+     */
     readonly crypto?: CrbmCrypto;
     /**
      * Opaque marker for the *incarnation of the name* this object belongs to — the caller's own identity for the
@@ -44,6 +49,15 @@ export interface CrbmReaderOptions {
      */
     readonly lineage?: unknown;
 }
+/** An object's fingerprint, from its size and its footer's CRC (see {@link CrbmReader.fingerprint}). */
+export declare const fingerprintFor: (size: number, footerCrc: number) => string;
+/**
+ * Whether the object behind `blob` says it is encrypted, from one tail read of a footer's worth, with no key and no
+ * index; a footer that fails its own checks throws, as an open would. For a caller that must not open an object with
+ * the key it holds: an erasure looking for an id in a cleartext object under an encrypted segment, and a rollback
+ * checking that its target is what the row says.
+ */
+export declare function footerSaysEncrypted(blob: BlobReader): Promise<boolean>;
 export declare class CrbmReader {
     private readonly blob;
     private readonly objectSize;
@@ -52,12 +66,22 @@ export declare class CrbmReader {
     readonly lineage: unknown;
     readonly totalCardinality: number;
     private readonly index;
-    /** True when `open()` satisfied the index from the tail GET alone (no second range read). */
+    /**
+     * True when `open()` satisfied the index, and any extension block, from the tail GET alone (no second range
+     * read).
+     */
     readonly servedFromTail: boolean;
     /** Set iff the object is encrypted — used to decrypt each chunk payload in {@link getChunk}. */
     private readonly crypto;
     /** The footer's own CRC, as verified at open: it covers the index's CRC, the chunk count and the generation. */
     private readonly footerCrc;
+    /**
+     * The metadata the generation was written with, checked and decrypted at open; `undefined` when it has none
+     * (every format 1.0 object). Frozen: every caller shares one copy.
+     */
+    readonly metadata: GenerationMetadata | undefined;
+    /** What that metadata adds to {@link retainedBytes}; 0 when there is none. */
+    private readonly metadataWeight;
     private constructor();
     /**
      * Which object this reader opened, as its size and its footer's CRC. The footer covers the index's CRC, so two
@@ -73,6 +97,13 @@ export declare class CrbmReader {
      * arrays that hold it, {@link RETAINED_BYTES_PER_INDEX_ENTRY} per entry.
      */
     get retainedIndexBytes(): number;
+    /**
+     * What this reader holds, the weight the storage reader cache bounds on: its parsed index
+     * ({@link retainedIndexBytes}), plus a weight for the metadata it decoded, from its canonical length and its number
+     * of keys. Equal to {@link retainedIndexBytes} for a generation with no metadata. A cache heuristic, not a contract:
+     * how the metadata is weighed may change in any release.
+     */
+    get retainedBytes(): number;
     /** Per-chunk cardinality (`chunkKey → count`) from the parsed index — no payload reads. */
     cardinalities(): Map<number, number>;
     /**
@@ -100,4 +131,15 @@ export declare class CrbmReader {
      */
     getChunk(chunkKey: number): Promise<Uint8Array | null>;
 }
+/**
+ * Read the sections of an extension block, its bytes before the trailer, once their CRC has passed. Each section is
+ * `u8 type ‖ u32 length ‖ bytes`, in strictly ascending type order, and together they fill the region exactly. Type 1
+ * is the generation's metadata, held to the metadata rules and its canonical form (and opened first with `crypto`,
+ * under the metadata scope, when the object is encrypted); a type this build does not know is a later build's, and
+ * is skipped. Returns the metadata, or `undefined` when the block has none. Every other shape is an
+ * {@link IntegrityError}.
+ *
+ * Exported for the coverage-guided fuzz harness, which drives it directly, past the block's CRC; not public API.
+ */
+export declare function parseExtension(sections: Uint8Array, crypto: CrbmCrypto | undefined): GenerationMetadata | undefined;
 export declare function parseIndex(indexBytes: Uint8Array, payloadEnd: number, maxPayloadBytes: number, minPayloadBytes?: number): ParsedIndex;

package/dist/core/crbm/writer.d.ts

@@ -1,4 +1,5 @@
 import type { CrbmCrypto } from '../crypto.js';
+import type { GenerationMetadata } from '../ports.js';
 import type { BlobSink } from '../blob.js';
 export interface CrbmWriterOptions {
     /** Self-describing generation number (also encoded in the object key). */
@@ -13,6 +14,13 @@ export interface CrbmWriterOptions {
     readonly elementWidth?: number;
     /** When set, payloads + index are AES-256-GCM-encrypted, bound to `(segment, generation, scope)` via AAD. */
     readonly crypto?: CrbmCrypto;
+    /**
+     * The generation's metadata, checked against the metadata rules and copied as its canonical JSON when the writer
+     * is constructed, so a later change to the caller's object never reaches the object. A value that breaks a rule
+     * throws {@link ValidationError} from the constructor, before a byte is written. None, or the empty object, writes
+     * format 1.0.
+     */
+    readonly metadata?: GenerationMetadata;
 }
 export declare class CrbmWriter {
     private readonly sink;
@@ -23,17 +31,38 @@ export declare class CrbmWriter {
     private totalCardinality;
     private preambleWritten;
     private finished;
+    /** The metadata's canonical JSON, copied at construction; `undefined` leaves the footer's extension flag clear. */
+    private readonly metadata;
+    /** Bytes written so far, the footer included once {@link finish} has run. */
+    private written;
+    private footerCrc32c;
     constructor(sink: BlobSink, options: CrbmWriterOptions);
     /**
      * Append one chunk's payload (the roaring-serialized bytes) with its cardinality. `chunkKey` must be
      * strictly greater than the previous one (ascending, no duplicates); `cardinality` is `[1, 65536]`.
      */
     addChunk(chunkKey: number, payload: Uint8Array, cardinality: number): Promise<void>;
-    /** Seal one chunk payload into the on-disk frame `nonce ‖ ciphertext ‖ tag`, bound to its chunkKey. */
-    private sealChunk;
-    /** Write the index region + the fixed footer. After this the object is complete and immutable. */
+    /**
+     * Write the extension block (when there is metadata), the index region and the fixed footer. After this the object
+     * is complete and immutable.
+     */
     finish(): Promise<void>;
+    /**
+     * The finished object's size and its footer's CRC: what names it, as a reader's fingerprint does. A writer that
+     * has to tell its own object from another stored later under the same key compares these with the object's
+     * footer. Throws before {@link finish}.
+     */
+    get identity(): {
+        readonly size: number;
+        readonly footerCrc: number;
+    };
     private ensurePreamble;
+    /**
+     * The extension block: one metadata section (`u8 type ‖ u32 length ‖ bytes`), then the trailer
+     * (`u32 sectionsLength ‖ u32 crc32c(sections ‖ sectionsLength) ‖ "CRBX"`). Encrypted, the section holds
+     * `nonce ‖ ciphertext ‖ tag`, sealed with the metadata scope of the associated data.
+     */
+    private extensionBlock;
     private encodeIndex;
     private buildFooter;
 }

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

@@ -1,11 +1,12 @@
 import { type IAuditSink } from './audit.js';
 import type { Yielder } from './cooperative.js';
-import type { Clock } from './determinism.js';
+import type { Clock, Rng } from './determinism.js';
 import type { CrbmCrypto, IKeystore, WrappedDek } from './crypto.js';
-import type { ChunkRef, StorageChunkSource, GenKey, IStorageDriver, IRegistryDriver, SegmentRef, SegmentSize, Token } from './ports.js';
+import type { ChunkRef, StorageChunkSource, GenerationMetadata, GenerationSummary, GenKey, IStorageDriver, IRegistryDriver, RegistryRecord, RegistrySummary, SegmentRef, SegmentSize, Token } from './ports.js';
 import { CrbmReader } from './crbm/reader.js';
 import type { CrbmReaderOptions } from './crbm/reader.js';
 import type { CodecBitmap, CodecInterface } from './codec.js';
+import { DecodedLoadInput } from './load-input.js';
 export interface CrbmStorageChunkSourceOptions extends CrbmReaderOptions {
     /**
      * Optional {@link IRegistryDriver}. When provided, the current generation is resolved via the registry's
@@ -57,8 +58,8 @@ export interface CrbmStorageChunkSourceOptions extends CrbmReaderOptions {
      * Aggregate byte ceiling on the parsed `.crbm` indices resident in the reader cache (default 64 MiB) — the
      * **second half of that memory bound**. `maxOpenSegments` alone bounds by *count*, but a wide/dense segment's
      * parsed index can reach about 1.3 MB, so 1024 wide indices could pin over a GB and blow a small heap (e.g. a 128 MB
-     * Lambda) while the count is nominally "in bounds". This caps the summed {@link CrbmReader.retainedIndexBytes}
-     * across cached readers; the least-recently-used reader is evicted once the total would exceed it — whichever
+     * Lambda) while the count is nominally "in bounds". This caps the summed {@link CrbmReader.retainedBytes} (the
+     * parsed index, and any metadata a generation carries) across cached readers; the least-recently-used reader is evicted once the total would exceed it — whichever
      * of the count/byte bounds binds first. Lower it for memory-tight deployments with wide segments; a single
      * segment whose index alone exceeds the budget is still cached (it can't be shrunk) but nothing else alongside.
      */
@@ -110,6 +111,13 @@ export declare class CrbmStorageChunkSource implements StorageChunkSource {
      * check again.
      */
     private invalidations;
+    /**
+     * Generations whose row summary this process found to disagree with their object, by segment and generation. A
+     * summary here is not used again: a count of that generation reads the object. Bounded as the readers are, so a
+     * long-lived process cannot grow it without limit; one that falls out is trusted again until its next open finds
+     * the disagreement again.
+     */
+    private readonly distrusted;
     private readonly registry;
     private readonly keystore;
     private readonly requireEncryption;
@@ -117,7 +125,12 @@ export declare class CrbmStorageChunkSource implements StorageChunkSource {
     private readonly clock;
     private readonly currentGenTtlMs;
     constructor(driver: IStorageDriver, options?: CrbmStorageChunkSourceOptions);
-    /** The current resolved reader for a segment, refreshing on the TTL. Cheap within the TTL window. */
+    /**
+     * The segment's live snapshot, refreshing on the TTL. Cheap within the TTL window. The snapshot holds the resolved
+     * target, and its reader once a read has asked for one.
+     */
+    private liveSnapshot;
+    /** The current resolved reader for a segment, refreshing on the TTL. */
     private resolvedReader;
     /**
      * A refresh failed transiently and the prior reader keeps serving: make this snapshot lapse after
@@ -125,12 +138,16 @@ export declare class CrbmStorageChunkSource implements StorageChunkSource {
      * that asks the registry again. It costs no read of its own; it only changes when the next refresh happens.
      */
     private retrySoon;
-    /** TTL elapsed: cheaply re-resolve `currentGen`; reopen only if it actually changed, else reuse the prior reader. */
-    private computeRefreshedReader;
     /**
-     * Memoize a reader-promise as the segment's snapshot at `now()`, forgetting it later if it resolves to
-     * null / throws (identity-guarded, so a stale cleanup never clobbers a fresher snapshot). Installing the
-     * (pending) promise **synchronously** is what lets concurrent callers coalesce onto one in-flight resolve.
+     * TTL elapsed: cheaply re-resolve the pointer. The row read is always fresh, so what the new snapshot says of the
+     * generation (its summary included) is what the row says now, never the prior snapshot's. The reader is reopened
+     * only if the generation or the row changed, and only when a read asks for it.
+     */
+    private refreshedTarget;
+    /**
+     * Memoize a snapshot as the segment's at `now()`, forgetting it later if it resolves to null / throws
+     * (identity-guarded, so a stale cleanup never clobbers a fresher snapshot). Installing the (pending) snapshot
+     * **synchronously** is what lets concurrent callers coalesce onto one in-flight resolve.
      */
     private install;
     private now;
@@ -273,26 +290,51 @@ export declare class CrbmStorageChunkSource implements StorageChunkSource {
      */
     exists(ref: SegmentRef): Promise<boolean>;
     /**
-     * Evict a snapshot we just failed to read from — matched by its reader *promise*, so a concurrent call's
+     * Evict a snapshot we just failed to read from — matched by the snapshot itself, so a concurrent call's
      * fresher snapshot is never clobbered. The identity guard is the whole point: `install` replaces the entry
      * wholesale, so comparing anything else would drop a good snapshot on the floor.
      */
     private dropStale;
-    private resolveLatest;
     /** Open a {@link CrbmReader} for an already-resolved generation target (decrypting if the segment is encrypted). */
     private openForTarget;
+    private openGeneration;
+    /**
+     * Open the generation a resolution found, and hold the row's summary against the object while it is open anyway:
+     * the same count and metadata, or the summary is not believed again in this process ({@link distrusted}). This
+     * costs no request; a mismatch is not an error, since the object is the truth and this read has it.
+     */
+    private openLive;
+    private distrustKey;
+    /** What the row says of the generation, unless it is a summary this process has found to disagree with its object. */
+    private trustedSummary;
     /**
      * The current generation + its DEK wrappings: the registry's authoritative record (one strong read), or a
      * `list` scan for the max generation when there's no registry (a registry-less source can only read cleartext
-     * — there's nowhere a wrapped DEK could live).
+     * — there's nowhere a wrapped DEK could live). The row's summary rides along, to be used or not by whoever
+     * asks.
      */
-    private resolveTarget;
+    private resolveLive;
     /** Build the per-generation decryption context for an encrypted segment (undefined for cleartext). */
     private cryptoForRead;
     getChunk(ref: ChunkRef): Promise<Uint8Array | null>;
     listChunkKeys(ref: SegmentRef): Promise<number[]>;
     sizeOf(ref: SegmentRef): Promise<SegmentSize | null>;
     cardinalities(ref: SegmentRef): Promise<ReadonlyMap<number, number> | null>;
+    /**
+     * The current generation's number, id count and metadata. The answer comes from the row the snapshot resolved when
+     * it can: the row's summary of the generation it names, on an active row, in the shape the row's keys call for
+     * (a sealed one is opened with the segment's key), and one this process has not found to disagree with its
+     * object. That is one registry read when the snapshot is cold, none when it is warm, and no read of the object.
+     * With no summary it can use (an older row, one for another generation, one that does not open), it opens the
+     * generation and answers from the object. A row that names an object that is gone still answers, while a read
+     * of the object throws: the number is true of the generation the row names.
+     *
+     * What the row says is not confirmed here: a summary edited to agree with itself by whoever can write the row is
+     * believed until the next time the object is opened, which holds it against the summary.
+     */
+    summary(ref: SegmentRef): Promise<GenerationSummary | null>;
+    /** {@link summary} of a specific generation, from the object a pin holds. `held` as for {@link getChunkAt}. */
+    summaryAt(ref: SegmentRef, generation: number, held?: PinnedObject): Promise<GenerationSummary | null>;
     /**
      * Run `read` against the pinned snapshot, healing the torn-read window generation GC can open: if the
      * generation we resolved was superseded *and* swept (the grace window elapsed), the Storage driver throws
@@ -320,6 +362,17 @@ export declare class CrbmStorageChunkSource implements StorageChunkSource {
      * `intersect` would do it N times. Gated in `tests/core/storage-source-heal-open.test.ts` by counting calls.
      */
     private withFreshSnapshot;
+    /**
+     * Whether `err`, raised by a read through the snapshot's reader, came from an object that is no longer the one the
+     * reader opened. A generation number can be taken again once its object is deleted (an erasure removes the
+     * generations above a rolled-back pointer that held the id, a collection pass can stop part-way, and a load then
+     * numbers `currentGen + 1` again), so a reader that still holds the old object's index reads the new object's
+     * bytes at the old offsets: a chunk checksum fails, or a range runs past the end. The object's footer says which it
+     * was, as it does for a pin ({@link CrbmReader.sameObject}): replaced, or gone, re-resolves; the same object means
+     * the error is real, and it stands. Only these two errors pay for the footer read, never a read that succeeded. A
+     * transient fault in the check is rethrown; a footer that cannot be read says nothing, and the error stands.
+     */
+    private replacedUnder;
 }
 /**
  * Write one immutable generation from in-memory bitmaps. Chunks are
@@ -333,9 +386,30 @@ export declare function writeCrbmGeneration(driver: IStorageDriver, key: GenKey,
 }>, options?: {
     crypto?: CrbmCrypto;
     clock?: Yielder;
+    metadata?: GenerationMetadata;
 }): Promise<{
     size: number;
     sha256: string;
+    fingerprint: string;
+}>;
+/**
+ * Whether the object under `key` is provably the one `fingerprint` names ({@link CrbmReader.fingerprint}), from one
+ * read of its footer. False when it is another object, when it is gone, and when the read fails in any way: a caller
+ * that deletes on `true` deletes nothing it cannot prove is its own.
+ */
+export declare function holdsObject(storage: IStorageDriver, key: GenKey, fingerprint: string): Promise<boolean>;
+/** Whether the object under `key` says it is encrypted, from one read of its footer, with no key. */
+export declare function objectIsEncrypted(storage: IStorageDriver, key: GenKey): Promise<boolean>;
+/**
+ * What one tail read of the object under `key` tells a rollback about it: whether the footer says it is encrypted, and,
+ * when the object and the key agree (an encrypted object opened with `crypto`, a cleartext one with none), the reader
+ * the open gives, which holds its count and metadata. No reader when they disagree, which the caller refuses as a
+ * target the row cannot use, and none for an encrypted object when the caller has no key. A footer that fails its own
+ * checks, an object another generation's, and an index or metadata that do not open are an {@link IntegrityError}.
+ */
+export declare function openRollbackTarget(storage: IStorageDriver, key: GenKey, crypto: CrbmCrypto | undefined): Promise<{
+    encrypted: boolean;
+    reader: CrbmReader | undefined;
 }>;
 /** What {@link writeCrbmGenerationStream} wrote: the driver's `{ size, sha256 }` + a tally of the generation. */
 export interface StreamWriteResult {
@@ -345,6 +419,8 @@ export interface StreamWriteResult {
     readonly chunkKeys: number[];
     /** Total ids written. */
     readonly cardinality: number;
+    /** The fingerprint of what this call wrote ({@link CrbmReader.fingerprint}), which tells it from another object under its key. */
+    readonly fingerprint: string;
 }
 /**
  * Streaming variant of {@link writeCrbmGeneration} for a **constant-memory** rewrite (the erasure rewrite, a
@@ -360,6 +436,7 @@ export declare function writeCrbmGenerationStream(driver: IStorageDriver, key: G
 }>, options?: {
     crypto?: CrbmCrypto;
     clock?: Yielder;
+    metadata?: GenerationMetadata;
 }): Promise<StreamWriteResult>;
 /**
  * Point a segment's registry `currentGen` at `key.generation` — the publish step that makes a freshly-written
@@ -385,17 +462,43 @@ export declare function writeCrbmGenerationStream(driver: IStorageDriver, key: G
  * 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: `nextGeneration` restarts at `0` once the row is purged and
+ * 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: {@link IRegistryDriver.delete} tombstones rather than unlinks,
- * so "a later `create` still gets a fresh, greater token" and no token is ever reused across incarnations.
+ * 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
+ *   `holdsOwnObject` proves the object under it the caller's: the write landed, and the publish returns `true`. Only
+ *   the writer of a write-once object publishes its number, and a number is never taken while an object holds it;
+ * - 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.
+ *
+ * **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 publishGeneration(registry: IRegistryDriver, key: GenKey, options?: {
     wrappedDeks?: readonly WrappedDek[];
@@ -417,7 +520,55 @@ export declare function publishGeneration(registry: IRegistryDriver, key: GenKey
      * destination that does not exist yet is the ordinary first run of a pipeline.
      */
     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`, to tell this publish's write from another
+     * writer's at the same number. Every caller that writes the object passes it. Without it, 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;
 }): Promise<boolean>;
+/**
+ * Whether the object under `key` is the one `fingerprint` names, from one read of its footer: false when it is another
+ * object or gone. Unlike {@link holdsObject}, a read that cannot tell throws, for a caller that must not take "could
+ * not look" for "not this object".
+ */
+export declare function provesOwnObject(storage: IStorageDriver, key: GenKey, fingerprint: string): Promise<boolean>;
 /** What a bulk-load wrote — the driver's `{ size, sha256 }` plus a summary of the built generation. */
 export interface BulkLoadResult {
     /** Bytes written to the Storage object. */
@@ -436,8 +587,18 @@ export interface BulkLoadResult {
      * unreadable: the bytes are encrypted with a key nothing recorded.
      */
     readonly wrappedDeks?: readonly WrappedDek[];
+    /** Whether the object was written encrypted: under the segment's key, or under one this call minted. */
+    readonly encrypted: boolean;
+    /** The written object's fingerprint, which tells it from an object stored later under the same key. */
+    readonly fingerprint: string;
     /** Total distinct ids in the generation (post-dedup). */
     readonly cardinality: number;
+    /**
+     * The summary of what was written, for the write that makes it current: its id count and metadata, sealed under the
+     * segment's key when the object was written with one. A caller that defers the publish (`publish: false`) passes it
+     * to {@link publishGeneration}.
+     */
+    readonly summary: RegistrySummary;
     /**
      * Whether this generation is now the segment's **current** one — `undefined` when no `registry` was wired, so
      * there is no pointer and no publish step to report on.
@@ -467,11 +628,12 @@ export interface BulkLoadResult {
  * commits only after the callback resolves). An empty source writes a valid empty generation.
  *
  * Writes a fresh full snapshot of a segment. The caller picks the generation number in `key` — `nextGeneration`
- * computes the right one from the registry and the bucket — and re-using an existing generation throws
+ * computes one from the registry and the bucket, as `nextLoadGeneration` does for a load — and re-using an existing
+ * generation throws
  * {@link WriteConflictError} (write-once). Without a registry a `StorageChunkSource` serves the **highest**
  * generation present, so a too-high number silently shadows real data; with one, `publishGeneration` decides.
  */
-export declare function bulkLoadCrbmGeneration(driver: IStorageDriver, key: GenKey, ids: Iterable<number> | AsyncIterable<number>, options?: {
+export declare function bulkLoadCrbmGeneration(driver: IStorageDriver, key: GenKey, ids: Iterable<number> | AsyncIterable<number> | DecodedLoadInput, options?: {
     registry?: IRegistryDriver;
     keystore?: IKeystore;
     requireEncryption?: boolean;
@@ -502,6 +664,22 @@ export declare function bulkLoadCrbmGeneration(driver: IStorageDriver, key: GenK
      * current.
      */
     publish?: boolean;
+    /**
+     * The generation's metadata (see {@link GenerationMetadata}), written into the object and carried in the summary.
+     * The caller has checked it against the metadata rules; the writer checks it again, and refuses a record that breaks
+     * one before a byte is written.
+     */
+    metadata?: GenerationMetadata;
+    /**
+     * The segment's row as the caller already read it (`null`: it found none), for a caller that defers the
+     * publish (`publish: false`) and fences it on that same row. A present cleartext row is then used as read,
+     * rather than read again: a row that changes in between (a publish, a drop, a purge and re-create) makes the
+     * fenced publish lose, so the object is never published on the strength of the stale read. A row read as
+     * absent, or one carrying key material, is read again after the ids, as with no row passed: a first load must
+     * see a row another writer created meanwhile, and an encrypted segment's key is unwrapped only from a row read
+     * after the ids, so a segment shredded while they streamed is refused before its key is used.
+     */
+    row?: RegistryRecord | null;
 }): Promise<BulkLoadResult>;
 /**
  * Open a {@link CrbmReader} on one generation over the storage driver's range/tail reads (decrypting if `crypto`).
@@ -511,12 +689,15 @@ export declare function bulkLoadCrbmGeneration(driver: IStorageDriver, key: GenK
 export declare function openGenerationReader(storage: IStorageDriver, key: GenKey, crypto: CrbmCrypto | undefined, options?: Omit<CrbmReaderOptions, 'crypto'>): Promise<CrbmReader>;
 /**
  * Re-open a freshly written generation and assert it round-trips exactly what was streamed into it: the same
- * per-chunk key set *and* the same total cardinality (on top of the codec's own per-chunk CRC + footer checks).
- * `expected` is the streaming writer's tally (the stream is consumed, so it can't be re-iterated) — the key-set
- * comparison catches a dropped/extra chunk that a cardinality-only check could miss when two errors cancel out.
+ * per-chunk key set *and* the same total cardinality (on top of the codec's own per-chunk CRC + footer checks), and the
+ * metadata it was given. `expected` is the streaming writer's tally (the stream is consumed, so it can't be
+ * re-iterated) — the key-set comparison catches a dropped/extra chunk that a cardinality-only check could miss when
+ * two errors cancel out. The count and the metadata are what the generation's row summary is about to claim, so the
+ * summary is held to the object it describes before it is published.
  * Throws {@link IntegrityError}: the object is on disk but must not be published.
  */
 export declare function verifyGeneration(storage: IStorageDriver, key: GenKey, expected: {
     readonly chunkKeys: readonly number[];
     readonly cardinality: number;
+    readonly metadata?: GenerationMetadata | undefined;
 }, crypto: CrbmCrypto | undefined): Promise<void>;

package/dist/core/crypto.d.ts

@@ -62,19 +62,23 @@ export interface IKeystore {
 }
 /**
  * What the encrypting codec needs: the {@link Aead} for this segment's DEK plus a way to build the AAD for a
- * given scope (`'index'` or a chunkKey). Built per (segment, generation) by the storage-source bridge so the
- * codec itself stays segment-agnostic.
+ * given scope (a chunkKey, `'index'`, or `'metadata'` for the generation's metadata section). Built per
+ * (segment, generation) by the storage-source bridge so the codec itself stays segment-agnostic.
  */
 export interface CrbmCrypto {
     readonly aead: Aead;
-    aadFor(scope: number | 'index'): Uint8Array;
+    aadFor(scope: number | 'index' | 'metadata'): Uint8Array;
 }
 /**
- * Build the AEAD associated-data binding a chunk (or the index) to its exact location:
- * `v1 ‖ len(namespace) ‖ namespace ‖ len(segment) ‖ segment ‖ generation ‖ scope ‖ chunkKey`. Length-prefixed
- * so distinct `(namespace, segment)` pairs can never collide. Pure (no crypto) — just the authenticated label.
+ * Build the AEAD associated-data binding a chunk, the index, the metadata section or a registry row's sealed summary
+ * to its exact location:
+ * `v1 ‖ len(namespace) ‖ namespace ‖ len(segment) ‖ segment ‖ generation ‖ scope ‖ chunkKey`, where scope is
+ * `0` for a chunk, `1` for the index, `2` for the metadata and `3` for the row's summary, and chunkKey is `0` for
+ * the last three.
+ * Length-prefixed so distinct `(namespace, segment)` pairs can never collide. Pure (no crypto) — just the
+ * authenticated label.
  */
 export declare function aadFor(ref: {
     readonly namespace?: string;
     readonly segment: string;
-}, generation: number, scope: number | 'index'): Uint8Array;
+}, generation: number, scope: number | 'index' | 'metadata' | 'summary'): Uint8Array;

package/dist/core/determinism.d.ts

@@ -40,3 +40,10 @@ export interface Rng {
     /** A float in the half-open interval [0, 1). */
     next(): number;
 }
+/**
+ * Injected entropy: `length` cryptographically strong random bytes, for an identity that must never repeat (a
+ * registry row's incarnation id, and the random part every registry write adds to its token). Deliberately not an
+ * {@link Rng}: an `Rng` is seedable for simulation, and a seeded source hands every process the same "random"
+ * identity. Production wiring uses the platform's Web Crypto; a test injects a deterministic source to replay a run.
+ */
+export type Entropy = (length: number) => Uint8Array;