@brightchain/brightchain-lib 0.13.0 → 0.15.0

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

@@ -1,6 +1,7 @@
 import { RawDataBlock } from '../../blocks/rawData';
 import { DurabilityLevel } from '../../enumerations/durabilityLevel';
 import { ReplicationStatus } from '../../enumerations/replicationStatus';
+import { PoolId } from './pooledBlockStore';
 /**
  * Block metadata including durability, parity, and replication information.
  * This metadata is stored alongside block data to track lifecycle, access patterns,
@@ -56,6 +57,11 @@ export interface IBlockMetadata {
      * Checksum of the block data (hex encoded)
      */
     checksum: string;
+    /**
+     * Optional pool identifier for pool-scoped blocks.
+     * When set, indicates which pool this block belongs to.
+     */
+    poolId?: PoolId;
 }
 /**
  * Options for storing a block with durability and replication settings
@@ -118,7 +124,8 @@ export interface BrightenResult {
  * @param size - The size of the block data in bytes
  * @param checksum - The checksum of the block data
  * @param options - Optional storage options
+ * @param poolId - Optional pool identifier for pool-scoped blocks
  * @returns Default metadata for the block
  */
-export declare function createDefaultBlockMetadata(blockId: string, size: number, checksum: string, options?: BlockStoreOptions): IBlockMetadata;
+export declare function createDefaultBlockMetadata(blockId: string, size: number, checksum: string, options?: BlockStoreOptions, poolId?: PoolId): IBlockMetadata;
 //# sourceMappingURL=blockMetadata.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"blockMetadata.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/storage/blockMetadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AAEzE;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,SAAS,EAAE,IAAI,CAAC;IAEhB;;;OAGG;IACH,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;IAEvB;;OAEG;IACH,eAAe,EAAE,eAAe,CAAC;IAEjC;;OAEG;IACH,cAAc,EAAE,MAAM,EAAE,CAAC;IAEzB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,cAAc,EAAE,IAAI,CAAC;IAErB;;OAEG;IACH,iBAAiB,EAAE,iBAAiB,CAAC;IAErC;;OAEG;IACH,uBAAuB,EAAE,MAAM,CAAC;IAEhC;;OAEG;IACH,cAAc,EAAE,MAAM,EAAE,CAAC;IAEzB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,SAAS,CAAC,EAAE,IAAI,CAAC;IAEjB;;;OAGG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAElC;;;OAGG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,cAAc,CAAC,EAAE,YAAY,CAAC;IAE9B;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,cAAc,EAAE,MAAM,EAAE,CAAC;IAEzB;;OAEG;IACH,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,cAAc,CAgBhB"}
+{"version":3,"file":"blockMetadata.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/storage/blockMetadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AAEzE,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE5C;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,SAAS,EAAE,IAAI,CAAC;IAEhB;;;OAGG;IACH,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;IAEvB;;OAEG;IACH,eAAe,EAAE,eAAe,CAAC;IAEjC;;OAEG;IACH,cAAc,EAAE,MAAM,EAAE,CAAC;IAEzB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,cAAc,EAAE,IAAI,CAAC;IAErB;;OAEG;IACH,iBAAiB,EAAE,iBAAiB,CAAC;IAErC;;OAEG;IACH,uBAAuB,EAAE,MAAM,CAAC;IAEhC;;OAEG;IACH,cAAc,EAAE,MAAM,EAAE,CAAC;IAEzB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,SAAS,CAAC,EAAE,IAAI,CAAC;IAEjB;;;OAGG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAElC;;;OAGG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,cAAc,CAAC,EAAE,YAAY,CAAC;IAE9B;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,cAAc,EAAE,MAAM,EAAE,CAAC;IAEzB;;OAEG;IACH,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,iBAAiB,EAC3B,MAAM,CAAC,EAAE,MAAM,GACd,cAAc,CAiBhB"}

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

@@ -9,9 +9,10 @@ const replicationStatus_1 = require("../../enumerations/replicationStatus");
  * @param size - The size of the block data in bytes
  * @param checksum - The checksum of the block data
  * @param options - Optional storage options
