@cloudbitmaps/core 0.8.2 → 0.10.0

package/dist/drivers/_shared/object-registry.d.ts

@@ -0,0 +1,84 @@
+import type { IRegistryDriver, NewRegistryRecord, RegCaps, RegistryPatch, RegistryRecord, SegmentRef, Token } from '../../core/ports.js';
+/** Defensive cap on a single registry object read from storage, before allocation (rows are tiny; ~1 KB). */
+export declare const MAX_ROW_BYTES: number;
+/**
+ * Raised by a store when the version it pinned for a read vanished before it could fetch the bytes —
+ * a concurrent writer overwrote or deleted the object in between.
+ *
+ * This is deliberately **neither** of the two things it superficially resembles. It is not absence: the row
+ * is very likely still live, just one version further on. And it is not a write conflict: the caller may be
+ * a read-only `get()`, which has nothing to conflict with. Both of those mistakes were made — one per cloud —
+ * before this type existed, which is exactly why the signal is now part of the port rather than left to each
+ * store's judgement. {@link ObjectStoreRegistry} answers it the only way that is correct for every caller:
+ * it reads again.
+ *
+ * Stores whose read is atomic (S3 serves bytes and `ETag` from one `GetObject`) can never raise it.
+ */
+export declare class ObjectVersionRaced extends Error {
+    constructor(objectKey: string);
+}
+/** One object as read, with the opaque version that fences a later conditional write. */
+export interface ObjectRow {
+    readonly bytes: Uint8Array;
+    /** The store's version fence — an S3/Azure ETag, a GCS generation. Opaque to this class. */
+    readonly version: string;
+}
+/**
+ * The three I/O calls an object store must provide to host a registry. Everything else — the OCC counter,
+ * tombstones, the delete retry, key parsing — is implemented once above.
+ */
+export interface ObjectRegistryStore {
+    /** A label for error messages, e.g. `GCS` or `Azure Blob`. */
+    readonly label: string;
+    /**
+     * Read one object, or `null` when it is absent.
+     *
+     * **`null` means the object does not exist** — nothing weaker. A store that reads in two round trips
+     * (metadata for the version fence, then the bytes pinned to it) can find that version already gone; it
+     * MUST report that with {@link ObjectVersionRaced} rather than `null` or {@link WriteConflictError}, and
+     * the caller re-reads. Retryable faults throw {@link TransientError}.
+     *
+     * `bytes` and `version` MUST describe the **same** observation of the object: `version` is the fence a
+     * later conditional write is conditioned on, so a pair drawn from two different versions would either
+     * fail a write that should have succeeded or, worse, pass one that should not.
+     */
+    read(key: string): Promise<ObjectRow | null>;
+    /**
+     * Write one object under a precondition: `'absent'` means create-only, a version means
+     * compare-and-swap against exactly that version. A lost race MUST throw {@link WriteConflictError}.
+     */
+    write(key: string, body: Uint8Array, expect: 'absent' | {
+        version: string;
+    }): Promise<void>;
+    /** Every object key under `prefix`, paginated internally. */
+    listKeys(prefix: string): AsyncIterable<string>;
+}
+export declare class ObjectStoreRegistry implements IRegistryDriver {
+    private readonly store;
+    private readonly prefix;
+    private readonly now;
+    constructor(store: ObjectRegistryStore, prefix: string | undefined, now: () => number);
+    capabilities(): RegCaps;
+    get(ref: SegmentRef): Promise<RegistryRecord | null>;
+    create(ref: SegmentRef, record: NewRegistryRecord): Promise<{
+        token: Token;
+    }>;
+    compareAndSwap(ref: SegmentRef, expected: Token, patch: RegistryPatch): Promise<{
+        token: Token;
+    }>;
+    list(namespace?: string): AsyncIterable<RegistryRecord>;
+    delete(ref: SegmentRef): Promise<void>;
+    /**
+     * Read + parse a registry object, returning its envelope and version fence, or null if absent.
+     *
+     * A store that pins a version to read consistently ({@link ObjectVersionRaced}) loses that pin whenever a
+     * concurrent writer lands mid-read. Re-reading is the whole answer — the next read simply observes the
+     * newer version — and it is bounded so a row under permanent write saturation fails typed instead of
+     * spinning. Only a store racing itself gets here; S3 never does.
+     */
+    private readRow;
+    /** {@link ObjectRegistryStore.read}, retrying the bounded number of times a mid-read overwrite allows. */
+    private readRaced;
+    /** Conditional write of an envelope. The store maps a lost precondition to {@link WriteConflictError}. */
+    private putRow;
+}

