@cloudbitmaps/core 0.21.0 → 0.23.0

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

@@ -1,72 +0,0 @@
-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). */
-    readonly generation: number;
-    /**
-     * Which codec produced the chunk payloads. Defaults to {@link PAYLOAD_CODEC_ROARING_PORTABLE}.
-     *
-     * A codec id rather than a roaring-specific one, because `.crbm` is a shared container and a second codec is
-     * expected before the format freezes.
-     */
-    readonly payloadCodecId?: number;
-    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;
-    private readonly options;
-    private readonly entries;
-    private offset;
-    private lastKey;
-    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;
-    /** 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);
-    /**
-     * 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>;
-    /**
-     * 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. `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;
-    /**
-     * 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-open.d.ts

@@ -1,154 +0,0 @@
-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 {};

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

@@ -1,75 +0,0 @@
-import type { Yielder } from './cooperative.js';
-import type { CrbmCrypto } from './crypto.js';
-import type { GenerationMetadata, GenKey, IStorageDriver } from './ports.js';
-import type { CodecBitmap, EncodedChunk } from './codec.js';
-/**
- * Write one immutable generation from in-memory bitmaps. Chunks are
- * sorted ascending and empty bitmaps skipped (empty chunks are never stored). Returns the driver's
- * `{ size, sha256 }` for the written object. Pass `options.crypto` to AES-256-GCM-encrypt the generation
- * (built from the segment's DEK, with associated data bound to `(segment, generation)`).
- */
-export declare function writeCrbmGeneration(driver: IStorageDriver, key: GenKey, chunks: Iterable<{
-    chunkKey: number;
-    bitmap: CodecBitmap;
-}>, options?: {
-    crypto?: CrbmCrypto;
-    clock?: Yielder;
-    metadata?: GenerationMetadata;
-}): Promise<{
-    size: number;
-    sha256: string;
-    fingerprint: string;
-    tailBytes: number;
-}>;
-/** Each non-empty bitmap as the chunk it stores, in the order given. */
-export declare function encodeEach(chunks: Iterable<{
-    chunkKey: number;
-    bitmap: CodecBitmap;
-}>): Generator<EncodedChunk>;
-/**
- * Write one immutable generation from chunks already encoded, which must ascend by key (the writer refuses one
- * that does not). Returns the driver's `{ size, sha256 }` and a tally of what was written.
- */
-export declare function writeEncodedChunks(driver: IStorageDriver, key: GenKey, chunks: Iterable<EncodedChunk>, options: {
-    crypto?: CrbmCrypto;
-    clock?: Yielder;
-    metadata?: GenerationMetadata;
-}): Promise<{
-    size: number;
-    sha256: string;
-    chunkCount: number;
-    cardinality: number;
-    fingerprint: string;
-    /** The bytes after the chunk payloads ({@link CrbmReader.tailBytes}). */
-    tailBytes: number;
-}>;
-/** What {@link writeCrbmGenerationStream} wrote: the driver's `{ size, sha256 }` + a tally of the generation. */
-interface StreamWriteResult {
-    readonly size: number;
-    readonly sha256: string;
-    /** Non-empty chunk keys written, in ascending order (for the post-write verify, since the stream is consumed). */
-    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;
-    /** The bytes after the chunk payloads ({@link CrbmReader.tailBytes}). */
-    readonly tailBytes: number;
-}
-/**
- * Streaming variant of {@link writeCrbmGeneration} for a **constant-memory** rewrite (the erasure rewrite, a
- * sorted load): consumes an **already-ascending** async stream of `{ chunkKey, bitmap }`, feeding each to the
- * codec and freeing it, instead of materializing the whole generation. Paired with a streaming storage sink (S3
- * multipart / LocalFs temp file), the writer itself holds ~one chunk + one part. Returns a tally so the caller can verify
- * the re-opened object without re-iterating the (now-consumed) stream. Input **must** be ascending by `chunkKey`
- * — the codec rejects an out-of-order chunk; empty bitmaps are skipped.
- */
-export declare function writeCrbmGenerationStream(driver: IStorageDriver, key: GenKey, chunks: AsyncIterable<{
-    chunkKey: number;
-    bitmap: CodecBitmap;
-}>, options?: {
-    crypto?: CrbmCrypto;
-    clock?: Yielder;
-    metadata?: GenerationMetadata;
-}): Promise<StreamWriteResult>;
-export {};

