@cloudbitmaps/core 0.21.0 → 0.23.0

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

@@ -1,11 +0,0 @@
-/**
- * The generations a segment's bucket holds.
- */
-import type { IStorageDriver, SegmentRef } from './ports.js';
-/**
- * The generations the bucket holds for `ref`, from one listing, each once and in ascending order. A listing that spans
- * a purge and a re-create can yield one number twice (the objects are re-created under the numbers just swept), so the
- * duplicates are dropped here rather than counted by each caller. A caller that stops at the first object it wants
- * reads the listing itself.
- */
-export declare function generationsOf(storage: IStorageDriver, ref: SegmentRef): Promise<number[]>;

package/dist/core/id-window.d.ts

@@ -1,46 +0,0 @@
-import type { CodecBitmap, CodecInterface } from './codec.js';
-/** A validated range: inclusive id bounds, as the chunk key and the remainder at each end. */
-export interface IdWindow {
-    readonly loKey: number;
-    readonly loRem: number;
-    readonly hiKey: number;
-    readonly hiRem: number;
-}
-/** A range as a read is asked for it: each bound optional. */
-interface IdBounds {
-    readonly after?: number | undefined;
-    readonly through?: number | undefined;
-}
-/**
- * Throws {@link ValidationError} unless `bound` is left out or is an id: an integer from 0 to 4294967295. The message
- * says what is wrong and never carries the value, which is an id.
- */
-export declare function assertIdBound(name: 'after' | 'through', bound: number | undefined): void;
-/**
- * Validate a read's range. `null` when none was asked for, so the read does no extra work; `'empty'` when no id can be
- * in it (`after >= through`, which is a cursor at the end of its window, not an error).
- */
-export declare function windowOf(range: IdBounds | undefined): IdWindow | 'empty' | null;
-/** The window a range with neither bound set describes: every id. */
-export declare const WHOLE_ID_SPACE: IdWindow;
-/**
- * Whether the window cuts inside `chunkKey`: one of its two edge chunks, and only where the bound falls inside the chunk
- * rather than on its boundary. A chunk the window covers whole is read as it is.
- */
-export declare const isEdge: (chunkKey: number, w: IdWindow) => boolean;
-/** The ids of an edge chunk that lie inside the window. The chunk iterates ascending, so it stops at the top. */
-export declare function edgeIds(chunk: CodecBitmap, chunkKey: number, w: IdWindow): Generator<number>;
-/** The ascending `keys` inside the window's chunk span, as a new array: two binary searches, no scan. */
-export declare function keysWithin(keys: readonly number[], w: IdWindow): number[];
-/**
- * The ascending `keys` inside the window's chunk span (every key, for `null`) and above the key `after`: what a read
- * that plans again after taking `after` still reads.
- */
-export declare function keysAbove(keys: readonly number[], w: IdWindow | null, after: number): number[];
-/** The index of the first element of ascending `a` greater than `value`: a binary search. */
-export declare function firstAbove(a: Uint32Array, value: number): number;
-/** The part of an edge chunk's ascending remainders `rem` inside the window, as a view of `rem`. */
-export declare function remaindersWithin(rem: Uint32Array, chunkKey: number, w: IdWindow): Uint32Array;
-/** An edge chunk cut to the window, as a new bitmap: the remainders {@link edgeIds} would yield. */
-export declare function cutToWindow(codec: CodecInterface, chunk: CodecBitmap, chunkKey: number, w: IdWindow): CodecBitmap;
-export {};

package/dist/core/invalidation-scope.d.ts

