@cloudbitmaps/core 0.8.2 → 0.10.0

package/dist/core/errors.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Typed errors — callers learn *why* something failed, never by parsing strings. Retry is the driver
+ * decorators' job, not the engine's: a driver classifies its backend's failures into this vocabulary, and
+ * `withRetry` decides what is transient.
+ */
+/**
+ * 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; thrown by
+ * the persistent drivers (S3, GCS, Azure Blob, local filesystem) — the in-memory drivers return
+ * `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, an
+ * encrypted file before the crypto path exists) — 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 that is safe to retry — throttling, a 5xx, a dropped connection,
+ * a client-side request timeout. 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 the whole transient subtree (incl. {@link TimeoutError}) is classifiable cross-bundle. */
+    readonly [TRANSIENT_BRAND]: true;
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * A single attempt exceeded its time budget. Subclass of {@link TransientError} so the retry layer treats a
+ * timeout as retryable by default — a stalled request often succeeds on a fresh connection. Raised by a
+ * driver whose injected client reports a request timeout — setting one on your injected client is the
+ * recommended way to bound a hang.
+ */
+export declare class TimeoutError extends TransientError {
+}
+/** 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 (incl. {@link TimeoutError}). 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,52 @@
+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} if the segment changed underneath the pass** — 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. 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 reader pinned to it re-resolves on its next 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-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**: `nextGeneration` 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,102 @@
+/**
+ * `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. Done by hand they are `nextGeneration` + `bulkLoadCrbmGeneration` +
+ * `publishGeneration` + `gcOrphanGenerations`, and the step people leave out is the last one — so stores that
+ * compose it themselves accumulate superseded generations they keep paying for. Composing it here 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). Nothing else would ever reclaim it, so a refused load deletes its own object before returning.
+ */
+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). 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 buys nothing a pinned read would not do better.
+     */
+    readonly keep?: number;
+    readonly audit?: IAuditSink;
+}
+/** Why a load did not become current. */
+export type LoadRefusal = 'empty' | 'min-cardinality' | 'min-retained'
+/** Another writer published a higher generation first. The object was written, then removed. */
+ | 'superseded';
+export interface LoadResult {
+    /** The generation written. Present even when refused — it is what was deleted again. */
+    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;
+}

