@brightchain/brightchain-api-lib 0.14.0 → 0.15.0

package/src/lib/stores/availabilityAwareBlockStore.d.ts

@@ -7,7 +7,8 @@
  *
  * @see Requirements 12.1, 12.2, 12.3, 12.4, 12.5, 12.6, 8.1, 8.2, 8.3, 8.4, 8.5, 8.6
  */
-import { BaseBlock, BlockHandle, BlockStoreOptions, BrightenResult, CBLMagnetComponents, CBLStorageResult, CBLWhiteningOptions, Checksum, IAvailabilityService, IBlockMetadata, IBlockRegistry, IBlockStore, IGossipService, IReconciliationService, RawDataBlock, RecoveryResult } from '@brightchain/brightchain-lib';
+import { BaseBlock, BlockFetcherConfig, BlockHandle, BlockStoreOptions, BrightenResult, CBLMagnetComponents, CBLStorageResult, CBLWhiteningOptions, Checksum, FetchQueueConfig, IAvailabilityService, IBlockFetcher, IBlockMetadata, IBlockRegistry, IBlockStore, IGossipService, IReconciliationService, PoolDeletionTombstoneConfig, PoolId, RawDataBlock, ReadConcern, RecoveryResult } from '@brightchain/brightchain-lib';
+export { PoolDeletionTombstoneError } from '@brightchain/brightchain-lib';
 /**
  * Error thrown when an operation is attempted during partition mode
  * that requires network access.
@@ -33,11 +34,39 @@ export interface AvailabilityAwareBlockStoreConfig {
      * Default: true
      */
     trackAccess?: boolean;
+    /**
+     * Default read concern for getData calls when none is specified.
+     * Default: ReadConcern.Local (preserves backward compatibility)
+     */
+    defaultReadConcern?: ReadConcern;
+    /**
+     * Configuration for the block fetcher service.
+     * Only relevant when an IBlockFetcher is provided.
+     */
+    blockFetcherConfig?: BlockFetcherConfig;
+    /**
+     * Configuration for the fetch queue.
+     * Only relevant when an IBlockFetcher is provided.
+     */
+    fetchQueueConfig?: FetchQueueConfig;
+    /**
+     * Tombstone configuration for pool deletion tracking.
+     * Default: DEFAULT_TOMBSTONE_CONFIG (7 days TTL)
+     */
+    tombstoneConfig?: PoolDeletionTombstoneConfig;
 }
+/**
+ * Resolved configuration type for AvailabilityAwareBlockStore.
+ * Core fields are required; fetch-related configs remain optional since
+ * they are only meaningful when an IBlockFetcher is provided.
+ */
+export type ResolvedAvailabilityAwareBlockStoreConfig = Omit<Required<AvailabilityAwareBlockStoreConfig>, 'blockFetcherConfig' | 'fetchQueueConfig' | 'tombstoneConfig'> & Pick<AvailabilityAwareBlockStoreConfig, 'blockFetcherConfig' | 'fetchQueueConfig'> & {
+    tombstoneConfig: PoolDeletionTombstoneConfig;
+};
 /**
  * Default configuration values.
  */
-export declare const DEFAULT_AVAILABILITY_AWARE_BLOCK_STORE_CONFIG: Required<AvailabilityAwareBlockStoreConfig>;
+export declare const DEFAULT_AVAILABILITY_AWARE_BLOCK_STORE_CONFIG: ResolvedAvailabilityAwareBlockStoreConfig;
 /**
  * AvailabilityAwareBlockStore
  *
@@ -78,6 +107,16 @@ export declare class AvailabilityAwareBlockStore implements IBlockStore {
      * Configuration.
      */
     private readonly config;
+    /**
+     * Optional block fetcher for remote block retrieval.
+     * When provided, enables Available and Consistent read concerns.
+     */
+    private readonly blockFetcher?;
+    /**
+     * Tombstones for deleted pools. Blocks cannot be stored in a pool
+     * with an active tombstone until it expires.
+     */
+    private readonly tombstones;
     /**
      * Create a new AvailabilityAwareBlockStore.
      *
@@ -87,8 +126,9 @@ export declare class AvailabilityAwareBlockStore implements IBlockStore {
      * @param gossipService - Service for block announcements
      * @param reconciliationService - Service for pending sync queue
      * @param config - Configuration options
+     * @param blockFetcher - Optional block fetcher for remote block retrieval
      */
