@brightchain/db 0.20.0

package/src/lib/cblIndex.d.ts

@@ -0,0 +1,268 @@
+/**
+ * CBLIndex – higher-level CBL index built on top of a brightchain-db Collection.
+ *
+ * Tracks whitened CBL storage results with metadata, pool scoping,
+ * user-level organization, and file version history.
+ *
+ * Backed by a `Collection<ICBLIndexEntry>` named `__cbl_index__`.
+ */
+import { type CBLIndexManifest, type IBlockStore, type ICBLIndexEntry, type ICBLIndexQueryOptions, type IGossipService } from '@brightchain/brightchain-lib';
+import type { BrightChainDb } from './database';
+/**
+ * Options for configuring the CBL Index.
+ */
+export interface CBLIndexOptions {
+    /**
+     * Number of FEC parity blocks to generate for the collection's metadata
+     * blocks after each mutation. Set to 0 (default) to disable FEC redundancy.
+     *
+     * Uses the existing `IBlockStore.generateParityBlocks()` method.
+     */
+    parityCount?: number;
+    /**
+     * Number of index mutations after which an automatic snapshot is taken.
+     * Set to 0 to disable auto-snapshots. Default: 100.
+     *
+     * Auto-snapshots are best-effort — failures are logged but don't break mutations.
+     */
+    snapshotInterval?: number;
+    /**
+     * Enable recovery on startup when the index collection is empty.
+     * Recovery order: (1) latest snapshot, (2) FEC parity rebuild, (3) block store scan.
+     * Default: true.
+     */
+    enableRecovery?: boolean;
+    /**
+     * Optional gossip service for announcing CBL index changes to peers.
+     * When provided, new entries and soft-deletions are announced to peers
+     * in the same pool via cbl_index_update and cbl_index_delete announcements.
+     *
+     * @see Requirements 8.1, 8.6
+     */
+    gossipService?: IGossipService;
+}
+/**
+ * Higher-level CBL index built on top of a brightchain-db Collection.
+ * Tracks whitened CBL storage results with metadata, pool scoping,
+ * and user-level organization.
+ */
+export declare class CBLIndex {
+    private readonly collection;
+    private sequenceCounter;
+    private readonly blockStore;
+    private readonly parityCount;
+    private readonly snapshotInterval;
+    private mutationsSinceSnapshot;
+    private readonly headRegistry;
+    private readonly dbName;
+    private readonly enableRecovery;
+    private readonly gossipService?;
+    constructor(db: BrightChainDb, blockStore: IBlockStore, options?: CBLIndexOptions);
+    /**
+     * Generate FEC parity blocks for the collection's current head (metadata) block.
+     * This is a best-effort operation — failures are logged but do not propagate.
+     */
+    private generateParityForHead;
+    /**
+     * Track a mutation and trigger an auto-snapshot if the threshold is reached.
+     * Auto-snapshots are best-effort — failures are logged but don't break mutations.
+     */
+    private trackMutationForAutoSnapshot;
+    /**
+     * Create a snapshot of the current index state.
+     * Serializes all entries (including soft-deleted) and the sequence counter,
+     * stores the data as a CBL via the block store, and returns the magnet URL.
+     *
+     * Persists the snapshot magnet URL in the head registry so recovery can find it.
+     * Resets the mutation counter on success so auto-snapshot tracking restarts.
+     */
+    snapshot(): Promise<string>;
+    /**
+     * Initialize the sequence counter from existing entries.
+     * Call this after construction to resume from the highest existing sequence number.
+     *
+     * If the collection is empty and recovery is enabled, attempts recovery in order:
+     * (1) latest snapshot, (2) FEC parity rebuild, (3) block store scan.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Attempt to recover the CBL index from available sources.
+     * Recovery order:
+     *   1. Latest snapshot (magnet URL stored in head registry)
+     *   2. FEC parity rebuild of the collection's head block
+     *   3. Block store scan for CBL blocks (partial rebuild — metadata lost)
+     *
+     * @returns true if any recovery method succeeded, false if all failed
+     */
+    private recover;
+    /**
+     * Strategy 1: Restore from the latest snapshot whose magnet URL is
+     * persisted in the head registry.
+     */
+    private recoverFromSnapshot;
+    /**
+     * Strategy 2: Recover the collection's head metadata block via FEC parity,
+     * then let the Collection re-load its documents from the recovered block.
+     */
+    private recoverFromFEC;
+    /**
+     * Strategy 3: Scan the block store for CBL blocks and rebuild a minimal
+     * index from structural data only. This is a last-resort recovery that
+     * loses all user metadata (file names, tags, collections, visibility, etc.).
+     *
+     * Iterates all blocks in all pools, checks for the BrightChain CBL magic
+     * prefix (0xBC), and creates minimal index entries for discovered CBL blocks.
+     */
+    private recoverFromBlockScan;
+    /**
+     * Heuristic check for whether block data looks like a CBL block.
+     * CBL blocks in BrightChain start with the magic prefix 0xBC.
+     */
+    private looksLikeCblBlock;
+    /**
+     * Add a new CBL index entry.
+     * Validates that both referenced block IDs exist in the block store,
+     * assigns a monotonically increasing sequence number, and inserts.
+     */
+    addEntry(entry: Omit<ICBLIndexEntry, '_id' | 'sequenceNumber'>): Promise<ICBLIndexEntry>;
+    /**
+     * Look up a single entry by its magnet URL.
+     */
+    getByMagnetUrl(magnetUrl: string): Promise<ICBLIndexEntry | null>;
+    /**
+     * Look up entries by block ID (matches either blockId1 or blockId2).
+     */
+    getByBlockId(blockId: string): Promise<ICBLIndexEntry[]>;
+    /**
+     * Query entries with multi-attribute filtering, pagination, and sort.
+     */
+    query(options: ICBLIndexQueryOptions): Promise<ICBLIndexEntry[]>;
+    /**
+     * Soft-delete an entry by magnet URL (sets deletedAt timestamp).
+     */
+    softDelete(magnetUrl: string): Promise<void>;
+    /**
+     * Aggregate CBL counts per pool.
+     * Returns a Map of poolId → count for all non-deleted entries.
+     */
+    getPoolCBLCounts(): Promise<Map<string, number>>;
+    /**
+     * Find entries whose XOR component blocks exist in pools other than the given poolId.
+     * Returns block IDs and the set of pools they appear in.
+     */
+    getCrossPoolDependencies(poolId: string): Promise<{
+        blockId: string;
+        pools: string[];
+    }[]>;
+    /**
+     * Get all CBL entries belonging to a specific pool (for pool deletion validation).
+     * Returns all non-deleted entries in the pool so the caller can assess
+     * whether the pool is safe to delete.
+     *
+     * Requirement 5.3: report all CBL entries in a pool as part of deletion validation.
+     */
+    getPoolEntries(poolId: string): Promise<ICBLIndexEntry[]>;
+    /**
+     * Share a CBL entry with another user.
+     * Adds the userId to the sharedWith array and sets visibility to Shared.
+     */
+    shareWith(magnetUrl: string, userId: string): Promise<void>;
+    /**
+     * Restore the index from a snapshot.
+     * Retrieves the CBL by magnet URL, deserializes the JSON payload,
+     * clears the current collection, and re-inserts all entries from the snapshot.
+     * Also restores the sequence counter.
+     */
+    restoreFromSnapshot(magnetUrl: string): Promise<void>;
+    /**
+     * Add a new version of a file.
+     * Auto-assigns versionNumber (previous max + 1) and sets previousVersion
+     * to the current latest version's magnet URL.
+     *
+     * IMPORTANT: version numbering considers ALL versions including soft-deleted
+     * ones so that the version chain remains intact (Requirement 27.8).
+     */
+    addVersion(fileId: string, entry: Omit<ICBLIndexEntry, '_id' | 'sequenceNumber' | 'fileId' | 'versionNumber' | 'previousVersion'>): Promise<ICBLIndexEntry>;
+    /**
+     * Get all versions of a file, ordered by versionNumber ascending.
+     *
+     * @param fileId - The stable file identifier grouping all versions.
+     * @param includeDeleted - When true, includes soft-deleted versions in the
+     *   result. Useful for verifying chain integrity (Requirement 27.8).
+     *   Defaults to false.
+     */
+    getVersionHistory(fileId: string, includeDeleted?: boolean): Promise<ICBLIndexEntry[]>;
+    /**
+     * Get the latest version of a file (O(1) via sort + limit 1).
+     *
+     * @param fileId - The stable file identifier grouping all versions.
+     * @param includeDeleted - When true, considers soft-deleted versions.
+     *   Used internally by addVersion to maintain chain integrity.
+     *   Defaults to false.
+     */
+    getLatestVersion(fileId: string, includeDeleted?: boolean): Promise<ICBLIndexEntry | null>;
+    /**
+     * Merge an incoming CBL index entry from a remote peer (via gossip).
+     *
+     * Idempotent: if an entry with the same magnet URL already exists and has
+     * identical content (blockId1, blockId2, blockSize), the merge is a no-op.
+     *
+     * Conflict: if an entry with the same magnet URL exists but has different
+     * content, both entries are preserved and flagged with `hasConflict: true`
+     * and cross-referenced via `conflictsWith`.
+     *
+     * New entry: if no entry with the magnet URL exists, the entry is inserted
+     * with a new local sequence number.
+     *
+     * @param entry - The incoming entry from a remote peer.
+     * @returns The merged entry (existing, new, or conflict-flagged).
+     *
+     * @see Requirements 8.2, 8.3
+     */
+    mergeEntry(entry: ICBLIndexEntry): Promise<ICBLIndexEntry>;
+    /**
+     * Apply a soft-delete from a remote peer (via gossip).
+     *
+     * If the entry exists locally and is not already soft-deleted, marks it
+     * as deleted with the provided timestamp. If the entry doesn't exist
+     * locally or is already deleted, this is a no-op.
+     *
+     * @param magnetUrl - The magnet URL of the entry to soft-delete.
+     * @param deletedAt - The deletion timestamp from the remote peer.
+     *
+     * @see Requirements 8.6
+     */
+    mergeSoftDelete(magnetUrl: string, deletedAt: Date): Promise<void>;
+    /**
+     * Get a CBL index manifest for a specific pool.
+     * Returns a list of (magnetUrl, sequenceNumber) pairs for all non-deleted
+     * entries in the given pool. Used during pool-scoped reconciliation to
+     * compare CBL index state between nodes.
+     *
+     * @param poolId - The pool to generate a manifest for
+     * @param nodeId - The local node ID to include in the manifest
+     * @returns A CBLIndexManifest for the specified pool
+     * @see Requirements 8.4
+     */
+    getCBLIndexManifest(poolId: string, nodeId: string): Promise<CBLIndexManifest>;
+    /**
+     * Reconcile the local CBL index for a pool against a remote manifest.
+     * Identifies entries present in the remote manifest but missing locally,
+     * and merges them using the provided entry fetcher.
+     *
+     * @param poolId - The pool being reconciled
+     * @param remoteManifest - The remote node's CBL index manifest
+     * @param fetchEntry - Callback to fetch a full CBL index entry from the remote peer by magnet URL
+     * @returns The number of entries merged
+     * @see Requirements 8.4
+     */
+    reconcileCBLIndex(poolId: string, remoteManifest: CBLIndexManifest, fetchEntry: (magnetUrl: string) => Promise<ICBLIndexEntry | null>): Promise<number>;
+    /**
+     * Build a FilterQuery from ICBLIndexQueryOptions.
+     */
+    private buildFilter;
+    /**
+     * Build a SortSpec from ICBLIndexQueryOptions.
+     */
+    private buildSort;
+}