@@ -1,77 +0,0 @@
-/**
- * What the engines reading through one chunk cache share about invalidations: how many there have been, the segment
- * each of the latest was of, and the chunk reads open right now. A store's own engine, each pin's and each combine's
- * with a pinned operand read through one cache, and an invalidation through any of them must reach a read running on
- * another: a read that had its bytes before the invalidation would otherwise write them back into the cache it
- * shares, and later reads would be answered from them, an erased id included, until the cache evicted them.
- *
- * ```
- *  engine (store) ──┐
- *  engine (pin)   ──┼── one InvalidationScope ── epoch · latest invalidation of each segment · open reads
- *  engine (combine)─┘        └── one chunk cache
- * ```
- *
- * A stream records the epoch it opened at and asks {@link InvalidationRecord.invalidatedSince} before it caches a
- * chunk, so the scope holds no reference to a stream: a read its caller drops without closing holds nothing here. The
- * `.crbm` source keeps an {@link InvalidationRecord} of its own, by segment, which a pinned stream asks before it hands
- * out a chunk, so only its own segment's invalidation makes it open its object again.
- *
- * Internal to core: not exported from any entry point.
- */
-import type { CodecBitmap } from './codec.js';
-/**
- * How many segments' latest invalidation a record remembers. Past it the oldest is forgotten, and a segment the record
- * does not remember, never-invalidated ones included, counts as invalidated at the newest invalidation it has
- * forgotten, which is always on the safe side. In the engines' scope it means a stream that opened before then caches
- * no more of that segment's chunks, which costs it cache entries, never correctness: so a sweep that invalidates more
- * than this many segments at once (a `retireExpired` or an `eraseSubject` over a large fleet) stops every stream open
- * at the time caching, whatever segment it reads. In the `.crbm` source it means a pinned stream looks its pin up
- * again, which costs a request only where the reader cache has let the pin's reader go. With names at their
- * 256-character limit a record is about 0.6 MB, and about 0.1 MB with 30-character names; a store keeps two.
- */
-export declare const REMEMBERED_INVALIDATIONS = 1024;
-/** A chunk read in flight: `token` tells the read whether its entry is still the registered one. */
-export interface OpenRead {
-    readonly token: object;
-    readonly read: Promise<CodecBitmap | null>;
-}
-/**
- * How many invalidations there have been, and the epoch of each of the latest {@link REMEMBERED_INVALIDATIONS}
- * segments' latest one, by whatever key names a segment to its owner: a cache-key prefix in the engines' scope, a
- * segment key in the `.crbm` source.
- */
-export declare class InvalidationRecord {
-    private count;
-    /** The epoch of each remembered segment's latest invalidation, the oldest first. */
-    private readonly latest;
-    /** The epoch of the newest invalidation the record has forgotten: what a segment it does not remember counts as. */
-    private floor;
-    /** How many invalidations there have been: a read compares it with the epoch it began under. */
-    get epoch(): number;
-    /** Record an invalidation of the segment `key` names. */
-    invalidate(key: string): void;
-    /** Whether the segment `key` names has been invalidated since epoch `since`. */
-    invalidatedSince(key: string, since: number): boolean;
-}
-/** The engines' record, by cache-key prefix, and the chunk reads open on all of them. */
-export declare class InvalidationScope extends InvalidationRecord {
-    /**
-     * The chunk reads open right now, by cache key: a caller that misses the cache and finds its key here awaits that
-     * read instead of making its own. An entry lives from the request until it settles, so the map holds at most one
-     * promise per distinct key in flight. An invalidation drops the segment's entries, and a read whose entry is gone
-     * caches nothing.
-     */
-    private readonly openReads;
-    /** Record an invalidation of the segment whose cache keys start with `prefix`, and drop its open reads. */
-    invalidate(prefix: string): void;
-    /** The read of `key` open now, for a caller that misses the cache to await instead of making its own. */
-    openRead(key: string): Promise<CodecBitmap | null> | undefined;
-    /** Whether a read of `key` is open, without joining it. */
-    hasOpenRead(key: string): boolean;
-    /** Register `entry` as the open read of `key`. */
-    beginRead(key: string, entry: OpenRead): void;
-    /** `entry` has settled: forget it, unless an invalidation dropped it and a newer read has taken the key. */
-    endRead(key: string, entry: OpenRead): void;
-    /** Whether the read `token` names is still the open read of `key`: one an invalidation dropped caches nothing. */
-    isOpen(key: string, token: object): boolean;
-}

package/dist/core/item-pull.d.ts

@@ -1,29 +0,0 @@
-/**
- * Pulls the items of an async iterator one at a time so that the code relaying them never holds the one it just
- * handed on. A binding of a generator's body (`for await (const item of …)`, `yield*`) is kept in the generator's
- * frame across its next `yield`, so the relay would hold the previous item, and whatever buffer it is a view into,
- * for as long as it waits for the next. Here the item sits in the pull between {@link advance} and {@link take}, and
- * `take` clears it before it returns.
- *
- * ```ts
- * const pull = new ItemPull(source);
- * try {
- *   while (await pull.advance()) yield pull.take((item) => wrap(item));
- * } finally {
- *   await pull.close();
- * }
- * ```
- *
- * Internal to core: not exported from any entry point.
- */
-export declare class ItemPull<A> {
-    private readonly iterator;
-    private item;
-    constructor(source: AsyncIterable<A>);
-    /** Waits for the next item and keeps it inside; `false` once the source has ended. A failure of the source throws. */
-    advance(): Promise<boolean>;
-    /** Hands over the item {@link advance} fetched, through `map`, and forgets it. */
-    take<B>(map: (item: A) => B): B;
-    /** Ends the source early (a consumer that stopped), as leaving a `for await` does. */
-    close(): Promise<void>;
-}

