@brightchain/brightchain-lib 0.30.1 → 0.31.0

package/src/lib/interfaces/staging/stagedFileRecord.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Metadata tracked for each staged file.
+ * Persisted as a JSON sidecar file alongside the staged file bytes.
+ *
+ * TId defaults to string for frontend, GuidV4Buffer for backend.
+ */
+export interface IStagedFileRecord<TId = string> {
+    /** Cryptographically random UUID v4 — acts as both ID and bearer credential */
+    commitToken: string;
+    /** Original filename from the upload */
+    originalFilename: string;
+    /** MIME type of the uploaded file */
+    mimeType: string;
+    /** File size in bytes */
+    sizeBytes: number;
+    /** ISO 8601 timestamp of when the file was staged */
+    uploadedAt: Date | string;
+    /** ISO 8601 timestamp of when the staged file expires */
+    expiresAt: Date | string;
+    /** ID of the user who uploaded the file */
+    uploaderId: TId;
+}
+//# sourceMappingURL=stagedFileRecord.d.ts.map

package/src/lib/interfaces/staging/stagedFileRecord.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stagedFileRecord.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/staging/stagedFileRecord.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB,CAAC,GAAG,GAAG,MAAM;IAC7C,+EAA+E;IAC/E,WAAW,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,gBAAgB,EAAE,MAAM,CAAC;IACzB,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,UAAU,EAAE,IAAI,GAAG,MAAM,CAAC;IAC1B,yDAAyD;IACzD,SAAS,EAAE,IAAI,GAAG,MAAM,CAAC;IACzB,2CAA2C;IAC3C,UAAU,EAAE,GAAG,CAAC;CACjB"}

package/src/lib/interfaces/staging/stagedFileRecord.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=stagedFileRecord.js.map

package/src/lib/interfaces/staging/stagedFileRecord.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stagedFileRecord.js","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/staging/stagedFileRecord.ts"],"names":[],"mappings":""}

package/src/lib/interfaces/staging/stagingConfig.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Configuration for the temporary upload staging system.
+ * All values have sensible defaults; override via environment variables
+ * or constructor injection.
+ */
+export interface IStagingConfig {
+    /** Filesystem directory for staged files */
+    stagingDir: string;
+    /** Default TTL in seconds (default: 3600 = 1 hour) */
+    defaultTtlSeconds: number;
+    /** Maximum TTL in seconds (default: 86400 = 24 hours) */
+    maxTtlSeconds: number;
+    /** Maximum upload file size in bytes (default: 52428800 = 50MB) */
+    maxFileSizeBytes: number;
+    /** Cleanup interval in milliseconds (default: 300000 = 5 minutes) */
+    cleanupIntervalMs: number;
+}
+export declare const DEFAULT_STAGING_CONFIG: IStagingConfig;
+//# sourceMappingURL=stagingConfig.d.ts.map

package/src/lib/interfaces/staging/stagingConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stagingConfig.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/staging/stagingConfig.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,yDAAyD;IACzD,aAAa,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,gBAAgB,EAAE,MAAM,CAAC;IACzB,qEAAqE;IACrE,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,eAAO,MAAM,sBAAsB,EAAE,cAMpC,CAAC"}

package/src/lib/interfaces/staging/stagingConfig.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_STAGING_CONFIG = void 0;
+exports.DEFAULT_STAGING_CONFIG = {
+    stagingDir: `${process.cwd()}/tmp/staging`,
+    defaultTtlSeconds: 3600,
+    maxTtlSeconds: 86400,
+    maxFileSizeBytes: 50 * 1024 * 1024,
+    cleanupIntervalMs: 5 * 60 * 1000,
+};
+//# sourceMappingURL=stagingConfig.js.map

package/src/lib/interfaces/staging/stagingConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stagingConfig.js","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/staging/stagingConfig.ts"],"names":[],"mappings":";;;AAkBa,QAAA,sBAAsB,GAAmB;IACpD,UAAU,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,cAAc;IAC1C,iBAAiB,EAAE,IAAI;IACvB,aAAa,EAAE,KAAK;IACpB,gBAAgB,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI;IAClC,iBAAiB,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI;CACjC,CAAC"}

