@cloudbitmaps/core 0.10.0 → 0.11.0

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

@@ -0,0 +1,59 @@
+/**
+ * The store's read retry.
+ *
+ * {@link RetryingStorageChunkSource} wraps a {@link StorageChunkSource} so every read it serves retries
+ * **transient** faults with bounded, jittered backoff, through the one shared `core/retry` primitive, so every
+ * backend (S3, GCS, Azure Blob, LocalFS, …) inherits the same policy instead of each rolling its own. `CloudRoaring`
+ * wraps the source it reads segment data through in one — a `StorageChunkSource` passed as `storage` included, so
+ * wrapping that one first multiplies each read's attempts — and a pinned handle's source too, unless it is built
+ * with `retry: false`.
+ * Pure composition over the port (no SDK, no I/O of its own); the driver under the source is responsible for
+ * *classifying* its transient faults (raising {@link TransientError}), and this wrapper decides *whether and when*
+ * to retry.
+ *
+ * **Reads only, on purpose.** A read changes nothing, so running it again is safe. A write is not: a conditional put
+ * or compare-and-swap that lands and then loses its response would, replayed, find its own write already there and
+ * report it as a conflict. So nothing here wraps a write, and the store's writes and admin calls report a transient
+ * fault to their caller, who re-runs the call or checks what landed.
+ *
+ * What is **not** retried: 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, StorageChunkSource, SegmentRef, SegmentSize } from '../../core/ports.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>;
+    /**
+     * Forwarded, not retried: a property, with no request behind it. Without it the grounded cost report priced a
+     * retrying store's refresh at the default TTL whatever the store was configured with.
+     */
+    get pointerRefreshMs(): number | undefined;
+    constructor(inner: StorageChunkSource, opts: RetryingOptions);
+    getChunk(ref: ChunkRef): Promise<Uint8Array | null>;
+    listChunkKeys(ref: SegmentRef): Promise<number[]>;
+}

package/dist/export/index.d.ts