package/dist/core/known-generations-shape.d.ts

@@ -1,13 +0,0 @@
-/**
- * The shape of a row's known-generations ledger (`knownGens`), in one place. A registry holds a row to it when it writes
- * and when it reads back, and `checkConsistency` holds a row to it before it reads or walks a ledger a registry of your
- * own handed back, so the two cannot part on what a ledger is. Pure: no I/O, time or randomness.
- */
-/**
- * Why `value` is not a ledger, or `undefined` when it is one (an absent ledger, `undefined`, passes: whether a row
- * without one is usable is another rule). A ledger is an array of at most `max` entries, each exactly `{ generation,
- * footerCrc }`, the generation a non-negative safe integer and unique, the checksum an integer from 0 to 2^32 - 1. The
- * order is not checked: it is not derivable from the numbers. `show` renders a value for the description, which a
- * caller can truncate.
- */
-export declare function knownGensShapeFault(value: unknown, max: number, show?: (v: unknown) => string): string | undefined;

package/dist/core/known-generations.d.ts

@@ -1,147 +0,0 @@
-import type { KnownGeneration, RegistryRecord } from './ports.js';
-/**
- * The most generations a load that collects by name records as its window. A `keep` above it collects by listing.
- */
-export declare const MAX_KEPT_GENERATIONS = 64;
-/**
- * A writer keeps entries that nothing protects and no lease holds only while the ledger holds fewer than this many.
- */
-export declare const KNOWN_FILL = 128;
-/** The most entries a writer writes, and the most the shared validator accepts at a write. */
-export declare const MAX_KNOWN_GENERATIONS = 192;
-/** The most entries a stored row may hold: twice what a writer writes. */
-export declare const MAX_STORED_KNOWN_GENERATIONS = 384;
-/**
- * The row's ledger when a collection or a rollback may rely on it: present and not empty, on an active row with a
- * pointer, its last entry the pointer, and, where the row's summary is in the clear and describes that generation, its
- * checksum the one the summary's fingerprint carries. A well-formed ledger that disagrees with its row is read but not
- * used (the row counts as one with no ledger), as a summary that names another generation is.
- */
-export declare function usableKnownGens(record: RegistryRecord | null): readonly KnownGeneration[] | undefined;
-/**
- * The generations the row keeps as its window: the numbers of the usable ledger's entries below the pointer, in the order
- * they were made current, or `undefined` when the ledger is not usable. A collection compares against these. An entry
- * numbered above the pointer is one a rollback left; no collection can take it, so it is no part of the window.
- */
-export declare function windowOf(record: RegistryRecord | null): readonly number[] | undefined;
-/**
- * Whether the row's ledger is a window a load with a small `keep` can extend: usable, and naming no more than
- * {@link MAX_KEPT_GENERATIONS} generations below the pointer that no live lease holds. A ledger carried through
- * publishes with a larger `keep` (`*Into`, `materializeMany`) names up to 127, and a count by a small `keep` would keep
- * fewer than it names, so the next small-`keep` load collects by listing instead of by name, over the same ledger. A
- * generation held only for a lease is no part of the window and does not count toward the limit.
- */
-export declare function carriesWindow(record: RegistryRecord | null, leased: ReadonlySet<number>): boolean;
-/**
- * How many generations below its own a publish vouches for at most: what the writer cap leaves beside the new
- * generation and the 64 generations live leases can hold.
- */
-export declare const KNOWN_SPAN = 127;
-/** Which generations below a new pointer a grace window holds, and which it lets go: both ascending. */
-interface KeptWindow {
-    readonly kept: number[];
-    readonly evict: number[];
-}
-/**
- * The generations below a new pointer that a grace window of `keep` holds, out of `below`, when no ledger says which
- * were made current most recently: the generation the publish superseded first, when it is among them, then the newest
- * of the rest by number. When it is not among them (no generation was current, or its object has gone from the bucket),
- * the newest `keep`.
- *
- * The superseded generation is the one reads were on until the publish, and, after a rollback, the one the operator
- * restored, which a pin taken since reads, and the one to roll back to if the new load is bad too. The generations a
- * rollback moved away from are newer by number, so a window by number alone would keep those and delete it. The window
- * a listing keeps over a row with no usable ledger comes from here, and so does a ledger's first window
- * (`ledger-seed.ts`); once the row has a ledger, its order says which were made current most recently.
- */
-export declare function keptWindow(below: readonly number[], superseded: number | undefined, keep: number): KeptWindow;
-/**
- * `known`, held to the cap, in the same order. It always keeps the entries numbered in `protect`, then the ones numbered
- * in `leased`, most recently current first, up to {@link MAX_KNOWN_GENERATIONS}, then the rest, most recently current
- * first, while the ledger holds fewer than {@link KNOWN_FILL}. So a protected or leased entry is never dropped for room,
- * and an unprotected one only when the ledger is full. "Most recently current" is the end of the list.
- */
-export declare function capKnown(known: readonly KnownGeneration[], protect: ReadonlySet<number>, leased?: ReadonlySet<number>): KnownGeneration[];
-/** `known` with `entry` made the most recent: any entry for its generation removed, and the entry added last. */
-export declare function makeCurrent(known: readonly KnownGeneration[], entry: KnownGeneration): KnownGeneration[];
-/** What a publish of a generation writes into the row, and which names it pushes out of the window. */
-export interface KnownAfter {
-    /** The ledger to write: the generation published is its last entry. */
-    readonly known: readonly KnownGeneration[];
-    /** The window as numbers to collect by name, or `undefined` to collect by listing. */
-    readonly list: readonly number[] | undefined;
-    /** The generations the window no longer keeps, ascending: the names to delete. */
-    readonly evict: readonly number[];
-}
-/**
- * What a publish of `generation` (its object's footer checksum `footerCrc`) over `prev` writes into the row.
- *
- * The ledger is in the order the generations were made current, so the order says which were current most recently.
- * That ranks the window, and the window is drawn from the entries numbered below the new generation only: collection
- * can only take generations numbered below the pointer. The window is the `keep` most recently current of them (at most
- * {@link KNOWN_SPAN}), so the generation the publish superseded, the ledger's last entry, comes first, and after a
- * rollback the ones the operator restored outrank the ones the rollback moved away from.
- *
- * What it writes, in the order the entries were made current and the new generation last:
- *
- *  - the window;
- *  - the entries below the new generation that `leased` names (a generation a live lease holds stays known, so it stays a
- *    rollback target while the lease lives), whatever `keep` says;
- *  - the entries numbered above the new generation, which a rollback left and a load numbered under: they are carried and
- *    never evicted, and take no slot of `keep`, while the ledger holds fewer than {@link KNOWN_FILL} entries (see
- *    {@link capKnown});
- *  - the new generation. An entry already numbered `generation` is a stale one (its object went outside the ledger) and
- *    is replaced.
- *
- * `evict` is the entries below the new generation that it leaves out, ascending: never a name at or above the new
- * generation. With a `keep` of at most {@link MAX_KEPT_GENERATIONS} the publish collects by name, so `list` is the
- * generations of the ledger below the new one; above that, or with no `keep`, `list` is `undefined` and `evict` empty, and
- * a load lists. A row with a pointer and no usable ledger writes the new generation alone and lists, unless the caller
- * passes a `seed` (see `ledger-seed.ts`): the window a count keeps, read from the bucket, then the new generation, and
- * the publish collects by that count. A publish that clears leases is an erasure's rewrite, which deletes every older
- * generation, so its ledger is the new generation alone.
- */
-export declare function nextKnown(prev: RegistryRecord | null, generation: number, footerCrc: number, keep: number | undefined, options?: {
-    readonly clearsLeases?: boolean;
-    readonly seed?: readonly KnownGeneration[];
-    readonly leased?: ReadonlySet<number>;
-}): KnownAfter;
-/**
- * The ledger a rollback onto `target` writes over `prev`: the ledger it found with the target moved to the end, as the
- * most recently current. A rollback never starts a ledger: over a row with no usable ledger it writes none, and the
- * next publish seeds one. A target the ledger did not name
- * is an insert, and the ledger it makes is held to the cap with the target and the generation the rollback leaves
- * protected; a known target's ledger is written as read, unless another build wrote one that is past the writer's cap.
- */
-export declare function rollbackKnown(prev: RegistryRecord, target: KnownGeneration): readonly KnownGeneration[] | undefined;
-/**
- * The row's ledger with the entries numbered in `doomed` removed, which a write that is about to delete those
- * generations makes first: the entries left keep their order, and the current generation is never removed (the ledger
- * must end with it). Another build's ledger past the writer's cap is held to it, with the current generation protected
- * and the generations the row's leases name kept. `undefined` for a row with no usable ledger, which names nothing to
- * remove.
- */
-export declare function pruneKnown(record: RegistryRecord, doomed: ReadonlySet<number>): readonly KnownGeneration[] | undefined;
-/**
- * The ledger that puts a row back as it was, for the undo of a rollback: the row's own when it is usable (the
- * generation it left is its last entry), held to the writer's cap when another build wrote one past it, with the
- * generation the undo leaves and the one it moves from protected; `undefined` for a row that had none to put back.
- */
-export declare function describingKnown(record: RegistryRecord, movedTo: number): readonly KnownGeneration[] | undefined;
-/**
- * Whether the ledger is full: it names at least {@link KNOWN_FILL} generations, which is when a writer may have let an
- * older one go (a publish vouches for at most {@link KNOWN_SPAN} below its own, and an inserting rollback drops an entry
- * once 128 that no lease holds are named). Leased entries do not switch it off: a lease on an entry inside the span
- * leaves the ledger as full as it was. Past the least recently current entry of a full ledger, a rollback can no longer
- * tell a generation the row forgot from one it never knew, so it judges a target numbered below that entry as it did
- * before the ledger existed.
- */
-export declare function isFullLedger(known: readonly KnownGeneration[]): boolean;
-/**
- * The number a target below the pointer is judged against on a full ledger: the least recently current entry that no
- * lease entry of the row names (live or ended: a rollback has no clock). A leased entry stays in the ledger for its lease,
- * however far the window has moved on since, so it does not mark where the ledger stopped remembering; the first entry no
- * lease holds does. A ledger whose every entry is leased is judged against its first entry.
- */
-export declare function fallbackBound(record: RegistryRecord, known: readonly KnownGeneration[]): number;
-export {};