package/src/lib/interfaces/staging/tempUploadResponse.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Response body returned after a successful staging upload.
+ * Contains everything the client needs to preview, commit, or discard.
+ */
+export interface ITempUploadResponse {
+    /** The commit token (UUID v4) for this staged file */
+    commitToken: string;
+    /** URL to preview the staged file */
+    previewUrl: string;
+    /** ISO 8601 timestamp when the staged file expires */
+    expiresAt: string;
+    /** Original filename from the upload */
+    originalFilename: string;
+    /** MIME type of the uploaded file */
+    mimeType: string;
+    /** File size in bytes */
+    sizeBytes: number;
+}
+//# sourceMappingURL=tempUploadResponse.d.ts.map

package/src/lib/interfaces/staging/tempUploadResponse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tempUploadResponse.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/staging/tempUploadResponse.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,gBAAgB,EAAE,MAAM,CAAC;IACzB,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB"}

package/src/lib/interfaces/staging/tempUploadResponse.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=tempUploadResponse.js.map

package/src/lib/interfaces/staging/tempUploadResponse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tempUploadResponse.js","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/staging/tempUploadResponse.ts"],"names":[],"mappings":""}

package/src/lib/interfaces/storage/blockStore.d.ts

@@ -202,11 +202,29 @@ export interface IBlockStore {
     generateCBLMagnetUrl(blockId1: Checksum | string, blockId2: Checksum | string, blockSize: number, block1ParityIds?: string[], block2ParityIds?: string[], isEncrypted?: boolean): string;
     /**
      * Create a head registry backed by this store's persistence layer.
-     * Cloud stores return a CloudHeadRegistry that stores head pointers
-     * in the same container as the blocks. Disk and memory stores may
-     * return undefined (they use PersistentHeadRegistry or InMemoryHeadRegistry
-     * configured separately).
+     * - MemoryBlockStore  → InMemoryHeadRegistry
+     * - DiskBlockStore    → DriverBackedHeadRegistry(FileHeadRegistryDriver)
+     * - Cloud stores      → DriverBackedHeadRegistry(CloudHeadRegistryDriver)
+     * Wrappers and adapters may delegate to their inner store or omit this.
      */
     createHeadRegistry?(): IHeadRegistry;
+    /**
+     * List all block IDs in the store with optional cursor-based pagination.
+     * Used by the block explorer to enumerate blocks in non-pooled stores.
+     *
+     * @param options - Optional pagination: limit and cursor (last block ID from previous page)
+     * @returns Async iterable of block ID hex strings
+     */
+    listBlockIds?(options?: {
+        limit?: number;
+        cursor?: string;
+    }): AsyncIterable<string>;
+    /**
+     * Get the total number of blocks in the store.
+     * Used by the block explorer for pagination metadata.
+     *
+     * @returns Total block count
+     */
+    getBlockCount?(): Promise<number>;
 }
 //# sourceMappingURL=blockStore.d.ts.map

package/src/lib/interfaces/storage/blockStore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blockStore.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/storage/blockStore.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"blockStore.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/storage/blockStore.ts"],"names":[],"mappings":"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"}

package/src/lib/interfaces/storage/headRegistry.d.ts

@@ -1,4 +1,5 @@
 import type { IWriteProof } from '../auth/writeProof';
+import type { HeadRecord } from './headRegistryDriver';
 /**
  * Represents a deferred head update for a block not yet available locally.
  * When the block is fetched, the deferred update can be applied.
@@ -128,5 +129,42 @@ export interface IHeadRegistry {
      * @returns Array of deferred head updates
      */
     getDeferredUpdates(): DeferredHeadUpdate[];