-    constructor(innerStore: IBlockStore, registry: IBlockRegistry, availabilityService: IAvailabilityService, gossipService: IGossipService, reconciliationService: IReconciliationService, config: AvailabilityAwareBlockStoreConfig);
+    constructor(innerStore: IBlockStore, registry: IBlockRegistry, availabilityService: IAvailabilityService, gossipService: IGossipService, reconciliationService: IReconciliationService, config: AvailabilityAwareBlockStoreConfig, blockFetcher?: IBlockFetcher);
     /**
      * Get the block size for this store.
      */
@@ -101,15 +141,41 @@ export declare class AvailabilityAwareBlockStore implements IBlockStore {
      */
     has(key: Checksum | string): Promise<boolean>;
     /**
-     * Get a block's data.
+     * Get a block's data with optional read concern.
      * Updates access metadata if tracking is enabled.
      *
+     * Read concern behavior:
+     * - Local (default): return only locally available blocks, error for remote/unknown
+     * - Consistent: await remote fetch, store result, return or timeout
+     * - Available: try fetch with initialWaitMs, return PendingBlockError if not resolved
+     *
+     * During partition mode, remote blocks always throw PartitionModeError
+     * regardless of read concern.
+     *
      * @param key - The block's checksum
+     * @param readConcern - Optional read concern level (defaults to config.defaultReadConcern)
      * @returns Promise resolving to the block data
-     * @throws StoreError if block not found
-     * @see Requirements 12.4
+     * @throws PartitionModeError if block is remote and system is in partition mode
+     * @throws PendingBlockError if Available concern and fetch not resolved in time
+     * @throws FetchTimeoutError if Consistent concern and fetch exceeds timeout
+     * @throws Error if block not found locally and concern is Local
+     * @see Requirements 2.2, 2.3, 2.4, 2.5, 7.3
      */
-    getData(key: Checksum): Promise<RawDataBlock>;
+    getData(key: Checksum, readConcern?: ReadConcern): Promise<RawDataBlock>;
+    /**
+     * Fetch a block with Consistent read concern.
+     * Awaits the full fetch result — returns the block or throws on timeout/failure.
+     *
+     * @see Requirements 2.4, 2.5
+     */
+    private fetchBlockConsistent;
+    /**
+     * Fetch a block with Available read concern.
+     * Tries to fetch within initialWaitMs; throws PendingBlockError if not resolved in time.
+     *
+     * @see Requirements 2.3
+     */
+    private fetchBlockAvailable;
     /**
      * Store a block's data with optional durability settings.
      * Updates registry, availability state, and announces via gossip.
@@ -199,24 +265,45 @@ export declare class AvailabilityAwareBlockStore implements IBlockStore {
      */
     verifyBlockIntegrity(key: Checksum | string): Promise<boolean>;
     /**
-     * Get blocks that are pending replication.
+     * Get blocks that are pending replication, scoped by pool.
+     *
+     * A block's replication count for pool P = number of distinct nodes
+     * with a location record for that block with poolId: P.
+     * Blocks without a poolId use the inner store's default pending check.
      *
      * @returns Array of block checksums pending replication
+     * @see Requirements 6.1, 6.2
      */
     getBlocksPendingReplication(): Promise<Checksum[]>;
     /**
-     * Get blocks that are under-replicated.
+     * Get blocks that are under-replicated, scoped by pool.
+     *
+     * A block's replication count for pool P = number of distinct nodes
+     * with a location record for that block with poolId: P.
+     * Under-replicated when pool-scoped replica count < targetReplicationFactor.
      *
      * @returns Array of block checksums that need additional replicas
+     * @see Requirements 6.1, 6.2
      */
     getUnderReplicatedBlocks(): Promise<Checksum[]>;
     /**
      * Record that a block has been replicated to a node.
+     * Includes poolId in the location record when the block belongs to a pool.
      *
      * @param key - The block's checksum or ID
      * @param nodeId - The ID of the node that now holds a replica
+     * @see Requirements 6.1, 6.2
      */
     recordReplication(key: Checksum | string, nodeId: string): Promise<void>;
+    /**
+     * Count the number of distinct nodes with a location record
+     * for a block that matches the given poolId.
+     *
+     * @param locations - All location records for the block
+     * @param poolId - The pool to scope the count to
+     * @returns Number of distinct nodes with matching poolId
+     */
+    private countPoolScopedReplicas;
     /**
      * Record that a replica node is no longer available.
      *
@@ -232,6 +319,24 @@ export declare class AvailabilityAwareBlockStore implements IBlockStore {
      * @returns Result containing the brightened block ID and random block IDs
      */
     brightenBlock(key: Checksum | string, randomBlockCount: number): Promise<BrightenResult>;
+    /**
+     * Handle a pool deletion event (triggered by a gossip `pool_deleted` announcement).
+     * Records a tombstone, removes all blocks in the pool from the local store,
+     * and removes pool entries from the registry.
+     *
+     * @param poolId - The pool that was deleted
+     * @param originNodeId - The node that originated the deletion
+     * @see Requirements 2.3, 2.4, 2.5
+     */
+    handlePoolDeletion(poolId: PoolId, originNodeId: string): Promise<void>;
+    /**
+     * Check if a pool has an active deletion tombstone.
+     * Cleans up expired tombstones automatically.
+     *
+     * @param poolId - The pool ID to check
+     * @returns True if an active (non-expired) tombstone exists
+     */
+    private hasTombstone;
     /**
      * Convert a key to hex string format.
      */
@@ -282,7 +387,7 @@ export declare class AvailabilityAwareBlockStore implements IBlockStore {
      *
      * @returns The configuration
      */
-    getConfig(): Required<AvailabilityAwareBlockStoreConfig>;
+    getConfig(): ResolvedAvailabilityAwareBlockStoreConfig;
     /**
      * Store a CBL with XOR whitening for Owner-Free storage.
      * Delegates to the inner store and updates availability tracking for both blocks.

package/src/lib/stores/availabilityAwareBlockStore.d.ts.map

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

package/src/lib/stores/availabilityAwareBlockStore.js

@@ -9,8 +9,11 @@
  * @see Requirements 12.1, 12.2, 12.3, 12.4, 12.5, 12.6, 8.1, 8.2, 8.3, 8.4, 8.5, 8.6
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AvailabilityAwareBlockStore = exports.DEFAULT_AVAILABILITY_AWARE_BLOCK_STORE_CONFIG = exports.PartitionModeError = void 0;
+exports.AvailabilityAwareBlockStore = exports.DEFAULT_AVAILABILITY_AWARE_BLOCK_STORE_CONFIG = exports.PartitionModeError = exports.PoolDeletionTombstoneError = void 0;
 const brightchain_lib_1 = require("@brightchain/brightchain-lib");
+// Re-export so existing consumers of this module continue to work
+var brightchain_lib_2 = require("@brightchain/brightchain-lib");
+Object.defineProperty(exports, "PoolDeletionTombstoneError", { enumerable: true, get: function () { return brightchain_lib_2.PoolDeletionTombstoneError; } });
 /**
  * Error thrown when an operation is attempted during partition mode
  * that requires network access.
@@ -29,6 +32,10 @@ exports.DEFAULT_AVAILABILITY_AWARE_BLOCK_STORE_CONFIG = {
     localNodeId: '',
     autoAnnounce: true,
     trackAccess: true,
+    defaultReadConcern: brightchain_lib_1.ReadConcern.Local,
+    blockFetcherConfig: undefined,
+    fetchQueueConfig: undefined,
+    tombstoneConfig: brightchain_lib_1.DEFAULT_TOMBSTONE_CONFIG,
 };
 /**
  * AvailabilityAwareBlockStore
@@ -55,8 +62,14 @@ class AvailabilityAwareBlockStore {
      * @param gossipService - Service for block announcements
      * @param reconciliationService - Service for pending sync queue
      * @param config - Configuration options
-     */
-    constructor(innerStore, registry, availabilityService, gossipService, reconciliationService, config) {
+     * @param blockFetcher - Optional block fetcher for remote block retrieval
+     */
+    constructor(innerStore, registry, availabilityService, gossipService, reconciliationService, config, blockFetcher) {
+        /**
+         * Tombstones for deleted pools. Blocks cannot be stored in a pool
+         * with an active tombstone until it expires.
+         */
+        this.tombstones = new Map();
         this.innerStore = innerStore;
         this.registry = registry;
         this.availabilityService = availabilityService;
@@ -66,6 +79,7 @@ class AvailabilityAwareBlockStore {
             ...exports.DEFAULT_AVAILABILITY_AWARE_BLOCK_STORE_CONFIG,
             ...config,
         };
+        this.blockFetcher = blockFetcher;
     }
     /**
      * Get the block size for this store.
@@ -84,30 +98,128 @@ class AvailabilityAwareBlockStore {
         return this.innerStore.has(key);
     }
     /**
-     * Get a block's data.
+     * Get a block's data with optional read concern.
      * Updates access metadata if tracking is enabled.
      *
+     * Read concern behavior:
+     * - Local (default): return only locally available blocks, error for remote/unknown
+     * - Consistent: await remote fetch, store result, return or timeout
+     * - Available: try fetch with initialWaitMs, return PendingBlockError if not resolved
+     *
+     * During partition mode, remote blocks always throw PartitionModeError
+     * regardless of read concern.
+     *
      * @param key - The block's checksum
+     * @param readConcern - Optional read concern level (defaults to config.defaultReadConcern)
      * @returns Promise resolving to the block data
-     * @throws StoreError if block not found
-     * @see Requirements 12.4
+     * @throws PartitionModeError if block is remote and system is in partition mode
+     * @throws PendingBlockError if Available concern and fetch not resolved in time
+     * @throws FetchTimeoutError if Consistent concern and fetch exceeds timeout
+     * @throws Error if block not found locally and concern is Local
+     * @see Requirements 2.2, 2.3, 2.4, 2.5, 7.3
      */
-    async getData(key) {
+    async getData(key, readConcern) {
         const blockId = this.keyToHex(key);
-        // Check availability state for remote blocks during partition mode
+        const concern = readConcern ?? this.config.defaultReadConcern;
+        // Step 1: Check partition mode for remote blocks BEFORE trying inner store.
+        // This preserves the original contract: remote blocks are inaccessible during partition
+        // regardless of whether the data happens to be in the inner store.
         if (this.availabilityService.isInPartitionMode()) {
             const state = await this.availabilityService.getAvailabilityState(blockId);
             if (state === brightchain_lib_1.AvailabilityState.Remote) {
                 throw new PartitionModeError(`Cannot access remote block ${blockId} during partition mode`);
             }
         }
-        // Delegate to inner store
-        const block = await this.innerStore.getData(key);
+        // Step 2: Try inner store first
+        try {
+            const block = await this.innerStore.getData(key);
+            // Update access metadata if tracking is enabled
+            if (this.config.trackAccess) {
+                await this.updateAccessMetadata(blockId);
+            }
+            return block;
+        }
+        catch {
+            // Block not found locally — fall through to read concern logic
+        }
+        // Step 3: Block not found locally — check availability state
+        const state = await this.availabilityService.getAvailabilityState(blockId);
+        // Step 4: Apply read concern logic
+        if (concern === brightchain_lib_1.ReadConcern.Local) {
+            // Local concern: only return locally available blocks
+            throw new Error(`Block ${blockId} not found locally (state: ${state})`);
+        }
+        // For Available and Consistent concerns, we need a block fetcher
+        if (!this.blockFetcher) {
+            throw new Error(`Block ${blockId} not found locally and no block fetcher configured (state: ${state})`);
+        }
+        // Only attempt remote fetch for Remote state
+        if (state !== brightchain_lib_1.AvailabilityState.Remote) {
+            throw new Error(`Block ${blockId} not found (state: ${state})`);
+        }
+        if (concern === brightchain_lib_1.ReadConcern.Consistent) {
+            return this.fetchBlockConsistent(key, blockId);
+        }
+        // ReadConcern.Available
+        return this.fetchBlockAvailable(key, blockId);
+    }
+    /**
+     * Fetch a block with Consistent read concern.
+     * Awaits the full fetch result — returns the block or throws on timeout/failure.
+     *
+     * @see Requirements 2.4, 2.5
+     */
+    async fetchBlockConsistent(key, blockId) {
+        const result = await this.blockFetcher.fetchBlock(blockId);
+        if (!result.success) {
+            const fetcherConfig = this.blockFetcher.getConfig();
+            throw new brightchain_lib_1.FetchTimeoutError(blockId, fetcherConfig.fetchTimeoutMs);
+        }
+        // Store the fetched block locally and update state to Cached
+        await this.innerStore.put(blockId, result.data);
+        await this.availabilityService.setAvailabilityState(blockId, brightchain_lib_1.AvailabilityState.Cached);
+        // Update access metadata if tracking is enabled
+        if (this.config.trackAccess) {
+            await this.updateAccessMetadata(blockId);
+        }
+        // Return the block from the inner store (now stored locally)
+        return this.innerStore.getData(key);
+    }
+    /**
+     * Fetch a block with Available read concern.
+     * Tries to fetch within initialWaitMs; throws PendingBlockError if not resolved in time.
+     *
+     * @see Requirements 2.3
+     */
+    async fetchBlockAvailable(key, blockId) {
+        const fetcherConfig = this.blockFetcher.getConfig();
+        const initialWaitMs = fetcherConfig.initialWaitMs;
+        const fetchPromise = this.blockFetcher.fetchBlock(blockId);
+        // Race the fetch against the initial wait timeout
+        const result = await Promise.race([
+            fetchPromise.then((r) => ({ kind: 'result', value: r })),
+            new Promise((resolve) => setTimeout(() => resolve({ kind: 'timeout' }), initialWaitMs)),
+        ]);
+        if (result.kind === 'timeout') {
+            // Fetch didn't complete in time — throw PendingBlockError
+            const locations = await this.availabilityService.getBlockLocations(blockId);
+            throw new brightchain_lib_1.PendingBlockError(blockId, brightchain_lib_1.AvailabilityState.Remote, locations.map((loc) => loc.nodeId));
+        }
+        // Fetch completed within initialWaitMs
+        if (!result.value.success) {
+            // Fetch failed — still throw PendingBlockError since the block may become available later
+            const locations = await this.availabilityService.getBlockLocations(blockId);
+            throw new brightchain_lib_1.PendingBlockError(blockId, brightchain_lib_1.AvailabilityState.Remote, locations.map((loc) => loc.nodeId));
+        }
+        // Store the fetched block locally and update state to Cached
+        await this.innerStore.put(blockId, result.value.data);
+        await this.availabilityService.setAvailabilityState(blockId, brightchain_lib_1.AvailabilityState.Cached);
         // Update access metadata if tracking is enabled
         if (this.config.trackAccess) {
             await this.updateAccessMetadata(blockId);
         }
-        return block;
+        // Return the block from the inner store
+        return this.innerStore.getData(key);
     }
     /**
      * Store a block's data with optional durability settings.
@@ -119,17 +231,33 @@ class AvailabilityAwareBlockStore {
      */
     async setData(block, options) {
         const blockId = this.keyToHex(block.idChecksum);
+        // Look up pool context from the inner store's metadata
+        // (metadata may already exist if the block was previously stored)
+        const existingMetadata = await this.innerStore.getMetadata(blockId);
+        const poolId = existingMetadata?.poolId;
+        // Check tombstone — reject if pool was deleted
+        if (poolId && this.hasTombstone(poolId)) {
+            throw new brightchain_lib_1.PoolDeletionTombstoneError(poolId);
+        }
         // Store in inner store first
         await this.innerStore.setData(block, options);
-        // Update registry
-        this.registry.addLocal(blockId);
+        // Re-read metadata after store in case it was created during setData
+        const storedMetadata = await this.innerStore.getMetadata(blockId);
+        const resolvedPoolId = poolId ?? storedMetadata?.poolId;
+        // Check tombstone again with resolved poolId (in case metadata was created during store)
+        if (resolvedPoolId && !poolId && this.hasTombstone(resolvedPoolId)) {
+            throw new brightchain_lib_1.PoolDeletionTombstoneError(resolvedPoolId);
+        }
+        // Update registry with pool context
+        this.registry.addLocal(blockId, resolvedPoolId);
         // Update availability state to Local
         await this.availabilityService.setAvailabilityState(blockId, brightchain_lib_1.AvailabilityState.Local);
-        // Update location metadata
+        // Update location metadata with pool context
         const locationRecord = {
             nodeId: this.config.localNodeId,
             lastSeen: new Date(),
             isAuthoritative: true,
+            ...(resolvedPoolId ? { poolId: resolvedPoolId } : {}),
         };
         await this.availabilityService.updateLocation(blockId, locationRecord);
         // Handle partition mode - add to pending sync queue
@@ -143,8 +271,8 @@ class AvailabilityAwareBlockStore {
             this.reconciliationService.addToPendingSyncQueue(syncItem);
         }
         else if (this.config.autoAnnounce) {
-            // Announce to network via gossip
-            await this.gossipService.announceBlock(blockId);
+            // Announce to network via gossip with pool context
+            await this.gossipService.announceBlock(blockId, resolvedPoolId);
         }
     }
     /**
@@ -156,6 +284,9 @@ class AvailabilityAwareBlockStore {
      */
     async deleteData(key) {
         const blockId = this.keyToHex(key);
+        // Look up pool context before deletion
+        const metadata = await this.innerStore.getMetadata(blockId);
+        const poolId = metadata?.poolId;
         // Delete from inner store first
         await this.innerStore.deleteData(key);
         // Update registry
@@ -172,8 +303,8 @@ class AvailabilityAwareBlockStore {
             this.reconciliationService.addToPendingSyncQueue(syncItem);
         }
         else if (this.config.autoAnnounce) {
-            // Announce removal to network via gossip
-            await this.gossipService.announceRemoval(blockId);
+            // Announce removal to network via gossip with pool context
+            await this.gossipService.announceRemoval(blockId, poolId);
         }
     }
     /**
@@ -299,39 +430,108 @@ class AvailabilityAwareBlockStore {
     }
     // === Replication Operations ===
     /**
-     * Get blocks that are pending replication.
+     * Get blocks that are pending replication, scoped by pool.
+     *
+     * A block's replication count for pool P = number of distinct nodes
+     * with a location record for that block with poolId: P.
+     * Blocks without a poolId use the inner store's default pending check.
      *
      * @returns Array of block checksums pending replication
+     * @see Requirements 6.1, 6.2
      */
     async getBlocksPendingReplication() {
-        return this.innerStore.getBlocksPendingReplication();
+        const pendingFromInner = await this.innerStore.getBlocksPendingReplication();
+        const result = [];
+        for (const checksum of pendingFromInner) {
+            const blockId = this.keyToHex(checksum);
+            const metadata = await this.innerStore.getMetadata(blockId);
+            if (!metadata?.poolId) {
+                // No pool context — use inner store's determination
+                result.push(checksum);
+                continue;
+            }
+            // Pool-scoped: count distinct nodes with matching poolId
+            const locations = await this.availabilityService.getBlockLocations(blockId);
+            const poolReplicaCount = this.countPoolScopedReplicas(locations, metadata.poolId);
+            // Still pending if no pool-scoped replicas exist (excluding local node)
+            if (poolReplicaCount <= 1) {
+                result.push(checksum);
+            }
+        }
+        return result;
     }
     /**
-     * Get blocks that are under-replicated.
+     * Get blocks that are under-replicated, scoped by pool.
+     *
+     * A block's replication count for pool P = number of distinct nodes
+     * with a location record for that block with poolId: P.
+     * Under-replicated when pool-scoped replica count < targetReplicationFactor.
      *
      * @returns Array of block checksums that need additional replicas
+     * @see Requirements 6.1, 6.2
      */
     async getUnderReplicatedBlocks() {
-        return this.innerStore.getUnderReplicatedBlocks();
+        const underReplicatedFromInner = await this.innerStore.getUnderReplicatedBlocks();
+        const result = [];
+        for (const checksum of underReplicatedFromInner) {
+            const blockId = this.keyToHex(checksum);
+            const metadata = await this.innerStore.getMetadata(blockId);
+            if (!metadata?.poolId) {
+                // No pool context — use inner store's determination
+                result.push(checksum);
+                continue;
+            }
+            // Pool-scoped: count distinct nodes with matching poolId
+            const locations = await this.availabilityService.getBlockLocations(blockId);
+            const poolReplicaCount = this.countPoolScopedReplicas(locations, metadata.poolId);
+            // Under-replicated if pool-scoped replicas < target
+            if (poolReplicaCount < metadata.targetReplicationFactor) {
+                result.push(checksum);
+            }
+        }
+        return result;
     }
     /**
      * Record that a block has been replicated to a node.
+     * Includes poolId in the location record when the block belongs to a pool.
      *
      * @param key - The block's checksum or ID
      * @param nodeId - The ID of the node that now holds a replica
+     * @see Requirements 6.1, 6.2
      */
     async recordReplication(key, nodeId) {
         const blockId = this.keyToHex(key);
         // Record in inner store
         await this.innerStore.recordReplication(key, nodeId);
-        // Update location metadata
+        // Look up pool context from block metadata
+        const metadata = await this.innerStore.getMetadata(blockId);
+        const poolId = metadata?.poolId;
+        // Update location metadata with pool context
         const locationRecord = {
             nodeId,
             lastSeen: new Date(),
             isAuthoritative: false,
+            ...(poolId ? { poolId } : {}),
         };
         await this.availabilityService.updateLocation(blockId, locationRecord);
     }
+    /**
+     * Count the number of distinct nodes with a location record
+     * for a block that matches the given poolId.
+     *
+     * @param locations - All location records for the block
+     * @param poolId - The pool to scope the count to
+     * @returns Number of distinct nodes with matching poolId
+     */
+    countPoolScopedReplicas(locations, poolId) {
+        const nodeIds = new Set();
+        for (const loc of locations) {
+            if (loc.poolId === poolId) {
+                nodeIds.add(loc.nodeId);
+            }
+        }
+        return nodeIds.size;
+    }
     /**
      * Record that a replica node is no longer available.
      *
@@ -371,7 +571,51 @@ class AvailabilityAwareBlockStore {
         }
         return result;
     }
+    // === Pool Deletion ===
+    /**
+     * Handle a pool deletion event (triggered by a gossip `pool_deleted` announcement).
+     * Records a tombstone, removes all blocks in the pool from the local store,
+     * and removes pool entries from the registry.
+     *
+     * @param poolId - The pool that was deleted
+     * @param originNodeId - The node that originated the deletion
+     * @see Requirements 2.3, 2.4, 2.5
+     */
+    async handlePoolDeletion(poolId, originNodeId) {
+        // Record tombstone
+        this.tombstones.set(poolId, {
+            poolId,
+            deletedAt: new Date(),
+            expiresAt: new Date(Date.now() + this.config.tombstoneConfig.tombstoneTtlMs),
+            originNodeId,
+        });
+        // Remove all blocks in the pool from local store
+        if ((0, brightchain_lib_1.isPooledBlockStore)(this.innerStore)) {
+            await this.innerStore.forceDeletePool(poolId);
+        }
+        // Remove from registry (bulk removal by pool)
+        // The registry's removeLocal with poolId handles per-block removal;
+        // for bulk removal we rely on the pool-scoped manifest to identify blocks.
+        // Future task 11.1 will add pool-aware registry internals.
+    }
     // === Helper Methods ===
+    /**
+     * Check if a pool has an active deletion tombstone.
+     * Cleans up expired tombstones automatically.
+     *
+     * @param poolId - The pool ID to check
+     * @returns True if an active (non-expired) tombstone exists
+     */
+    hasTombstone(poolId) {
+        const tombstone = this.tombstones.get(poolId);
+        if (!tombstone)
+            return false;
+        if (new Date() > tombstone.expiresAt) {
+            this.tombstones.delete(poolId); // Clean up expired
+            return false;
+        }
+        return true;
+    }
     /**
      * Convert a key to hex string format.
      */