package/dist/core/due-index.d.ts

@@ -1,53 +0,0 @@
-import { MAX_NAME_LENGTH } from './validate.js';
-import type { RegistryRecord, SegmentRef } from './ports.js';
-/** Bucket width. One day: small enough that a cycle reads little, coarse enough that the index stays tiny. */
-export declare const DUE_BUCKET_MS = 86400000;
-/**
- * The name-length cap, and an index row encodes **both** of the original ref's parts into one name — so a ref
- * whose encoding would exceed it is simply not indexed (see {@link canIndex}).
- *
- * Re-exported from the validator rather than restated. The two were separate constants with the same value
- * until the validator started measuring the **encoded** length; `canIndex` went on counting raw characters and
- * began answering `true` for refs the registry then refused, turning a documented graceful degradation into a
- * guaranteed throw on the retention fast path.
- */
-export { MAX_NAME_LENGTH };
-/** Which bucket an expiry falls in. Total and reversible; no calendar, no timezone, no ambient time. */
-export declare function dueBucket(expiresAt: number): number;
-/** The namespace holding one bucket's pointers. */
-export declare function dueNamespace(bucket: number): string;
-/** Is this record a due-index pointer rather than a segment? */
-export declare function isDueIndexRow(record: Pick<RegistryRecord, 'namespace'>): boolean;
-/**
- * Encode a ref into one index-row name, unambiguously.
- *
- * `${namespaceLength}.${namespace}${segment}` — a decimal length, a dot, then the two parts concatenated. The
- * length prefix is what makes it reversible: a name may contain any character, the dot included, so no
- * separator character could ever be unambiguous on its own. Reading the digits
- * up to the first dot tells the parser exactly where the namespace ends.
- */
-export declare function encodeDueName(ref: SegmentRef): string;
-/**
- * Can this ref be indexed at all? False when the encoded name would exceed the 256-character name cap —
- * possible only for a ref whose namespace and segment are together near the limit.
- *
- * **Not indexable is not "not retired".** The repair scan still sees the segment's own row, so the consequence
- * is that it expires on the repair cadence instead of the fast one. Callers must not treat `false` as an error.
- */
-export declare function canIndex(ref: SegmentRef): boolean;
-/** The registry ref of the pointer for `ref` in `bucket`. Throws if the ref cannot be encoded — check first. */
-export declare function dueIndexRef(bucket: number, ref: SegmentRef): SegmentRef;
-/**
- * Recover the original ref from an index row's name. `null` for anything we did not write — a foreign row in
- * the reserved namespace is ignored rather than acted upon.
- */
-export declare function decodeDueName(name: string): SegmentRef | null;
-/**
- * Which buckets a cycle must read at `now`: everything from `since` up to and including the current one.
- *
- * Past buckets are included because a sweep that did not run — a scaled-to-zero worker, a failed deploy, a
- * paused schedule — must not leave its buckets stranded. `lookbackBuckets` bounds how far back a first run
- * reaches, so a long outage costs a bounded number of list calls per cycle rather than one per day since the
- * epoch; anything older is the repair scan's job.
- */
-export declare function dueBucketsAt(now: number, lookbackBuckets: number): number[];

package/dist/core/generation-gc.d.ts

