@cloudbitmaps/core 0.9.0 → 0.11.0

package/dist/core/erasure.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Whole-segment erasure: crypto-shred (`destroySegment`, `eraseNamespace`) and disposal (`dropSegment`).
+ *
+ * GDPR "right to erasure" on immutable, backed-up storage: you can't delete a `.crbm` object from every
+ * backup, but you can **delete its key**. `destroySegment` drops the segment's wrapped DEK(s) from the registry
+ * (a CAS to a `destroyed` tombstone) — the encrypted Storage bytes are then permanently unreadable, everywhere,
+ * forever. **Immediate + irreversible**, so it's gated behind an explicit confirmation (name the exact
+ * segment/namespace). A `destroyed` segment reads as empty (its DEK is gone). Only works on an **encrypted**
+ * segment; a cleartext segment has no key to shred.
+ *
+ * The tombstone is also the fence every writer respects: a load refuses
+ * a `destroyed` row, so a load racing an erasure cannot resurrect the segment. A single id's erasure is a different
+ * operation — `eraseIdFromSegment` rewrites the generation without it.
+ */
+import { type IAuditSink } from './audit.js';
+import type { IStorageDriver, IRegistryDriver, SegmentRef } from './ports.js';
+export interface EraseDeps {
+    readonly registry: IRegistryDriver;
+}
+export interface DestroyResult {
+    readonly segment: string;
+    readonly namespace?: string;
+    /** True iff the segment is now a `destroyed` tombstone (incl. the idempotent already-destroyed case). */
+    readonly destroyed: boolean;
+    /**
+     * True iff **this call** performed a genuine crypto-shred — an encrypted segment whose wrapped DEK(s) were
+     * dropped, so its Storage bytes are now permanently unreadable. False for a cleartext tombstone (bytes remain
+     * readable), for the idempotent already-destroyed case, and for an absent segment. This is what the
+     * `segment.erase` audit event keys off — a cleartext "erase" is not an irreversible destruction.
+     */
+    readonly cryptoShredded: boolean;
+    /**
+     * Why this segment was not a fresh crypto-shred. `'absent'` (no registry row), `'already'` (already
+     * destroyed), `'cleartext'` (no DEK to shred) — and from `eraseNamespace` only, where per-segment faults are
+     * isolated so one failure cannot discard the ledger: `'contended'` (the row was rewritten during every CAS
+     * attempt) or `` `failed: <message>` `` (any other fault).
+     *
+     * The last two come with `destroyed: false` and mean **the segment still holds data**. A namespace erase
+     * returns them rather than throwing, so its entries have to be inspected — see {@link eraseNamespace}.
+     */
+    readonly reason?: string;
+}
+/**
+ * Crypto-shred one segment. **Irreversible.** `confirmSegment` must equal `ref.segment` (a guard against an
+ * accidental destroy — you must name the exact segment). A non-encrypted segment is rejected unless you opt in
+ * via `allowCleartext` (there's no key to shred; its Storage bytes stay readable — the tombstone only stops the
+ * segment resolving).
+ */
+export declare function destroySegment(ref: SegmentRef, deps: EraseDeps, options: {
+    confirmSegment: string;
+    allowCleartext?: boolean;
+    audit?: IAuditSink;
+}): Promise<DestroyResult>;
+/**
+ * Crypto-shred every segment in a namespace. **Irreversible.** `confirmNamespace` must equal `namespace`.
+ * Returns a per-segment result (skips cleartext segments unless `allowCleartext`).
+ *
+ * **Bounded.** It lists the whole namespace before it destroys anything, and holds the listing resident, so the
+ * listing is capped at `maxScanSegments` (default {@link DEFAULT_MAX_SCAN_SEGMENTS}, 250,000), the ceiling every
+ * other fleet scan keeps. A namespace over it throws `BudgetExceededError` **before any segment is destroyed**,
+ * never part-way through; raise `maxScanSegments` when the namespace really is that large and the memory is there.
+ * A `maxScanSegments` that is not a finite number >= 1 throws `ValidationError`, again before anything is destroyed.
+ */
+export declare function eraseNamespace(namespace: string, deps: EraseDeps, options: {
+    confirmNamespace: string;
+    allowCleartext?: boolean;
+    audit?: IAuditSink;
+    maxScanSegments?: number;
+}): Promise<{
+    destroyed: DestroyResult[];
+}>;
+/**
+ * Deps for {@link dropSegment}. Adds `storage`, because unlike a crypto-shred this one deletes the objects.
+ */
+export interface DropDeps extends EraseDeps {
+    readonly storage: IStorageDriver;
+}
+export interface DropResult {
+    readonly segment: string;
+    readonly namespace?: string;
+    /**
+     * **True iff this segment is now empty as a result of this call — or already was.** This is the field a
+     * retention job should branch on: `false` means the call found nothing to do and your ref is probably wrong.
+     */
+    readonly dropped: boolean;
+    /** Storage generations physically deleted, ascending. Empty on a dry run — see {@link DropResult.wouldDelete}. */
+    readonly generationsDeleted: readonly number[];
+    /**
+     * Generations still present in Storage when the sweep gave up, ascending. **Empty is the normal outcome** — a
+     * non-empty value means the storage was NOT fully reclaimed and the drop should be re-run.
+     *
+     * Without it, a drop would return `dropped: true` with a populated `generationsDeleted` and no `reason` even
+     * when an object holding the **complete set** had just been left in the bucket by a writer that was already
+     * mid-write when the tombstone landed (its publish is refused, but the object survives). For a cleartext
+     * segment those bytes are readable — and the collection only takes a destroyed segment's generations
+     * when something runs it. That result would look like a clean drop, and an operator would get no signal to
+     * re-run.
+     */
+    readonly generationsRemaining: readonly number[];
+    /**
+     * On a dry run, the generations that **would** be deleted. `undefined` on a real run.
+     *
+     * This exists because the confirmation guard the erasure calls use — naming the segment twice — protects a
+     * hand-typed literal and nothing else. In the loop this operation is actually *for*
+     * (`for (const day of expired) drop({segment: day}, {confirmSegment: day})`) the same variable appears twice
+     * and the guard is pure ceremony. A dry run is the guard that still works when a machine is calling.
+     *
+     * It is a **snapshot**: a later real run can see a different set.
+     */
+    readonly wouldDelete?: readonly number[];
+    /**
+     * On a dry run, whether the real drop would **also** crypto-shred (i.e. the segment is encrypted).
+     * `undefined` on a real run. This is the one fact in the preview that is irreversible *everywhere*, backups
+     * included — a dry run that did not surface it was previewing the recoverable half only.
+     */
+    readonly wouldCryptoShred?: boolean;
+    /**
+     * True iff the segment was encrypted and its wrapped DEK(s) were dropped as part of this call — so its bytes
+     * are unreadable *everywhere*, backups included, not merely deleted from the bucket. Deleting an object does
+     * not reach a noncurrent version, a replica, or a PITR snapshot; discarding the key does.
+     */
+    readonly cryptoShredded: boolean;
+    /**
+     * How the segment got to its current state. Absent on a fresh, ordinary drop (tombstone written, Storage swept).
+     *
+     * - `'already'` — it was already a tombstone. Idempotent; pairs with `dropped: true`. A re-drop is **not** a
+     *   no-op — it re-sweeps Storage, so it is how a residual in `generationsRemaining` is collected.
+     * - `'absent'` — **nothing existed.** No registry row and no Storage objects. Pairs with `dropped: false`, and it
+     *   is the one value worth alerting on: the usual cause is a mistyped name or an omitted `namespace`, both of
+     *   which address a *different* segment than you meant.
+     */
+    readonly reason?: string;
+}
+/**
+ * **Dispose of a segment: tombstone it, then delete its Storage objects.** Irreversible.
+ *
+ * WHY THIS EXISTS, given {@link destroySegment} already erases. Because `destroySegment` answers a *compliance*
+ * question and this one answers an *operational* question, and they are not the same:
+ *
+ * - `destroySegment` **crypto-shreds** — it discards the key so the bytes are unreadable everywhere including
+ *   immutable backups, which is the only erasure that survives WORM. But it **leaves the objects in the
+ *   bucket**, still billed, and it *requires* encryption because a cleartext segment has no key to discard.
+ * - `dropSegment` **removes the storage**. It works on a cleartext segment, and on an encrypted one it *also*
+ *   drops the DEKs, so it is a strict superset there.
+ *
+ * It is the supported way to delete a segment and stop paying for it. The obvious workaround — an object-store
+ * lifecycle rule on the key prefix — deletes the bytes while the registry still points at them. That is exactly the `missing-storage-generation` state the DR runbook says not to serve traffic
+ * on, and it surfaces *intermittently*, because a read consults the cache before Storage: cached chunks answer
+ * correctly and evicted ones throw. The whole value of this function is that the ordering below cannot be got
+ * wrong by a caller.
+ *
+ * **THE ORDER IS THE CONTRACT — registry first, then Storage.**
+ *
+ * 1. **Registry first.** After the tombstone nothing resolves a generation for this segment, so no reader can
+ *    reach for bytes that are about to disappear, and no writer can publish onto it (a
+ *    load refuses a `destroyed` row).
+ * 2. **Storage second, best-effort, and re-swept.** Once the pointer is a tombstone the segment resolves as empty,
+ *    so a failure part-way through leaves **orphaned bytes, not a wrong answer.** Orphans cost money and are
+ *    cleaned up by re-running; a torn pointer costs correctness and is not self-healing. Given the choice, leak
+ *    bytes — but say so: whatever survives the sweep is reported in {@link DropResult.generationsRemaining}.
+ *
+ * **Why step 2 sweeps more than once.** A load that was already writing its object when the tombstone landed
+ * still finishes the write — its publish is then refused, but the object survives, and it holds the complete
+ * set. A single list-then-delete misses it entirely. The re-sweep converges because the tombstone *is* a hard
+ * fence on **publishing**, so only already-in-flight writes can appear and they are finite.
+ *
+ * **When "reads as empty" starts being true.** Not instantly, for a store that has already read this segment: a
+ * resolved generation is cached and decoded chunks sit in the cache, so an in-flight reader can answer from
+ * cache for a window. A fresh store, or any reader that had not touched the segment, sees empty at once.
+ *
+ * That window is bounded by `cache.genTtlMs` (default 2 s) **only for a reader whose storage source has both a clock
+ * and a registry and a positive TTL** — expiry needs all three. A source built without a clock or a registry, or
+ * with `cache.genTtlMs: 0`, has no timed refresh: it notices the drop only when a read has to fetch from a deleted
+ * generation or its reader cache evicts the segment. Because a cache-LRU hit never reaches Storage, such a reader
+ * can answer `true` for a dropped segment **indefinitely**, and must be invalidated or restarted. This is the *same* caching that makes the delete-bytes-first ordering fail intermittently rather
+ * than loudly — it cuts both ways.
+ *
+ * `confirmSegment` must equal `ref.segment`, matching `destroySegment`/`eraseNamespace`. For an automated
+ * caller that guard is ceremony — use `dryRun` first, which reports what would go without touching anything.
+ */
+export declare function dropSegment(ref: SegmentRef, deps: DropDeps, options: {
+    confirmSegment: string;
+    dryRun?: boolean;
+    audit?: IAuditSink;
+}): Promise<DropResult>;

