@cloudbitmaps/core 0.16.0 → 0.17.0

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

@@ -1,4 +1,4 @@
-import type { IRegistryDriver, NewRegistryRecord, RegCaps, RegistryPatch, RegistryRecord, RegistryWriteOptions, SegmentRef, Token } from '../../core/ports.js';
+import type { IRegistryDriver, NewRegistryRecord, ReapLegacyTombstonesOptions, ReapLegacyTombstonesResult, RegCaps, RegistryPatch, RegistryRecord, RegistryWriteOptions, 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;
@@ -79,6 +79,11 @@ export interface ObjectRegistryStore {
      * a live one included. Absent or `false`, the registry never calls `delete` and tombstones every row instead.
      */
     readonly conditionalDelete?: boolean;
+    /**
+     * Optional: settle {@link conditionalDelete} without a request to the backend, for a store that learns it from its
+     * client rather than knowing it at construction. A caller that must refuse before its first request awaits it first.
+     */
+    resolveCapabilities?(): Promise<void>;
 }
 export declare class ObjectStoreRegistry implements IRegistryDriver {
     private readonly store;
@@ -114,6 +119,19 @@ export declare class ObjectStoreRegistry implements IRegistryDriver {
     private observedRow;
     list(namespace?: string): AsyncIterable<RegistryRecord>;
     delete(ref: SegmentRef, expected?: Token): Promise<void>;
+    /**
+     * Remove the `deleted: true` rows with no incarnation id (the envelopes a release before 0.12 left), or count them.
+     * One listing, a read per key and a conditional delete per envelope, so a row that a create wrote over since it was
+     * read keeps its new version and the delete is refused. Refuses with {@link CapabilityError}, before any request,
+     * where the store's delete is not known to apply its precondition.
+     *
+     * An object that cannot be read or parsed stops the run with the error that names its key, and removes nothing
+     * more: it may be a newer release's row. Rows removed before the stop stay removed, and a re-run is safe.
+     *
+     * Not resumable: it lists and reads from the start on every call. A delete refused as a conflict, including one for a
+     * row already gone, is counted as `raced`.
+     */
+    reapLegacyTombstones(options: ReapLegacyTombstonesOptions): Promise<ReapLegacyTombstonesResult>;
     /**
      * Read + parse a registry object, returning its envelope and version fence, or null if absent.
      *

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

@@ -1,11 +1,8 @@
 import type { Entropy } from '../../core/determinism.js';
 import { incarnationOf } from '../../core/token.js';
+import { usableKeptGens } from '../../core/kept-generations.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", "summary", "createdAt", "updatedAt", "token"];
+export declare const RECORD_FIELDS: readonly ["namespace", "segment", "currentGen", "wrappedDeks", "keyId", "status", "retention", "residency", "summary", "createdAt", "updatedAt", "token", "keptGens", "leases"];
 /**
  * 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.
@@ -38,11 +35,11 @@ export interface RegistryEnvelope {
  * 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.
+ * Schema 2 added the record's `summary` and the incarnation-form token; schema 3 adds `keptGens`. Every row this
+ * build writes is stamped 3, whatever it holds, and a build that reads only schema 2 refuses it, so a fleet cannot go
+ * back once one has been written.
  */
-export declare const REGISTRY_SCHEMA_VERSION = 2;
+export declare const REGISTRY_SCHEMA_VERSION = 3;
 /**
  * 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
@@ -51,6 +48,7 @@ export declare const REGISTRY_SCHEMA_VERSION = 2;
 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 { usableKeptGens };
 export { incarnationOf };
 /** A fresh incarnation id from `entropy`: 128 bits as 32 lowercase hex digits. */
 export declare function drawIncarnation(entropy: Entropy): string;

package/dist/export/index.d.ts

@@ -64,12 +64,18 @@ export interface ExportManifest {
      */
     readonly failed: readonly ExportFailure[];
 }
-/** The minimal read surface the export needs from a store — a `CloudRoaring` satisfies this structurally. */
+/**
+ * The minimal read surface the export needs from a store — a `CloudRoaring` satisfies this structurally: `segment(name,
+ * { namespace? })` returns a handle whose `pin()` resolves to something that iterates the ids. A segment's
+ * `pin()` resolves its generation once and reads only that generation's object, so one segment's export is one instant.
+ */
 export interface SegmentReader {
     segment(name: string, options?: {
         namespace?: string;
     }): {
-        iterate(): AsyncIterable<number>;
+        pin(): Promise<{
+            iterate(): AsyncIterable<number>;
+        }>;
     };
 }
 /**
@@ -83,11 +89,17 @@ export interface SegmentReader {
  * `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, 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.
+ * disappeared — export to a fresh directory for a clean dump.
+ *
+ * Each segment is pinned for its export: its generation is read from the registry when its export begins, on a warm
+ * store as on a cold one, and only that generation's object is read for the whole segment, so a publish during a long
+ * segment's export cannot put two generations in one file. A cold store makes one registry read and one tail read
+ * per segment; a warm store makes one registry read per segment. A pin holds nothing: if a collection or an erasure
+ * removes the pinned generation mid-export, that segment's export fails, recorded in `failed`, and never reads the
+ * newer generation. Different segments are different instants.
+ *
+ * `reader` is any object with `segment(name, { namespace? })` returning a handle with `pin()`, which resolves to
+ * `{ iterate(): AsyncIterable<number> }` (see {@link SegmentReader}). A reader without that shape throws a
+ * `ValidationError` before any file is opened.
  */
 export declare function runExport(reader: SegmentReader, registry: IRegistryDriver, sink: ExportSink, options?: ExportOptions): Promise<ExportManifest>;

package/dist/index.d.ts

@@ -21,6 +21,7 @@ export { BoundedLru } from './core/lru.js';
 export { safeMetrics } from './core/metrics.js';
 export { groundedReport } from './core/cost.js';
 export { runExport } from './export/index.js';
+export type { SegmentReader } 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';
@@ -32,20 +33,23 @@ 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, PinnedObject } 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';
+export type { LeaseDeps, LeaseTake, TakenLease } from './core/leases.js';
 export { PinnedStorageChunkSource } from './core/pinned-storage-source.js';
 export type { PinnedAt } from './core/pinned-storage-source.js';
 export { loadSegment, loadSegmentChunks } 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 { 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 type { CodecInterface, CodecBitmap, EncodedChunk } from './core/codec.js';
 export type { Clock, Entropy, Rng } from './core/determinism.js';
-export type { StorageChunkSource, IStorageDriver, StorageCaps, ChunkRef, ChunkRead, ReadChunksOptions, SegmentRef, GenKey, IRegistryDriver, StorageBackend, RegistryRecord, NewRegistryRecord, RegistryPatch, RegistryStatus, RegistrySummary, RegistryWriteOptions, 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 { StorageChunkSource, IStorageDriver, StorageCaps, ChunkRef, ChunkRead, ReadChunksOptions, SegmentRef, GenKey, IRegistryDriver, StorageBackend, RegistryRecord, NewRegistryRecord, RegistryPatch, RegistryStatus, RegistrySummary, RegistryWriteOptions, LeaseEntry, ReapLegacyTombstonesOptions, ReapLegacyTombstonesResult, ClearRegistrySummary, SealedRegistrySummary, GenerationMetadata, GenerationSummary, RegCaps, GovernanceMeta, SegmentSize, } from './core/ports.js';
+export { CloudRoaringError, ValidationError, WriteConflictError, IntegrityError, NotFoundError, UnsupportedError, CapabilityError, TransientError, KeyUnavailableError, BudgetExceededError, LeaseExpiredError, LeaseLimitError, isCloudRoaringError, isWriteConflictError, isTransientError, isNotFoundError, isIntegrityError, isValidationError, isLeaseExpiredError, isLeaseLimitError, } 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';
@@ -55,6 +59,8 @@ export type { DropDeps, DropResult, EraseDeps, DestroyResult } from './core/eras
 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 { reapRegistryTombstones } from './core/registry-reap.js';
+export type { ReapRegistryTombstonesOptions, ReapRegistryTombstonesResult, } from './core/registry-reap.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';