@cloudbitmaps/core 0.19.1 → 0.21.0

package/dist/drivers/localfs/fs-util.d.ts

@@ -19,6 +19,13 @@ export declare const mapFsError: (err: unknown) => unknown;
  * Containment of symlinked *directory* components assumes the root itself is not attacker-writable.
  */
 export declare const O_NOFOLLOW: number;
+/**
+ * The modes LocalFs creates what it stores with: files readable and writable by their owner alone, directories
+ * searchable by it alone, so another user of the machine cannot read or list a segment. A process umask can only
+ * remove bits from these, never add any. On Windows Node ignores a mode apart from the read-only bit, so passing
+ * them there changes nothing.
+ */
+export declare const FILE_MODE = 384;
 /**
  * Best-effort parent-directory fsync, so a just-published `rename`/`link` survives a crash. Without it the
  * directory entry can still be in the page cache when power goes: the generation's bytes are durable and
@@ -31,3 +38,18 @@ export declare function fsyncDir(dir: string): Promise<void>;
  * or object as a whole one. A write that makes no progress is a full device.
  */
 export declare function writeAll(handle: FileHandle, bytes: Uint8Array): Promise<void>;
+/**
+ * Create `dir` and the directories missing above it, private from `top` down: what is missing above `top` is created
+ * with the default mode (another service may need to traverse it), `top` and everything below it {@link DIR_MODE}. A
+ * directory that exists keeps its mode.
+ */
+export declare function makeDirs(dir: string, top: string): Promise<void>;
+/** The name of a temp file beside `finalPath`: `<finalPath>.<uuid>.tmp`. The only names {@link sweepOrphanTemps} removes. */
+export declare const tempPathFor: (finalPath: string) => string;
+/**
+ * Remove the temp files in `dir` named by {@link tempPathFor} that were last written more than a day ago, streaming the
+ * directory, and at most once an hour per directory in this process. Only regular files go (a symlink is never followed
+ * or removed). Best effort: a failure leaves the files for a later sweep and is never raised. Callers start it without
+ * awaiting it.
+ */
+export declare function sweepOrphanTemps(dir: string, now?: number): Promise<void>;

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

@@ -1,15 +1,18 @@
 import type { Entropy } from '../../core/determinism.js';