+    /**
+     * Export all current head records (blockId + timestamp) as a snapshot.
+     * Suitable for transmission to a remote peer for eventual-consistency sync.
+     * The map keys are composite strings in the format "dbName:collectionName".
+     */
+    exportSnapshot(): ReadonlyMap<string, HeadRecord>;
+    /**
+     * Merge a snapshot received from a remote peer using last-writer-wins conflict
+     * resolution. Each entry is compared by timestamp; if the remote entry is
+     * strictly newer than the local entry, the local record is updated.
+     *
+     * This is the primary entry point for gossip-based eventual-consistency sync:
+     * each node periodically calls exportSnapshot() and sends the result to peers,
+     * and peers call mergeSnapshot() to converge toward the same state.
+     *
+     * @param snapshot - Iterable of [compositeKey, HeadRecord] pairs from the remote peer
+     * @returns Counts of merged (updated) and skipped (local was newer or equal) entries
+     */
+    mergeSnapshot(snapshot: Iterable<readonly [string, HeadRecord]>): Promise<{
+        merged: number;
+        skipped: number;
+    }>;
+    /**
+     * Subscribe to external head changes — i.e. updates applied by
+     * mergeHeadUpdate() (inbound gossip).  The callback is NOT fired for local
+     * writes (setHead / removeHead) so Collection instances can distinguish
+     * their own writes from remote ones without risk of re-entrancy.
+     *
+     * @param dbName         - Database name to watch
+     * @param collectionName - Collection name to watch
+     * @param callback       - Invoked with the new blockId whenever a remote
+     *                         update is applied for this (db, collection) pair
+     * @returns An unsubscribe function — call it to remove the listener
+     *
+     * @see Requirements 2.2, 7.1
+     */
+    onHeadChange(dbName: string, collectionName: string, callback: (blockId: string) => void): () => void;
 }
 //# sourceMappingURL=headRegistry.d.ts.map

package/src/lib/interfaces/storage/headRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"headRegistry.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/storage/headRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,wBAAwB;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,0BAA0B;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,SAAS,EAAE,IAAI,CAAC;CACjB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAEpE;;;;;;;;OAQG;IACH,OAAO,CACL,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,WAAW,GACvB,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;OAMG;IACH,UAAU,CACR,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,UAAU,CAAC,EAAE,WAAW,GACvB,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;OAGG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtB;;;;;OAKG;IACH,WAAW,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEnC;;;;;;;;OAQG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAE3E;;;;;;;;;;;;;OAaG;IACH,eAAe,CACb,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,IAAI,EACf,UAAU,CAAC,EAAE,WAAW,GACvB,OAAO,CAAC,OAAO,CAAC,CAAC;IAEpB;;;;;;;;;;;OAWG;IACH,eAAe,CACb,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,IAAI,GACd,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;;;OAQG;IACH,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEvD;;;;OAIG;IACH,kBAAkB,IAAI,kBAAkB,EAAE,CAAC;CAC5C"}
+{"version":3,"file":"headRegistry.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/storage/headRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,wBAAwB;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,0BAA0B;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,SAAS,EAAE,IAAI,CAAC;CACjB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAEpE;;;;;;;;OAQG;IACH,OAAO,CACL,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,WAAW,GACvB,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;OAMG;IACH,UAAU,CACR,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,UAAU,CAAC,EAAE,WAAW,GACvB,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;OAGG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtB;;;;;OAKG;IACH,WAAW,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEnC;;;;;;;;OAQG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAE3E;;;;;;;;;;;;;OAaG;IACH,eAAe,CACb,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,IAAI,EACf,UAAU,CAAC,EAAE,WAAW,GACvB,OAAO,CAAC,OAAO,CAAC,CAAC;IAEpB;;;;;;;;;;;OAWG;IACH,eAAe,CACb,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,IAAI,GACd,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;;;OAQG;IACH,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEvD;;;;OAIG;IACH,kBAAkB,IAAI,kBAAkB,EAAE,CAAC;IAE3C;;;;OAIG;IACH,cAAc,IAAI,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAElD;;;;;;;;;;;OAWG;IACH,aAAa,CACX,QAAQ,EAAE,QAAQ,CAAC,SAAS,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,GAChD,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAEhD;;;;;;;;;;;;;OAaG;IACH,YAAY,CACV,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAClC,MAAM,IAAI,CAAC;CACf"}

package/src/lib/interfaces/storage/headRegistryDriver.d.ts