package/dist/core/ledger-seed.d.ts

@@ -1,17 +0,0 @@
-import { type ReadRetry } from './retry.js';
-import type { IStorageDriver, KnownGeneration, RegistryRecord, SegmentRef } from './ports.js';
-/**
- * Whether a publish over `row` seeds its ledger: only at a birth, over an active row that has a pointer and no usable
- * ledger. A usable ledger is never seeded again, however wide it is.
- */
-export declare function wantsSeed(row: RegistryRecord | null): boolean;
-/**
- * The entries a seed names: the listed generations below the new one that a live lease holds and the window does not
- * keep, then the window oldest first by number with the generation the row named as current last. `listed` is the
- * listing the load's numbering made, when it made one; otherwise the bucket is listed once. Every entry's checksum is
- * read from its object's footer (a 104-byte read, under the store's read retry, {@link SEED_READS} at a time), the
- * superseded generation's too: when a clear summary describes it with another checksum, the row and the bucket
- * disagree about that number and it is left out. A generation gone from the bucket, or whose footer fails its own
- * checks, is left out; any other failed read throws, before anything is published.
- */
-export declare function readSeed(storage: IStorageDriver, ref: SegmentRef, row: RegistryRecord | null, generation: number, keep: number, listed: readonly number[] | undefined, leased: ReadonlySet<number>, readRetry?: ReadRetry): Promise<KnownGeneration[]>;

