@cloudbitmaps/core 0.19.1 → 0.21.0

package/dist/core/consistency.d.ts

@@ -3,18 +3,23 @@
  * generations can be restored **independently**, so a failover can recover the registry *ahead of* the storage
  * objects — leaving `currentGen` pointing at a generation whose `.crbm` isn't present yet. That is likelier
  * than it sounds even with both in one bucket: a restore scoped to a prefix, or replayed
- * per-object from a version history, recovers the two prefixes at different points. That's a torn restore: reads of the affected segment then throw. This scan
+ * per-object from a version history, recovers the two prefixes at different points. That's a torn restore: reads of
+ * the affected segment then throw. This scan
  * detects it up front (run it at startup after a restore) instead of discovering it on the first read.
  *
  * Read-only; bounded fan-out. `destroyed` (crypto-shredded) segments are skipped — their Storage is intentionally
  * gone/unreadable, not a torn restore. A segment whose Storage/registry can't be read this pass is recorded in
- * `errored` (never aborts the scan). Each segment is checked against its **authoritative live pointer** — one
+ * `errored` (never aborts the scan). One segment can add several entries to `inconsistent` (its current object, and with
+ * `generations` one per known generation whose object is not the one recorded) and can also be in `errored`, when a
+ * read failed after those were found; with `generations` a segment costs up to one read per entry of its ledger.
+ * Each segment is checked against its **authoritative live pointer** — one
  * strong `registry.get` per segment — never the enumeration snapshot from `registry.list`, which a driver may
  * serve eventually-consistently and so lag a recent in-place pointer advance: trusting it would both
  * miss a torn *live* generation and cry torn on a generation the pointer has already advanced past (GC'd during
- * the scan). Residual: a load's publish plus a GC landing in the tiny per-segment get→list gap can still yield a
- * transient false positive — run the scan against a quiesced fleet (the documented restore procedure), or re-run
- * to confirm a reported tear.
+ * the scan). Residual: a load's publish plus a GC landing in the per-segment gap between the pointer read and the
+ * object reads (one read, or with `generations` as many as the ledger names) can still yield a transient false
+ * positive — run the scan against a quiesced fleet (the documented restore procedure), or re-run to confirm a
+ * reported tear.
  */
 import type { IStorageDriver, IRegistryDriver } from './ports.js';
 import type { IKeystore } from './crypto.js';