package/dist/core/metrics.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Metrics seam — an injected sink the engine pushes typed events to, exactly like the `Clock`/driver seams
+ * keep `core/` pure and storage-agnostic.
+ *
+ * Design: the library emits **neutral domain events** and stays vendor-agnostic — you (or a ~12-line
+ * adapter) map them to OpenTelemetry / Datadog / a log line. The default is a **no-op**, and emission is
+ * skipped entirely when no sink is wired (near-zero overhead, no telemetry dependency). Events carry **raw
+ * observations** (bytes, counts, ms); turning those into billable units / dollars is the cost model's job,
+ * which keeps rates pluggable.
+ *
+ * Two caveats for sink authors: `onEvent` runs **synchronously on the I/O path**, so keep it cheap and
+ * non-blocking (offload batching/network to your own async queue); and `segment`/`namespace` are
+ * caller-controlled strings that may be PII and are **unbounded-cardinality** — do not map them to
+ * per-series metric labels unless they're known low-cardinality and PII-free. See the getting-started
+ * "Observability" section.
+ */
+/** The segment operations that emit an `op` latency event (timed with the injected clock, at the facade). */
+export type MetricOpName = 'has' | 'count' | 'intersectInto' | 'unionInto' | 'andNotInto';
+/**
+ * One observability event. A discriminated union on `kind` — new variants can be added over time without
+ * breaking consumers (they switch on the kinds they care about). `namespace` is the segment's namespace
+ * (absent ⇒ the default namespace). Segment names are identifiers, never bitmap contents (threat model:
+ * never log PII / bitmap bits).
+ */
+export type MetricEvent = {
+    readonly kind: 'storage.get';
+    readonly namespace?: string;
+    readonly segment: string;
+    /** Bytes returned (0 if the chunk was absent — a GET still happened). */
+    readonly bytes: number;
+    /**
+     * Elapsed wall time of the read — includes any transient-retry backoff on the storage call. From the
+     * injected clock, clamped to ≥ 0 (0 under the no-wait test clock).
+     */
+    readonly ms: number;
+} | {
+    readonly kind: 'cache';
+    readonly hit: boolean;
+} | {
+    readonly kind: 'retry';
+    /** Infrastructure-fault backoff (throttling, 5xx, a dropped connection) — the one kind of retry the store does. */
+    readonly reason: 'transient';
+    /** 1-based number of the attempt about to be retried. */
+    readonly attempt: number;
+    readonly delayMs: number;
+} | {
+    readonly kind: 'intersect';
+    /**
+     * Which chunk-aligned combine this was. **Optional for backward compatibility** — absent means
+     * `'intersect'`, which is all this event reported before `union`/`andNot` existed.
+     *
+     * For `'union'` over its *include* operands alone, `skippedChunks` is 0 by construction — union reads
+     * every chunk of every operand, so there is nothing to prune. It can still be non-zero when a union
+     * carries `exclude` operands, because a suppression list may hold keys no include does and those are
+     * legitimately never fetched. So: 0 is the expected shape for a plain union, not a guarantee.
+     */
+    readonly op?: 'intersect' | 'union' | 'andNot';
+    /** Operand count, including any `exclude` (suppression) operands. */
+    readonly operands: number;
+    /**
+     * Distinct chunk **keys** selected to fetch — for `'intersect'`, those present in every operand.
+     *
+     * **Keys, not requests.** The actual storage GETs are roughly `fetchedChunks × operands`, plus one per
+     * `exclude` that holds a given key, which is why this number is smaller than what the per-op budget
+     * charges for the same call. The two are different units by design; if you are reconciling a bill, the
+     * budget's accounting is the one that models requests.
+     */
+    readonly fetchedChunks: number;
+    /**
+     * **Distinct** chunk-keys pruned — never fetched (the chunk-skipping saving). Counts distinct keys,
+     * not per-operand GETs, so it under-states the true GET saving when 3+ operands partially overlap.
+     */
+    readonly skippedChunks: number;
+} | {
+    readonly kind: 'op';
+    readonly name: MetricOpName;
+    readonly ms: number;
+};
+/**
+ * The sink you plug in. One method, synchronous, fire-and-forget. It must never throw back into the
+ * caller — `CloudRoaring` wraps a user sink with {@link safeMetrics} so a buggy sink can't break I/O.
+ */
+export interface IMetricsSink {
+    onEvent(event: MetricEvent): void;
+}
+/** The default sink: discards everything, zero overhead. Used whenever no sink is wired. */
+export declare const NOOP_METRICS: IMetricsSink;
+/**
+ * Wrap a sink so a throwing/buggy `onEvent` can never break the data path — observability is strictly
+ * best-effort. `CloudRoaring` applies this to the user-supplied sink at construction.
+ */
+export declare function safeMetrics(sink: IMetricsSink): IMetricsSink;
+/** Accumulated totals — the shape returned by {@link CountingMetricsSink.snapshot}. */
+export interface MetricsSnapshot {
+    readonly storage: {
+        readonly gets: number;
+        readonly bytes: number;
+        readonly totalMs: number;
+    };
+    readonly cache: {
+        readonly hits: number;
+        readonly misses: number;
+    };
+    readonly retries: {
+        readonly transient: number;
+    };
+    readonly intersect: {
+        readonly calls: number;
+        readonly fetchedChunks: number;
+        readonly skippedChunks: number;
+    };
+    readonly ops: Readonly<Record<MetricOpName, {
+        readonly count: number;
+        readonly totalMs: number;
+    }>>;
+}
+/**
+ * A ready-made sink that tallies events into a {@link MetricsSnapshot} — handy for tests, quick scripts,
+ * and as the grounded-request-cost source behind `costReport()`. `snapshot()` returns an independent copy;
+ * `reset()` zeroes the counters.
+ */
+export declare class CountingMetricsSink implements IMetricsSink {
+    private storage;
+    private cache;
+    private retries;
+    private intersect;
+    private ops;
+    private static zeroOps;
+    onEvent(event: MetricEvent): void;
+    snapshot(): MetricsSnapshot;
+    reset(): void;
+}

