@cloudbitmaps/core 0.22.0 → 0.23.0

package/dist/drivers/crypto.d.ts

@@ -3,7 +3,8 @@ import type { Aead, AeadSealed, IKeystore, WrappedDek } from '../core/crypto.js'
  * 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. */
+ * re-seeded (a fresh segment ⇒ fresh DEK). A segment at the 65,536-chunk maximum reaches it after about 65,500 loads
+ * or rewrites (230 days at one every 5 minutes): load into a fresh segment, or load less often, before then. */
 export declare class NodeAead implements Aead {
     private readonly key;
     constructor(key: Uint8Array);
@@ -14,11 +15,18 @@ export declare class NodeAead implements Aead {
  * 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.
+ * re-encryption: add the new KEK, point `activeKeyId` at it, keep the old one to unwrap existing segments. An option
+ * it does not take, such as a misspelt `recoveryKeyId`, throws `ValidationError`.
  */
 export interface InProcessKeystoreOptions {
+    /** Each key-encryption key (KEK) by its id: 32 bytes each, at least one. */
     readonly keys: Readonly<Record<string, Uint8Array>>;
+    /** The id of the KEK new data keys are wrapped under. It must be in `keys`. */
     readonly activeKeyId: string;
+    /**
+     * The id of a second KEK each new data key is also wrapped under, such as an offline one. Absent for none, and the
+     * same id as `activeKeyId` means none too; it must be in `keys` when given.
+     */
     readonly recoveryKeyId?: string;
 }
 /**
@@ -29,6 +37,13 @@ export declare class InProcessKeystore implements IKeystore {
     private readonly keys;
     private readonly activeKeyId;
     private readonly recoveryKeyId;
+    /**
+     * Builds a keystore from `options`; throws `ValidationError` for no options object, an option it does not take
+     * (a misspelt `recoveryKeyId` would otherwise leave no recovery wrapping), a `keys` that is not an object, an
+     * `activeKeyId` or `recoveryKeyId` that is not a string, no keys, a key given as text rather than a
+     * `Uint8Array`, a key that is not 32 bytes, or an `activeKeyId` or `recoveryKeyId` that is not in `keys`. A
+     * `recoveryKeyId` equal to `activeKeyId` means no recovery key.
+     */
     constructor(options: InProcessKeystoreOptions);
     createDek(): Promise<{
         wrapped: WrappedDek[];

package/dist/export/index.d.ts

@@ -16,8 +16,10 @@ export interface ExportWriter {
 }
 /** A destination the export writes each segment to. `ext` is `.roaring` or `.ndjson`. */
 export interface ExportSink {
+    /** Opens the writer for one segment. `ext` is `.roaring` or `.ndjson`, by the export's format. */
     open(ref: SegmentRef, ext: string): Promise<ExportWriter> | ExportWriter;
 }
+/** Options of an export: the format, the namespace to scope it to, and the ndjson batch size. */
 export interface ExportOptions {
     /** Output format; defaults to `'roaring'`. */
     readonly format?: ExportFormat;
@@ -28,7 +30,9 @@ export interface ExportOptions {
 }
 /** Per-segment result recorded in the {@link ExportManifest}. */
 export interface ExportedSegment {
+    /** The segment's name. */
     readonly segment: string;
+    /** The segment's namespace, or `undefined` for the default one. */
     readonly namespace?: string;
     /** Ids written (the segment's effective cardinality at export time). */
     readonly count: number;
@@ -40,27 +44,37 @@ export interface ExportedSegment {
  * single corrupt/undecryptable segment never blocks the rest of the dump.
  */
 export interface ExportFailure {
+    /** The name of the segment that could not be exported. */
     readonly segment: string;
+    /** That segment's namespace, or `undefined` for the default one. */
     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;
 }
 /**
- * A registered segment the export did not read, and why. `'destroyed'` is a tombstone: the segment was crypto-shredded
- * or dropped, so it resolves no generation and has nothing to export.
+ * A registered segment the export did not read, and why. `'destroyed'` is a tombstone: the segment was
+ * crypto-shredded,
+ * destroyed in the clear or dropped, so it resolves no generation and has nothing to export.
  */
 export interface ExportSkipped {
+    /** The name of the segment that was skipped. */
     readonly segment: string;
+    /** That segment's namespace, or `undefined` for the default one. */
     readonly namespace?: string;
+    /** Why it was skipped: `'destroyed'`, a tombstone. */
     readonly reason: 'destroyed';
 }
 /** What `CloudRoaring.exportSegments` 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;
+    /** The format the segments were written in. */
     readonly format: ExportFormat;
+    /** How many segments were exported. */
     readonly totalSegments: number;
+    /** How many ids were written, over all segments. */
     readonly totalIds: number;
+    /** One entry for each segment exported. */
     readonly segments: readonly ExportedSegment[];
     /**
      * Segments that could not be read (empty when everything succeeded). Its presence in the manifest is the point:

package/dist/index.d.ts

@@ -1,17 +1,19 @@
 /**
  * `@cloudbitmaps/core` — the codec-agnostic cloud engine behind the @cloudbitmaps family.
  *
- * Everything here is **independent of any bitmap codec**: the read engine, the SDK-free storage backends, the `.crbm`
+ * Everything here is **independent of any bitmap codec**: the read engine, 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.
  *
  * **This entry is internal.** It is the engine `@cloudbitmaps/roaring` and the storage-driver packages import, and it is
- * outside the stability promise: it can change in any minor release, and a change to it gets no CHANGELOG Breaking
+ * outside the stability promise: it can change in any release, and a change to it gets no CHANGELOG Breaking
  * entry. Install `@cloudbitmaps/roaring` and a driver; `@cloudbitmaps/roaring` re-exports, by name, what an application
  * uses. The public entry of this package is `@cloudbitmaps/core/driver-kit`, the contract for writing a driver.
- * Within a minor, this entry changes only additively: a removal or a changed signature waits for the next minor.
+ *
+ * The drivers that need a Node builtin (the in-memory and local-filesystem backends, the in-process cipher and
+ * keystore) are exported by `@cloudbitmaps/core/node`, so nothing this entry reaches imports a `node:*` builtin.
  *
  * 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.
@@ -26,11 +28,10 @@ export { splitId } from './core/bit-route.js';
 export { mapWithConcurrency } from './core/concurrency.js';
 export { resolveBudget, resolvePerOpBudget, checkBudget, collectWithinBudget } from './core/budget.js';
 export { segmentExists, listSegments } from './core/discover.js';
+export { refuseUnknownRefKeys } from './core/validate.js';
 export type { SegmentInfo } from './core/discover.js';
 export { segmentKey } from './core/keys.js';
 export { isStorageBackend } from './core/ports.js';
-export { LocalFsStorage, MemoryStorage } from './drivers/backends.js';
-export type { LocalFsStorageOptions, MemoryStorageOptions } from './drivers/backends.js';
 export { CrbmStorageChunkSource } from './core/crbm-storage-source.js';
 export type { CrbmStorageChunkSourceOptions, PinLease, PinnedObject, } from './core/crbm-storage-source.js';
 export { LEASE_SKEW_MS, MAX_LEASE_MS, MAX_LEASES_PER_SEGMENT, releaseLease, takeLease, } from './core/leases.js';
@@ -45,21 +46,21 @@ export type { LoadInput, PortableBitmap } from './core/load-input.js';
 export { decodeSerialized } from './core/load-input.js';
 export { listGenerations, rollbackSegment } from './core/rollback.js';
 export type { GenerationListDeps, GenerationEntry, RollbackResult } from './core/rollback.js';
-export { eraseIdFromSegment } from './core/erase-id.js';
-export type { EraseIdDeps, EraseIdResult } from './core/erase-id.js';
+export { eraseIdFromSegment, findIdUnderTombstone } from './core/erase-id.js';
+export type { EraseIdDeps, EraseIdResult, SearchDeps } from './core/erase-id.js';
 export type { CodecInterface, CodecBitmap, EncodedChunk } from './core/codec.js';
 export type { Clock, Entropy, Rng } from './core/determinism.js';
 export type { SegmentRef, GenerationMetadata } from './core/ports.js';
 export { CloudRoaringError, ValidationError, WriteConflictError, IntegrityError, NotFoundError, UnsupportedError, CapabilityError, TransientError, KeyUnavailableError, BudgetExceededError, LeaseExpiredError, LeaseLimitError, StaleOperandError, errorKind, } from './core/errors.js';
 export type { CrbmCrypto } from './core/crypto.js';
 export { aadFor } from './core/crypto.js';
-export { NodeAead, InProcessKeystore } from './drivers/crypto.js';
-export type { InProcessKeystoreOptions } from './drivers/crypto.js';
 export { destroySegment, dropSegment, eraseNamespace } from './core/erasure.js';
 export type { DropDeps, DropResult, EraseDeps, DestroyResult } from './core/erasure.js';
 export { setSegmentRetention, clearSegmentRetention, getSegmentRetention, readRetentionPolicy, MIN_EXPIRES_AT_MS, } from './core/retention.js';
 export type { RetentionPolicy, RetentionDeps, SetRetentionResult } from './core/retention.js';
 export { retireExpired } from './core/retention-sweep.js';
+export { runPreflight } from './core/preflight.js';
+export type { PreflightCheck, PreflightDeps, PreflightResult } from './core/preflight.js';
 export { excludingReservedRows } from './core/registry-scan.js';
 export type { RetireExpiredOptions, RetireExpiredResult, RetireEntry, } from './core/retention-sweep.js';
 export { DEFAULT_BUDGET } from './core/budget.js';