@@ -0,0 +1,47 @@
+/**
+ * IHeadRegistryDriver — pluggable per-key storage backend for head registries.
+ *
+ * Each (dbName, collectionName) pair maps to exactly one record. All operations
+ * are O(1) — there is no global lock and no full-collection rewrite.
+ *
+ * Implementations:
+ *  - InMemoryHeadRegistryDriver (brightchain-lib)  — Map-backed, browser-safe
+ *  - FileHeadRegistryDriver (brightchain-db)        — one .json file per key
+ *  - AzureBlobHeadRegistryDriver (brightchain-azure-store) — one blob per key
+ *  - S3HeadRegistryDriver (brightchain-s3-store)    — one object per key
+ */
+/** The value stored for a single (dbName, collectionName) head pointer. */
+export interface HeadRecord {
+    blockId: string;
+    /** ISO 8601 timestamp for last-writer-wins merge. */
+    timestamp: string;
+    /**
+     * Block ID of the previous HeadRecord block written to the block store,
+     * forming an immutable audit chain. Optional — set by callers that write
+     * head record blocks. Enables conflict resolution via common-ancestor walk
+     * (analogous to Git refs) and replicates for free with the block store.
+     */
+    prevHeadBlockId?: string;
+}
+export interface IHeadRegistryDriver {
+    /**
+     * Read the head record for the given composite key.
+     * Returns null if no record exists.
+     */
+    readRecord(key: string): Promise<HeadRecord | null>;
+    /**
+     * Write (create or overwrite) the head record for the given key.
+     */
+    writeRecord(key: string, record: HeadRecord): Promise<void>;
+    /**
+     * Delete the head record for the given key.
+     * Must not throw if the key does not exist.
+     */
+    deleteRecord(key: string): Promise<void>;
+    /**
+     * Return all stored keys.
+     * Used by load() to hydrate the in-memory cache on startup.
+     */
+    listKeys(): Promise<string[]>;
+}
+//# sourceMappingURL=headRegistryDriver.d.ts.map

package/src/lib/interfaces/storage/headRegistryDriver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headRegistryDriver.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/storage/headRegistryDriver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,2EAA2E;AAC3E,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAEpD;;OAEG;IACH,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5D;;;OAGG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzC;;;OAGG;IACH,QAAQ,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CAC/B"}

package/src/lib/interfaces/storage/headRegistryDriver.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * IHeadRegistryDriver — pluggable per-key storage backend for head registries.
+ *
+ * Each (dbName, collectionName) pair maps to exactly one record. All operations
+ * are O(1) — there is no global lock and no full-collection rewrite.
+ *
+ * Implementations:
+ *  - InMemoryHeadRegistryDriver (brightchain-lib)  — Map-backed, browser-safe
+ *  - FileHeadRegistryDriver (brightchain-db)        — one .json file per key
+ *  - AzureBlobHeadRegistryDriver (brightchain-azure-store) — one blob per key
+ *  - S3HeadRegistryDriver (brightchain-s3-store)    — one object per key
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=headRegistryDriver.js.map

package/src/lib/interfaces/storage/headRegistryDriver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"headRegistryDriver.js","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/storage/headRegistryDriver.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG"}

package/src/lib/interfaces/storage/index.d.ts

@@ -11,6 +11,7 @@ export type * from './documentStore';
 export type * from './encryptedPool';
 export { EncryptionMode } from './encryptedPool';
 export type * from './headRegistry';
+export type * from './headRegistryDriver';
 export type * from './memberIndexSchema';
 export type * from './mnemonicSchema';
 export type * from './pooledBlockStore';

package/src/lib/interfaces/storage/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/storage/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,iBAAiB,CAAC;AACrC,OAAO,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAC7D,mBAAmB,sBAAsB,CAAC;AAC1C,mBAAmB,cAAc,CAAC;AAClC,mBAAmB,YAAY,CAAC;AAChC,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,mBAAmB,YAAY,CAAC;AAChC,mBAAmB,gBAAgB,CAAC;AACpC,mBAAmB,yBAAyB,CAAC;AAC7C,mBAAmB,iBAAiB,CAAC;AACrC,mBAAmB,iBAAiB,CAAC;AACrC,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,mBAAmB,gBAAgB,CAAC;AACpC,mBAAmB,qBAAqB,CAAC;AACzC,mBAAmB,kBAAkB,CAAC;AACtC,mBAAmB,oBAAoB,CAAC;AACxC,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,eAAe,EACf,cAAc,GACf,MAAM,oBAAoB,CAAC;AAC5B,mBAAmB,yBAAyB,CAAC;AAC7C,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAClE,mBAAmB,cAAc,CAAC;AAClC,mBAAmB,uBAAuB,CAAC;AAC3C,mBAAmB,kBAAkB,CAAC;AACtC,mBAAmB,cAAc,CAAC;AAGlC,mBAAmB,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/storage/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,iBAAiB,CAAC;AACrC,OAAO,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAC7D,mBAAmB,sBAAsB,CAAC;AAC1C,mBAAmB,cAAc,CAAC;AAClC,mBAAmB,YAAY,CAAC;AAChC,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,mBAAmB,YAAY,CAAC;AAChC,mBAAmB,gBAAgB,CAAC;AACpC,mBAAmB,yBAAyB,CAAC;AAC7C,mBAAmB,iBAAiB,CAAC;AACrC,mBAAmB,iBAAiB,CAAC;AACrC,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,mBAAmB,gBAAgB,CAAC;AACpC,mBAAmB,sBAAsB,CAAC;AAC1C,mBAAmB,qBAAqB,CAAC;AACzC,mBAAmB,kBAAkB,CAAC;AACtC,mBAAmB,oBAAoB,CAAC;AACxC,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,eAAe,EACf,cAAc,GACf,MAAM,oBAAoB,CAAC;AAC5B,mBAAmB,yBAAyB,CAAC;AAC7C,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAClE,mBAAmB,cAAc,CAAC;AAClC,mBAAmB,uBAAuB,CAAC;AAC3C,mBAAmB,kBAAkB,CAAC;AACtC,mBAAmB,cAAc,CAAC;AAGlC,mBAAmB,iBAAiB,CAAC"}