package/dist/core/name-codec.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Name → physical-key encoding. The library validates *length*, and encodes everything else.
+ *
+ * Lives in `core/` rather than beside the drivers because it is pure string logic — no I/O, no SDK, no
+ * `node:` builtin — and because `validate.ts` needs it to measure a name against the key budget. Core may
+ * not import a driver (invariant 7), and a driver may import core, so this is the only layer both can see.
+ *
+ * The old grammar was an allowlist — `[A-Za-z0-9._:-]`. Widening it one character at a time is what exposed the
+ * real problem: the colon had been missing from it by accident rather than by decision, and nothing in the
+ * process would have caught the next omission either. An allowlist rejects names for the storage layer's
+ * convenience, and the storage layer's convenience is the library's job, not the caller's. So a name is **any
+ * non-empty string**, and each physical boundary escapes what *it* cannot take literally.
+ *
+ * It also fixes a hazard the allowlist *permitted*: `con`, `nul` and `com1` are Windows device names that
+ * validated cleanly and failed only on a user's machine. A grammar can be both too narrow and too permissive
+ * at once, which is the argument against having one.
+ *
+ * Percent-encoding, because it is the one escape everybody already reads. `%` escapes itself as `%25` and is
+ * encoded **first**, which is what makes the transform injective: every `%` in an encoded string starts an
+ * escape, so decoding is unambiguous and two distinct names can never collide on one key.
+ *
+ * There are two alphabets, because the boundaries differ:
+ *
+ * - **Object keys** (S3, GCS, Azure Blob) take almost anything. They need `/` escaped so a name cannot
+ *   invent hierarchy or break a key parser that splits on it, `#` and `|` (see below), and control characters
+ *   because they are not legal in the XML an S3 LIST returns.
+ * - **Filesystem paths** need all of that plus `:` (an NTFS alternate-data-stream separator, where a write can
+ *   *succeed* while `readdir` never lists the result), plus three hazards that are about the component as a
+ *   whole rather than its characters — see {@link encodeNameForPath}.
+ *
+ * **`#` and `|` are escaped for compatibility, not for any backend still here.** They were reserved because
+ * the DynamoDB registry composed its partition key from `<namespace>#<segment>|…`, and that driver is gone.
+ * The escaping stays anyway: it is baked into every key already written, and un-reserving the two characters
+ * would change what `encodeNameForKey` emits for a name containing either — silently moving those segments
+ * to a key nothing looks up. A cheap two-character reservation is the right price for not migrating a
+ * bucket; the property test below pins it.
+ *
+ * **Every name that was legal before encodes to itself on the OBJECT-KEY alphabet** — so S3, GCS and Azure
+ * keys are byte-identical and there is nothing to migrate there. That is the property to preserve if this
+ * file is ever edited, and a property test asserts it over the whole old grammar.
+ *
+ * The **path** alphabet is not identical, and the difference is a breaking change for an existing LocalFs
+ * store. Two classes move: a Windows device-name stem (`con`, `nul`, `com1`, `con.backup`) and a trailing dot
+ * (`a.`). Both were legal before and are escaped now — deliberately, since both silently alias or fail on
+ * Windows — but a 0.9 store holding one will not find it after the upgrade, because the readers' round-trip
+ * guard skips a spelling the driver would never have written. See the upgrade note in `CHANGELOG.md`.
+ */
+/**
+ * Encode a name for use inside an **object key** (S3, GCS, Azure Blob).
+ *
+ * Leaves the historically-legal alphabet literal so existing keys do not move, and escapes everything else —
+ * including `/` (which would invent hierarchy and break a parser that splits on it), `#` and `|` (reserved by
+ * the former DynamoDB registry and kept reserved so existing keys stay valid), and control characters (not
+ * legal in S3's XML responses).
+ */
+export declare function encodeNameForKey(name: string): string;
+/** Inverse of {@link encodeNameForKey}. */
+export declare function decodeNameFromKey(encoded: string): string;
+/**
+ * Encode a name for use as a **filesystem path component**.
+ *
+ * Everything {@link encodeNameForKey} escapes, plus `:`, plus three hazards that are properties of the whole
+ * component rather than of any character in it. All three are silent corruption rather than errors, which is
+ * why they are handled here instead of being left to the OS:
+ *
+ * 1. **`.` and `..`** are traversal. `join(root, '..')` leaves the storage root.
+ * 2. **Windows reserved device names** — `CON`, `PRN`, `AUX`, `NUL`, `COM1`–`COM9`, `LPT1`–`LPT9`, case
+ *    insensitive and *with or without an extension*, so `con.0.crbm` is reserved too. Opening one addresses a
+ *    device rather than a file. Note the old grammar **permitted** these: `store.segment('con')` validated
+ *    cleanly and broke only on a user's Windows box.
+ * 3. **A trailing `.` or space**, which Windows silently strips — so `a.` and `a` would become the same
+ *    directory, quietly merging two segments.
+ *
+ * Each is fixed by escaping the one character that defuses it, which keeps the encoding injective: a name that
+ * needed defusing produces a `%XX` no other name produces.
+ */
+export declare function encodeNameForPath(name: string): string;
+/** Inverse of {@link encodeNameForPath}. */
+export declare function decodeNameFromPath(encoded: string): string;