package/dist/drivers/_shared/registry.d.ts

@@ -0,0 +1,62 @@
+import type { NewRegistryRecord, RegistryPatch, RegistryRecord, SegmentRef, Token } from '../../core/ports.js';
+/** Validate the caller-settable fields at `create`. */
+export declare function validateNewRegistryRecord(rec: NewRegistryRecord): void;
+/** Validate the caller-settable fields in a `compareAndSwap` patch. */
+export declare function validateRegistryPatch(patch: RegistryPatch): void;
+/**
+ * The persisted envelope for a registry row: the record plus a tombstone flag. A **deleted** row keeps its
+ * record (with an advanced counter) rather than being removed, so the monotonic token survives a
+ * delete→recreate — ABA-safety. Shared by the persistent drivers (LocalFs file, S3 object).
+ *
+ * `schemaVersion` is a wire-only concern — it stamps the persisted bytes, not the in-memory domain object —
+ * so it lives on the serialize/parse boundary ({@link serializeRegistryEnvelope} /
+ * {@link parseRegistryEnvelope}), never on this interface.
+ */
+export interface RegistryEnvelope {
+    readonly deleted: boolean;
+    readonly record: RegistryRecord;
+}
+/**
+ * Current registry-row schema version — a pre-1.0 format-freeze prerequisite. Every persistent
+ * registry driver — every one of which persists the `{ deleted, record }` envelope — stamps its rows
+ * with this so a reader can fail-closed on a future, incompatible layout instead of misparsing it. Bump only
+ * on a backward-incompatible change. Policy: a **higher** stamp than this build knows → `UnsupportedError`
+ * (fail-closed); an **absent** stamp → legacy pre-freeze row, tolerated as v1.
+ */
+export declare const REGISTRY_SCHEMA_VERSION = 1;
+/**
+ * Validate a persisted registry row's `schemaVersion` (untrusted bytes, invariant 5): absent → legacy v1
+ * (tolerated); a malformed value → `IntegrityError`; a version newer than this build → `UnsupportedError`
+ * (fail-closed rather than misread a format we don't understand).
+ */
+export declare function assertRegistrySchemaVersion(raw: unknown, ctx: string): void;
+/** Serialize a registry envelope for persistence, stamping the current {@link REGISTRY_SCHEMA_VERSION}. */
+export declare function serializeRegistryEnvelope(env: RegistryEnvelope): string;
+/**
+ * The OCC counter encoded in a record's token. A published row always has a **canonical decimal** token
+ * (`String(counter)`), so anything else (`"1e3"`, `"0x10"`, `" 5 "`, `""`, a >2^53 value) is corruption /
+ * tampering — reject it (invariant 5) rather than let `Number()` coerce it and silently break monotonicity.
+ */
+export declare function registryCounterOf(record: RegistryRecord): number;
+/**
+ * Parse + structurally validate a persisted `{ deleted, record }` envelope from stored bytes. A published row
+ * is always whole (atomic write), so a parse failure or a missing/mistyped field means corruption/tampering —
+ * fail fast (invariant 5), never silently report "absent". `ctx` names the source (path/key) for the message.
+ */
+export declare function parseRegistryEnvelope(text: string, ctx: string): RegistryEnvelope;
+/** Build a full record from a {@link NewRegistryRecord} plus identity, audit timestamps, and an OCC token. */
+export declare function recordFromNew(ref: SegmentRef, rec: NewRegistryRecord, now: number, token: Token): RegistryRecord;
+/**
+ * Fail-fast structural check on a record read back from a persistent tier (untrusted bytes, invariant 5):
+ * a published row is always whole, so a missing/mistyped required field means corruption/tampering — reject
+ * it rather than silently report "absent". `token` is checked by the caller (its source differs per backend:
+ * an in-body field vs a derived OCC counter).
+ */
+export declare function assertStoredRecordShape(r: Record<string, unknown>, ctx: string): void;
+/**
+ * Apply a patch to an existing record, returning a new one with a fresh `updatedAt` + `token` (identity and
+ * `createdAt` are preserved). Optional fields use `'k' in patch` so a patch can *clear* them (set to
+ * `undefined`, e.g. dropping `keyId` on crypto-shred); required fields use `??` (they always have a value).
+ * Fields this build does not know (an older row's compaction bookkeeping) are not carried over.
+ */
+export declare function applyRegistryPatch(prev: RegistryRecord, patch: RegistryPatch, now: number, token: Token): RegistryRecord;