package/src/lib/interfaces/storage/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/storage/index.ts"],"names":[],"mappings":";;;AACA,iDAA6D;AAApD,2HAAA,0BAA0B,OAAA;AAInC,uCAA2C;AAAlC,yGAAA,aAAa,OAAA;AAMtB,iDAAiD;AAAxC,+GAAA,cAAc,OAAA;AAKvB,uDAO4B;AAN1B,gHAAA,YAAY,OAAA;AACZ,sHAAA,kBAAkB,OAAA;AAClB,iHAAA,aAAa,OAAA;AACb,kHAAA,cAAc,OAAA;AACd,mHAAA,eAAe,OAAA;AACf,kHAAA,cAAc,OAAA;AAGhB,iEAAkE;AAAzD,gIAAA,uBAAuB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/storage/index.ts"],"names":[],"mappings":";;;AACA,iDAA6D;AAApD,2HAAA,0BAA0B,OAAA;AAInC,uCAA2C;AAAlC,yGAAA,aAAa,OAAA;AAMtB,iDAAiD;AAAxC,+GAAA,cAAc,OAAA;AAMvB,uDAO4B;AAN1B,gHAAA,YAAY,OAAA;AACZ,sHAAA,kBAAkB,OAAA;AAClB,iHAAA,aAAa,OAAA;AACb,kHAAA,cAAc,OAAA;AACd,mHAAA,eAAe,OAAA;AACf,kHAAA,cAAc,OAAA;AAGhB,iEAAkE;AAAzD,gIAAA,uBAAuB,OAAA"}

package/src/lib/joule/formatJoule.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Scale-aware Joule formatter and parser.
+ *
+ * Rules (Req 7.7):
+ *  - ≥ 1 J  → render in J, up to 6 decimal places (trailing zeros trimmed
+ *              unless `opts.trim === false`).
+ *  - ≥ 1 mJ → render in mJ (3 µJ = 1 mJ = 1_000 µJ).
+ *  - otherwise → render in µJ with no decimal point.
+ *
+ * All arithmetic is bigint — `Number()` is NEVER used on µJ amounts.
+ * `parseJoule` is the exact inverse of `formatJoule` for round-trip fidelity.
+ *
+ * @see joule-resource-credits spec, Requirement 7.7
+ */
+export interface IFormatJouleOptions {
+    /**
+     * Trim trailing decimal zeros from fractional parts.
+     * Defaults to `true`.
+     */
+    trim?: boolean;
+}
+/**
+ * Format a µJ bigint amount as a human-readable string at the most
+ * appropriate scale (J, mJ, or µJ).
+ *
+ * Negative amounts render with a leading `-`.
+ *
+ * @example
+ * formatJoule(2_500_000n)  // '2.5 J'
+ * formatJoule(1_500n)      // '1.5 mJ'
+ * formatJoule(42n)         // '42 µJ'
+ */
+export declare function formatJoule(microJoules: bigint, opts?: IFormatJouleOptions): string;
+/**
+ * Parse a string produced by `formatJoule` back into µJ as a bigint.
+ *
+ * This is the exact inverse of `formatJoule` with default options (trim=true).
+ * Designed for test round-trips and serialization boundaries only;
+ * UI display layers should call `formatJoule` exclusively.
+ *
+ * @throws {Error} if the string cannot be parsed.
+ */
+export declare function parseJoule(formatted: string): bigint;
+//# sourceMappingURL=formatJoule.d.ts.map