package/dist/core/pinned-storage-source.d.ts

@@ -0,0 +1,69 @@
+/**
+ * A {@link StorageChunkSource} view that holds **one** segment at **one** generation, and passes everything else
+ * through to the live source.
+ *
+ * A pin exists so a long job describes a single instant. An ordinary handle re-resolves on `cache.genTtlMs`, so a
+ * publish part-way through an export, a send or a reconciliation means the second half of the job describes a
+ * different instant than the first — and nothing in the result says so.
+ *
+ * **A pin is a generation NUMBER, not a captured reader.** The number is immutable, so the reader behind it can
+ * live in the shared bounded LRU and be evicted freely: re-opening at the same number reproduces the same
+ * bytes. Holding the reader instead put every live pin outside the library's memory ceiling.
+ *
+ * **Other segments are not pinned, and that is the contract, not an omission.** `snap.intersect([other])` reads
+ * `snap` at its pinned generation and `other` at whatever is current. Pinning the whole query means pinning
+ * each segment. The alternative shapes are both worse: refusing the combine outright makes a pin useless to the
+ * export and reconciliation jobs it exists for, and silently pinning the operands would quietly change what
+ * `other` means to a caller who did not ask.
+ *
+ * What this must never do is the inverse — read a pinned handle's segment **live** because the call was made
+ * on some other handle. That is why the routing is by segment identity here rather than by which object the
+ * caller happened to start from.
+ */
+import type { ChunkRef, StorageChunkSource, SegmentRef, SegmentSize } from './ports.js';
+import type { CrbmStorageChunkSource } from './crbm-storage-source.js';
+/** What a pin holds for one segment: the generation, and the version identifying those exact bytes. */
+export interface PinnedAt {
+    readonly generation: number | null;
+    readonly version: string | null;
+}
+export declare class PinnedStorageChunkSource implements StorageChunkSource {
+    private readonly inner;
+    /**
+     * The pinned segments, keyed by {@link segmentKey}. A **set** rather than one entry because a combine may
+     * involve several pinned handles, and each must be read at its own pin — including when the call was made
+     * on a different handle. Reading a pinned handle live because the caller started elsewhere is the silent
+     * wrong answer this exists to prevent.
+     */
+    private readonly pins;
+    constructor(inner: CrbmStorageChunkSource, 
+    /**
+     * The pinned segments, keyed by {@link segmentKey}. A **set** rather than one entry because a combine may
+     * involve several pinned handles, and each must be read at its own pin — including when the call was made
+     * on a different handle. Reading a pinned handle live because the caller started elsewhere is the silent
+     * wrong answer this exists to prevent.
+     */
+    pins: ReadonlyMap<string, PinnedAt>);
+    /**
+     * The pin for this segment, or `undefined` if it is not pinned here.
+     *
+     * A pin whose `generation` is `null` is a segment that had none when it was pinned: that handle reads empty
+     * for its lifetime, which is exactly what an unpinned read of it does. That is **not** the same as "this
+     * source cannot pin" — a source that genuinely cannot is a capability gap and fails fast at `pin()`.
+     */
+    private pinFor;
+    getChunk(ref: ChunkRef): Promise<Uint8Array | null>;
+    listChunkKeys(ref: SegmentRef): Promise<number[]>;
+    sizeOf(ref: SegmentRef): Promise<SegmentSize | null>;
+    cardinalities(ref: SegmentRef): Promise<ReadonlyMap<number, number> | null>;
+    currentGeneration(ref: SegmentRef): Promise<number | null>;
+    /**
+     * A pinned segment reports the version captured when it was pinned, so its decoded chunks are cached under a
+     * key that cannot collide with the live generation's. That is what lets a pinned handle share the store's
+     * chunk cache safely; sharing it on a generation-only key was how a pinned read could resurrect an id that
+     * `eraseIdFromSegment` had reported physically gone.
+     */
+    currentVersion(ref: SegmentRef): Promise<string | null>;
+    exists(ref: SegmentRef): Promise<boolean>;
+    invalidate(ref: SegmentRef): void;
+}