@cloudbitmaps/core 0.11.2 → 0.13.0

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

@@ -1,4 +1,5 @@
 import type { IRegistryDriver, NewRegistryRecord, RegCaps, RegistryPatch, RegistryRecord, SegmentRef, Token } from '../../core/ports.js';
+import type { Entropy } from '../../core/determinism.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;
 /**
@@ -8,11 +9,12 @@ export declare const MAX_ROW_BYTES: number;
  * 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. Either is an easy misreading for a store that reads a
- * row in two calls, as the Azure Blob store does, which is why the signal is part of the port rather than
+ * row in two calls, metadata and then bytes pinned to it, which is why the signal is 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`, GCS bytes and `generation` from one GET) can never raise it.
+ * Stores whose read is atomic can never raise it, and every shipped store's is: S3 serves bytes and `ETag` from one
+ * `GetObject`, GCS bytes and `generation` from one GET, and Azure Blob bytes and `ETag` from one GET.
  */
 export declare class ObjectVersionRaced extends Error {
     constructor(objectKey: string);
@@ -24,8 +26,8 @@ export interface ObjectRow {
     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.
+ * The I/O calls an object store must provide to host a registry: three, and an optional conditional delete. Everything
+ * else — the OCC token, tombstones, the delete retry, key parsing — is implemented once above.
  */
 export interface ObjectRegistryStore {
     /** A label for error messages, e.g. `GCS` or `Azure Blob`. */
@@ -57,13 +59,41 @@ export interface ObjectRegistryStore {
     }): Promise<void>;
     /** Every object key under `prefix`, paginated internally. */
     listKeys(prefix: string): AsyncIterable<string>;
+    /**
+     * Optional: delete one object, and only while it is still at exactly `expect.version`, by a precondition the
+     * backend applies (`If-Match: <etag>`, `ifGenerationMatch: <generation>`). An object that was overwritten, or is
+     * gone, MUST throw {@link WriteConflictError} and delete nothing. Retryable faults throw {@link TransientError}.
+     *
+     * Sending it again after a lost response is safe, unlike a write: the precondition names one version, so a second
+     * copy can remove nothing the first was not allowed to. A copy that meets its own landed delete fails the
+     * precondition and reports a conflict; the registry re-reads, and finds the row gone.
+     *
+     * The registry calls it only when {@link conditionalDelete} is `true`.
+     */
+    delete?(key: string, expect: {
+        version: string;
+    }): Promise<void>;
+    /**
+     * Whether {@link delete} may be relied on: `true` only where the backend is known to apply the precondition. A
+     * backend that accepts the header and ignores it would let a delete remove a row written after the delete read it,
+     * a live one included. Absent or `false`, the registry never calls `delete` and tombstones every row instead.
+     */
+    readonly conditionalDelete?: boolean;
 }
 export declare class ObjectStoreRegistry implements IRegistryDriver {
     private readonly store;
     private readonly prefix;
     private readonly now;
-    constructor(store: ObjectRegistryStore, prefix: string | undefined, now: () => number);
+    private readonly entropy;
+    /**
+     * `entropy` draws the random parts of every token: a new row's incarnation id, and each write's own part. It
+     * defaults to the platform's Web Crypto. Inject one only to make a test replayable: a seeded source in production
+     * gives every process the same ids.
+     */
+    constructor(store: ObjectRegistryStore, prefix: string | undefined, now: () => number, entropy?: Entropy);
     capabilities(): RegCaps;
+    /** Whether a delete removes a row born with an incarnation id: the store has a delete, and vouches for it. */
+    private removesRows;
     get(ref: SegmentRef): Promise<RegistryRecord | null>;
     create(ref: SegmentRef, record: NewRegistryRecord): Promise<{
         token: Token;
@@ -79,7 +109,7 @@ export declare class ObjectStoreRegistry implements IRegistryDriver {
      * 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.
+     * spinning. Only a store that reads in two calls gets here; none of the shipped stores does.
      */
     private readRow;
     /** {@link ObjectRegistryStore.read}, retrying the bounded number of times a mid-read overwrite allows. */

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

@@ -1,17 +1,27 @@
+import type { Entropy } from '../../core/determinism.js';
+import { incarnationOf } from '../../core/token.js';
 import type { NewRegistryRecord, RegistryPatch, RegistryRecord, SegmentRef, Token } from '../../core/ports.js';
 /**
  * The fields a stored record may carry: {@link RegistryRecord}'s, and nothing else. A field no reader resolves
  * through is refused on read-back like any other corruption (invariant 5), rather than ignored.
  */
-export declare const RECORD_FIELDS: readonly ["namespace", "segment", "currentGen", "wrappedDeks", "keyId", "status", "retention", "residency", "createdAt", "updatedAt", "token"];
-/** 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;
+export declare const RECORD_FIELDS: readonly ["namespace", "segment", "currentGen", "wrappedDeks", "keyId", "status", "retention", "residency", "summary", "createdAt", "updatedAt", "token"];
+/**
+ * Validate the caller-settable fields at `create`, and return the record to store: the caller's, with its summary
+ * replaced by the checked, frozen copy {@link validateSummary} builds.
+ */
+export declare function validateNewRegistryRecord(rec: NewRegistryRecord): NewRegistryRecord;
+/**
+ * Validate the caller-settable fields in a `compareAndSwap` patch, and return the patch to apply: the caller's, with
+ * its summary replaced by the checked, frozen copy. That a given `summary` names the row's resulting `currentGen`,
+ * and agrees with its resulting keys, needs the stored row, so {@link applyRegistryPatch} checks both.
+ */
+export declare function validateRegistryPatch(patch: RegistryPatch): RegistryPatch;
 /**
  * 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).
+ * record (with an advanced counter) rather than being removed, so a re-create carries the counter on and the two
+ * incarnations' tokens are apart by construction, as well as by their random parts — 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} /
@@ -27,22 +37,35 @@ export interface RegistryEnvelope {
  * 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** or malformed stamp → `IntegrityError`, since every row this build writes has one.
+ *
+ * Schema 2 adds the record's `summary` and the incarnation-form token. Every row this build writes is stamped 2,
+ * whatever it holds, and a build that reads only schema 1 refuses it, so a fleet cannot go back once one has been
+ * written.
  */
-export declare const REGISTRY_SCHEMA_VERSION = 1;
+export declare const REGISTRY_SCHEMA_VERSION = 2;
 /**
- * Validate a persisted registry row's `schemaVersion` (untrusted bytes, invariant 5): an absent or malformed value
- * → `IntegrityError`; a version newer than this build → `UnsupportedError` (fail-closed rather than misread a
- * format we don't understand).
+ * Validate a persisted registry row's `schemaVersion` (untrusted bytes, invariant 5) and return it: an absent or
+ * 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;
+export declare function assertRegistrySchemaVersion(raw: unknown, ctx: string): number;
 /** Serialize a registry envelope for persistence, stamping the current {@link REGISTRY_SCHEMA_VERSION}. */
 export declare function serializeRegistryEnvelope(env: RegistryEnvelope): string;
+export { incarnationOf };
+/** A fresh incarnation id from `entropy`: 128 bits as 32 lowercase hex digits. */
+export declare function drawIncarnation(entropy: Entropy): string;
+/** A fresh write part from `entropy`: 64 bits as 16 lowercase hex digits. */
+export declare function drawWrite(entropy: Entropy): string;
+/**
+ * The token for the write after `record`'s: the same incarnation, if it has one, the counter one on, and a fresh write
+ * part. For a compare-and-swap or a tombstone.
+ */
+export declare function nextRegistryToken(record: RegistryRecord, entropy: Entropy): Token;
 /**
- * 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.
+ * The token of a new row: a fresh incarnation and write part from `entropy`, and a counter that continues
+ * `tombstone`'s when the row is created over one, else starts at 0.
  */
-export declare function registryCounterOf(record: RegistryRecord): number;
+export declare function newIncarnationToken(entropy: Entropy, tombstone: RegistryRecord | undefined): Token;
 /**
  * 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 —
@@ -54,13 +77,18 @@ export declare function recordFromNew(ref: SegmentRef, rec: NewRegistryRecord, n
 /**
  * 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).
+ * it rather than silently report "absent". A row of an older `schemaVersion` may carry only that schema's
+ * fields. `token` is checked by the caller.
  */
-export declare function assertStoredRecordShape(r: Record<string, unknown>, ctx: string): void;
+export declare function assertStoredRecordShape(r: Record<string, unknown>, ctx: string, schemaVersion?: number): 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).
+ *
+ * `summary` describes the current generation, so it follows the pointer and the keys: a patch that moves
+ * `currentGen`, or changes `wrappedDeks` so the summary's shape no longer agrees, without mentioning `summary` drops
+ * the old one; and a summary the patch gives must name the resulting `currentGen` and agree with the resulting keys
+ * (`ValidationError`, before anything is written).
  */
 export declare function applyRegistryPatch(prev: RegistryRecord, patch: RegistryPatch, now: number, token: Token): RegistryRecord;

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

@@ -1,14 +1,22 @@
+import type { Entropy } from '../../core/determinism.js';
 import type { IRegistryDriver, NewRegistryRecord, RegCaps, RegistryPatch, RegistryRecord, SegmentRef, Token } from '../../core/ports.js';
 /** Entries in the process-wide row-lock map; the map is empty whenever no registry operation is in flight. */
 export declare function localFsRowLockCount(): number;
 export interface LocalFsRegistryDriverOptions {
     /** Injected clock for `createdAt`/`updatedAt`; defaults to `Date.now`. */
     readonly now?: () => number;
+    /** Draws every token's random parts; defaults to Web Crypto. Inject one only to make a test replayable. */
+    readonly entropy?: Entropy;
 }
 export declare class LocalFsRegistryDriver implements IRegistryDriver {
     private readonly root;
     private readonly now;
+    private readonly entropy;
     constructor(root: string, options?: LocalFsRegistryDriverOptions);
+    /**
+     * `conditionalDelete`: a delete reads the row, checks it, and unlinks it under the row's lock, which every writer on
+     * the root in this process takes, so no write can land between the check and the unlink.
+     */
     capabilities(): RegCaps;
     get(ref: SegmentRef): Promise<RegistryRecord | null>;
     create(ref: SegmentRef, record: NewRegistryRecord): Promise<{
@@ -19,6 +27,8 @@ export declare class LocalFsRegistryDriver implements IRegistryDriver {
     }>;
     list(namespace?: string): AsyncIterable<RegistryRecord>;
     delete(ref: SegmentRef, expected?: Token): Promise<void>;
+    /** Remove a row's file and make the removal durable (fsync the directory). */
+    private unlinkRow;
     /** Namespaces to scan: just the one requested, or every namespace dir under the root. */
     private namespaceDirs;
     private readRow;

package/dist/drivers/memory.d.ts

@@ -1,20 +1,26 @@
 import type { BlobSink } from '../core/blob.js';
+import type { Entropy } from '../core/determinism.js';
 import type { StorageCaps, GenKey, IStorageDriver, IRegistryDriver, NewRegistryRecord, RegCaps, RegistryPatch, RegistryRecord, SegmentRef, Token } from '../core/ports.js';
 export interface MemoryRegistryDriverOptions {
     /** Injected clock for `createdAt`/`updatedAt`; defaults to `Date.now` (drivers may use ambient time). */
     readonly now?: () => number;
+    /** Draws every token's random parts; defaults to Web Crypto. Inject one only to make a test replayable. */
+    readonly entropy?: Entropy;
 }
 /**
- * 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).
+ * In-memory {@link IRegistryDriver} — one record per segment under OCC. The token has the form every shipped driver
+ * gives it, an incarnation id drawn at create, a counter and a per-write random part, but its counter is global to the
+ * driver: monotonic and never reused, so a record recreated after `delete` never meets an earlier token, by
+ * construction, even though `delete` removes the row physically.
  */
 export declare class MemoryRegistryDriver implements IRegistryDriver {
     private readonly rows;
     private readonly now;
+    private readonly entropy;
     private seq;
     constructor(options?: MemoryRegistryDriverOptions);
     private nextToken;
+    /** `conditionalDelete`: a delete checks the token and removes the row in one step, with no await between. */
     capabilities(): RegCaps;
     get(ref: SegmentRef): Promise<RegistryRecord | null>;
     create(ref: SegmentRef, record: NewRegistryRecord): Promise<{

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

@@ -21,7 +21,7 @@
  */
 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';
+import type { ChunkRef, GenerationSummary, StorageChunkSource, SegmentRef, SegmentSize } from '../../core/ports.js';
 export interface RetryingOptions {
     readonly clock: Clock;
     readonly rng: Rng;
@@ -44,6 +44,7 @@ export declare class RetryingStorageChunkSource implements StorageChunkSource {
     /** 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 summary?: (ref: SegmentRef) => Promise<GenerationSummary | null>;
     readonly currentGeneration?: (ref: SegmentRef) => Promise<number | null>;
     readonly invalidate?: (ref: SegmentRef) => void;
     readonly exists?: (ref: SegmentRef) => Promise<boolean>;

package/dist/index.d.ts

@@ -37,13 +37,14 @@ export { PinnedStorageChunkSource } from './core/pinned-storage-source.js';
 export type { PinnedAt } from './core/pinned-storage-source.js';
 export { loadSegment } from './core/load.js';
 export type { LoadDeps, LoadOptions, LoadGuard, LoadResult, LoadRefusal } from './core/load.js';
+export type { LoadInput, PortableBitmap } 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 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 type { CodecInterface, CodecBitmap, EncodedChunk } from './core/codec.js';
+export type { Clock, Entropy, Rng } from './core/determinism.js';
+export type { StorageChunkSource, IStorageDriver, StorageCaps, ChunkRef, SegmentRef, GenKey, IRegistryDriver, StorageBackend, RegistryRecord, NewRegistryRecord, RegistryPatch, RegistryStatus, RegistrySummary, ClearRegistrySummary, SealedRegistrySummary, GenerationMetadata, GenerationSummary, RegCaps, GovernanceMeta, SegmentSize, } from './core/ports.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';