@@ -1,293 +0,0 @@
-import { NotFoundError } from './errors.js';
-import type { GenKey, IStorageDriver, IRegistryDriver, KnownGeneration, RegistryRecord, SegmentRef, Token } from './ports.js';
-/** The two ports generation bookkeeping needs: the objects, and the pointer that says which one is current. */
-interface GenerationDeps {
-    readonly storage: IStorageDriver;
-    readonly registry: IRegistryDriver;
-    /** What a delete loop waits on before it reads the row again ({@link watchDeletes}). Absent, it does not wait. */
-    readonly clock?: {
-        readonly sleep?: (ms: number) => Promise<void>;
-    };
-}
-/**
- * The waits, in milliseconds, before each further read of the row when a delete loop finds the pointer on a generation
- * it deleted, with no object under it ({@link watchDeletes}). A rollback that moved the pointer there checks the bucket
- * after its move, and when the check runs after the delete it finds the object gone and puts the pointer back: one
- * listing of the segment's objects (one page while the segment holds under a thousand) and one compare-and-swap, two
- * round trips, three when a lease write lands first. A rollback client farther from the store than the deleting
- * client takes that much longer, so the loop reads the row once at once and, with a clock that can wait, three more
- * times over 1.75 s in all, which covers clients a few hundred milliseconds away. Paid only when a read finds the
- * pointer on a missing generation the loop deleted, never on a pass where nothing raced.
- */
-export declare const DELETE_SETTLE_WAITS_MS: readonly number[];
-/** What a delete loop has deleted, held to every read of the segment's row it makes after a delete. */
-interface DeleteWatch {
-    /** Note a delete that landed. */
-    deleted(generation: number): void;
-    /** Every generation noted so far. */
-    readonly gone: ReadonlySet<number>;
-    /**
-     * `row`, a read of the row made after `held`, the row a delete was decided on, held to what was deleted: the deleted
-     * generation it leaves the pointer on, with no object under it once the row is read again, or `undefined`.
-     */
-    check(held: RegistryRecord, row: RegistryRecord | null): Promise<number | undefined>;
-    /** The same for one more read of the row, made only when a delete landed since the last {@link check}. */
-    settle(held: RegistryRecord): Promise<number | undefined>;
-}
-/**
- * Hold a delete loop's reads of the row to what it deleted.
- *
- * Every loop that deletes generations reads the row before each delete, and one round trip remains between that read
- * and the delete. A rollback that lands inside it onto the generation being deleted passes its own check (a listing made
- * before the delete) and leaves the pointer on an object that is gone. Nothing can put the object back, so the loop
- * detects it instead: every read of the row it makes after a delete, and one more after its last delete when it made no
- * read since, is held to what it deleted.
- *
- * A read names a deleted generation when its row is active, of the incarnation `held` was read from, and its pointer
- * names one. A tombstone never does, since no rollback moves a `destroyed` row's pointer, and neither does a row purged
- * and made again, whose numbers are its own. Then:
- *
- *  - The bucket is asked, with one zero-byte read, a metadata request on every shipped driver. A number can be taken
- *    again once its object is deleted (invariant 2): after a rollback below it, a load can number it afresh and
- *    publish, and then the object there is that load's, and nothing is missing. Where the storage driver ignores a
- *    delete's condition, the loop's own delete can take that object too, and the read finds it missing, which it is.
- *  - A missing object is not yet the answer. A rollback whose own check ran after the delete finds the object gone and
- *    puts the pointer back, and the loop's read can fall between its move and that undo. So the row is read again, at
- *    once and, with a clock that can wait, after each of {@link DELETE_SETTLE_WAITS_MS}, each read judged as the first
- *    was, the bucket asked again; the answer is the generation the last of them names, only if every one names a
- *    deleted generation with no object under it.
- *
- * A read of the bucket that fails in any other way than "not found" throws: it says nothing about the object.
- */
-export declare function watchDeletes(deps: GenerationDeps, ref: SegmentRef): DeleteWatch;
-/** Who deleted the generation a {@link pointerOnDeletedError} names, which leads its message. */
-type Deleter = {
-    readonly kind: 'collection';
-} | {
-    readonly kind: 'erasure';
-} | {
-    readonly kind: 'load';
-    readonly published: number;
-} | {
-    readonly kind: 'refused-load';
-    readonly refusal: string;
-};
-/**
- * The error for a pointer a delete loop found on a generation it deleted ({@link watchDeletes}). The writer that moved
- * the pointer there is a rollback, or, where the storage driver ignores a delete's condition, a load that took the
- * number again and published. A rollback slower than the loop's further reads can still put the pointer back after
- * them, so the message says to look before acting.
- */
-export declare function pointerOnDeletedError(ref: SegmentRef, deleter: Deleter, generation: number): NotFoundError;
-/**
- * The generation number a writer should use for the segment's **next** object: one above the highest generation
- * the registry points at *or* that is present in Storage — whichever is higher. The erasure rewrite numbers this
- * way; a load numbers with {@link nextLoadGeneration}, which lists as this does when its existence check finds the
- * number taken or cannot answer.
- *
- * Both are consulted because they can disagree. A load that wrote its object and crashed before publishing leaves
- * an object *above* `currentGen`; a writer that consulted only the pointer would pick that same number and hit the
- * write-once conflict on every retry. Skipping past it costs one `list` and keeps the retry trivial — the crashed
- * object is an orphan {@link gcOrphanGenerations} collects once the pointer moves on. Reusing such an object
- * instead of skipping it (verify-and-publish) is `load()`'s job, not a numbering helper's.
- *
- * A segment with no row and no objects starts at 0. An admin/write-path helper, never on the read path.
- */
-export declare function nextGeneration(ref: SegmentRef, deps: GenerationDeps): Promise<number>;
-/** The number a load takes, and whether one existence check proved it free (so nothing is above the pointer). */
-interface LoadNumber {
-    readonly generation: number;
-    /**
-     * `true` when the number is `currentGen + 1` and the check found no object holding it. Collection by name rests
-     * on it: the row named `generation - 1` as current, so every number the window evicts is below it, and nothing
-     * the listing would have kept is a name the pass takes. `false` when the listing numbered the load.
-     */
-    readonly checked: boolean;
-    /** The generations that listing found, when the load listed: a seed of the ledger reads them instead of listing again. */
-    readonly listed?: readonly number[];
-}
-/**
- * The generation number a load takes, from the row it has already read: `currentGen + 1` (0 with no row or no
- * pointer yet) when no object holds that number, which one existence check proves (a zero-byte `getTail`, one
- * metadata request on every shipped driver); otherwise one above the pointer and above everything listed, as
- * {@link nextGeneration} numbers. The check finding the number taken (a crashed load's orphan, the object of a
- * load still in flight, or the generations a rollback left above the pointer) and the check failing in any way
- * other than "not found" both take the listing, so the listing stays the authority whenever the check cannot
- * prove the number free. A failed check falls back silently: nothing records it, and what it costs is the listing,
- * one more PUT-class request on S3, so a fault that makes every check fail shows only in the bill.
- *
- * A load can therefore take a number **below** an object already in the bucket: an orphan at `currentGen + 2`
- * with `currentGen + 1` free is numbered under, not past. That is as safe as a listing's number. A load never
- * takes a number an object holds, and a put that races onto one fails write-once, so the load reports
- * `superseded`. The orphan above stays unpublished; the load whose check meets it numbers past it by the listing,
- * and collection takes it once a generation above it is current. Like a listing's, the number can be one whose
- * object was deleted (an erasure removes the generations above a rolled-back pointer that held the id), which is
- * why nothing identifies a generation by its number alone: the reader cache and the chunk cache key on the number and
- * the row's `pointerId`, which every write that takes a number again renews, and an open of a row with a usable
- * summary holds the object to the fingerprint the summary records; a pin keys on its object's fingerprint.
- */
-export declare function nextLoadGeneration(ref: SegmentRef, deps: GenerationDeps, row: RegistryRecord | null): Promise<LoadNumber>;
-/**
- * How often a load that could collect by name lists instead: every generation divisible by this. A name-only pass
- * takes the names its publish pushed out of the row's window and never looks at the rest, so what it misses (a crashed
- * or refused load's object, a delete that failed, extras a fault left after a `keep` that shrank, an object a rollback
- * or an erasure left stranded below the pointer) waits for a listing. The number is a generation's, not a clock's, so the choice needs
- * no state and no time, and a segment that loads cleanly lists once in this many loads at most. The bound is in
- * generation numbers: a rollback moves the pointer down, and the loads that then take the numbers above it count
- * from there.
- */
-export declare const LIST_COLLECTION_CADENCE = 16;
-/**
- * Garbage-collect superseded Storage generations for a segment: everything strictly below `currentGen`, keeping
- * the most recent `keep` of them as a grace window, so a read still fetching from a just-superseded
- * generation need not re-resolve mid-call (**invariant 4**). It is a window, not a lock: a read whose
- * generation is swept anyway re-resolves and retries once rather than failing (see `withFreshSnapshot`), so
- * `keep` trades storage for round trips. Generations ≥ `currentGen` are never touched. Returns the generations
- * deleted.
- *
- * **Except on a `destroyed` segment, where EVERY generation is garbage** and the grace window is meaningless.
- * A tombstoned segment resolves no generation for any reader, pinned or not — a pin cannot be taken on one, and
- * a pin taken while it was still active re-checks the status on every open — and nothing else in the library
- * would ever collect them, so without this those objects are billed forever.
- *
- * **Throws {@link NotFoundError} when a rollback moved the pointer onto a generation it deleted**: the rollback landed
- * between the pass's re-proof of the row and that delete, so the pointer names an object that is gone. The pass finds
- * it at its next re-proof, or, after its last delete, by reading the row once more. A deleted object cannot be
- * restored: the answer is a rollback to a generation still in the bucket.
- *
- * **Throws {@link WriteConflictError} when it cannot act on the row it read**: the row is gone when it is re-read,
- * after the listing or before a delete; on an active segment, the pointer has fallen below the cutoff before a
- * delete; on a `destroyed` segment, the row's token has changed. Not to be confused with the empty array it still
- * returns when there was genuinely nothing to collect (no row at all, or no pointer yet), which is why an empty
- * array is not a receipt. The row is read before the listing and acted on after it, so a name that was purged and
- * re-created in that window is a *different* segment wearing the same name, and its live object must not be
- * collected on the strength of the old row: on an active segment the lower of the two pointers is what keeps it
- * safe, and on a `destroyed` one the token. Refusing is safe — the objects are not going anywhere and the next
- * pass reads a consistent row — but it has to be **distinguishable** from "there was nothing to collect", which
- * an empty array is not: `eraseIdFromSegment` reads the returned list as the physical half of its erasure
- * receipt, and would otherwise report `erased: true` over bytes still in the bucket. Re-run it.
- *
- * That state is reachable in practice: a `dropSegment` whose Storage sweep threw part-way, or a load that had read
- * the row before the tombstone landed, wrote its object afterwards, and stopped before its refusal deleted it. `dropSegment` re-sweeps
- * and reports whatever it could not reclaim in `generationsRemaining`, but a drop that was never re-run leaves a
- * residual, and this is what eventually collects it from the retention sweep.
- *
- * `keep: 0` is how a subject-erasure rewrite makes a bit **physically** gone on return: the generation that held
- * it is collected the moment the rewrite is current. A live read still fetching from it heals forward to the
- * rewrite, and a pin of it (`seg.pin()`) fails with `NotFoundError` for any chunk it has yet to read.
- */
-export declare function gcOrphanGenerations(ref: SegmentRef, deps: GenerationDeps, options?: {
-    keep?: number;
-}): Promise<number[]>;
-/**
- * {@link gcOrphanGenerations}, reporting a rollback onto a generation it deleted in `missing` instead of throwing it: the
- * pass stopped there. For a caller that records what it deleted before it raises, as an erasure does. With `skipKnown` the
- * pass also spares every generation the row names when it reads the row before a delete (an erasure's passes on an active
- * row, which remove from the row what they mean to delete first).
- */
-export declare function collectBelowPointer(ref: SegmentRef, deps: GenerationDeps, options?: {
-    keep?: number;
-    skipKnown?: boolean;
-}): Promise<{
-    readonly deleted: number[];
-    readonly missing?: number;
-    readonly knownSpared?: number[];
-}>;
-/**
- * What makes a collection spare leased generations: the clock that says whether a lease has ended. Only a load's
- * collection passes one, and a load with no clock passes none: it cannot tell a live lease from an ended one, so it
- * reads none. A pass without a guard never reads the row's leases, which is what keeps erasure, shred and drop deleting
- * what a lease names.
- */
-interface LeaseGuard {
-    readonly now: () => number;
-}
-/** What a load's publish recorded in the row, as `publishGeneration` reports it. */
-export interface PublishedKept {
-    /** The window the publish recorded, as numbers, or `undefined` when it recorded none (the row then does not know which are kept). */
-    readonly list: readonly number[] | undefined;
-    /** The ledger the publish wrote, in the order the generations were made current, when it wrote one. */
-    readonly known?: readonly KnownGeneration[];
-    /** The names the publish pushed out of the window, ascending. */
-    readonly evict: readonly number[];
-    /** The token of the row the publish wrote, when it is known: a write settled by reading the row has none. */
-    readonly token: Token | undefined;
-}
-/**
- * Collect after a load's publish. The row's ledger records the generations the load keeps, so the pass deletes by name
- * what the publish pushed out of that window ({@link deleteEvicted}) and lists the segment ({@link gcOrphanGenerations}'s
- * pass) only when it cannot rely on the row or must catch what a name does not:
- *
- *  - the publish recorded no window to collect by name (a `keep` above {@link MAX_KEPT_GENERATIONS}, a publish that
- *    seeded its ledger from the bucket, a row with no usable ledger, or a publish whose write was settled by reading the
- *    row): the pass keeps `keep` of the generations present below the pointer, the ledger's own most recently current
- *    names first and then the newest others by number, or, over a row with no usable ledger, `previous` first and then
- *    the newest by number ({@link keptWindow}), and writes nothing: the publish already wrote the ledger, which is what
- *    the next load derives its window from. It spares every name the row knows when it re-reads the row before a
- *    delete, which a publish or a rollback that landed since can have added to;
- *  - the guard found the current generation's object gone, or, for a `keep` of 1 or more when the guard took the size
- *    from the row's summary and opened nothing, one zero-byte read of it does not find it (`proveCurrent`): the
- *    window then counts a generation that is not there, so the same pass keeps what is;
- *  - a number the listing chose (something sits above the pointer, or the existence check could not answer), a
- *    caller that asks for a listing, and every {@link LIST_COLLECTION_CADENCE}th generation: the pass deletes every
- *    generation below the pointer the row does not name, which collects what a name-only pass leaves.
- *
- * It makes no request when `keep` is at least the generation published, since no more generations than that exist
- * below it. A load onto a `destroyed` row is refused at its publish and never reaches here; a drop that lands after
- * the publish leaves this pass collecting the tombstone's generations, and the drop's own sweep takes the rest.
- *
- * Any fault of the collection is raised, as every fault of a collection after a landed publish is.
- *
- * So is a rollback onto a generation the pass deleted, which the pass finds by holding every read of the row it makes
- * after a delete to what it deleted, and by reading the row once more after its last delete
- * ({@link watchDeletes}): it throws {@link NotFoundError}, saying the load took effect at `generation` and the
- * generation the pointer names is missing. That read is the one request this adds to a load whose pass deleted
- * anything.
- */
-export declare function collectAfterLoad(ref: SegmentRef, deps: GenerationDeps, options: {
-    generation: number;
-    keep: number;
-    /** The load's number was proved free by one existence check, and no caller asked for a listing. */
-    byName: boolean;
-    /** The guard opened the current generation's object and found it gone. */
-    currentGone?: boolean;
-    kept: PublishedKept | undefined;
-    /**
-     * The object the load's row named as current, which the caller did not open. Before it collects by name, the pass
-     * looks for this object with one zero-byte read, and lists instead unless that finds it: a name-only pass is
-     * safe only while the object the row named is in the bucket.
-     */
-    proveCurrent?: GenKey;
-    /** Spare the generations the row's live leases hold. Absent, the pass ignores leases. */
-    leases?: LeaseGuard;
-    /**
-     * The generation the row named as current when the load read it, which its publish superseded. A window kept by
-     * listing holds it first, while the pointer is still the load's. Absent: the load found no pointer.
-     */
-    previous?: number;
-}): Promise<number[]>;
-/**
- * Delete, with no listing, the generations a publish of `generation` pushed out of its row's window, `evict`, taken
- * from the list the publish was written against. Returns the names asked for, whether or not an object was there: a
- * delete of an absent object succeeds on every backend and says nothing, so a generation a concurrent pass, an erasure
- * or a lifecycle rule had already taken is listed all the same. A list is not a receipt (invariant 4), and neither is
- * this.
- *
- * Each delete re-reads the row first (invariant 4) and stops the pass, deleting nothing more and raising nothing, unless
- * the row still has a pointer at or above `generation` (a rollback, or a name purged and re-created with fewer loads,
- * has moved it below: the publish already landed, nothing here protects it or needs the result), the name is below
- * that pointer, and the row's own list is usable and does not name it. The last condition is what keeps a late delete
- * from taking a generation that a later publish, after a rollback, put in the window. A pointer that has moved above
- * `generation` does not stop it: a publish landing in the meantime leaves routine collection working. A fault, a
- * registry read or a delete that throws, propagates, with the pointer at `generation`.
- *
- * A rollback onto a name it deleted is not a stop: every read of the row after a delete is held to what it deleted, and
- * so is one more read after its last delete when it made none since ({@link watchDeletes}). One that names a
- * deleted generation throws {@link NotFoundError}, saying the load took effect at `generation`.
- */
-export declare function deleteEvicted(ref: SegmentRef, deps: GenerationDeps, options: {
-    generation: number;
-    evict: readonly number[];
-    leases?: LeaseGuard;
-}): Promise<number[]>;
-export {};