@brightchain/brightchain-api-lib 0.15.0 → 0.17.0

package/src/lib/stores/diskBlockStore.js

@@ -1,16 +1,66 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DiskBlockStore = void 0;
 const brightchain_lib_1 = require("@brightchain/brightchain-lib");
 const fs_1 = require("fs");
+const promises_1 = require("fs/promises");
 const path_1 = require("path");
 /**
- * DiskBlockStore provides base functionality for storing blocks on disk.
- * It handles block paths, metadata paths, and directory structure.
- * Supports blocks of any size.
+ * DiskBlockStore provides filesystem-backed block storage implementing IBlockStore.
+ *
+ * Storage layout (simple flat structure):
+ *   {basePath}/blocks/{checksumHex}        - Raw block data files
+ *   {basePath}/meta/{checksumHex}.json     - Block metadata as JSON
+ *   {basePath}/parity/{checksumHex}/       - Parity block data files
+ *
+ * This class also serves as a base class for DiskBlockAsyncStore and DiskBlockSyncStore,
+ * which use a more complex directory layout via the protected helper methods.
+ *
+ * @see IBlockStore for the interface definition
  */
 class DiskBlockStore {
     constructor(config) {
+        /**
+         * Optional FEC service for parity generation and recovery.
+         */
+        this.fecService = null;
+        /**
+         * Track whether the blocks/meta directories have been created.
+         */
+        this.dirsEnsured = false;
         if (!config.storePath) {
             throw new brightchain_lib_1.StoreError(brightchain_lib_1.StoreErrorType.StorePathRequired);
         }
@@ -24,8 +74,62 @@ class DiskBlockStore {
             (0, fs_1.mkdirSync)(config.storePath, { recursive: true });
         }
     }
+    // ─── Public Accessors ───────────────────────────────────────────────
+    get blockSize() {
+        return this._blockSize;
+    }
+    get storePath() {
+        return this._storePath;
+    }
+    setFecService(fecService) {
+        this.fecService = fecService;
+    }
+    getFecService() {
+        return this.fecService;
+    }
+    // ─── Simple Layout Path Helpers (for IBlockStore implementation) ─────
+    /** Directory for raw block data files: {basePath}/blocks/ */
+    get blocksDir() {
+        return (0, path_1.join)(this._storePath, 'blocks');
+    }
+    /** Directory for metadata JSON files: {basePath}/meta/ */
+    get metaDir() {
+        return (0, path_1.join)(this._storePath, 'meta');
+    }
+    /** Directory for parity data: {basePath}/parity/ */
+    get parityDir() {
+        return (0, path_1.join)(this._storePath, 'parity');
+    }
+    /** File path for a block's raw data */
+    blockFilePath(checksumHex) {
+        return (0, path_1.join)(this.blocksDir, checksumHex);
+    }
+    /** File path for a block's metadata JSON */
+    metaFilePath(checksumHex) {
+        return (0, path_1.join)(this.metaDir, `${checksumHex}.json`);
+    }
+    /** Directory path for a block's parity files */
+    parityBlockDir(checksumHex) {
+        return (0, path_1.join)(this.parityDir, checksumHex);
+    }
+    /** Ensure blocks/ and meta/ directories exist (lazy, once per instance) */
+    async ensureDirs() {
+        if (this.dirsEnsured)
+            return;
+        await (0, promises_1.mkdir)(this.blocksDir, { recursive: true });
+        await (0, promises_1.mkdir)(this.metaDir, { recursive: true });
+        this.dirsEnsured = true;
+    }
+    // ─── Key Conversion Helpers ─────────────────────────────────────────
+    keyToHex(key) {
+        return typeof key === 'string' ? key : key.toHex();
+    }
+    hexToChecksum(hex) {
+        return brightchain_lib_1.Checksum.fromHex(hex);
+    }
+    // ─── Protected Path Helpers (for subclass compatibility) ────────────
     /**
-     * Get the directory path for a block
+     * Get the directory path for a block (complex layout used by subclasses).
      * Directory structure: storePath/blockSize/checksumChar1/checksumChar2/
      */
     blockDir(blockId, blockSize) {
@@ -37,7 +141,7 @@ class DiskBlockStore {
         return (0, path_1.join)(this._storePath, blockSizeString, checksumString[0], checksumString[1]);
     }
     /**
-     * Get the file path for a block
+     * Get the file path for a block (complex layout used by subclasses).
      * File structure: storePath/blockSize/checksumChar1/checksumChar2/fullChecksum
      */
     blockPath(blockId, blockSize) {
@@ -49,20 +153,19 @@ class DiskBlockStore {
         return (0, path_1.join)(this._storePath, blockSizeString, checksumString[0], checksumString[1], checksumString);
     }
     /**
-     * Get the metadata file path for a block
-     * Metadata files are stored alongside block files with a .m.json extension
+     * Get the metadata file path for a block (complex layout used by subclasses).
      */
     metadataPath(blockId, blockSize) {
         return this.blockPath(blockId, blockSize) + '.m.json';
     }
     /**
-     * Ensure the directory structure exists for a block
+     * Ensure the directory structure exists for a block (complex layout used by subclasses).
      */
     ensureBlockPath(blockId, blockSize) {
-        const blockDir = this.blockDir(blockId, blockSize);
-        if (!(0, fs_1.existsSync)(blockDir)) {
+        const dir = this.blockDir(blockId, blockSize);
+        if (!(0, fs_1.existsSync)(dir)) {
             try {
-                (0, fs_1.mkdirSync)(blockDir, { recursive: true });
+                (0, fs_1.mkdirSync)(dir, { recursive: true });
             }
             catch (error) {
                 throw new brightchain_lib_1.StoreError(brightchain_lib_1.StoreErrorType.BlockDirectoryCreationFailed, undefined, {
@@ -71,17 +174,682 @@ class DiskBlockStore {
             }
         }
     }
-    /**
-     * Get the block size
-     */
-    get blockSize() {
-        return this._blockSize;
+    // ─── IBlockStore: Core Block Operations ─────────────────────────────
+    async has(key) {
+        const keyHex = this.keyToHex(key);
+        try {
+            await (0, promises_1.access)(this.blockFilePath(keyHex));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async getData(key) {
+        const keyHex = this.keyToHex(key);
+        const filePath = this.blockFilePath(keyHex);
+        try {
+            await (0, promises_1.access)(filePath);
+        }
+        catch {
+            throw new brightchain_lib_1.StoreError(brightchain_lib_1.StoreErrorType.KeyNotFound, undefined, {
+                KEY: keyHex,
+            });
+        }
+        const data = await (0, promises_1.readFile)(filePath);
+        const block = new brightchain_lib_1.RawDataBlock(this._blockSize, new Uint8Array(data));
+        // Record access in metadata
+        await this.touchMetadataAccess(keyHex);
+        return block;
+    }
+    async setData(block, options) {
+        const keyHex = block.idChecksum.toHex();
+        const filePath = this.blockFilePath(keyHex);
+        // Idempotent — block already exists
+        try {
+            await (0, promises_1.access)(filePath);
+            return;
+        }
+        catch {
+            // File doesn't exist, proceed to write
+        }
+        try {
+            block.validate();
+        }
+        catch {
+            throw new brightchain_lib_1.StoreError(brightchain_lib_1.StoreErrorType.BlockValidationFailed);
+        }
+        await this.ensureDirs();
+        // Write block data
+        await (0, promises_1.writeFile)(filePath, block.data);
+        // Write metadata
+        const metadata = (0, brightchain_lib_1.createDefaultBlockMetadata)(keyHex, block.data.length, keyHex, options);
+        await this.writeMetadata(keyHex, metadata);
+        // Generate parity blocks based on durability level
+        const durabilityLevel = options?.durabilityLevel ?? brightchain_lib_1.DurabilityLevel.Standard;
+        const parityCount = (0, brightchain_lib_1.getParityCountForDurability)(durabilityLevel);
+        if (parityCount > 0 && this.fecService) {
+            try {
+                await this.generateParityBlocks(keyHex, parityCount);
+            }
+            catch {
+                // Parity generation failure is non-fatal; block is still stored
+            }
+        }
+    }
+    async deleteData(key) {
+        const keyHex = this.keyToHex(key);
+        const filePath = this.blockFilePath(keyHex);
+        try {
+            await (0, promises_1.access)(filePath);
+        }
+        catch {
+            throw new brightchain_lib_1.StoreError(brightchain_lib_1.StoreErrorType.KeyNotFound);
+        }
+        // Delete block data
+        try {
+            await (0, promises_1.unlink)(filePath);
+        }
+        catch (error) {
+            throw new brightchain_lib_1.StoreError(brightchain_lib_1.StoreErrorType.BlockDeletionFailed, undefined, {
+                ERROR: error instanceof Error ? error.message : String(error),
+            });
+        }
+        // Delete metadata
+        try {
+            await (0, promises_1.unlink)(this.metaFilePath(keyHex));
+        }
+        catch {
+            // Metadata may not exist; non-fatal
+        }
+        // Delete parity directory
+        try {
+            const parDir = this.parityBlockDir(keyHex);
+            await (0, promises_1.access)(parDir);
+            const files = await (0, promises_1.readdir)(parDir);
+            for (const f of files) {
+                await (0, promises_1.unlink)((0, path_1.join)(parDir, f));
+            }
+            // Remove the directory itself via rmdir-like approach
+            const { rmdir } = await Promise.resolve().then(() => __importStar(require('fs/promises')));
+            await rmdir(parDir);
+        }
+        catch {
+            // Parity data may not exist; non-fatal
+        }
+    }
+    async getRandomBlocks(count) {
+        try {
+            await (0, promises_1.access)(this.blocksDir);
+        }
+        catch {
+            return [];
+        }
+        const files = await (0, promises_1.readdir)(this.blocksDir);
+        const actualCount = Math.min(count, files.length);
+        const shuffled = [...files].sort(() => Math.random() - 0.5);
+        const result = [];
+        for (let i = 0; i < actualCount; i++) {
+            try {
+                result.push(brightchain_lib_1.Checksum.fromHex(shuffled[i]));
+            }
+            catch {
+                // Skip files with non-checksum names
+            }
+        }
+        return result;
+    }
+    get(key) {
+        const keyHex = this.keyToHex(key);
+        const filePath = this.blockFilePath(keyHex);
+        if (!(0, fs_1.existsSync)(filePath)) {
+            throw new brightchain_lib_1.StoreError(brightchain_lib_1.StoreErrorType.KeyNotFound, undefined, {
+                KEY: keyHex,
+            });
+        }
+        const data = (0, fs_1.readFileSync)(filePath);
+        const checksum = typeof key === 'string' ? this.hexToChecksum(key) : key;
+        return (0, brightchain_lib_1.createBlockHandle)(
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        brightchain_lib_1.RawDataBlock, this._blockSize, new Uint8Array(data), checksum, true, true);
+    }
+    async put(key, data, options) {
+        const block = new brightchain_lib_1.RawDataBlock(this._blockSize, data);
+        await this.setData(block, options);
+    }
+    async delete(key) {
+        const checksum = typeof key === 'string' ? this.hexToChecksum(key) : key;
+        await this.deleteData(checksum);
+    }
+    // ─── IBlockStore: Metadata Operations ───────────────────────────────
+    async getMetadata(key) {
+        const keyHex = this.keyToHex(key);
+        return this.readMetadata(keyHex);
+    }
+    async updateMetadata(key, updates) {
+        const keyHex = this.keyToHex(key);
+        const existing = await this.readMetadata(keyHex);
+        if (!existing) {
+            throw new brightchain_lib_1.StoreError(brightchain_lib_1.StoreErrorType.KeyNotFound, undefined, {
+                KEY: keyHex,
+            });
+        }
+        const updated = {
+            ...existing,
+            ...updates,
+            blockId: existing.blockId, // Prevent blockId from being changed
+        };
+        await this.writeMetadata(keyHex, updated);
+    }
+    // ─── IBlockStore: FEC/Durability Operations ─────────────────────────
+    async generateParityBlocks(key, parityCount) {
+        const keyHex = this.keyToHex(key);
+        if (!this.fecService) {
+            throw new brightchain_lib_1.FecError(brightchain_lib_1.FecErrorType.FecEncodingFailed, undefined, {
+                ERROR: 'FEC service is not available',
+            });
+        }
+        if (!(await this.has(key))) {
+            throw new brightchain_lib_1.StoreError(brightchain_lib_1.StoreErrorType.KeyNotFound, undefined, {
+                KEY: keyHex,
+            });
+        }
+        const isAvailable = await this.fecService.isAvailable();
+        if (!isAvailable) {
+            throw new brightchain_lib_1.FecError(brightchain_lib_1.FecErrorType.FecEncodingFailed, undefined, {
+                ERROR: 'FEC service is not available in this environment',
+            });
+        }
+        const blockData = await (0, promises_1.readFile)(this.blockFilePath(keyHex));
+        const parityData = await this.fecService.createParityData(new Uint8Array(blockData), parityCount);
+        // Store parity data to disk
+        const parDir = this.parityBlockDir(keyHex);
+        await (0, promises_1.mkdir)(parDir, { recursive: true });
+        const checksumService = (0, brightchain_lib_1.getGlobalServiceProvider)().checksumService;
+        const parityBlockIds = [];
+        for (let i = 0; i < parityData.length; i++) {
+            const parityId = checksumService
+                .calculateChecksum(parityData[i].data)
+                .toHex();
+            parityBlockIds.push(parityId);
+            await (0, promises_1.writeFile)((0, path_1.join)(parDir, `${i}.parity`), JSON.stringify({
+                id: parityId,
+                index: parityData[i].index,
+                data: Array.from(parityData[i].data),
+            }));
+        }
+        // Update metadata with parity block IDs
+        const meta = await this.readMetadata(keyHex);
+        if (meta) {
+            await this.writeMetadata(keyHex, { ...meta, parityBlockIds });
+        }
+        return parityBlockIds.map((id) => brightchain_lib_1.Checksum.fromHex(id));
+    }
+    async getParityBlocks(key) {
+        const keyHex = this.keyToHex(key);
+        const meta = await this.readMetadata(keyHex);
+        if (!meta)
+            return [];
+        return meta.parityBlockIds.map((id) => brightchain_lib_1.Checksum.fromHex(id));
+    }
+    async recoverBlock(key) {
+        const keyHex = this.keyToHex(key);
+        if (!this.fecService) {
+            return { success: false, error: 'FEC service is not available' };
+        }
+        const isAvailable = await this.fecService.isAvailable();
+        if (!isAvailable) {
+            return {
+                success: false,
+                error: 'FEC service is not available in this environment',
+            };
+        }
+        // Load parity data from disk
+        const parityData = await this.loadParityFromDisk(keyHex);
+        if (parityData.length === 0) {
+            return { success: false, error: 'No parity data available' };
+        }
+        const meta = await this.readMetadata(keyHex);
+        if (!meta) {
+            return { success: false, error: 'Block metadata not found' };
+        }
+        try {
+            let corruptedData = null;
+            try {
+                const raw = await (0, promises_1.readFile)(this.blockFilePath(keyHex));
+                corruptedData = new Uint8Array(raw);
+            }
+            catch {
+                // Block may be missing entirely
+            }
+            const result = await this.fecService.recoverFileData(corruptedData, parityData, meta.size);
+            if (result.recovered) {
+                const recoveredBlock = new brightchain_lib_1.RawDataBlock(this._blockSize, new Uint8Array(result.data));
+                await this.ensureDirs();
+                await (0, promises_1.writeFile)(this.blockFilePath(keyHex), recoveredBlock.data);
+                return { success: true, recoveredBlock };
+            }
+            return {
+                success: false,
+                error: 'Recovery failed: insufficient parity data',
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : 'Unknown recovery error',
+            };
+        }
+    }
+    async verifyBlockIntegrity(key) {
+        const keyHex = this.keyToHex(key);
+        if (!this.fecService) {
+            return this.has(key);
+        }
+        const isAvailable = await this.fecService.isAvailable();
+        if (!isAvailable) {
+            return this.has(key);
+        }
+        try {
+            await (0, promises_1.access)(this.blockFilePath(keyHex));
+        }
+        catch {
+            return false;
+        }
+        const parityData = await this.loadParityFromDisk(keyHex);
+        if (parityData.length === 0) {
+            return true; // No parity data — can only verify block exists
+        }
+        try {
+            const blockData = await (0, promises_1.readFile)(this.blockFilePath(keyHex));
+            return await this.fecService.verifyFileIntegrity(new Uint8Array(blockData), parityData);
+        }
+        catch {
+            return false;
+        }
+    }
+    // ─── IBlockStore: Replication Operations ─────────────────────────────
+    async getBlocksPendingReplication() {
+        return this.findBlocksByReplicationStatus(brightchain_lib_1.ReplicationStatus.Pending, true);
+    }
+    async getUnderReplicatedBlocks() {
+        return this.findBlocksByReplicationStatus(brightchain_lib_1.ReplicationStatus.UnderReplicated, false);
+    }
+    async recordReplication(key, nodeId) {
+        const keyHex = this.keyToHex(key);
+        const meta = await this.readMetadata(keyHex);
+        if (!meta) {
+            throw new brightchain_lib_1.StoreError(brightchain_lib_1.StoreErrorType.KeyNotFound, undefined, {
+                KEY: keyHex,
+            });
+        }
+        const replicaNodeIds = [...meta.replicaNodeIds];
+        if (!replicaNodeIds.includes(nodeId)) {
+            replicaNodeIds.push(nodeId);
+        }
+        let replicationStatus = meta.replicationStatus;
+        if (replicaNodeIds.length >= meta.targetReplicationFactor) {
+            replicationStatus = brightchain_lib_1.ReplicationStatus.Replicated;
+        }
+        else if (replicaNodeIds.length > 0) {
+            replicationStatus = brightchain_lib_1.ReplicationStatus.UnderReplicated;
+        }
+        await this.writeMetadata(keyHex, {
+            ...meta,
+            replicaNodeIds,
+            replicationStatus,
+        });
+    }
+    async recordReplicaLoss(key, nodeId) {
+        const keyHex = this.keyToHex(key);
+        const meta = await this.readMetadata(keyHex);
+        if (!meta) {
+            throw new brightchain_lib_1.StoreError(brightchain_lib_1.StoreErrorType.KeyNotFound, undefined, {
+                KEY: keyHex,
+            });
+        }
+        const replicaNodeIds = meta.replicaNodeIds.filter((id) => id !== nodeId);
+        let replicationStatus = meta.replicationStatus;
+        if (meta.targetReplicationFactor > 0) {
+            if (replicaNodeIds.length >= meta.targetReplicationFactor) {
+                replicationStatus = brightchain_lib_1.ReplicationStatus.Replicated;
+            }
+            else if (replicaNodeIds.length > 0) {
+                replicationStatus = brightchain_lib_1.ReplicationStatus.UnderReplicated;
+            }
+            else {
+                replicationStatus = brightchain_lib_1.ReplicationStatus.Pending;
+            }
+        }
+        await this.writeMetadata(keyHex, {
+            ...meta,
+            replicaNodeIds,
+            replicationStatus,
+        });
+    }
+    // ─── IBlockStore: XOR Brightening Operations ────────────────────────
+    async brightenBlock(key, randomBlockCount) {
+        const keyHex = this.keyToHex(key);
+        if (!(await this.has(key))) {
+            throw new brightchain_lib_1.StoreError(brightchain_lib_1.StoreErrorType.KeyNotFound, undefined, {
+                KEY: keyHex,
+            });
+        }
+        const randomBlockChecksums = await this.getRandomBlocks(randomBlockCount);
+        if (randomBlockChecksums.length < randomBlockCount) {
+            throw new brightchain_lib_1.StoreError(brightchain_lib_1.StoreErrorType.InsufficientRandomBlocks, undefined, {
+                REQUESTED: randomBlockCount.toString(),
+                AVAILABLE: randomBlockChecksums.length.toString(),
+            });
+        }
+        const sourceData = await (0, promises_1.readFile)(this.blockFilePath(keyHex));
+        const allBlockData = [new Uint8Array(sourceData)];
+        for (const checksum of randomBlockChecksums) {
+            const block = await this.getData(checksum);
+            allBlockData.push(block.data);
+        }
+        const brightenedData = brightchain_lib_1.XorService.xorMultiple(allBlockData);
+        const brightenedBlock = new brightchain_lib_1.RawDataBlock(this._blockSize, brightenedData);
+        const brightenedBlockId = brightenedBlock.idChecksum.toHex();
+        if (!(await this.has(brightenedBlockId))) {
+            await this.setData(brightenedBlock);
+        }
+        return {
+            brightenedBlockId,
+            randomBlockIds: randomBlockChecksums.map((c) => c.toHex()),
+            originalBlockId: keyHex,
+        };
+    }
+    // ─── IBlockStore: CBL Whitening Operations ──────────────────────────
+    async storeCBLWithWhitening(cblData, options) {
+        if (!cblData || cblData.length === 0) {
+            throw new brightchain_lib_1.StoreError(brightchain_lib_1.StoreErrorType.BlockValidationFailed, undefined, {
+                ERROR: 'CBL data cannot be empty',
+            });
+        }
+        const paddedCbl = (0, brightchain_lib_1.padToBlockSize)(cblData, this._blockSize);
+        if (paddedCbl.length > this._blockSize) {
+            throw new brightchain_lib_1.StoreError(brightchain_lib_1.StoreErrorType.BlockValidationFailed, undefined, {
+                ERROR: `CBL data too large: padded size (${paddedCbl.length}) exceeds block size (${this._blockSize})`,
+            });
+        }
+        const randomBlock = await this.selectOrGenerateRandomizer(paddedCbl.length);
+        const xorResult = (0, brightchain_lib_1.xorArrays)(paddedCbl, randomBlock);
+        let block1Stored = false;
+        let block1Id = '';
+        try {
+            const block1 = new brightchain_lib_1.RawDataBlock(this._blockSize, randomBlock);
+            const block1Checksum = block1.idChecksum;
+            if (!(await this.has(block1Checksum))) {
+                await this.setData(block1, options);
+                block1Stored = true;
+            }
+            block1Id = block1Checksum.toHex();
+            const block2 = new brightchain_lib_1.RawDataBlock(this._blockSize, xorResult);
+            await this.setData(block2, options);
+            const block2Id = block2.idChecksum.toHex();
+            let block1ParityIds;
+            let block2ParityIds;
+            const block1Meta = await this.getMetadata(block1Id);
+            if (block1Meta?.parityBlockIds?.length) {
+                block1ParityIds = block1Meta.parityBlockIds;
+            }
+            const block2Meta = await this.getMetadata(block2Id);
+            if (block2Meta?.parityBlockIds?.length) {
+                block2ParityIds = block2Meta.parityBlockIds;
+            }
+            const magnetUrl = this.generateCBLMagnetUrl(block1Id, block2Id, this._blockSize, block1ParityIds, block2ParityIds, options?.isEncrypted);
+            return {
+                blockId1: block1Id,
+                blockId2: block2Id,
+                blockSize: this._blockSize,
+                magnetUrl,
+                block1ParityIds,
+                block2ParityIds,
+                isEncrypted: options?.isEncrypted,
+            };
+        }
+        catch (error) {
+            if (block1Stored && block1Id) {
+                try {
+                    await this.deleteData(this.hexToChecksum(block1Id));
+                }
+                catch {
+                    // Ignore rollback errors
+                }
+            }
+            throw error;
+        }
+    }
+    async retrieveCBL(blockId1, blockId2, block1ParityIds, block2ParityIds) {
+        const b1Checksum = typeof blockId1 === 'string' ? this.hexToChecksum(blockId1) : blockId1;
+        let block1Data;
+        try {
+            block1Data = await this.getData(b1Checksum);
+        }
+        catch (error) {
+            if (block1ParityIds?.length) {
+                const recovery = await this.recoverBlock(b1Checksum);
+                if (recovery.success && recovery.recoveredBlock) {
+                    block1Data = recovery.recoveredBlock;
+                }
+                else {
+                    throw new brightchain_lib_1.StoreError(brightchain_lib_1.StoreErrorType.KeyNotFound, undefined, {
+                        KEY: this.keyToHex(blockId1),
+                    });
+                }
+            }
+            else {
+                throw error;
+            }
+        }
+        const b2Checksum = typeof blockId2 === 'string' ? this.hexToChecksum(blockId2) : blockId2;
+        let block2Data;
+        try {
+            block2Data = await this.getData(b2Checksum);
+        }
+        catch (error) {
+            if (block2ParityIds?.length) {
+                const recovery = await this.recoverBlock(b2Checksum);
+                if (recovery.success && recovery.recoveredBlock) {
+                    block2Data = recovery.recoveredBlock;
+                }
+                else {
+                    throw new brightchain_lib_1.StoreError(brightchain_lib_1.StoreErrorType.KeyNotFound, undefined, {
+                        KEY: this.keyToHex(blockId2),
+                    });
+                }
+            }
+            else {
+                throw error;
+            }
+        }
+        const reconstructedPadded = (0, brightchain_lib_1.xorArrays)(block1Data.data, block2Data.data);
+        return (0, brightchain_lib_1.unpadCblData)(reconstructedPadded);
+    }
+    parseCBLMagnetUrl(magnetUrl) {
+        if (!magnetUrl || !magnetUrl.startsWith('magnet:?')) {
+            throw new Error('Invalid magnet URL format');
+        }
+        const queryString = magnetUrl.substring('magnet:?'.length);
+        const params = new URLSearchParams(queryString);
+        const xt = params.get('xt');
+        if (xt !== 'urn:brightchain:cbl') {
+            throw new Error('Invalid magnet URL: wrong xt parameter');
+        }
+        const blockId1 = params.get('b1');
+        const blockId2 = params.get('b2');
+        const blockSizeStr = params.get('bs');
+        if (!blockId1)
+            throw new Error('Invalid magnet URL: missing b1');
+        if (!blockId2)
+            throw new Error('Invalid magnet URL: missing b2');
+        if (!blockSizeStr)
+            throw new Error('Invalid magnet URL: missing bs');
+        const blockSize = parseInt(blockSizeStr, 10);
+        if (isNaN(blockSize) || blockSize <= 0) {
+            throw new Error('Invalid magnet URL: invalid block size');
+        }
+        const p1Param = params.get('p1');
+        const p2Param = params.get('p2');
+        const block1ParityIds = p1Param
+            ? p1Param.split(',').filter((id) => id)
+            : undefined;
+        const block2ParityIds = p2Param
+            ? p2Param.split(',').filter((id) => id)
+            : undefined;
+        const isEncrypted = params.get('enc') === '1';
+        return {
+            blockId1,
+            blockId2,
+            blockSize,
+            block1ParityIds,
+            block2ParityIds,
+            isEncrypted,
+        };
+    }
+    generateCBLMagnetUrl(blockId1, blockId2, blockSize, block1ParityIds, block2ParityIds, isEncrypted) {
+        const b1Id = typeof blockId1 === 'string' ? blockId1 : blockId1.toHex();
+        const b2Id = typeof blockId2 === 'string' ? blockId2 : blockId2.toHex();
+        const params = new URLSearchParams();
+        params.set('xt', 'urn:brightchain:cbl');
+        params.set('bs', blockSize.toString());
+        params.set('b1', b1Id);
+        params.set('b2', b2Id);
+        if (block1ParityIds?.length) {
+            params.set('p1', block1ParityIds.join(','));
+        }
+        if (block2ParityIds?.length) {
+            params.set('p2', block2ParityIds.join(','));
+        }
+        if (isEncrypted) {
+            params.set('enc', '1');
+        }
+        return `magnet:?${params.toString()}`;
+    }
+    // ─── Private Helpers ────────────────────────────────────────────────
+    /** Read metadata JSON from disk, returning null if not found. */
+    async readMetadata(keyHex) {
+        const filePath = this.metaFilePath(keyHex);
+        try {
+            await (0, promises_1.access)(filePath);
+        }
+        catch {
+            return null;
+        }
+        try {
+            const raw = await (0, promises_1.readFile)(filePath, 'utf-8');
+            const parsed = JSON.parse(raw);
+            return {
+                ...parsed,
+                createdAt: new Date(parsed.createdAt),
+                expiresAt: parsed.expiresAt ? new Date(parsed.expiresAt) : null,
+                lastAccessedAt: new Date(parsed.lastAccessedAt),
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Write metadata JSON to disk. */
+    async writeMetadata(keyHex, metadata) {
+        await this.ensureDirs();
+        const filePath = this.metaFilePath(keyHex);
+        await (0, promises_1.writeFile)(filePath, JSON.stringify(metadata, null, 2), 'utf-8');
+    }
+    /** Update access count and timestamp in metadata. */
+    async touchMetadataAccess(keyHex) {
+        const meta = await this.readMetadata(keyHex);
+        if (meta) {
+            meta.accessCount += 1;
+            meta.lastAccessedAt = new Date();
+            await this.writeMetadata(keyHex, meta);
+        }
+    }
+    /** Load parity data from disk for a given block. */
+    async loadParityFromDisk(keyHex) {
+        const parDir = this.parityBlockDir(keyHex);
+        try {
+            await (0, promises_1.access)(parDir);
+        }
+        catch {
+            return [];
+        }
+        const files = await (0, promises_1.readdir)(parDir);
+        const parityFiles = files.filter((f) => f.endsWith('.parity')).sort();
+        const result = [];
+        for (const f of parityFiles) {
+            try {
+                const raw = await (0, promises_1.readFile)((0, path_1.join)(parDir, f), 'utf-8');
+                const parsed = JSON.parse(raw);
+                result.push({
+                    index: parsed.index,
+                    data: new Uint8Array(parsed.data),
+                });
+            }
+            catch {
+                // Skip corrupt parity files
+            }
+        }
+        return result;
+    }
+    /** Scan all metadata files and find blocks matching a replication status. */
+    async findBlocksByReplicationStatus(status, requirePositiveTarget) {
+        try {
+            await (0, promises_1.access)(this.metaDir);
+        }
+        catch {
+            return [];
+        }
+        const files = await (0, promises_1.readdir)(this.metaDir);
+        const result = [];
+        for (const f of files) {
+            if (!f.endsWith('.json'))
+                continue;
+            const keyHex = f.replace('.json', '');
+            const meta = await this.readMetadata(keyHex);
+            if (!meta)
+                continue;
+            if (meta.replicationStatus === status) {
+                if (requirePositiveTarget && meta.targetReplicationFactor <= 0) {
+                    continue;
+                }
+                try {
+                    result.push(brightchain_lib_1.Checksum.fromHex(keyHex));
+                }
+                catch {
+                    // Skip invalid checksums
+                }
+            }
+        }
+        return result;
     }
     /**
-     * Get the store path
+     * Select an existing block as a randomizer, or generate a new one.
+     * Following OFFSystem principles: preferentially reuse existing blocks.
      */
-    get storePath() {
-        return this._storePath;
+    async selectOrGenerateRandomizer(size) {
+        try {
+            await (0, promises_1.access)(this.blocksDir);
+            const files = await (0, promises_1.readdir)(this.blocksDir);
+            if (files.length > 0) {
+                const randomIndex = Math.floor(Math.random() * files.length);
+                const selectedFile = files[randomIndex];
+                try {
+                    const data = await (0, promises_1.readFile)((0, path_1.join)(this.blocksDir, selectedFile));
+                    if (data.length >= size) {
+                        return new Uint8Array(data.subarray(0, size));
+                    }
+                }
+                catch {
+                    // Fall through to generation
+                }
+            }
+        }
+        catch {
+            // blocksDir doesn't exist yet; fall through
+        }
+        return brightchain_lib_1.XorService.generateKey(size);
     }
 }
 exports.DiskBlockStore = DiskBlockStore;