-import type { IRegistryDriver, NewRegistryRecord, RegCaps, RegistryPatch, RegistryRecord, SegmentRef, Token } from '../../core/ports.js';
+import type { IRegistryDriver, NewRegistryRecord, RegCaps, RegistryPatch, RegistryRecord, RegistryWriteOptions, 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 {
+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;
+    /** The directory this root lives under, from which down directories are created private; defaults to the root. */
+    readonly privateRoot?: string;
 }
 export declare class LocalFsRegistryDriver implements IRegistryDriver {
     private readonly root;
+    private readonly options;
     private readonly now;
     private readonly entropy;
     private readonly exactCase;
@@ -19,15 +22,17 @@ export declare class LocalFsRegistryDriver implements IRegistryDriver {
      * the root in this process takes, so no write can land between the check and the unlink.
      */
     capabilities(): RegCaps;
+    /** Every write reports its token to `onToken` before the row's file is written. */
+    get reportsWriteTokens(): true;
     get(ref: SegmentRef): Promise<RegistryRecord | null>;
-    create(ref: SegmentRef, record: NewRegistryRecord): Promise<{
+    create(ref: SegmentRef, record: NewRegistryRecord, options?: RegistryWriteOptions): Promise<{
         token: Token;
     }>;
     /**
      * A caller's `held` row (see `RegistryWriteOptions`) has no read to spare here: the row's file is read under its lock and its token compared
      * there, a local read and no request, so a stale one fails exactly as a lost race does.
      */
-    compareAndSwap(ref: SegmentRef, expected: Token, patch: RegistryPatch): Promise<{
+    compareAndSwap(ref: SegmentRef, expected: Token, patch: RegistryPatch, options?: RegistryWriteOptions): Promise<{
         token: Token;
     }>;
     list(namespace?: string): AsyncIterable<RegistryRecord>;
@@ -42,3 +47,4 @@ export declare class LocalFsRegistryDriver implements IRegistryDriver {
     /** Serialize callbacks for a row so read-modify-write is atomic across every instance in the process. */
     private withRowLock;
 }
+export {};

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

@@ -1,20 +1,28 @@
-import type { BlobSink } from '../../core/blob.js';
-import type { StorageCaps, GenKey, IStorageDriver, SegmentRef } from '../../core/ports.js';
+import { type BlobSink } from '../../core/blob.js';
+import type { StorageCaps, GenKey, IStorageDriver, SegmentRef, StorageDeleteOptions, TailRead } from '../../core/ports.js';
 export declare class LocalFsStorageDriver implements IStorageDriver {
     private readonly root;
+    private readonly options;
     private readonly exactCase;
-    constructor(root: string);
+    /**
+     * `options.privateRoot` is the directory this one lives under, from which down directories are created private; it
+     * defaults to `root`.
+     */
+    constructor(root: string, options?: {
+        readonly privateRoot?: string;
+    });
     capabilities(): StorageCaps;
     putImmutable(key: GenKey, write: (sink: BlobSink) => Promise<void>): Promise<{
         size: number;
         sha256: string;
     }>;
     getRange(key: GenKey, offset: number, length: number): Promise<Uint8Array>;
-    getTail(key: GenKey, maxBytes: number): Promise<{
-        bytes: Uint8Array;
-        size: number;
-    }>;
-    delete(key: GenKey): Promise<void>;
+    getTail(key: GenKey, maxBytes: number): Promise<TailRead>;
+    /**
+     * Idempotent. Ignores `options.ifVersion`, as `conditionalDelete: false` says: see the note on the class for why it
+     * cannot apply one. The parameter is declared so that a wrapper of this driver can hand the port's options on.
+     */
+    delete(key: GenKey, options?: StorageDeleteOptions): Promise<void>;
     list(ref: SegmentRef): AsyncIterable<GenKey>;
     private openRead;
 }

package/dist/drivers/memory.d.ts

@@ -1,7 +1,7 @@
 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 {
+import type { StorageCaps, StorageDeleteOptions, TailRead, GenKey, IStorageDriver, IRegistryDriver, NewRegistryRecord, RegCaps, RegistryPatch, RegistryRecord, RegistryWriteOptions, SegmentRef, Token } from '../core/ports.js';
+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. */
@@ -22,15 +22,17 @@ export declare class MemoryRegistryDriver implements IRegistryDriver {
     private nextToken;
     /** `conditionalDelete`: a delete checks the token and removes the row in one step, with no await between. */
     capabilities(): RegCaps;
+    /** Every write reports its token to `onToken` before it is applied. */
+    get reportsWriteTokens(): true;
     get(ref: SegmentRef): Promise<RegistryRecord | null>;
-    create(ref: SegmentRef, record: NewRegistryRecord): Promise<{
+    create(ref: SegmentRef, record: NewRegistryRecord, options?: RegistryWriteOptions): Promise<{
         token: Token;
     }>;
     /**
      * A caller's `held` row (see `RegistryWriteOptions`) has no read to spare here: the token is compared with the stored row in the same step
      * as the write, in memory, so a stale one fails exactly as a lost race does.
      */
-    compareAndSwap(ref: SegmentRef, expected: Token, patch: RegistryPatch): Promise<{
+    compareAndSwap(ref: SegmentRef, expected: Token, patch: RegistryPatch, options?: RegistryWriteOptions): Promise<{
         token: Token;
     }>;
     list(namespace?: string): AsyncIterable<RegistryRecord>;
@@ -40,20 +42,23 @@ export declare class MemoryRegistryDriver implements IRegistryDriver {
  * In-memory {@link IStorageDriver} — write-once immutable generation objects as opaque bytes. A "dumb byte
  * mover" (understands neither roaring nor `.crbm`), so it's a faithful storage backend for tests and a zero-setup
  * local storage tier. Mirrors the LocalFs/S3 contract (write-once, range/tail reads).
+ *
+ * Every object stored gets a version from a counter the driver never reuses, so two objects stored one after the other
+ * under one key never share one, whatever their bytes. A delete given `ifVersion` compares it with the stored object's
+ * and removes it in the same step, with no await between them: `conditionalDelete` is `true`.
  */
 export declare class MemoryStorageDriver implements IStorageDriver {
     private readonly objects;
+    private stored;
     capabilities(): StorageCaps;
     putImmutable(key: GenKey, write: (sink: BlobSink) => Promise<void>): Promise<{
         size: number;
         sha256: string;
     }>;
     getRange(key: GenKey, offset: number, length: number): Promise<Uint8Array>;
-    getTail(key: GenKey, maxBytes: number): Promise<{
-        bytes: Uint8Array;
-        size: number;
-    }>;
-    delete(key: GenKey): Promise<void>;
+    getTail(key: GenKey, maxBytes: number): Promise<TailRead>;
+    delete(key: GenKey, options?: StorageDeleteOptions): Promise<void>;
     list(ref: SegmentRef): AsyncIterable<GenKey>;
     private require;
 }
+export {};

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

@@ -46,15 +46,11 @@ export declare class RetryingStorageChunkSource implements StorageChunkSource {
     readonly getChunks?: (ref: SegmentRef, keys: readonly number[], options?: ReadChunksOptions) => AsyncIterable<ChunkRead>;
     readonly cardinalities?: (ref: SegmentRef) => Promise<ReadonlyMap<number, number> | null>;
     readonly summary?: (ref: SegmentRef) => Promise<GenerationSummary | null>;
+    readonly stat?: (ref: SegmentRef) => Promise<(GenerationSummary & SegmentSize) | 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

@@ -50,6 +50,15 @@ export interface ExportFailure {
     /** 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.
+ */
+export interface ExportSkipped {
+    readonly segment: string;
+    readonly namespace?: string;
+    readonly reason: 'destroyed';
+}
 /** What {@link runExport} 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. */
@@ -63,6 +72,13 @@ export interface ExportManifest {
      * "a manifest exists" ⇒ the run finished, **not** that every segment succeeded — always check this list.
      */
     readonly failed: readonly ExportFailure[];
+    /**
+     * Registered segments the export did not read, each with its reason (empty when there were none). With `segments`
+     * and `failed` it accounts for every segment row the registry listed, so a `totalSegments` below the registry's
+     * segment count is explained rather than silent. The registry's internal due-index rows are not segments, and are in
+     * none of the three.
+     */
+    readonly skipped: readonly ExportSkipped[];
 }
 /**
  * The minimal read surface the export needs from a store — a `CloudRoaring` satisfies this structurally: `segment(name,

package/dist/index.d.ts

@@ -19,7 +19,6 @@ export { SegmentEngine } 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';
 export { runExport } from './export/index.js';
 export type { SegmentReader } from './export/index.js';
 export { splitId } from './core/bit-route.js';
@@ -50,7 +49,7 @@ 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, LeaseEntry, ClearRegistrySummary, SealedRegistrySummary, GenerationMetadata, GenerationSummary, RegCaps, GovernanceMeta, SegmentSize, } from './core/ports.js';
+export type { StorageChunkSource, IStorageDriver, StorageCaps, StorageDeleteOptions, TailRead, ChunkRef, ChunkRead, ReadChunksOptions, SegmentRef, GenKey, IRegistryDriver, StorageBackend, RegistryRecord, NewRegistryRecord, RegistryPatch, RegistryStatus, RegistrySummary, RegistryWriteOptions, LeaseEntry, KnownGeneration, ClearRegistrySummary, SealedRegistrySummary, GenerationMetadata, GenerationSummary, RegCaps, GovernanceMeta, SegmentSize, } from './core/ports.js';
 export { CloudRoaringError, ValidationError, WriteConflictError, IntegrityError, NotFoundError, UnsupportedError, CapabilityError, TransientError, KeyUnavailableError, BudgetExceededError, LeaseExpiredError, LeaseLimitError, StaleOperandError, isCloudRoaringError, isWriteConflictError, isTransientError, isNotFoundError, isIntegrityError, isValidationError, isLeaseExpiredError, isLeaseLimitError, isStaleOperandError, isUnsupportedError, isCapabilityError, isBudgetExceededError, isKeyUnavailableError, } from './core/errors.js';
 export type { Aead, AeadSealed, IKeystore, WrappedDek, CrbmCrypto } from './core/crypto.js';
 export { aadFor } from './core/crypto.js';
@@ -67,7 +66,7 @@ export { DEFAULT_BUDGET } from './core/budget.js';
 export type { Budget, BudgetOption } from './core/budget.js';
 export { runConsistencyCheck } from './core/consistency.js';
 export type { ConsistencyReport, ConsistencyIssue, ConsistencyErrorEntry, } from './core/consistency.js';
-export type { ExportFormat, ExportSink, ExportWriter, ExportOptions, ExportedSegment, ExportFailure, ExportManifest, } from './export/index.js';
+export type { ExportFormat, ExportSink, ExportWriter, ExportOptions, ExportedSegment, ExportFailure, ExportManifest, ExportSkipped, } from './export/index.js';
 export { withRetry, DEFAULT_RETRY_POLICY } from './core/retry.js';
 export type { RetryPolicy, RetryDeps } from './core/retry.js';
 export { RetryingStorageChunkSource } from './drivers/retry/retrying-chunk-source.js';
@@ -78,7 +77,5 @@ 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, 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 } from './core/audit.js';