package/src/lib/joule/formatJoule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatJoule.d.ts","sourceRoot":"","sources":["../../../../../brightchain-lib/src/lib/joule/formatJoule.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAOH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CACzB,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,mBAAmB,GACzB,MAAM,CAmCR;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAqBpD"}

package/src/lib/joule/formatJoule.js

@@ -0,0 +1,121 @@
+"use strict";
+/**
+ * Scale-aware Joule formatter and parser.
+ *
+ * Rules (Req 7.7):
+ *  - ≥ 1 J  → render in J, up to 6 decimal places (trailing zeros trimmed
+ *              unless `opts.trim === false`).
+ *  - ≥ 1 mJ → render in mJ (3 µJ = 1 mJ = 1_000 µJ).
+ *  - otherwise → render in µJ with no decimal point.
+ *
+ * All arithmetic is bigint — `Number()` is NEVER used on µJ amounts.
+ * `parseJoule` is the exact inverse of `formatJoule` for round-trip fidelity.
+ *
+ * @see joule-resource-credits spec, Requirement 7.7
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatJoule = formatJoule;
+exports.parseJoule = parseJoule;
+const jouleConstants_1 = require("./jouleConstants");
+/** µJ per mJ */
+const MICROJOULES_PER_MILLIJOULE = 1000n;
+/**
+ * Format a µJ bigint amount as a human-readable string at the most
+ * appropriate scale (J, mJ, or µJ).
+ *
+ * Negative amounts render with a leading `-`.
+ *
+ * @example
+ * formatJoule(2_500_000n)  // '2.5 J'
+ * formatJoule(1_500n)      // '1.5 mJ'
+ * formatJoule(42n)         // '42 µJ'
+ */
+function formatJoule(microJoules, opts) {
+    const trim = opts?.trim !== false; // default true
+    const negative = microJoules < 0n;
+    const abs = negative ? -microJoules : microJoules;
+    const sign = negative ? '-' : '';
+    if (abs === 0n) {
+        return '0.00 J';
+    }
+    if (abs >= jouleConstants_1.JOULE_MICROUNITS_PER_UNIT) {
+        // J scale — 6 decimal places, bigint division
+        const wholeJ = abs / jouleConstants_1.JOULE_MICROUNITS_PER_UNIT;
+        const remainder = abs % jouleConstants_1.JOULE_MICROUNITS_PER_UNIT;
+        const fracStr = remainder.toString().padStart(6, '0');
+        const fracTrimmed = trim ? fracStr.replace(/0+$/, '') : fracStr;
+        const body = fracTrimmed.length > 0 ? `${wholeJ}.${fracTrimmed}` : wholeJ.toString();
+        return `${sign}${body} J`;
+    }
+    if (abs >= MICROJOULES_PER_MILLIJOULE) {
+        // mJ scale — 3 decimal places
+        const wholeMJ = abs / MICROJOULES_PER_MILLIJOULE;
+        const remainder = abs % MICROJOULES_PER_MILLIJOULE;
+        const fracStr = remainder.toString().padStart(3, '0');
+        const fracTrimmed = trim ? fracStr.replace(/0+$/, '') : fracStr;
+        const body = fracTrimmed.length > 0 ? `${wholeMJ}.${fracTrimmed}` : wholeMJ.toString();
+        return `${sign}${body} mJ`;
+    }
+    // µJ scale — exact integer
+    return `${sign}${abs} µJ`;
+}
+/**
+ * Parse a string produced by `formatJoule` back into µJ as a bigint.
+ *
+ * This is the exact inverse of `formatJoule` with default options (trim=true).
+ * Designed for test round-trips and serialization boundaries only;
+ * UI display layers should call `formatJoule` exclusively.
+ *
+ * @throws {Error} if the string cannot be parsed.
+ */
+function parseJoule(formatted) {
+    const s = formatted.trim();
+    if (s.endsWith(' J')) {
+        return parseScaled(s.slice(0, -2).trim(), jouleConstants_1.JOULE_MICROUNITS_PER_UNIT, 6);
+    }
+    if (s.endsWith(' mJ')) {
+        return parseScaled(s.slice(0, -3).trim(), MICROJOULES_PER_MILLIJOULE, 3);
+    }
+    if (s.endsWith(' µJ')) {
+        const inner = s.slice(0, -3).trim();
+        const negative = inner.startsWith('-');
+        const digits = negative ? inner.slice(1) : inner;
+        if (!/^\d+$/.test(digits)) {
+            throw new Error(`parseJoule: invalid µJ value: ${JSON.stringify(s)}`);
+        }
+        const val = BigInt(digits);
+        return negative ? -val : val;
+    }
+    throw new Error(`parseJoule: unrecognized format: ${JSON.stringify(s)}`);
+}
+/**
+ * Helper: parse `"<integer>[.<fraction>]"` and return the value scaled
+ * to µJ using the given multiplier.
+ */
+function parseScaled(numStr, multiplier, maxFracDigits) {
+    const negative = numStr.startsWith('-');
+    const abs = negative ? numStr.slice(1) : numStr;
+    const dotIdx = abs.indexOf('.');
+    let intPart;
+    let fracPart;
+    if (dotIdx === -1) {
+        intPart = abs;
+        fracPart = '';
+    }
+    else {
+        intPart = abs.slice(0, dotIdx);
+        fracPart = abs.slice(dotIdx + 1);
+    }
+    if (!/^\d*$/.test(intPart) || !/^\d*$/.test(fracPart)) {
+        throw new Error(`parseJoule: invalid number: ${JSON.stringify(numStr)}`);
+    }
+    // Pad or truncate fractional part to maxFracDigits
+    const paddedFrac = fracPart
+        .padEnd(maxFracDigits, '0')
+        .slice(0, maxFracDigits);
+    const intBig = intPart.length > 0 ? BigInt(intPart) : 0n;
+    const fracBig = paddedFrac.length > 0 ? BigInt(paddedFrac) : 0n;
+    const val = intBig * multiplier + fracBig;
+    return negative ? -val : val;
+}
+//# sourceMappingURL=formatJoule.js.map