@@ -33,15 +38,35 @@ export { DEFAULT_MAX_SCAN_SEGMENTS } from './registry-scan.js';
 export interface ConsistencyIssue {
     readonly segment: string;
     readonly namespace?: string;
-    /** The registry's `currentGen` for the segment — the generation whose `.crbm` is missing from Storage. */
+    /**
+     * The registry's `currentGen` for the segment. For `missing-storage-generation` it is the generation whose `.crbm` is
+     * missing from Storage; for the other issues it is the segment's current generation, whichever generation the issue
+     * is about (see `generation`).
+     */
     readonly currentGen: number;
     /**
      * `missing-storage-generation`: `currentGen` references a Storage generation that is not present (torn restore).
-     * `summary-mismatch` (only when asked for): the generation is there, but its row's summary says a different id
-     * count or metadata than the object holds (a row restored from another point than its bucket, or a number re-taken
-     * since). A count answers from that summary until a read opens the object, so it is what a restore leaves wrong.
+     * `summary-mismatch` (only when asked for): the generation is there, but its row's summary names another object
+     * than the one under its number, says a different id count or metadata than the object holds (a row restored from
+     * another point than its bucket, or an object put back from outside the library), or records a fingerprint that
+     * names no object. A summary that names another object is what a count and a `stat()` answer from while every read
+     * that opens the object refuses it; one whose count or metadata disagrees is answered from until a read opens the
+     * object, which stops that store using it; one whose fingerprint names no object is not used, so every read opens the
+     * object unchecked.
+     * `known-generation-mismatch` (only when asked for): the object under the number `generation` is not the one the row's
+     * ledger of known generations recorded for it: its footer checksum differs, or its footer fails its own checks (it is
+     * not a `.crbm` object, or is cut short). It says nothing of what a rollback does with that generation.
+     * What it covers: each object's footer is held to the recorded checksum, so another object, or bytes that are not a
+     * `.crbm`, under a known number is found. It does not find damage inside an object whose footer is intact (a cut or a
+     * flipped byte in the body: a read of that generation reports it as `IntegrityError`), nor a metadata change that keeps
+     * the footer's bytes.
      */
-    readonly issue: 'missing-storage-generation' | 'summary-mismatch';
+    readonly issue: 'missing-storage-generation' | 'summary-mismatch' | 'known-generation-mismatch';
+    /**
+     * With `known-generation-mismatch` only: the generation whose object is not the one the row recorded. It is
+     * `currentGen` when the current object is the one that differs. Absent on every other issue.
+     */
+    readonly generation?: number;
 }
 /** A segment that could not be checked this pass (Storage/registry read fault) — not proof of a torn restore. */
 export interface ConsistencyErrorEntry {
@@ -53,12 +78,17 @@ export interface ConsistencyErrorEntry {
 export interface ConsistencyReport {
     /** Registered segments scanned (a `destroyed` segment counts as scanned but is never an issue). */
     readonly checked: number;
-    /** Segments whose `currentGen` `.crbm` is absent — recover the object store (or restore to a coherent point). */
+    /**
+     * The issues found, one entry each: a segment whose `currentGen` `.crbm` is absent (recover the object store, or
+     * restore to a coherent point), and with the options asked for the other kinds. One segment can have several entries:
+     * at most one for its current object plus one per entry of its ledger, so at most 1 plus the ledger's length (384 at
+     * most). The ledger's length is bounded by the registry, and the report is not capped.
+     */
     readonly inconsistent: ConsistencyIssue[];
     /**
      * Segments that couldn't be read this pass (a transient/partial object store during a restore is exactly when
-     * this runs) — **triage these too**: an unread segment is neither proven-coherent nor proven-torn. Empty on a
-     * clean pass.
+     * this runs) — **triage these too**: an unread segment is neither proven-coherent nor proven-torn. A segment can be in
+     * this list and in `inconsistent` too: what was found before the read that failed is kept. Empty on a clean pass.
      */
     readonly errored: ConsistencyErrorEntry[];
     /**
@@ -67,17 +97,44 @@ export interface ConsistencyReport {
      * only when summaries were asked for.
      */
     readonly summariesUnchecked?: number;
+    /**
+     * With `generations: true`, the rows with a pointer whose ledger of known generations could not be used (absent, or
+     * failing the validation every reader of it applies, or not shaped as a ledger a registry of this library stores):
+     * none of their known generations was held against its object. A count, not an issue. Present only when generations
+     * were asked for.
+     */
+    readonly generationsUnchecked?: number;
 }
 /**
  * Verify every registered segment's `currentGen` `.crbm` actually exists in Storage. Enumerates the registry
- * (optionally one namespace) and, for each non-`destroyed` segment, checks the object store lists that
- * generation. Returns the torn segments in `inconsistent` (empty ⇒ coherent) and any unreadable segments in
+ * (optionally one namespace) and, for each non-`destroyed` segment, asks the object store for that generation with a
+ * zero-length tail read. Returns the torn segments in `inconsistent` (empty ⇒ coherent) and any unreadable segments in
  * `errored`.
  *
+ * When that read fails, in any way, the segment's listing decides and its own error is the segment's, so a missing
+ * object, a missing bucket and a failing store are reported as when every segment was listed. One difference: a store
+ * that answers reads but refuses listings (an identity without list permission, or a listing-only outage) reports each
+ * object that is there as present, where every segment was reported errored.
+ *
  * With `summaries: true` it also opens each segment's current object (one tail read, and a second for an index longer
- * than it) and holds the row's summary against it, reporting `summary-mismatch` where they disagree. A sealed summary
- * needs `deps.keystore`; without it the segment is counted in `summariesUnchecked`. Off by default, since the
- * default check only lists.
+ * than it) and holds the row's summary against it: the object it names by its fingerprint, and the count and metadata
+ * it says, reporting `summary-mismatch` where they disagree, and for a clear summary whose fingerprint names no
+ * object, which no read uses. For a row with a clear summary that open is the only request of the object; if it fails
+ * before its first read answered, the listing decides, and once that read has answered a failure is an error of the
+ * segment. A sealed summary needs `deps.keystore`; without it the segment is counted in `summariesUnchecked`. Off by
+ * default, since the default check only looks for the object.
+ *
+ * With `generations: true` it also holds every generation a row's ledger of known generations names, the current one
+ * included, against its object: one footer read each (104 bytes, no key, not retried), reporting
+ * `known-generation-mismatch` with the `generation` where the object's footer checksum is not the one the ledger records
+ * or its footer fails its own checks. That finds another object, or bytes that are not a `.crbm`, under a known number;
+ * it does not find damage inside an object whose footer is intact (a read of it reports that as `IntegrityError`), nor a
+ * metadata change that keeps the footer's bytes. A segment adds at most 1 plus its ledger's length issues. A named
+ * generation that is not in the bucket is not reported. A row with a pointer whose ledger cannot be used (absent, failing
+ * the validation every reader of it applies, or not shaped as a ledger a registry of this library stores) is counted in
+ * `generationsUnchecked` and none of its objects is read. The listing is not used: a read of a missing object
+ * answers `NotFoundError`, which is how an absent one is told. A segment whose current object is missing is reported as
+ * ever and its older generations are still checked. Off by default.
  */
 export declare function runConsistencyCheck(deps: {
     readonly storage: IStorageDriver;
@@ -88,4 +145,5 @@ export declare function runConsistencyCheck(deps: {
     concurrency?: number;
     maxScanSegments?: number;
     summaries?: boolean;
+    generations?: boolean;
 }): Promise<ConsistencyReport>;

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

@@ -0,0 +1,23 @@
+/** What names an object: its size, then its footer's CRC. One spelling, for an open reader and a footer read alone. */
+export declare const sizePart: (size: number) => string;
+/** An object's fingerprint, from its size and its footer's CRC (see `CrbmReader.fingerprint`). */
+export declare const fingerprintFor: (size: number, footerCrc: number) => string;
+/**
+ * A fingerprint taken apart, or `undefined` for text that is not one an object can have: a size that is a safe integer
+ * no smaller than a `.crbm` preamble and footer, and a footer CRC that fits in 32 bits. For a row's summary, which
+ * names its object by it and reports the size from it.
+ */
+export declare function fingerprintParts(fingerprint: unknown): {
+    readonly size: number;
+    readonly footerCrc: number;
+} | undefined;
+/**
+ * The footer CRC of a fingerprint a writer or a reader produced, which a row's ledger records beside the generation.
+ * Throws {@link IntegrityError} for text that is not a fingerprint, which neither produces.
+ */
+export declare function footerCrcOf(fingerprint: string): number;
+/**
+ * A fingerprint spelled short, for a key a read builds on every chunk: its size and its footer's CRC in base 36,
+ * `<size>.<crc>`. Two compact spellings are equal exactly when the fingerprints are.
+ */
+export declare function compactFingerprint(fingerprint: string): string;

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

@@ -4,16 +4,14 @@
  * 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).
  */
+import { FOOTER_BYTES, PREAMBLE_BYTES } from './frame.js';
 /** 4-byte magic at both file ends: "CRBM". */
 export declare const MAGIC: Uint8Array<ArrayBuffer>;
 export declare const VERSION_MAJOR = 1;
 export declare const VERSION_MINOR = 0;
-/** Front preamble: magic(4) + version_major(1) + version_minor(1) + reserved(2). */
-export declare const PREAMBLE_BYTES = 8;
+export { FOOTER_BYTES, PREAMBLE_BYTES };
 /** Payloads begin immediately after the preamble. */
 export declare const PAYLOAD_START = 8;
-/** Fixed footer size (v1.0). */
-export declare const FOOTER_BYTES = 104;
 /** Byte offsets of each field within the 104-byte footer. */
 export declare const FOOTER: {
     readonly indexOffset: 0;
@@ -39,7 +37,6 @@ export declare const FOOTER: {
 export declare const FOOTER_CRC_COVERAGE: 96;
 /** `flags` bit positions. */
 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

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

@@ -0,0 +1,10 @@
+/**
+ * The two widths every `.crbm` v1 object is framed by: its front preamble and its footer. Frozen with the rest of the
+ * layout in `format.ts`, which re-exports them. They live in a module of their own, with no imports, so that what needs
+ * only the smallest size an object can have (the registry's check of a summary's fingerprint) does not bring the
+ * format's other constants, or the reader, with it.
+ */
+/** Front preamble: magic(4) + version_major(1) + version_minor(1) + reserved(2). */
+export declare const PREAMBLE_BYTES = 8;
+/** Fixed footer size (v1.0). */
+export declare const FOOTER_BYTES = 104;

package/dist/core/crbm/plan-reads.d.ts

@@ -34,11 +34,17 @@ export interface ChunkRegion {
 }
 /**
  * Plan the reads for `extents`: the needed chunks of one object, ascending by offset (the index lists chunks in key
- * order, which is object order), each at least a byte long, none overlapping another. The reads come back
- * ascending and disjoint, each covering one or more of the chunks, every chunk in exactly one read.
+ * order, which is object order), each at least a byte long, none overlapping another. The reads come out ascending
+ * and disjoint, each covering one or more of the chunks, every chunk in exactly one read.
+ *
+ * Lazy: the plan is a walk, so a consumer that takes the first reads pulls only the extents those reads cover (and
+ * the one after, which closes the last of them), and a plan over a very wide object costs nothing until it is read.
+ * Each extent is checked as the walk reaches it, before the read that would carry it is handed out, so no read ever
+ * covers an extent that was not checked; a plan taken to its end has checked them all. The reads are exactly the ones
+ * a plan made all at once would hold, in the same order.
  *
  * Throws {@link IntegrityError} for an extent that is not a pair of safe integers, or is outside `region`, or out of
  * order, or overlapping the one before it:
  * the index a plan is made from is untrusted bytes, and a read is never planned outside the chunk region.
  */
-export declare function planChunkReads(extents: readonly ChunkExtent[], region: ChunkRegion): readonly PlannedRead[];
+export declare function planChunkReads(extents: Iterable<ChunkExtent>, region: ChunkRegion): Generator<PlannedRead, void, undefined>;

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

@@ -7,7 +7,7 @@ import type { ChunkRead, GenerationMetadata, ReadChunksOptions } from '../ports.
  * `cardinalityMinusOne` stores `cardinality - 1` because a chunk's cardinality runs `[1, 65536]` and 65,536 does
  * not fit a `u16`; an offset is a `f64` because an object past 4 GiB puts a payload beyond a `u32`.
  */
-export interface ParsedIndex {
+interface ParsedIndex {
     readonly keys: Uint16Array;
     readonly cardinalityMinusOne: Uint16Array;
     readonly lengths: Uint32Array;
@@ -29,7 +29,12 @@ export declare const RETAINED_BYTES_PER_INDEX_ENTRY = 20;
  */
 export declare function indexCapacity(indexLength: number): number;
 export interface CrbmReaderOptions {
-    /** Speculative tail size in bytes (default 256 KB; clamped up to at least the footer size). */
+    /**
+     * How many bytes the first tail read asks for, a whole number (default 256 KiB; clamped up to at least the footer
+     * size). Any value of at least an object's `tailBytes` opens it in that one read. Where an open keeps a small object's
+     * chunks (a `CrbmStorageChunkSource`'s does), it keeps them only when this read covers the whole object, so a value
+     * below the default can leave them to reads of their own.
+     */
     readonly tailBytes?: number;
     /** Hard cap on a single chunk payload length (default: the 1 MiB decode cap, plus the 28-byte nonce and tag on an encrypted object). The engine decodes under `maxBitmapBytes`; raise this with it. */
     readonly maxPayloadBytes?: number;
@@ -49,13 +54,20 @@ 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;
 /**
- * A fingerprint spelled short, for a key a read builds on every chunk: its size and its footer's CRC in base 36,
- * `<size>.<crc>`. Two compact spellings are equal exactly when the fingerprints are.
+ * Refuses a `size` that is not a whole byte count its own tail fits in. The size is the tier's word too: one that
+ * is not would turn off every bounds check an open makes against it.
+ */
+export declare function checkSize(tail: Uint8Array, size: number): void;
+/**
+ * What the footer of the object behind `blob` says with no key and no index, from one tail read of a footer's worth:
+ * whether it is encrypted, and its CRC (the one in {@link CrbmReader.fingerprint}). A footer that fails its own checks
+ * throws, as an open would.
  */
-export declare function compactFingerprint(fingerprint: string): string;
+export declare function readFooter(blob: BlobReader): Promise<{
+    readonly encrypted: boolean;
+    readonly footerCrc: number;
+}>;
 /**
  * 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
@@ -68,6 +80,14 @@ export declare function footerSaysEncrypted(blob: BlobReader): Promise<boolean>;
  * object and that region is at most `keepChunkBytesUpTo` bytes. Not exported from a package entry.
  */
 export declare function openCrbmReaderKeeping(blob: BlobReader, options: CrbmReaderOptions, keepChunkBytesUpTo: number | undefined): Promise<CrbmReader>;
+/**
+ * How many bytes the first tail read of an open asks for: the caller's `tailBytes` or the default, and a footer's worth
+ * at least. Not exported from a package entry: {@link CrbmReader.open} and a caller that sends that read ahead of it
+ * ask for the same size.
+ */
+export declare function openTailBytes(options: {
+    readonly tailBytes?: number;
+}): number;
 export declare class CrbmReader {
     private readonly blob;
     private readonly objectSize;
@@ -107,8 +127,13 @@ export declare class CrbmReader {
      * the object it reopens is the one it pinned, since a purged and reloaded name reuses the generation number.
      */
     get fingerprint(): string;
-    /** Total object bytes (from the one-GET tail read) — for grounded storage cost. */
+    /** Total object bytes (from the one-GET tail read): the `sizeBytes` a segment's `stat()` reports. */
     get sizeBytes(): number;
+    /**
+     * The bytes of the object after its chunk payloads: any extension block, the index and the footer. A tail read of
+     * this many bytes covers all of them.
+     */
+    get tailBytes(): number;
     /**
      * Retained JS heap of this reader's parsed index — the weight the storage reader cache bounds on (a wide
      * segment's parsed index, not its payloads, dominates the reader's footprint): the exact byte length of the
@@ -141,6 +166,16 @@ export declare class CrbmReader {
     count(): number;
     /** The slot holding `chunkKey` (binary search over the ascending keys), or -1 when this generation has none. */
     private slotOf;
+    /**
+     * {@link slotOf} for a key at or after the one that held slot `at`, which a walk over ascending keys has: the slot
+     * itself or the next are tried first, so a read of nearly every chunk costs no search.
+     */
+    private slotFrom;
+    /**
+     * The extents of the chunks `chunkKeys` name that this generation holds, in key order, each once (a key given twice
+     * is read once). A walk, so nothing is looked up until the plan pulls it.
+     */
+    private neededExtents;
     has(chunkKey: number): boolean;
     /**
      * Range-GET one chunk's payload, verifying its CRC32C before returning. Returns `null` if the chunk is
@@ -175,10 +210,13 @@ export declare class CrbmReader {
      * as {@link getChunk} answers for an absent key. A key given twice is read once and answered at both positions with
      * the same view.
      *
-     * The whole key list is planned once, up front, against this one generation's index. The ranges then run through a
-     * window of `options.concurrency` reads ({@link MAX_RANGES_IN_FLIGHT} by default) that counts a range until the
-     * consumer has taken it, so a stream never holds more than that many ranges, in flight or landed, however many keys
-     * it was given or how slowly it is read; with `options.ramp` the window opens 1, 2, 4 … wide. A range is at most 1 MiB
+     * The key list is planned against this one generation's index ({@link planChunkReads}), as a walk the window pulls
+     * from only as it opens a range, so a stream that stops early has planned little: the same ranges, in the same
+     * order, as a plan of the whole list would make, and each chunk's extent is checked before the range that carries
+     * it is requested. The ranges run through a window of `options.concurrency` reads ({@link MAX_RANGES_IN_FLIGHT} by
+     * default) that counts a range until the consumer has taken it, so a stream never holds more than that many ranges,
+     * in flight or landed, however many keys it was given or how slowly it is read; with `options.ramp` the window opens
+     * 1, 2, 4 … wide. A range is at most 1 MiB
      * unless it is one chunk, which is at most the payload cap, so the bound is that many times the per-chunk cap
      * (1 MiB, and 28 bytes more for an encrypted chunk). Nothing is read until the first item is asked for, and a
      * consumer that stops launches no more: ranges already in flight finish and are dropped, and a failure of one of
@@ -230,3 +268,4 @@ export type ChunkStream = AsyncGenerator<Omit<ChunkRead, 'version'>> & {
  */
 export declare function parseExtension(sections: Uint8Array, crypto: CrbmCrypto | undefined): GenerationMetadata | undefined;
 export declare function parseIndex(indexBytes: Uint8Array, payloadEnd: number, maxPayloadBytes: number, minPayloadBytes?: number): ParsedIndex;
+export {};

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

@@ -1,6 +1,6 @@
 /** Append the LEB128 encoding of a u32 `value` to `out`. */
 export declare function writeVarint(out: number[], value: number): void;
-export interface VarintRead {
+interface VarintRead {
     readonly value: number;
     /** Offset just past the bytes consumed. */
     readonly next: number;
@@ -11,3 +11,4 @@ export interface VarintRead {
  * cleanly, never loop or overflow.
  */
 export declare function readVarint(bytes: Uint8Array, offset: number): VarintRead;
+export {};

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

@@ -35,6 +35,8 @@ export declare class CrbmWriter {
     private readonly metadata;
     /** Bytes written so far, the footer included once {@link finish} has run. */
     private written;
+    /** Where the chunk payloads end: the extension block's start when there is metadata, else the index's. */
+    private payloadEnd;
     private footerCrc32c;
     constructor(sink: BlobSink, options: CrbmWriterOptions);
     /**
@@ -50,11 +52,13 @@ export declare class CrbmWriter {
     /**
      * 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}.
+     * footer. `tailBytes` is the bytes after the chunk payloads (any extension block, the index and the footer), which
+     * is what {@link CrbmReader.tailBytes} reports for the object. Throws before {@link finish}.
      */
     get identity(): {
         readonly size: number;
         readonly footerCrc: number;
+        readonly tailBytes: number;
     };
     private ensurePreamble;
     /**

package/dist/core/crbm-open.d.ts

@@ -0,0 +1,154 @@
+import type { BlobReader } from './blob.js';
+import type { CrbmCrypto } from './crypto.js';
+import type { GenerationMetadata, GenKey, IStorageDriver, TailRead } from './ports.js';
+import { CrbmReader } from './crbm/reader.js';
+import type { CrbmReaderOptions } from './crbm/reader.js';
+import type { SummaryDescription } from './summary.js';
+/**
+ * Adapt one `(driver, key)` pair to the codec's `BlobReader` seam. With `noteTail`, each tail read the reader makes is
+ * shown to it with the bytes, `size` and `version` the driver answered, after the copy below when one is made.
+ *
+ * A tail's bytes reach the reader as a plain `Uint8Array`: the reader keeps a small object's chunk region by slicing
+ * the tail, and a subclass's `slice` need not copy. A Node `Buffer`'s is a view, so a driver that answered with one
+ * would leave the reader holding the driver's memory, all of it, as the cache weighs only the region. Such an answer
+ * is copied here, once ({@link ownedTail}); a plain `Uint8Array` of this realm, which every shipped driver returns, is
+ * handed through as it is.
+ */
+export declare function storageBlobReader(driver: IStorageDriver, key: GenKey, noteTail?: (tail: TailRead) => void): BlobReader;
+/**
+ * `tail` with its bytes in a plain `Uint8Array` of this realm. Any other `Uint8Array`, a subclass (a Node `Buffer`) or
+ * one made in another realm (a `vm` context), is copied once, and the copy is built from the answer's fields by name,
+ * so a `size` or `version` the driver serves from a getter on its own class carries over. The brand is read, not
+ * `instanceof`, which is false for another realm's arrays. A plain `Uint8Array` of this realm is handed through as it is.
+ */
+export declare function ownedTail(tail: TailRead): TailRead;
+/**
+ * The object under `key`, when one read of its footer matches `fingerprint` ({@link CrbmReader.fingerprint}), with the
+ * version the driver reported on that read (`undefined` from a driver that reports none). `null` when it is another
+ * object, when it is gone, and when the read fails in any way. A fingerprint names the object's bytes, not the writer:
+ * an object another writer stored under the number with the same bytes matches too. A caller that deletes what this
+ * matches passes the version as the delete's `ifVersion`, so a number taken again between the read and the delete keeps
+ * the object put under it since.
+ */
+export declare function provenObject(storage: IStorageDriver, key: GenKey, fingerprint: string): Promise<{
+    readonly version: string | undefined;
+} | null>;
+/**
+ * Whether the object under `key` is still the one `fingerprint` names ({@link CrbmReader.fingerprint}), from one read
+ * of its footer. Unlike {@link provenObject}, a fault is not an answer: `NotFoundError` when the key holds no object,
+ * and any other failure of the read, thrown as it is.
+ */
+export declare function sameObjectUnder(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. `noteVersion` is shown
+ * the version the driver reported on that read, when it reported one: a caller that deletes the object for what its
+ * footer says passes it as the delete's `ifVersion`.
+ */
+export declare function objectIsEncrypted(storage: IStorageDriver, key: GenKey, noteVersion?: (version: string) => void): Promise<boolean>;
+/**
+ * What one tail read of a rollback target says about it with no key: whether the footer says it is encrypted and its
+ * CRC, and the remembered tail an open from it ({@link openRollbackTargetFrom}) is answered from.
+ */
+interface RollbackTargetFooter {
+    readonly encrypted: boolean;
+    readonly footerCrc: number;
+    readonly blob: BlobReader;
+}
+/**
+ * The footer step of a rollback: one tail read of the object under `key`, which is remembered for the open that may
+ * follow. A footer that fails its own checks is an {@link IntegrityError}; a missing object is {@link NotFoundError}.
+ */
+export declare function readRollbackTargetFooter(storage: IStorageDriver, key: GenKey): Promise<RollbackTargetFooter>;
+/**
+ * The reader {@link RollbackTargetFooter}'s object opens as, from its remembered tail, when the object and the key
+ * agree (an encrypted object opened with `crypto`, a cleartext one with none); `undefined` when they disagree, which
+ * the caller refuses as a target the row cannot use. An object that is another generation's, and an index or metadata
+ * that do not open, are an {@link IntegrityError}.
+ */
+export declare function openRollbackTargetFrom(footer: RollbackTargetFooter, key: GenKey, crypto: CrbmCrypto | undefined): Promise<CrbmReader | undefined>;
+/**
+ * The footer CRC of the object under `key` ({@link CrbmReader.fingerprint} carries it), from one read of a footer's
+ * worth, so it reads an encrypted object's CRC as it does a cleartext one's, with no key. {@link NotFoundError} when
+ * the key holds no object; a footer that fails its own checks is an {@link IntegrityError}.
+ */
+export declare function footerCrcUnder(storage: IStorageDriver, key: GenKey): Promise<number>;
+/**
+ * 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 provenObject}, 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>;
+/**
+ * Open a {@link CrbmReader} on one generation over the storage driver's range/tail reads (decrypting if `crypto`).
+ * The reader the write paths use to re-read what they wrote, and the erasure rewrite uses to stream the old
+ * generation; the engine's read path goes through {@link CrbmStorageChunkSource} instead, which caches these. With
+ * `named`, the fingerprint the row's summary records, the object must be that one: another is {@link NotFoundError}.
+ * The version of the object it opened, from the tail read the open made, is what {@link objectVersionOf} answers.
+ */
+export declare function openGenerationReader(storage: IStorageDriver, key: GenKey, crypto: CrbmCrypto | undefined, options?: Omit<CrbmReaderOptions, 'crypto'>, named?: string): Promise<CrbmReader>;
+/**
+ * {@link openGenerationReader}, with `noteVersion` shown the version {@link objectVersionOf} would answer as soon as the
+ * tail read that carries it returns, before the open goes on: a caller whose open then fails, on an object sealed under
+ * another key, say, still knows which object it met, and can condition a delete of it on that read.
+ */
+export declare function openGenerationReaderNoting(storage: IStorageDriver, key: GenKey, crypto: CrbmCrypto | undefined, noteVersion: (version: string) => void): Promise<CrbmReader>;
+/**
+ * The version of the object `reader` was opened on, as the driver reported it on the tail read the open made, for a
+ * delete conditioned on that object ({@link StorageDeleteOptions.ifVersion}); `undefined` for a reader
+ * {@link openGenerationReader} did not open, or a driver that reports none. Held beside the reader rather than on it, so
+ * nothing is added to the reader's public surface, and no read the engine makes pays for it.
+ */
+export declare function objectVersionOf(reader: CrbmReader): string | undefined;
+/**
+ * {@link openGenerationReader}, of the object `summary.fingerprint` names: `undefined` when the object under the key is
+ * another one, found from its footer before its index is opened, so an object sealed under another key is told apart as
+ * well. The tail read is sized from the summary's `tailBytes` ({@link sizedTailBytes}), so a wide generation's index
+ * comes in that read.
+ */
+export declare function openNamedGeneration(storage: IStorageDriver, key: GenKey, crypto: CrbmCrypto | undefined, summary: Pick<SummaryDescription, 'fingerprint' | 'tailBytes'>, noteTail?: (tail: TailRead) => void): Promise<CrbmReader | undefined>;
+/**
+ * Open a reader on `key`, refusing an object whose footer names another generation. Every writer stamps the key's
+ * number, and the chunk cache, the load guard and the erasure rewrite all trust it, so an object that disagrees
+ * was written under another key or altered. Every open, the live read's, a pin's and the write paths', comes here.
+ * With `named`, the object must also be the one that fingerprint names: another one is {@link NotFoundError}, a move.
+ * With `early`, the tail read {@link startTailRead} began, the open takes that read as its own instead of making one.
+ */
+export declare function openChecked(storage: IStorageDriver, key: GenKey, options: CrbmReaderOptions, keepChunkBytesUpTo?: number, named?: string, noteTail?: (tail: TailRead) => void, early?: Promise<TailRead>): Promise<CrbmReader>;
+/**
+ * The size of the tail read an open makes when its row's summary says how many bytes of the object's end the open
+ * needs (`tailBytes`: any extension block, the index and the footer), so that one read reaches the index of a wide
+ * generation and no range read follows it. With no summary it is the source's own size ({@link openTailBytes}).
+ *
+ * The number came from a registry the library may not have written, so it only ever sizes a read: never below the
+ * source's own tail, at most the object less its preamble (the size its fingerprint names), and at most the source's
+ * `maxIndexBytes` (or the default) plus an extension block, its trailer and the footer, the most any open reads past
+ * its own tail. A hint that is not a whole number of bytes above zero is ignored, and so is a result that is not one. A
+ * wrong hint is a longer read or one more range read, never a different answer: the reader checks every byte it takes.
+ */
+export declare function sizedTailBytes(summary: Pick<SummaryDescription, 'fingerprint' | 'tailBytes'> | undefined, options: {
+    readonly tailBytes?: number;
+    readonly maxIndexBytes?: number;
+}): number;
+/**
+ * Send the tail read an open of `key` makes, now, and hand back its answer for {@link openChecked}'s `early`: the open
+ * then waits on the one request instead of sending its own, so work the open waits on first, such as a keystore call,
+ * runs beside the request and not before it. Nothing is parsed here: the bytes are untrusted until the open reads them.
+ * The returned promise already has a handler attached, so a caller that never reaches the open (its key failed) leaves
+ * no unhandled rejection; the open that does reach it still sees the rejection.
+ */
+export declare function startTailRead(storage: IStorageDriver, key: GenKey, options: CrbmReaderOptions): Promise<TailRead>;
+/**
+ * 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), 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>;
+export {};