@@ -22,9 +22,8 @@ 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.
+     * Bitmap codec that builds the exported bitmap for the `'roaring'` format. Optional in the type; a **flavor**'s
+     * store passes its own (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. */
@@ -85,8 +84,10 @@ export interface SegmentReader {
  *
  * 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.
+ * freshly-constructed store: a store's storage source re-resolves each segment's generation on a short TTL, or, with
+ * no registry, with `cache.genTtlMs: 0`, or built without a clock, only when an eviction, a sweep or an invalidation
+ * makes it, so a long-lived store may export a view one load behind, or more. Each segment is read live, not pinned:
+ * a publish while a long segment exports can re-resolve it part-way, and its file then holds chunks of two
+ * generations, each whole and verified. For one generation per file, export from a quiet window.
  */
 export declare function runExport(reader: SegmentReader, registry: IRegistryDriver, sink: ExportSink, options?: ExportOptions): Promise<ExportManifest>;

package/dist/index.d.ts

@@ -1,21 +1,22 @@
 /**
  * `@cloudbitmaps/core` — the codec-agnostic cloud engine behind the @cloudbitmaps family.
  *
- * Everything here is **independent of any bitmap codec**: the read engine, every storage driver, the `.crbm`
- * format, the loaded store's write path (bulk load + forward-only publish), encryption/crypto-shred, the registry,
+ * Everything here is **independent of any bitmap codec**: the read engine, the SDK-free storage backends, the `.crbm`
+ * format, the loaded store's write path (`loadSegment`: write, guard, publish, collect), encryption/crypto-shred, the registry,
  * the budget/consistency/eject machinery. Bitmaps are only ever constructed and combined through the
  * {@link CodecInterface} seam, so a *flavor* package (`@cloudbitmaps/roaring` today) supplies the codec and a
  * facade on top.
  *
  * **You normally install a flavor, not this package** — `pnpm add @cloudbitmaps/roaring` pulls this in
- * transitively and re-exports it, so `@cloudbitmaps/roaring` is the one name to know. Depend on `core`
- * directly only when authoring a new flavor or a driver.
+ * transitively and re-exports, by name, what an application uses, so `@cloudbitmaps/roaring` is the one name to
+ * know. The engine, the standalone forms of the store's methods and the retry and budget internals stay here:
+ * depend on `core` directly only when authoring a new flavor or a driver.
  *
  * Nothing in here may import a flavor package — the dependency arrow is one-way (flavor → core), so core stays
  * publishable on its own and every codec reuses one driver set with zero duplication.
  */
 export { SegmentEngine } from './core/engine.js';
-export type { EngineDeps, CombineOptions as EngineCombineOptions } from './core/engine.js';
+export type { EngineDeps, CombineOptions as EngineCombineOptions, IdRange } from './core/engine.js';
 export { BoundedLru } from './core/lru.js';
 export { safeMetrics } from './core/metrics.js';
 export { groundedReport } from './core/cost.js';
@@ -23,27 +24,17 @@ export { runExport } from './export/index.js';
 export { splitId } from './core/bit-route.js';
 export { mapWithConcurrency } from './core/concurrency.js';
 export { resolveBudget, resolvePerOpBudget, checkBudget, collectWithinBudget } from './core/budget.js';
-export { validateSegmentRef } from './core/validate.js';
 export { segmentExists, listSegments } from './core/discover.js';
 export type { SegmentInfo } from './core/discover.js';
-export { encodeNameForPath } from './core/name-codec.js';
-export { namespacePathPart } from './drivers/_shared/keys.js';
 export type { Token } from './core/ports.js';
 export { segmentKey } from './core/keys.js';
-export { createBackend, isStorageBackend } from './core/ports.js';
-export { MemoryStorageChunkSource, MemoryStorageDriver, MemoryRegistryDriver, } from './drivers/memory.js';
-export type { MemoryRegistryDriverOptions } from './drivers/memory.js';
-export { LocalFsStorageDriver } from './drivers/localfs/storage.js';
-export { LocalFsRegistryDriver } from './drivers/localfs/registry.js';
+export { isStorageBackend } from './core/ports.js';
 export { LocalFsStorage, MemoryStorage } from './drivers/backends.js';
 export type { LocalFsStorageOptions, MemoryStorageOptions } from './drivers/backends.js';
-export type { LocalFsRegistryDriverOptions } from './drivers/localfs/registry.js';
-export { CrbmStorageChunkSource, writeCrbmGeneration, bulkLoadCrbmGeneration, publishGeneration, } from './core/crbm-storage-source.js';
-export type { BulkLoadResult, CrbmStorageChunkSourceOptions } from './core/crbm-storage-source.js';
+export { CrbmStorageChunkSource } from './core/crbm-storage-source.js';
+export type { CrbmStorageChunkSourceOptions, PinnedObject } from './core/crbm-storage-source.js';
 export { PinnedStorageChunkSource } from './core/pinned-storage-source.js';
 export type { PinnedAt } from './core/pinned-storage-source.js';
-export { gcOrphanGenerations, nextGeneration } from './core/generation-gc.js';
-export type { GenerationDeps } from './core/generation-gc.js';
 export { loadSegment } from './core/load.js';
 export type { LoadDeps, LoadOptions, LoadGuard, LoadResult, LoadRefusal } from './core/load.js';
 export { listGenerations, rollbackSegment } from './core/rollback.js';
@@ -53,7 +44,7 @@ export type { EraseIdDeps, EraseIdResult } from './core/erase-id.js';
 export type { CodecInterface, CodecBitmap } from './core/codec.js';
 export type { Clock, Rng } from './core/determinism.js';
 export type { StorageChunkSource, IStorageDriver, StorageCaps, ChunkRef, SegmentRef, GenKey, IRegistryDriver, StorageBackend, RegistryRecord, NewRegistryRecord, RegistryPatch, RegistryStatus, RegCaps, GovernanceMeta, SegmentSize, } from './core/ports.js';
-export { CloudRoaringError, ValidationError, WriteConflictError, IntegrityError, NotFoundError, UnsupportedError, CapabilityError, TransientError, TimeoutError, KeyUnavailableError, BudgetExceededError, isCloudRoaringError, isWriteConflictError, isTransientError, isNotFoundError, isIntegrityError, isValidationError, } from './core/errors.js';
+export { CloudRoaringError, ValidationError, WriteConflictError, IntegrityError, NotFoundError, UnsupportedError, CapabilityError, TransientError, KeyUnavailableError, BudgetExceededError, isCloudRoaringError, isWriteConflictError, isTransientError, isNotFoundError, isIntegrityError, isValidationError, } from './core/errors.js';
 export type { Aead, AeadSealed, IKeystore, WrappedDek, CrbmCrypto } from './core/crypto.js';
 export { aadFor } from './core/crypto.js';
 export { NodeAead, InProcessKeystore } from './drivers/crypto.js';
@@ -72,15 +63,15 @@ export type { ConsistencyReport, ConsistencyIssue, ConsistencyErrorEntry, } from
 export type { ExportFormat, ExportSink, ExportWriter, ExportOptions, ExportedSegment, ExportFailure, ExportManifest, } from './export/index.js';
 export { withRetry, DEFAULT_RETRY_POLICY } from './core/retry.js';
 export type { RetryPolicy, RetryDeps } from './core/retry.js';
-export { RetryingStorageChunkSource, RetryingStorageDriver, RetryingRegistryDriver, } from './drivers/retry/retrying-drivers.js';
-export type { RetryingOptions } from './drivers/retry/retrying-drivers.js';
+export { RetryingStorageChunkSource } from './drivers/retry/retrying-chunk-source.js';
+export type { RetryingOptions } from './drivers/retry/retrying-chunk-source.js';
 export { CrbmReader } from './core/crbm/reader.js';
 export type { CrbmReaderOptions } from './core/crbm/reader.js';
 export { BufferReader } from './core/blob.js';
 export type { BlobReader, BlobSink } from './core/blob.js';
 export { NOOP_METRICS, CountingMetricsSink } from './core/metrics.js';
 export type { IMetricsSink, MetricEvent, MetricOpName, MetricsSnapshot } from './core/metrics.js';
-export { estimateCost, DEFAULT_PRICING, AWS_US_EAST_1_ONDEMAND } from './core/cost.js';
-export type { PricingProfile, CostReport, Workload, SegmentSizing, EstimateInput, } from './core/cost.js';
+export { estimateCost, AWS_US_EAST_1_ONDEMAND, ELASTICACHE_REDIS_US_EAST_1_ONDEMAND, ONE_REDIS_HA_CLUSTER, } from './core/cost.js';
+export type { PricingProfile, RedisNodeType, RedisSizing, CostReport, Workload, SegmentSizing, EstimateInput, } from './core/cost.js';
 export { RecordingAuditSink } from './core/audit.js';
-export type { IAuditSink, AuditEvent, AuditEventKind } from './core/audit.js';
+export type { IAuditSink, AuditEvent } from './core/audit.js';