package/dist/core/metadata.d.ts

@@ -1,42 +0,0 @@
-/**
- * Generation metadata: a small, flat record of strings and finite numbers attached to one generation.
- *
- * The rules live here once, for every boundary that meets a value: a caller's input, refused with
- * `ValidationError`, and bytes read back from a tier, refused with `IntegrityError`. The caller passes the error
- * to raise. Pure: no I/O.
- */
-import type { GenerationMetadata } from './ports.js';
-/** Cap on the canonical JSON of one generation's metadata, in UTF-8 bytes (braces and quotes included). */
-export declare const MAX_METADATA_BYTES = 1024;
-/** Cap on one metadata key, in UTF-8 bytes. */
-export declare const MAX_METADATA_KEY_BYTES = 128;
-/**
- * Validate `value` as generation metadata (`GenerationMetadata` in the ports) and return its canonical JSON: RFC 8785
- * (the JSON Canonicalization Scheme) for a flat object of strings and finite numbers. Keys are sorted by UTF-16 code
- * unit, strings are escaped as `JSON.stringify` escapes them, numbers are written as ECMAScript's
- * `Number.prototype.toString` writes them (so `-0` is `0`, and `1e21` is `1e+21`), and there is no whitespace. Key
- * order therefore never changes the bytes, and `tests/golden/metadata-canonical.json` holds vectors a port can check
- * itself against. Both caps are in UTF-8 bytes. The container is an object whose prototype is
- * `Object.prototype` or `null`, holding only enumerable data properties with string keys. `fail` raises the error the
- * boundary calls for. The empty object passes and returns `{}`: whether it may be stored is the caller's rule.
- */
-export declare function canonicalMetadataJson(value: unknown, fail: (message: string) => never): string;
-/**
- * The bytes a generation stores for `value`: its canonical JSON in UTF-8, or `undefined` when it has none (`undefined`
- * or the empty object, which store nothing). Synchronous, so what is stored is what the caller passed at the call,
- * whatever it does with its object afterwards. `fail` raises the boundary's error.
- */
-export declare function metadataBytes(value: unknown, fail: (message: string) => never): Uint8Array | undefined;
-/**
- * A caller's metadata, checked against the rules and copied, so what is stored is what the caller passed at the call,
- * whatever it does with its object afterwards: the frozen record in canonical key order, or `undefined` when there is
- * none (`undefined`, or the empty object, which store nothing). Synchronous. `fail` raises the boundary's error.
- */
-export declare function copiedMetadata(value: unknown, fail: (message: string) => never): GenerationMetadata | undefined;
-/**
- * Read metadata back from bytes a tier holds, which are untrusted. They must be at most {@link MAX_METADATA_BYTES},
- * valid UTF-8, and exactly the canonical JSON of a non-empty record, so a stored copy has one spelling: whitespace, a
- * key out of order or listed twice, and a number or an escape `JSON.stringify` would write another way are all
- * refused. Returns a frozen record of its own. `fail` raises the boundary's error.
- */
-export declare function metadataFromBytes(bytes: Uint8Array, fail: (message: string) => never): GenerationMetadata;