package/src/lib/joule/formatJoule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatJoule.js","sourceRoot":"","sources":["../../../../../brightchain-lib/src/lib/joule/formatJoule.ts"],"names":[],"mappings":"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"}

package/src/lib/joule/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Joule resource-credit primitives — browser-safe barrel export.
+ *
+ * @see joule-resource-credits spec, Phase 1
+ */
+export * from './formatJoule';
+export * from './jouleConstants';
+export * from './rateTable';
+export * from './resourceClass';
+//# sourceMappingURL=index.d.ts.map

package/src/lib/joule/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../brightchain-lib/src/lib/joule/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC"}

package/src/lib/joule/index.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * Joule resource-credit primitives — browser-safe barrel export.
+ *
+ * @see joule-resource-credits spec, Phase 1
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./formatJoule"), exports);
+tslib_1.__exportStar(require("./jouleConstants"), exports);
+tslib_1.__exportStar(require("./rateTable"), exports);
+tslib_1.__exportStar(require("./resourceClass"), exports);
+//# sourceMappingURL=index.js.map

package/src/lib/joule/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../brightchain-lib/src/lib/joule/index.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAEH,wDAA8B;AAC9B,2DAAiC;AACjC,sDAA4B;AAC5B,0DAAgC"}

package/src/lib/joule/jouleConstants.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Joule resource-credit constants.
+ *
+ * Re-exports from the asset primitives module and adds the narrow `as const`
+ * type forms required by the joule-resource-credits spec (Req 1.1).
+ *
+ * All internal arithmetic uses bigint microjoules; these constants are the
+ * single source of truth for the Joule asset identity.
+ */
+export { JOULE_ASSET_ID, JOULE_DECIMALS, JOULE_MICROUNITS_PER_UNIT, JOULE_SYMBOL, } from '../asset/jouleConstants';
+/** Narrowly typed assetId literal — use for brand-checked comparisons. */
+export type JouleAssetId = 'joule';
+//# sourceMappingURL=jouleConstants.d.ts.map