package/dist/core/errors.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Typed errors — callers learn *why* something failed, never by parsing strings. Retry is not the engine's job: a
+ * driver classifies its backend's failures into this vocabulary, and the store's read wrapper retries the
+ * transient ones through `withRetry`.
+ */
+/**
+ * Registry-symbol brands, so an error stays classifiable when the class object is not shared.
+ *
+ * In an ordinary install there is ONE copy of these classes and `instanceof` holds everywhere — across the
+ * flavor, the driver packages and core itself — because every package leaves `@cloudbitmaps/*` external and
+ * resolves core at runtime rather than inlining it.
+ *
+ * What still breaks it is a SECOND copy: a version skew between our packages that the installer could not
+ * dedupe, or a bundler that emits core twice. Then a driver throws a class the catching side's `instanceof`
+ * does not match — and silently, because a `catch` that stops matching just falls through, defeating
+ * transient retry and the publish path's conflict handling with no error of its own.
+ *
+ * `Symbol.for` is identity-stable across copies, bundles and realms, so classify errors with the exported
+ * predicates below (never `instanceof`) anywhere an error may cross that boundary.
+ */
+declare const ERROR_BRAND: unique symbol;
+declare const TRANSIENT_BRAND: unique symbol;
+/** Base class for every error CloudRoaring throws. */
+export declare class CloudRoaringError extends Error {
+    /** Cross-bundle brand — see the predicates ({@link isCloudRoaringError}, …). Non-enumerable-ish (symbol key ⇒ not in JSON). */
+    readonly [ERROR_BRAND]: true;
+    constructor(message: string);
+}
+/** Invalid caller input (bad id, segment name, options). Raised before any storage call. */
+export declare class ValidationError extends CloudRoaringError {
+}
+/** An OCC conditional write/delete lost the race — the row changed since it was read. */
+export declare class WriteConflictError extends CloudRoaringError {
+}
+/** Bytes from a tier are corrupt, oversized, or fail a checksum/format check. */
+export declare class IntegrityError extends CloudRoaringError {
+}
+/**
+ * A requested object/row does not exist. Part of the driver error vocabulary: every storage driver this
+ * library ships, the in-memory one included, throws it for a read of a generation object that is not there.
+ * A registry `get` of a row that is not there returns `null` instead.
+ */
+export declare class NotFoundError extends CloudRoaringError {
+}
+/**
+ * This build/configuration cannot perform the requested operation, though nothing is malformed. Two uses:
+ * (1) **format** — the bytes are well-formed but unreadable here (an unknown `.crbm` major version) —
+ * distinct from `IntegrityError` (corruption); and (2)
+ * **store configuration** — an operation this store's wiring doesn't support (e.g. a lifecycle helper like
+ * `eraseSubject`/`retireExpired` called on a store built without a storage backend). Raised at
+ * operation time, before any mutation.
+ */
+export declare class UnsupportedError extends CloudRoaringError {
+}
+/**
+ * A driver cannot meet a capability the chosen topology requires (e.g. a Storage driver without range
+ * reads). Raised fail-fast at wiring time, never mid-operation.
+ */
+export declare class CapabilityError extends CloudRoaringError {
+}
+/**
+ * An operation would exceed its per-op **denial-of-wallet budget** — too many backend requests for a single
+ * `count`/`iterate`/`intersect`/`subjectReport`/`eraseSubject` call — so it is refused **before** fanning out
+ * (hard invariant 6). Default-on but generous (normal ops never hit it); tune it
+ * per store (`budget`) or per op, or disable with `budget: false`. Deterministic (never retried): the op is too
+ * big by policy, not by luck. Each request's bytes are separately capped (the safe-deserialize ceiling), so
+ * bounding the request count transitively bounds bytes. Carries the projected count + the limit, never data.
+ */
+export declare class BudgetExceededError extends CloudRoaringError {
+}
+/**
+ * An encrypted segment's data key (DEK) cannot be unwrapped because the keystore holds none of the
+ * key-encryption-keys (KEKs) its wrappings reference — the KEK was never configured, rotated away without
+ * keeping the old key, or lost. Deterministic (never retried): without a KEK the ciphertext is unreadable by
+ * design. The flip side of crypto-shred — when this is *intended* (a destroyed segment) the registry row is
+ * already a `destroyed` tombstone; when it's *not*, restore the missing KEK (or its recovery KEK). Carries no
+ * key material.
+ */
+export declare class KeyUnavailableError extends CloudRoaringError {
+}
+/**
+ * A **transient** infrastructure fault — throttling, a 5xx, a dropped connection, a client-side request
+ * timeout. Retrying a read that failed this way is safe; a write that failed this way may still have landed, so
+ * its caller re-runs the call rather than replaying the request. Drivers classify their backend's retryable faults and raise this (the
+ * SDK-specific knowledge stays in the SDK-specific driver); the retry layer (`core/retry`) retries **only**
+ * this class, never a deterministic error like {@link ValidationError}, {@link IntegrityError},
+ * {@link NotFoundError}, or {@link WriteConflictError} (retrying those is pointless or wrong). The original
+ * error is preserved in `cause` so callers can still inspect it.
+ *
+ * Note for logging hygiene: `cause` is the **raw SDK error**, which may carry operational
+ * metadata (endpoint host, request IDs, `$metadata`). The library's own `message` is identifier-only and safe
+ * to log; if you serialize the whole error *chain*, be aware you're including that metadata.
+ */
+export declare class TransientError extends CloudRoaringError {
+    /** A second brand so a transient fault is classifiable cross-bundle. */
+    readonly [TRANSIENT_BRAND]: true;
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Any error thrown by CloudRoaring (any tier, any bundle). */
+export declare function isCloudRoaringError(err: unknown): err is CloudRoaringError;
+/** An OCC conditional write/delete lost the race — retry the read-modify-write, don't fail. */
+export declare function isWriteConflictError(err: unknown): err is WriteConflictError;
+/** A retryable transient infrastructure fault. The retry layer keys on this. */
+export declare function isTransientError(err: unknown): err is TransientError;
+/** A requested object/row does not exist. */
+export declare function isNotFoundError(err: unknown): err is NotFoundError;
+/** Corrupt/oversized/failed-checksum bytes from a tier. */
+export declare function isIntegrityError(err: unknown): err is IntegrityError;
+/** Invalid caller input. */
+export declare function isValidationError(err: unknown): err is ValidationError;
+export {};

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

@@ -0,0 +1,56 @@
+import type { IStorageDriver, IRegistryDriver, SegmentRef } from './ports.js';
+/** The two ports generation bookkeeping needs: the objects, and the pointer that says which one is current. */
+export interface GenerationDeps {
+    readonly storage: IStorageDriver;
+    readonly registry: IRegistryDriver;
+}
+/**
+ * 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.
+ *
+ * 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>;
+/**
+ * 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 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 was
+ * already writing its object when the tombstone landed and finished the write afterwards. `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[]>;

package/dist/core/keys.d.ts

@@ -0,0 +1,23 @@
+import type { ChunkRef, SegmentRef } from './ports.js';
+export declare function segmentKey(ref: SegmentRef): string;
+export declare function segmentPrefix(ref: SegmentRef): string;
+export declare function chunkRefKey(ref: ChunkRef): string;
+/**
+ * Cache key for a chunk scoped to a specific **version** of the segment — {@link chunkRefKey} plus that
+ * version (space-delimited, injection-proof exactly as above — the name parts are already encoded). A publish bumps the version, so it naturally
+ * misses the cache instead of serving a stale superseded chunk, and the superseded entries age out under the
+ * LRU ceiling (no active purge needed).
+ *
+ * `version` is whatever the Storage source reports as identifying the bytes a read will see — its
+ * `currentVersion` where it has one, otherwise the bare generation number. **A generation number alone is not
+ * an identity**: a load's generation number restarts at 0 once a registry row is purged and the bucket emptied, so a
+ * retired-and-re-created name serves different data at the same `currentGen`, and a key built on the number
+ * hands the new incarnation the old one's decoded chunks.
+ */
+export declare function chunkGenKey(ref: ChunkRef, version: string | number): string;
+/**
+ * Deterministic FNV-1a shard assignment for a segment key — dependency-free, stable across workers and
+ * restarts. One definition, so every sharded fleet operation (today the retention sweep) agrees on it exactly:
+ * two definitions that disagreed would make the union across workers neither disjoint nor complete.
+ */
+export declare function shardOf(key: string, totalShards: number): number;

package/dist/core/load.d.ts

@@ -0,0 +1,121 @@
+/**
+ * `loadSegment` — the loaded store's primary write path, as one call.
+ *
+ * A load is always the same four steps: take the next generation number, write one immutable object, move the
+ * pointer, collect what the move superseded. Inside the library each is its own internal function, and the
+ * step a hand-composed load leaves out is the last one, so a store that composed it would accumulate superseded
+ * generations it keeps paying for.
+ * Composing it here, once, is the point.
+ *
+ * The other reason it is one call is the **guard**. A load REPLACES a segment: whatever the stream contains is
+ * what the segment contains afterwards. That makes an upstream query returning fewer rows than usual — or none —
+ * a silent, successful-looking wipe, and nothing downstream can tell it from a legitimate shrink. The guard is
+ * the place to say what a plausible result looks like, and it has to sit **between the write and the publish**,
+ * because that is the only moment where the new content is known and the old one is still authoritative.
+ *
+ * Refusing therefore has to clean up after itself. The object is already durable at that point, and it sits
+ * ABOVE `currentGen`, where generation collection deliberately never looks (it deletes strictly below the
+ * pointer), so a refused load deletes its own object before returning, while the segment's row is unchanged or
+ * gone. Once another write has changed the row, the object's number may name a re-created segment's live object,
+ * so it stays, and collection takes it like any other generation once one above it is current.
+ */
+import { type IAuditSink } from './audit.js';
+import { type CodecInterface } from './codec.js';
+import type { Clock } from './determinism.js';
+import type { IKeystore } from './crypto.js';
+import type { IStorageDriver, IRegistryDriver, SegmentRef } from './ports.js';
+/** What {@link loadSegment} needs: the objects, the pointer, the codec, and key material if encrypted. */
+export interface LoadDeps {
+    readonly storage: IStorageDriver;
+    readonly registry: IRegistryDriver;
+    readonly codec?: CodecInterface;
+    readonly keystore?: IKeystore;
+    readonly requireEncryption?: boolean;
+    readonly clock?: Clock;
+}
+/**
+ * What a plausible result looks like, so an implausible one is refused instead of published.
+ *
+ * Both bounds are compared against the **current** generation's cardinality, read from the `.crbm` index rather
+ * than its payload — one object-header read, and only when a bound is actually set.
+ */
+export interface LoadGuard {
+    /** Refuse a generation with fewer than this many ids. Use for "this segment is never legitimately tiny". */
+    readonly minCardinality?: number;
+    /**
+     * Refuse a generation that retains less than this fraction of the current one — `0.5` means "at least half the
+     * ids must survive". A *growing* load is never refused by this bound, and neither is the first load of a
+     * segment, which has nothing to shrink from.
+     *
+     * Phrased as a floor rather than a ceiling on the loss so that `0` means the same thing here as it does on
+     * `minCardinality` above: **no bound**. The inverse spelling (`maxShrink`) would make `0` mean "refuse any
+     * shrink at all" — maximally strict — sitting in the same object literal as a field where `0` is maximally
+     * permissive, which is where an inversion would eventually be written and not noticed.
+     */
+    readonly minRetained?: number;
+}
+export interface LoadOptions {
+    /**
+     * Publish an empty generation over a non-empty one. Off by default: an empty result is far more often an
+     * upstream failure than an intent, and the failure is indistinguishable from success once it lands.
+     */
+    readonly allowEmpty?: boolean;
+    readonly guard?: LoadGuard;
+    /**
+     * Generations to keep below the new pointer as a grace window (default 1). A non-negative integer: anything
+     * else (negative, fractional, `NaN`, infinite) throws `ValidationError` before anything is written. Keep at
+     * least one: a read that is
+     * still fetching chunks from the just-superseded generation would otherwise have it deleted out from under it
+     * and pay a re-resolve. A wider window costs storage, and it is what a pinned handle needs: a pin is never
+     * re-resolved, so a chunk a pinned read has not fetched fails with `NotFoundError` once its generation is
+     * collected. Keep at least one generation for every one that can be written above the pinned one while your
+     * longest pinned job runs, on every writer that loads the segment — see "Generations and `keep`" in the loading
+     * guide.
+     */
+    readonly keep?: number;
+    readonly audit?: IAuditSink;
+}
+/** Why a load did not become current. */
+export type LoadRefusal = 'empty' | 'min-cardinality' | 'min-retained'
+/**
+ * Another writer got there first. Either another load wrote the same generation number first, so the write-once
+ * put refused this one and it wrote nothing (`size: 0`); or the segment's registry row changed while the load was
+ * writing: another load published, a retention change, a rollback or an erasure wrote the row, or the row was
+ * deleted. Once another write has changed the row, the object stays in the bucket, because its generation number
+ * may by then name another incarnation's live object; once the row is gone, the object is deleted.
+ */
+ | 'superseded';
+export interface LoadResult {
+    /**
+     * The generation written. Present even when refused: a refusal deletes that object while the segment's row is
+     * unchanged or gone, and leaves it in the bucket once another write has changed the row. A load that lost its
+     * generation number to another wrote nothing, and reports `size: 0`.
+     */
+    readonly generation: number;
+    /** Whether this generation is now the segment's current one. */
+    readonly published: boolean;
+    /** Set only when `published` is false. */
+    readonly reason?: LoadRefusal;
+    readonly size: number;
+    readonly sha256: string;
+    readonly chunkCount: number;
+    /** Distinct ids in the generation that was written, post-dedup. */
+    readonly cardinality: number;
+    /**
+     * What the segment held when the guard judged it — `null` when there was no current generation, or when no
+     * bound needed it. Returned because an alert on `reason: 'min-retained'` is useless without it: "refused" is a
+     * page, "refused: 4 → 1" is a diagnosis, and re-reading the segment to find out costs a round trip and races
+     * whatever happens next.
+     */
+    readonly cardinalityBefore: number | null;
+    /** The superseded generations collected after publishing. Empty when nothing was published. */
+    readonly collected: readonly number[];
+}
+/**
+ * Replace a segment's contents with `ids`, as one immutable generation, and make it current.
+ *
+ * Returns what was written and whether it became current. A refusal is **not** an exception: `published: false`
+ * with a `reason` is a normal outcome a caller branches on, in the same shape as a successful load, because the
+ * interesting cases (a guard tripped, a racing writer won) are operational facts rather than faults.
+ */
+export declare function loadSegment(ref: SegmentRef, ids: Iterable<number> | AsyncIterable<number>, deps: LoadDeps, options?: LoadOptions): Promise<LoadResult>;

package/dist/core/lru.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Bounded LRU cache with optional TTL — the cache tier's memory ceiling.
+ *
+ * Time comes from an injected `Clock` (never `Date.now()`) so the cache is deterministic
+ * under simulation.
+ *
+ * The cache can be bounded by entry **count** (`maxEntries`, always) and, optionally, by an aggregate
+ * **byte weight** (`maxBytes`). The byte bound exists for values whose footprint is large and uneven — the
+ * storage reader cache, where one entry pins a fully-parsed `.crbm` index that can be ~6 MB for a wide segment
+ * yet a few hundred bytes for a small one (a count-only bound lets 1024 wide indices blow a Lambda's
+ * memory even though the count is "in bounds"). Weights arrive **after** insertion (a cached reader is a
+ * pending promise; its size is known only once it resolves), so weight is reported via {@link setWeight} and
+ * eviction re-runs then.
+ */
+import type { Clock } from './determinism.js';
+export interface LruOptions {
+    /** Hard ceiling on entries; the least-recently-used is evicted past it. */
+    readonly maxEntries: number;
+    /**
+     * Optional aggregate byte ceiling across all entries' reported weights (see {@link BoundedLru.setWeight}).
+     * When set, the least-recently-used entries are evicted until the total is within budget — in addition to
+     * the `maxEntries` bound. Omit for a pure count-bounded cache (weights stay 0, no byte eviction).
+     */
+    readonly maxBytes?: number;
+    /** Optional time-to-live in ms; an entry older than this is treated as absent. */
+    readonly ttlMs?: number;
+    /** Only `now()` is used (never `sleep`), so a count-only cache can pass a minimal time source. */
+    readonly clock: Pick<Clock, 'now'>;
+}
+export declare class BoundedLru<K, V> {
+    private readonly map;
+    private readonly maxEntries;
+    private readonly maxBytes;
+    private readonly ttlMs;
+    private readonly clock;
+    private totalBytes;
+    constructor(options: LruOptions);
+    get(key: K): V | undefined;
+    /** Read a value **without** counting as an access (recency unchanged, no purge on expiry). */
+    peek(key: K): V | undefined;
+    set(key: K, value: V): void;
+    /**
+     * Report an entry's byte weight (typically once a cached promise resolves and its size is known). Updates
+     * the running total and evicts the least-recently-used entries if the aggregate now exceeds `maxBytes`.
+     * Recency is **not** changed. The `key` being weighted is protected from this eviction pass (we just
+     * populated it) — so a single entry larger than the whole budget is kept rather than immediately dropped.
+     */
+    setWeight(key: K, bytes: number): void;
+    private evictToBudget;
+    /** The least-recently-used key that is not `protectKey`, or undefined if none other exists. */
+    private oldestExcept;
+    private dropKey;
+    private drop;
+    /** Membership test that does NOT count as an access (recency is unchanged). Purges if expired. */
+    has(key: K): boolean;
+    delete(key: K): boolean;
+    /**
+     * Delete every entry whose key matches `pred`, returning how many went. Used to drop one segment's decoded
+     * chunks when something destroys the generation they came from — a deletion the generation-keyed cache
+     * cannot express on its own, because a *destroyed* segment has no newer generation whose key would miss.
+     * Linear in the cache size; called on admin paths (erasure, drop, shred, retirement), never on a read.
+     */
+    deleteWhere(pred: (key: K) => boolean): number;
+    clear(): void;
+    /** Current entry count (may include not-yet-evicted expired entries). */
+    get size(): number;
+    /** Current aggregate reported weight (bytes) across all entries. */
+    get weightBytes(): number;
+}