+ * @param poolId - Optional pool identifier for pool-scoped blocks
  * @returns Default metadata for the block
  */
-function createDefaultBlockMetadata(blockId, size, checksum, options) {
+function createDefaultBlockMetadata(blockId, size, checksum, options, poolId) {
     const now = new Date();
     return {
         blockId,
@@ -26,6 +27,7 @@ function createDefaultBlockMetadata(blockId, size, checksum, options) {
         replicaNodeIds: [],
         size,
         checksum,
+        ...(poolId !== undefined ? { poolId } : {}),
     };
 }
 //# sourceMappingURL=blockMetadata.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"blockMetadata.js","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/storage/blockMetadata.ts"],"names":[],"mappings":";;AAgJA,gEAqBC;AApKD,wEAAqE;AACrE,4EAAyE;AAsIzE;;;;;;;GAOG;AACH,SAAgB,0BAA0B,CACxC,OAAe,EACf,IAAY,EACZ,QAAgB,EAChB,OAA2B;IAE3B,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,OAAO;QACL,OAAO;QACP,SAAS,EAAE,GAAG;QACd,SAAS,EAAE,OAAO,EAAE,SAAS,IAAI,IAAI;QACrC,eAAe,EAAE,OAAO,EAAE,eAAe,IAAI,iCAAe,CAAC,QAAQ;QACrE,cAAc,EAAE,EAAE;QAClB,WAAW,EAAE,CAAC;QACd,cAAc,EAAE,GAAG;QACnB,iBAAiB,EAAE,qCAAiB,CAAC,OAAO;QAC5C,uBAAuB,EAAE,OAAO,EAAE,uBAAuB,IAAI,CAAC;QAC9D,cAAc,EAAE,EAAE;QAClB,IAAI;QACJ,QAAQ;KACT,CAAC;AACJ,CAAC"}
+{"version":3,"file":"blockMetadata.js","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/storage/blockMetadata.ts"],"names":[],"mappings":";;AAyJA,gEAuBC;AA/KD,wEAAqE;AACrE,4EAAyE;AA8IzE;;;;;;;;GAQG;AACH,SAAgB,0BAA0B,CACxC,OAAe,EACf,IAAY,EACZ,QAAgB,EAChB,OAA2B,EAC3B,MAAe;IAEf,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,OAAO;QACL,OAAO;QACP,SAAS,EAAE,GAAG;QACd,SAAS,EAAE,OAAO,EAAE,SAAS,IAAI,IAAI;QACrC,eAAe,EAAE,OAAO,EAAE,eAAe,IAAI,iCAAe,CAAC,QAAQ;QACrE,cAAc,EAAE,EAAE;QAClB,WAAW,EAAE,CAAC;QACd,cAAc,EAAE,GAAG;QACnB,iBAAiB,EAAE,qCAAiB,CAAC,OAAO;QAC5C,uBAAuB,EAAE,OAAO,EAAE,uBAAuB,IAAI,CAAC;QAC9D,cAAc,EAAE,EAAE;QAClB,IAAI;QACJ,QAAQ;QACR,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5C,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,141 @@
+/**
+ * CBL Index interfaces for tracking whitened CBL storage results.
+ *
+ * The CBL Index is a higher-level registry — distinct from ICBLStore which
+ * handles raw CBL block storage. It tracks magnet URLs, block ID pairs,
+ * metadata, pool scoping, user-level organization, and file version history.
+ *
+ * All interfaces use generic type parameters for DTO flexibility:
+ * - Frontend: TId = string
+ * - Backend: TId = GuidV4Buffer or similar
+ */
+import type { PoolId } from './pooledBlockStore';
+/**
+ * Visibility levels for CBL index entries.
+ * Controls who can see and access a CBL entry.
+ */
+export declare enum CBLVisibility {
+    /** Only the creator can see this entry */
+    Private = "private",
+    /** Creator and explicitly shared users can see this entry */
+    Shared = "shared",
+    /** All pool members can see this entry */
+    Public = "public"
+}
+/**
+ * Optional user-facing metadata attached to a CBL index entry.
+ */
+export interface ICBLMetadata {
+    /** Original file name */
+    fileName?: string;
+    /** MIME type of the original content */
+    mimeType?: string;
+    /** Original uncompressed size in bytes */
+    originalSize?: number;
+    /** User-defined tags for categorization */
+    tags?: string[];
+}
+/**
+ * A CBL index entry tracking a whitened CBL storage result.
+ *
+ * Generic TId allows string for frontend DTO, or a buffer type for backend.
+ */
+export interface ICBLIndexEntry<TId = string> {
+    /** Unique entry ID */
+    _id: string;
+    /** Full magnet URL for CBL reconstruction */
+    magnetUrl: string;
+    /** First XOR component block ID (hex) */
+    blockId1: string;
+    /** Second XOR component block ID (hex) */
+    blockId2: string;
+    /** Block size used for storage */
+    blockSize: number;
+    /** Pool this CBL belongs to (undefined = default pool) */
+    poolId?: PoolId;
+    /** When the CBL was stored */
+    createdAt: Date;
+    /** Member ID of the creator */
+    createdBy?: TId;
+    /** Visibility level */
+    visibility: CBLVisibility;
+    /** Soft-delete timestamp (undefined = not deleted) */
+    deletedAt?: Date;
+    /** Optional user-facing metadata */
+    metadata?: ICBLMetadata;
+    /** FEC parity block IDs for each XOR component */
+    parityBlockIds?: {
+        block1: string[];
+        block2: string[];
+    };
+    /** User collection/folder this entry belongs to */
+    userCollection?: string;
+    /** Users this CBL is shared with (for Shared visibility) */
+    sharedWith?: TId[];
+    /** Sequence number for sync ordering */
+    sequenceNumber: number;
+    /** Stable ID grouping all versions of the same logical file */
+    fileId?: string;
+    /** Version number within the file group (1-based positive integer) */
+    versionNumber?: number;
+    /** Magnet URL of the previous version (audit chain) */
+    previousVersion?: string;
+    /** Encrypted field values (base64-encoded ciphertext), keyed by field name */
+    encryptedFields?: Record<string, string>;
+    /**
+     * Whether this entry has a conflict with another entry sharing the same magnet URL.
+     * Set during cross-node merge when the same magnet URL arrives with different content.
+     *
+     * @see Requirements 8.3
+     */
+    hasConflict?: boolean;
+    /**
+     * Entry IDs of conflicting entries that share the same magnet URL.
+     * Populated during cross-node merge for conflict resolution tracking.
+     *
+     * @see Requirements 8.3
+     */
+    conflictsWith?: string[];
+}
+/**
+ * Query options for searching and filtering CBL index entries.
+ * All filter fields are optional; only specified fields are applied.
+ */
+export interface ICBLIndexQueryOptions {
+    /** Filter by pool ID */
+    poolId?: string;
+    /** Filter by creator member ID */
+    createdBy?: string;
+    /** Filter by visibility level */
+    visibility?: CBLVisibility;
+    /** Filter by user collection/folder name */
+    userCollection?: string;
+    /** Filter by file name (from metadata) */
+    fileName?: string;
+    /** Filter by MIME type (from metadata) */
+    mimeType?: string;
+    /** Filter by tags (entries must have all specified tags) */
+    tags?: string[];
+    /** Filter by file ID (version group) */
+    fileId?: string;
+    /** Include soft-deleted entries (default: false) */
+    includeDeleted?: boolean;
+    /** Maximum number of entries to return */
+    limit?: number;
+    /** Number of entries to skip (for pagination) */
+    offset?: number;
+    /** Field to sort results by */
+    sortBy?: 'createdAt' | 'fileName' | 'originalSize' | 'versionNumber';
+    /** Sort direction */
+    sortOrder?: 'asc' | 'desc';
+    /**
+     * When set, applies visibility-based access control filtering:
+     * - Private entries: only returned if createdBy === requestingUserId
+     * - Shared entries: only returned if createdBy === requestingUserId OR sharedWith includes requestingUserId
+     * - Public entries: always returned
+     *
+     * When not set, no visibility access control is applied (all matching entries returned).
+     */
+    requestingUserId?: string;
+}
+//# sourceMappingURL=cblIndex.d.ts.map

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

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

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

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * CBL Index interfaces for tracking whitened CBL storage results.
+ *
+ * The CBL Index is a higher-level registry — distinct from ICBLStore which
+ * handles raw CBL block storage. It tracks magnet URLs, block ID pairs,
+ * metadata, pool scoping, user-level organization, and file version history.
+ *
+ * All interfaces use generic type parameters for DTO flexibility:
+ * - Frontend: TId = string
+ * - Backend: TId = GuidV4Buffer or similar
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CBLVisibility = void 0;
+/**
+ * Visibility levels for CBL index entries.
+ * Controls who can see and access a CBL entry.
+ */
+var CBLVisibility;
+(function (CBLVisibility) {
+    /** Only the creator can see this entry */
+    CBLVisibility["Private"] = "private";
+    /** Creator and explicitly shared users can see this entry */
+    CBLVisibility["Shared"] = "shared";
+    /** All pool members can see this entry */
+    CBLVisibility["Public"] = "public";
+})(CBLVisibility || (exports.CBLVisibility = CBLVisibility = {}));
+//# sourceMappingURL=cblIndex.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cblIndex.js","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/storage/cblIndex.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AAIH;;;GAGG;AACH,IAAY,aAOX;AAPD,WAAY,aAAa;IACvB,0CAA0C;IAC1C,oCAAmB,CAAA;IACnB,6DAA6D;IAC7D,kCAAiB,CAAA;IACjB,0CAA0C;IAC1C,kCAAiB,CAAA;AACnB,CAAC,EAPW,aAAa,6BAAb,aAAa,QAOxB"}

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

@@ -0,0 +1,22 @@
+/**
+ * Storage-agnostic client session interface for transaction support.
+ *
+ * Both brightchain-db's DbSession and mongoose-based session adapters
+ * implement this interface, allowing transaction-aware code to work
+ * with any database backend.
+ */
+export interface IClientSession {
+    /** Unique session ID */
+    readonly id: string;
+    /** Whether a transaction is currently active */
+    readonly inTransaction: boolean;
+    /** Start a new transaction */
+    startTransaction(): void;
+    /** Commit the current transaction */
+    commitTransaction(): Promise<void>;
+    /** Abort the current transaction */
+    abortTransaction(): Promise<void>;
+    /** End the session */
+    endSession(): void;
+}
+//# sourceMappingURL=clientSession.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"clientSession.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/storage/clientSession.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,wBAAwB;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,8BAA8B;IAC9B,gBAAgB,IAAI,IAAI,CAAC;IACzB,qCAAqC;IACrC,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,oCAAoC;IACpC,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,sBAAsB;IACtB,UAAU,IAAI,IAAI,CAAC;CACpB"}

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

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

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

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

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

@@ -0,0 +1,80 @@
+/**
+ * Storage-agnostic collection interface for document CRUD, query, index,
+ * aggregation, schema validation, and lifecycle operations.
+ *
+ * Both brightchain-db's Collection and mongoose-based collection adapters
+ * implement this interface, allowing collection-level code to work with
+ * any database backend.
+ */
+import { AggregationStage, BsonDocument, BulkWriteOperation, BulkWriteOptions, BulkWriteResult, ChangeListener, CollectionSchema, DeleteResult, DocumentId, FilterQuery, FindOptions, IndexOptions, IndexSpec, InsertManyResult, InsertOneResult, ReadPreference, ReplaceResult, TextIndexOptions, UpdateOptions, UpdateQuery, UpdateResult, ValidationFieldError, WriteConcern, WriteOptions } from './documentTypes';
+export interface ICollection<T extends BsonDocument = BsonDocument> {
+    /** Insert a single document. */
+    insertOne(doc: T, options?: WriteOptions): Promise<InsertOneResult>;
+    /** Insert multiple documents. */
+    insertMany(docs: T[], options?: WriteOptions): Promise<InsertManyResult>;
+    /** Find the first document matching the filter. */
+    findOne(filter?: FilterQuery<T>, options?: FindOptions<T>): Promise<T | null>;
+    /**
+     * Find all documents matching the filter.
+     *
+     * Return type is `T[] | PromiseLike<T[]>` to accommodate both synchronous
+     * in-memory results (brightchain-db Cursor, which is thenable) and async
+     * mongoose queries.
+     */
+    find(filter?: FilterQuery<T>, options?: FindOptions<T>): T[] | PromiseLike<T[]>;
+    /** Find a document by its `_id`. */
+    findById(id: DocumentId): Promise<T | null>;
+    /** Update the first document matching the filter. */
+    updateOne(filter: FilterQuery<T>, update: UpdateQuery<T>, options?: UpdateOptions): Promise<UpdateResult>;
+    /** Update all documents matching the filter. */
+    updateMany(filter: FilterQuery<T>, update: UpdateQuery<T>, options?: UpdateOptions): Promise<UpdateResult>;
+    /** Delete the first document matching the filter. */
+    deleteOne(filter: FilterQuery<T>, options?: WriteOptions): Promise<DeleteResult>;
+    /** Delete all documents matching the filter. */
+    deleteMany(filter: FilterQuery<T>, options?: WriteOptions): Promise<DeleteResult>;
+    /** Replace the first document matching the filter. */
+    replaceOne(filter: FilterQuery<T>, doc: T, options?: UpdateOptions): Promise<ReplaceResult>;
+    /** Count documents matching the filter. */
+    countDocuments(filter?: FilterQuery<T>): Promise<number>;
+    /** Estimated total document count (may be faster than countDocuments). */
+    estimatedDocumentCount(): Promise<number>;
+    /** Return distinct values for a field, optionally filtered. */
+    distinct<K extends keyof T>(field: K, filter?: FilterQuery<T>): Promise<Array<T[K]>>;
+    /** Run an aggregation pipeline. */
+    aggregate(pipeline: AggregationStage[]): Promise<BsonDocument[]>;
+    /** Create an index on the collection. Returns the index name. */
+    createIndex(spec: IndexSpec, options?: IndexOptions): Promise<string>;
+    /** Drop an index by name. */
+    dropIndex(name: string): Promise<void>;
+    /** List all index names on this collection. */
+    listIndexes(): string[];
+    /** Execute multiple write operations in bulk. */
+    bulkWrite(operations: BulkWriteOperation<T>[], options?: BulkWriteOptions): Promise<BulkWriteResult>;
+    /** Watch for changes on this collection. Returns an unsubscribe function. */
+    watch(listener: ChangeListener<T>): () => void;
+    /** Set a validation schema for this collection. */
+    setSchema(schema: CollectionSchema): void;
+    /** Get the current validation schema (if any). */
+    getSchema(): CollectionSchema | undefined;
+    /** Remove the validation schema. */
+    removeSchema(): void;
+    /** Validate a document against the current schema. */
+    validateDoc(doc: T): ValidationFieldError[];
+    /** Get the current write concern. */
+    getWriteConcern(): WriteConcern;
+    /** Set the write concern for this collection. */
+    setWriteConcern(wc: WriteConcern): void;
+    /** Get the current read preference. */
+    getReadPreference(): ReadPreference;
+    /** Set the read preference for this collection. */
+    setReadPreference(rp: ReadPreference): void;
+    /** Create a text index. Returns the index name. */
+    createTextIndex(options: TextIndexOptions): string;
+    /** Drop the text index. */
+    dropTextIndex(): void;
+    /** Whether a text index exists on this collection. */
+    hasTextIndex(): boolean;
+    /** Drop this collection and all its data. */
+    drop(): Promise<void>;
+}
+//# sourceMappingURL=collection.d.ts.map

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

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

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

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

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

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

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

@@ -0,0 +1,30 @@
+/**
+ * Storage-agnostic database interface for collection access, session/transaction
+ * management, and connection lifecycle.
+ *
+ * Both brightchain-db's BrightChainDb and mongoose-based database adapters
+ * implement this interface, allowing application code to work with any
+ * database backend through a single contract.
+ */
+import { IClientSession } from './clientSession';
+import { ICollection } from './collection';
+import { BsonDocument, CollectionOptions } from './documentTypes';
+export interface IDatabase {
+    /** Get or create a collection by name. */
+    collection<T extends BsonDocument = BsonDocument>(name: string, options?: CollectionOptions): ICollection<T>;
+    /** Start a client session for transaction support. */
+    startSession(): IClientSession;
+    /** Run a callback within a transaction (auto-commit/abort). */
+    withTransaction<R>(fn: (session: IClientSession) => Promise<R>): Promise<R>;
+    /** List all known collection names. */
+    listCollections(): string[];
+    /** Drop a collection by name. */
+    dropCollection(name: string): Promise<boolean>;
+    /** Connect to the backing store. URI may be ignored by non-network stores. */
+    connect(uri?: string): Promise<void>;
+    /** Disconnect from the backing store. */
+    disconnect(): Promise<void>;
+    /** Whether the store is currently connected. */
+    isConnected(): boolean;
+}
+//# sourceMappingURL=database.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/storage/database.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAElE,MAAM,WAAW,SAAS;IACxB,0CAA0C;IAC1C,UAAU,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EAC9C,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,iBAAiB,GAC1B,WAAW,CAAC,CAAC,CAAC,CAAC;IAElB,sDAAsD;IACtD,YAAY,IAAI,cAAc,CAAC;IAE/B,+DAA+D;IAC/D,eAAe,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAE5E,uCAAuC;IACvC,eAAe,IAAI,MAAM,EAAE,CAAC;IAE5B,iCAAiC;IACjC,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE/C,8EAA8E;IAC9E,OAAO,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErC,yCAAyC;IACzC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5B,gDAAgD;IAChD,WAAW,IAAI,OAAO,CAAC;CACxB"}

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

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

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

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

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

@@ -0,0 +1,43 @@
+import { IFailableResult } from '../failableResult';
+/**
+ * Storage-agnostic lifecycle hooks for database initialization.
+ * Provided to BaseApplication to enable init, validation, and dev setup
+ * regardless of which database backend (IDatabase or IDocumentStore) is used.
+ *
+ * All hooks are optional, allowing partial configuration.
+ * Each hook is a stateless function (or closure) receiving all needed context
+ * as parameters, enabling independent unit testing.
+ *
+ * @template TInitResults - Application-specific initialization result type
+ */
+export interface IDatabaseLifecycleHooks<TInitResults = unknown> {
+    /**
+     * Validate a database connection URI before connecting.
+     * Should throw on invalid or unsafe URIs.
+     * If not provided, BaseApplication uses a default validator.
+     */
+    validateUri?: (uri: string) => void;
+    /**
+     * Provision an ephemeral dev/test database.
+     * Returns the connection URI for the provisioned store.
+     * Called before connect() when environment.devDatabase is truthy.
+     */
+    setupDevStore?: () => Promise<string>;
+    /**
+     * Clean up the ephemeral dev/test database on shutdown.
+     * Called during stop() if setupDevStore was invoked.
+     */
+    teardownDevStore?: () => Promise<void>;
+    /**
+     * Initialize/seed the database after connection.
+     * Called after connect() when environment.devDatabase is truthy.
+     * Must return a failable result indicating success or failure.
+     */
+    initializeDatabase?: (application: unknown) => Promise<IFailableResult<TInitResults>>;
+    /**
+     * Hash the initialization results for logging purposes.
+     * Called after successful initializeDatabase when detailedDebug is enabled.
+     */
+    hashInitResults?: (initResults: TInitResults) => string;
+}
+//# sourceMappingURL=databaseLifecycleHooks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"databaseLifecycleHooks.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/storage/databaseLifecycleHooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,uBAAuB,CAAC,YAAY,GAAG,OAAO;IAC7D;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAEpC;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAEtC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,CACnB,WAAW,EAAE,OAAO,KACjB,OAAO,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC,CAAC;IAE5C;;;OAGG;IACH,eAAe,CAAC,EAAE,CAAC,WAAW,EAAE,YAAY,KAAK,MAAM,CAAC;CACzD"}

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

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

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

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