package/src/lib/joule/jouleConstants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jouleConstants.d.ts","sourceRoot":"","sources":["../../../../../brightchain-lib/src/lib/joule/jouleConstants.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,cAAc,EACd,cAAc,EACd,yBAAyB,EACzB,YAAY,GACb,MAAM,yBAAyB,CAAC;AAEjC,0EAA0E;AAC1E,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC"}

package/src/lib/joule/jouleConstants.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * Joule resource-credit constants.
+ *
+ * Re-exports from the asset primitives module and adds the narrow `as const`
+ * type forms required by the joule-resource-credits spec (Req 1.1).
+ *
+ * All internal arithmetic uses bigint microjoules; these constants are the
+ * single source of truth for the Joule asset identity.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JOULE_SYMBOL = exports.JOULE_MICROUNITS_PER_UNIT = exports.JOULE_DECIMALS = exports.JOULE_ASSET_ID = void 0;
+var jouleConstants_1 = require("../asset/jouleConstants");
+Object.defineProperty(exports, "JOULE_ASSET_ID", { enumerable: true, get: function () { return jouleConstants_1.JOULE_ASSET_ID; } });
+Object.defineProperty(exports, "JOULE_DECIMALS", { enumerable: true, get: function () { return jouleConstants_1.JOULE_DECIMALS; } });
+Object.defineProperty(exports, "JOULE_MICROUNITS_PER_UNIT", { enumerable: true, get: function () { return jouleConstants_1.JOULE_MICROUNITS_PER_UNIT; } });
+Object.defineProperty(exports, "JOULE_SYMBOL", { enumerable: true, get: function () { return jouleConstants_1.JOULE_SYMBOL; } });
+//# sourceMappingURL=jouleConstants.js.map

package/src/lib/joule/jouleConstants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jouleConstants.js","sourceRoot":"","sources":["../../../../../brightchain-lib/src/lib/joule/jouleConstants.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAEH,0DAKiC;AAJ/B,gHAAA,cAAc,OAAA;AACd,gHAAA,cAAc,OAAA;AACd,2HAAA,yBAAyB,OAAA;AACzB,8GAAA,YAAY,OAAA"}

package/src/lib/joule/rateTable.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Rate table primitives for Joule resource-credit metering.
+ *
+ * A `IRateTable` maps each `ResourceClass` to a `µJ-per-unit` price.
+ * All arithmetic is `bigint`; no floating-point is introduced.
+ *
+ * @see joule-resource-credits spec, Requirement 1.1, 1.6
+ */
+import { ResourceClass } from './resourceClass';
+/**
+ * Per-class pricing row inside a rate table.
+ */
+export interface IRateTableEntry {
+    /** Denominator unit string, e.g. `'request'`, `'MB-day'`, `'MB-out'`. */
+    unit: string;
+    /** Cost per one unit expressed in µJ (bigint). */
+    microJoulesPerUnit: bigint;
+    /** Human-readable description of what this class covers. */
+    description: string;
+}
+/**
+ * Versioned, signed rate table.
+ *
+ * Once recorded on-ledger, a rate table is immutable.
+ * Historical pricing is preserved so that per-request events can
+ * reference the version that was active at emit time (Req 1.3).
+ */
+export interface IRateTable {
+    /** Monotonically increasing, starting at 1. */
+    version: number;
+    /** Unix milliseconds at which this table becomes effective. */
+    effectiveAt: number;
+    /** One entry per resource class. All four v1 classes must be present. */
+    entries: Record<ResourceClass, IRateTableEntry>;
+    /** Operator quorum key fingerprints that signed this table. */
+    signedBy: ReadonlyArray<string>;
+}
+/**
+ * Compute the µJ cost for `units` of resource class `cls` under `rate`.
+ *
+ * Formula: `microJoules = units * microJoulesPerUnit` (bigint, exact).
+ *
+ * @see joule-resource-credits spec, Requirement 1.6
+ */
+export declare function priceMicroJoules(rate: IRateTable, cls: ResourceClass, units: bigint): bigint;
+/**
+ * Default bootstrap rate table (version 1).
+ *
+ * Rates are intentionally conservative placeholders; the operator quorum
+ * SHOULD submit a `RateTableUpdateAction` before opening to members.
+ *
+ * @see joule-resource-credits spec, Requirement 1.1
+ */
+export declare const BOOTSTRAP_RATE_TABLE: Readonly<IRateTable>;
+//# sourceMappingURL=rateTable.d.ts.map