package/dist/core/order.d.ts

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

package/dist/core/publish.d.ts

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

package/dist/core/reader-defaults.d.ts

@@ -1,29 +0,0 @@
-/**
- * The storage reader's defaults. `@cloudbitmaps/tools` prices what two of them cause and keeps its own copies, which
- * `tests/tools/store-defaults.test.ts` holds equal to these.
- */
-/** Default TTL (ms) for re-resolving a segment's `currentGen` — the bound on post-publish read staleness. */
-export declare const DEFAULT_CURRENT_GEN_TTL_MS = 2000;
-/**
- * How long (ms) a reader keeps serving after a pointer refresh failed transiently, before the next read asks the
- * registry again. Short, so an outage ends the stale serving soon after the registry answers; fixed, so a registry
- * that is down is asked at most once per this interval per segment being read (the refresh is coalesced per
- * segment). Never longer than the TTL itself.
- */
-export declare const REFRESH_RETRY_MS = 500;
-/** Default ceiling on cached segment readers (each holds a parsed `.crbm` index) — the steady-state count bound. */
-export declare const DEFAULT_MAX_OPEN_SEGMENTS = 1024;
-/** Default aggregate ceiling (bytes) on resident parsed indices in the reader cache — the steady-state byte bound. */
-export declare const DEFAULT_MAX_OPEN_INDEX_BYTES: number;
-/**
- * How many segments' resolutions a store keeps per reader it keeps open: the resolution cache's count bound is this
- * times `cache.readerMax` (8,192 by default). A resolution is the few hundred bytes of a row a read resolves through,
- * kept for `cache.genTtlMs` whether or not the segment's reader is still open, so a store reading more segments at once
- * than its readers hold keeps more of them than it keeps readers.
- */
-export declare const RESOLUTIONS_PER_OPEN_SEGMENT = 8;
-/**
- * The resolution cache's byte bound is `cache.readerMaxBytes` divided by this (4 MiB by default): what it holds is a
- * sixteenth of what the readers may.
- */
-export declare const RESOLUTION_BYTES_DIVISOR = 16;