package/dist/drivers/backends.d.ts

@@ -0,0 +1,49 @@
+import { STORAGE_BACKEND } from '../core/ports.js';
+import type { StorageBackend } from '../core/ports.js';
+import { MemoryRegistryDriver, MemoryStorageDriver } from './memory.js';
+import { LocalFsStorageDriver } from './localfs/storage.js';
+import { LocalFsRegistryDriver } from './localfs/registry.js';
+export interface MemoryStorageOptions {
+    /** Injected clock for the registry's `createdAt`/`updatedAt`; defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+/**
+ * An in-process backend — nothing to install, nothing to clean up, and it disappears with the process.
+ *
+ * This is the one to reach for in tests and in the first five minutes. It is **not** a cache in front of
+ * anything: it is the whole store, held in RAM, so a restart is a data loss.
+ */
+export declare class MemoryStorage implements StorageBackend {
+    /** Cross-bundle brand, stamped non-enumerably in the constructor so a spread cannot carry it. */
+    readonly [STORAGE_BACKEND]: true;
+    readonly storage: MemoryStorageDriver;
+    readonly registry: MemoryRegistryDriver;
+    constructor(options?: MemoryStorageOptions);
+}
+export interface LocalFsStorageOptions {
+    /** Injected clock for the registry's `createdAt`/`updatedAt`; defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+/**
+ * A local-filesystem backend rooted at one directory: generations under `<root>/storage`, pointers under
+ * `<root>/registry`.
+ *
+ * The layout is stated here rather than by the caller, which is the point — the two halves used to be two
+ * paths a caller wrote out separately, and nothing stopped them naming different roots. It is also the layout
+ * the `export-segments` CLI expects, so a store built this way can be ejected without being told where to look.
+ *
+ * **It refuses a store written before the tier was renamed**, because the alternative is much worse than an
+ * error. Such a store keeps its generations in `<root>/cold`, where this class does not look, so the registry
+ * half resolves a pointer the storage half cannot satisfy — and the store reports
+ * `missing-storage-generation`, which is the signature of a **torn restore**. The runbook's remedies for that
+ * include rolling `currentGen` back, which is destructive and would be applied to a store that was never
+ * damaged. One `existsSync` at wiring time is a cheap price for not sending someone down that path.
+ */
+export declare class LocalFsStorage implements StorageBackend {
+    readonly root: string;
+    /** Cross-bundle brand, stamped non-enumerably in the constructor so a spread cannot carry it. */
+    readonly [STORAGE_BACKEND]: true;
+    readonly storage: LocalFsStorageDriver;
+    readonly registry: LocalFsRegistryDriver;
+    constructor(root: string, options?: LocalFsStorageOptions);
+}

package/dist/drivers/crypto.d.ts

@@ -0,0 +1,38 @@
+import type { Aead, AeadSealed, IKeystore, WrappedDek } from '../core/crypto.js';
+/** AES-256-GCM AEAD bound to one 32-byte key. A fresh CSPRNG 96-bit nonce per `seal`; `aad` is authenticated,
+ * never stored. Nonce-reuse safety: the random-96-bit birthday bound is ~q²/2⁹⁷, negligible below ~2³² seals
+ * under one key. A per-segment DEK is **reused across all generations** (every load and rewrite encrypts under it), so
+ * seal count is cumulative over the segment's life — a segment approaching ~2³² lifetime chunk-seals should be
+ * re-seeded (a fresh segment ⇒ fresh DEK). Far beyond any realistic workload; noted for completeness. */
+export declare class NodeAead implements Aead {
+    private readonly key;
+    constructor(key: Uint8Array);
+    seal(plaintext: Uint8Array, aad: Uint8Array): AeadSealed;
+    open(sealed: AeadSealed, aad: Uint8Array): Uint8Array;
+}
+/**
+ * Options for {@link InProcessKeystore}. `keys` maps a `keyId` → its 32-byte KEK; `activeKeyId` names the KEK
+ * new DEKs are wrapped under; an optional `recoveryKeyId` additionally wraps each new DEK under a second
+ * (e.g. offline) KEK, so losing the active KEK isn't fatal. Rotating the active KEK needs no data
+ * re-encryption: add the new KEK, point `activeKeyId` at it, keep the old one to unwrap existing segments.
+ */
+export interface InProcessKeystoreOptions {
+    readonly keys: Readonly<Record<string, Uint8Array>>;
+    readonly activeKeyId: string;
+    readonly recoveryKeyId?: string;
+}
+/**
+ * Dependency-free BYOK keystore: envelope-wraps a fresh random per-segment DEK under the active (and optional
+ * recovery) KEK using `node:crypto`. No external service. The raw DEK never leaves a returned {@link NodeAead}.
+ */
+export declare class InProcessKeystore implements IKeystore {
+    private readonly keys;
+    private readonly activeKeyId;
+    private readonly recoveryKeyId;
+    constructor(options: InProcessKeystoreOptions);
+    createDek(): Promise<{
+        wrapped: WrappedDek[];
+        aead: Aead;
+    }>;
+    openDek(wrapped: readonly WrappedDek[]): Promise<Aead>;
+}

package/dist/drivers/localfs/fs-util.d.ts

@@ -0,0 +1,20 @@
+/** True when `err` is a Node system error with the given `code` (e.g. `'ENOENT'`, `'EEXIST'`). */
+export declare const isCode: (err: unknown, code: string) => boolean;
+export declare const isFsTransient: (err: unknown) => boolean;
+/**
+ * Reclassify a transient filesystem fault as a retryable {@link TransientError} (so the retry decorator can
+ * ride it out); everything else — including the driver's own typed errors — propagates unchanged.
+ */
+export declare const mapFsError: (err: unknown) => unknown;
+/**
+ * `O_NOFOLLOW` where the platform supports it (absent on Windows → 0). OR it into an `open` flag set so a
+ * symlink **at the final path component** is refused rather than followed outside the storage root.
+ * Containment of symlinked *directory* components assumes the root itself is not attacker-writable.
+ */
+export declare const O_NOFOLLOW: number;
+/**
+ * Best-effort parent-directory fsync, so a just-published `rename`/`link` survives a crash. Without it the
+ * directory entry can still be in the page cache when power goes: the generation's bytes are durable and
+ * the name pointing at them is not, which is the one way a published generation can come back missing.
+ */
+export declare function fsyncDir(dir: string): Promise<void>;

package/dist/drivers/localfs/paths.d.ts

@@ -0,0 +1,33 @@
+import type { GenKey, SegmentRef } from '../../core/ports.js';
+/** Directory holding all of a namespace's segment objects. */
+export declare function segmentsDir(root: string, ref: SegmentRef): string;
+/** Absolute path of one `.crbm` generation object. */
+export declare function storageObjectPath(root: string, key: GenKey): string;
+/** Filename pattern for a segment's generations: `<segment>.<gen>.crbm`. */
+export declare function storageObjectFilename(segment: string, generation: number): string;
+/** Parse a generation number out of a `<segment>.<gen>.crbm` filename, or `null` if it doesn't match. */
+export declare function parseGeneration(segment: string, filename: string): number | null;
+/** Directory holding a namespace's registry rows (one file per segment). */
+export declare function registryDir(root: string, namespace: string | undefined): string;
+/** Absolute path of one segment's registry row file: `<ns>/registry/<segment>.reg`. */
+export declare function registryRowPath(root: string, ref: SegmentRef): string;
+/**
+ * Parse a segment name out of a `<segment>.reg` filename, or `null` if it doesn't match — including any
+ * file whose stem isn't a valid segment name. A strict parser means a stray or planted `.reg` file makes
+ * `list()` *skip* it, never abort the whole enumeration on a boundary throw.
+ */
+export declare function parseRegistryRow(filename: string): string | null;
+/**
+ * Parse a namespace out of a directory name under the storage root, or `null` if it was not written by us.
+ *
+ * The inverse of the `namespacePathPart(ns)` that {@link segmentsDir} and {@link registryDir}
+ * write. A fleet-wide scan enumerates these directories, so getting it wrong does not fail one segment — it
+ * aborts the whole enumeration, taking the consistency check, the retention sweep and subject erasure with it.
+ *
+ * Like {@link parseRegistryRow} this requires the encoding to **round-trip**, so a planted literal `tenant:acme`
+ * directory sitting next to the driver's own `tenant%3Aacme` is skipped rather than reported as a namespace
+ * whose rows then resolve to the other directory. `_default` maps back to "no namespace".
+ */
+export declare function parseNamespaceDir(entry: string): {
+    namespace: string | undefined;
+} | null;

package/dist/drivers/localfs/registry.d.ts

@@ -0,0 +1,28 @@
+import type { IRegistryDriver, NewRegistryRecord, RegCaps, RegistryPatch, RegistryRecord, SegmentRef, Token } from '../../core/ports.js';
+export interface LocalFsRegistryDriverOptions {
+    /** Injected clock for `createdAt`/`updatedAt`; defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+export declare class LocalFsRegistryDriver implements IRegistryDriver {
+    private readonly root;
+    /** Per-row promise chain — serializes read-modify-write so an in-process CAS never loses an update. */
+    private readonly chain;
+    private readonly now;
+    constructor(root: string, options?: LocalFsRegistryDriverOptions);
+    capabilities(): RegCaps;
+    get(ref: SegmentRef): Promise<RegistryRecord | null>;
+    create(ref: SegmentRef, record: NewRegistryRecord): Promise<{
+        token: Token;
+    }>;
+    compareAndSwap(ref: SegmentRef, expected: Token, patch: RegistryPatch): Promise<{
+        token: Token;
+    }>;
+    list(namespace?: string): AsyncIterable<RegistryRecord>;
+    delete(ref: SegmentRef): Promise<void>;
+    /** Namespaces to scan: just the one requested, or every namespace dir under the root. */
+    private namespaceDirs;
+    private readRow;
+    private writeRow;
+    /** Serialize callbacks for a row path so read-modify-write is atomic in-process. */
+    private withRowLock;
+}

package/dist/drivers/localfs/storage.d.ts

@@ -0,0 +1,19 @@
+import type { BlobSink } from '../../core/blob.js';
+import type { StorageCaps, GenKey, IStorageDriver, SegmentRef } from '../../core/ports.js';
+export declare class LocalFsStorageDriver implements IStorageDriver {
+    private readonly root;
+    constructor(root: string);
+    capabilities(): StorageCaps;
+    putImmutable(key: GenKey, write: (sink: BlobSink) => Promise<void>): Promise<{
+        size: number;
+        sha256: string;
+    }>;
+    getRange(key: GenKey, offset: number, length: number): Promise<Uint8Array>;
+    getTail(key: GenKey, maxBytes: number): Promise<{
+        bytes: Uint8Array;
+        size: number;
+    }>;
+    delete(key: GenKey): Promise<void>;
+    list(ref: SegmentRef): AsyncIterable<GenKey>;
+    private openRead;
+}

package/dist/drivers/memory.d.ts

@@ -0,0 +1,57 @@
+import type { BlobSink } from '../core/blob.js';
+import type { ChunkRef, StorageCaps, StorageChunkSource, GenKey, IStorageDriver, IRegistryDriver, NewRegistryRecord, RegCaps, RegistryPatch, RegistryRecord, SegmentRef, SegmentSize, Token } from '../core/ports.js';
+export declare class MemoryStorageChunkSource implements StorageChunkSource {
+    private readonly chunks;
+    getChunk(ref: ChunkRef): Promise<Uint8Array | null>;
+    listChunkKeys(ref: SegmentRef): Promise<number[]>;
+    sizeOf(ref: SegmentRef): Promise<SegmentSize | null>;
+    /** Test/seed helper — populate immutable Storage bytes for a chunk directly (bypassing the `.crbm` format). */
+    seed(ref: ChunkRef, bytes: Uint8Array): void;
+}
+export interface MemoryRegistryDriverOptions {
+    /** Injected clock for `createdAt`/`updatedAt`; defaults to `Date.now` (drivers may use ambient time). */
+    readonly now?: () => number;
+}
+/**
+ * In-memory {@link IRegistryDriver} — one record per segment under OCC. The token is a single global,
+ * monotonic, never-reused counter (so a record recreated after `delete` always gets a strictly-greater
+ * token → ABA-safe even though `delete` removes the row physically).
+ */
+export declare class MemoryRegistryDriver implements IRegistryDriver {
+    private readonly rows;
+    private readonly now;
+    private seq;
+    constructor(options?: MemoryRegistryDriverOptions);
+    private nextToken;
+    capabilities(): RegCaps;
+    get(ref: SegmentRef): Promise<RegistryRecord | null>;
+    create(ref: SegmentRef, record: NewRegistryRecord): Promise<{
+        token: Token;
+    }>;
+    compareAndSwap(ref: SegmentRef, expected: Token, patch: RegistryPatch): Promise<{
+        token: Token;
+    }>;
+    list(namespace?: string): AsyncIterable<RegistryRecord>;
+    delete(ref: SegmentRef): Promise<void>;
+}
+/**
+ * In-memory {@link IStorageDriver} — write-once immutable generation objects as opaque bytes. A "dumb byte
+ * mover" (understands neither roaring nor `.crbm`), so it's a faithful storage backend for tests and a zero-setup
+ * local storage tier. Mirrors the LocalFs/S3 contract (write-once, range/tail reads).
+ */
+export declare class MemoryStorageDriver implements IStorageDriver {
+    private readonly objects;
+    capabilities(): StorageCaps;
+    putImmutable(key: GenKey, write: (sink: BlobSink) => Promise<void>): Promise<{
+        size: number;
+        sha256: string;
+    }>;
+    getRange(key: GenKey, offset: number, length: number): Promise<Uint8Array>;
+    getTail(key: GenKey, maxBytes: number): Promise<{
+        bytes: Uint8Array;
+        size: number;
+    }>;
+    delete(key: GenKey): Promise<void>;
+    list(ref: SegmentRef): AsyncIterable<GenKey>;
+    private require;
+}

package/dist/drivers/retry/retrying-drivers.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Retry decorators.
+ *
+ * Transparent wrappers that add bounded, jittered retry of **transient** faults to any driver, using the one
+ * shared `core/retry` primitive — so every backend (S3, GCS, Azure Blob, LocalFS, …) inherits the same
+ * policy instead of each rolling its own. Pure composition over the port interfaces (no SDK, no I/O of their
+ * own); the wrapped driver is responsible for *classifying* its transient faults (raising {@link TransientError});
+ * these decorators decide *whether and when* to retry.
+ *
+ * **Streaming methods buffer**, deliberately: a partially-consumed async iterator cannot be resumed mid-stream
+ * (it would re-yield earlier items), so `RetryingStorageDriver.list` and `RetryingRegistryDriver.list` collect the
+ * whole enumeration inside `withRetry` and re-run it from the start on a fault. Both are discovery scans over a
+ * generation or namespace listing, where the result set is small and whole-scan retry is worth the memory.
+ *
+ * Point methods are retried in place, with nothing to buffer.
+ *
+ * What is **not** retried here: {@link WriteConflictError} (OCC — the publish loop owns that; a blind replay
+ * would re-apply against a stale token), and every deterministic error
+ * (`ValidationError`/`IntegrityError`/`NotFoundError`/…). Default classifier: {@link isTransientError}.
+ */
+import type { Clock, Rng } from '../../core/determinism.js';
+import type { RetryPolicy } from '../../core/retry.js';
+import type { ChunkRef, StorageCaps, StorageChunkSource, GenKey, IStorageDriver, IRegistryDriver, NewRegistryRecord, RegCaps, RegistryPatch, RegistryRecord, SegmentRef, SegmentSize, Token } from '../../core/ports.js';
+import type { BlobSink } from '../../core/blob.js';
+export interface RetryingOptions {
+    readonly clock: Clock;
+    readonly rng: Rng;
+    /** Defaults to {@link DEFAULT_RETRY_POLICY}. */
+    readonly policy?: RetryPolicy;
+    /** Override which errors are retryable. Default: {@link isTransientError} (any `TransientError`). */
+    readonly isRetryable?: (err: unknown) => boolean;
+    /** Observability hook fired before each backoff wait. */
+    readonly onRetry?: (info: {
+        attempt: number;
+        delayMs: number;
+        err: unknown;
+    }) => void;
+}
+/** Wrap a storage chunk source so its reads retry transient faults. */
+export declare class RetryingStorageChunkSource implements StorageChunkSource {
+    private readonly inner;
+    private readonly policy;
+    private readonly deps;
+    /** Present only when the inner source supports it — so capability detection stays honest. */
+    readonly sizeOf?: (ref: SegmentRef) => Promise<SegmentSize | null>;
+    readonly cardinalities?: (ref: SegmentRef) => Promise<ReadonlyMap<number, number> | null>;
+    readonly currentGeneration?: (ref: SegmentRef) => Promise<number | null>;
+    readonly invalidate?: (ref: SegmentRef) => void;
+    readonly exists?: (ref: SegmentRef) => Promise<boolean>;
+    readonly currentVersion?: (ref: SegmentRef) => Promise<string | null>;
+    constructor(inner: StorageChunkSource, opts: RetryingOptions);
+    getChunk(ref: ChunkRef): Promise<Uint8Array | null>;
+    listChunkKeys(ref: SegmentRef): Promise<number[]>;
+}
+/** Wrap a storage driver so its byte operations retry transient faults. */
+export declare class RetryingStorageDriver implements IStorageDriver {
+    private readonly inner;
+    private readonly policy;
+    private readonly deps;
+    constructor(inner: IStorageDriver, opts: RetryingOptions);
+    capabilities(): StorageCaps;
+    putImmutable(key: GenKey, write: (sink: BlobSink) => Promise<void>): Promise<{
+        size: number;
+        sha256: string;
+    }>;
+    getRange(key: GenKey, offset: number, length: number): Promise<Uint8Array>;
+    getTail(key: GenKey, maxBytes: number): Promise<{
+        bytes: Uint8Array;
+        size: number;
+    }>;
+    delete(key: GenKey): Promise<void>;
+    list(ref: SegmentRef): AsyncIterable<GenKey>;
+}
+/** Wrap a registry driver so its calls retry transient faults. CAS conflicts are not retried (caller-owned). */
+export declare class RetryingRegistryDriver implements IRegistryDriver {
+    private readonly inner;
+    private readonly policy;
+    private readonly deps;
+    constructor(inner: IRegistryDriver, opts: RetryingOptions);
+    capabilities(): RegCaps;
+    get(ref: SegmentRef): Promise<RegistryRecord | null>;
+    create(ref: SegmentRef, record: NewRegistryRecord): Promise<{
+        token: Token;
+    }>;
+    compareAndSwap(ref: SegmentRef, expected: Token, patch: RegistryPatch): Promise<{
+        token: Token;
+    }>;
+    list(namespace?: string): AsyncIterable<RegistryRecord>;
+    delete(ref: SegmentRef): Promise<void>;
+}

package/dist/export/index.d.ts

@@ -0,0 +1,92 @@
+import type { CodecInterface } from '../core/codec.js';
+import type { IRegistryDriver, SegmentRef } from '../core/ports.js';
+/** Output format for {@link runExport} / `CloudRoaring.exportSegments`. */
+export type ExportFormat = 'roaring' | 'ndjson';
+/** A writer for one segment's output — inject a filesystem file, an S3 upload, stdout, or a test buffer. */
+export interface ExportWriter {
+    /** Append bytes (called one or more times; for `ndjson`, batched line chunks; for `roaring`, once). */
+    write(bytes: Uint8Array): Promise<void> | void;
+    /** **Commit** the output — called once, only on success (all bytes written). Finalize/flush/rename here. */
+    close(): Promise<void> | void;
+    /**
+     * **Discard** a partial output — called instead of `close()` if a fault occurs mid-segment, so a truncated file
+     * never masquerades as complete (e.g. delete the temp file). Optional; sinks with nothing to undo can omit it.
+     */
+    abort?(): Promise<void> | void;
+}
+/** A destination the export writes each segment to. `ext` is `.roaring` or `.ndjson`. */
+export interface ExportSink {
+    open(ref: SegmentRef, ext: string): Promise<ExportWriter> | ExportWriter;
+}
+export interface ExportOptions {
+    /** Output format; defaults to `'roaring'`. */
+    readonly format?: ExportFormat;
+    /**
+     * Bitmap codec used to build the exported bitmap for the `'roaring'` format. Optional in the
+     * type so this stays call-compatible public API; a **flavor** package binds it (see `requireCodec`). Not needed
+     * for `'ndjson'`, which streams plain ids.
+     */
+    readonly codec?: CodecInterface;
+    /** Scope the export to one namespace; omit to export every registered segment. */
+    readonly namespace?: string;
+    /** `ndjson` flush threshold in ~bytes (ids are ASCII, so ≈ chars); defaults to 64 KiB. */
+    readonly ndjsonBatchBytes?: number;
+}
+/** Per-segment result recorded in the {@link ExportManifest}. */
+export interface ExportedSegment {
+    readonly segment: string;
+    readonly namespace?: string;
+    /** Ids written (the segment's effective cardinality at export time). */
+    readonly count: number;
+    /** Bytes written to the sink for this segment. */
+    readonly bytes: number;
+}
+/**
+ * A segment that could **not** be exported — recorded rather than aborting the whole run (fault isolation), so a
+ * single corrupt/undecryptable segment never blocks the rest of the dump.
+ */
+export interface ExportFailure {
+    readonly segment: string;
+    readonly namespace?: string;
+    /** Why it failed (an error message) — e.g. a corrupt storage object, or an encrypted segment with no keystore. */
+    readonly error: string;
+}
+/** What {@link runExport} produced — a self-describing summary the CLI persists as `manifest.json`. */
+export interface ExportManifest {
+    /** Schema version of this manifest shape (currently `1`) — insurance for evolving the format post-1.0. */
+    readonly version: number;
+    readonly format: ExportFormat;
+    readonly totalSegments: number;
+    readonly totalIds: number;
+    readonly segments: readonly ExportedSegment[];
+    /**
+     * Segments that could not be read (empty when everything succeeded). Its presence in the manifest is the point:
+     * "a manifest exists" ⇒ the run finished, **not** that every segment succeeded — always check this list.
+     */
+    readonly failed: readonly ExportFailure[];
+}
+/** The minimal read surface the export needs from a store — a `CloudRoaring` satisfies this structurally. */
+export interface SegmentReader {
+    segment(name: string, options?: {
+        namespace?: string;
+    }): {
+        iterate(): AsyncIterable<number>;
+    };
+}
+/**
+ * Export every registered segment's current generation through `sink`. Enumerates via `registry`, reads via
+ * `reader` (the store). Returns a manifest. `CloudRoaring.exportSegments` is the
+ * public entry — it calls this with its own store + registry (so enumeration and the read path provably share one
+ * registry).
+ *
+ * **Fault isolation:** a per-segment read/write fault aborts that segment's partial (so a truncated file never
+ * looks complete), records it in `failed`, and the run continues — one bad segment never blocks the rest. A
+ * `close()` fault is likewise recorded (never triggering `abort()` — they're mutually exclusive).
+ *
+ * Re-running overwrites the segments it re-exports but does **not** prune files for segments that have since
+ * disappeared — export to a fresh directory for a clean dump. For a *current* image, run against a
+ * freshly-constructed store: a store's storage source re-resolves each segment's generation on a short TTL (or pins
+ * it for its lifetime when built without a clock or registry), so a long-lived store may export a view one load
+ * behind.
+ */
+export declare function runExport(reader: SegmentReader, registry: IRegistryDriver, sink: ExportSink, options?: ExportOptions): Promise<ExportManifest>;