plcbundle-bun / src / plcbundle.ts

import type { 
  BundleIndex, 
  BundleMetadata, 
  Operation, 
  ProcessCallback,
  ProcessOptions,
  ProcessStats,
  CloneOptions,
  CloneStats,
  ChainVerificationResult
} from './types';

/**
 * Calculate SHA-256 hash using Bun's native hasher
 */
function sha256(data: Uint8Array | string): string {
  const hasher = new Bun.CryptoHasher("sha256");
  hasher.update(data);
  return Buffer.from(hasher.digest()).toString('hex');
}

/**
 * Main class for reading and processing PLC bundle archives.
 * 
 * This class provides methods for:
 * - Cloning bundles from remote repositories
 * - Reading and verifying local bundles
 * - Streaming operations from bundles
 * - Processing bundles with custom callbacks
 * 
 * All operations use Bun's native features for optimal performance.
 * 
 * @example Basic usage
 * ```ts
 * const bundle = new PLCBundle('./my-bundles');
 * 
 * // Get repository information
 * const stats = await bundle.getStats();
 * console.log(`Repository has ${stats.lastBundle} bundles`);
 * 
 * // Stream operations from a bundle
 * for await (const op of bundle.streamOperations(1)) {
 *   console.log(op.did);
 * }
 * ```
 * 
 * @example Clone from remote
 * ```ts
 * const bundle = new PLCBundle('./bundles');
 * 
 * await bundle.clone('https://plcbundle.atscan.net', {
 *   bundles: '1-100',
 *   threads: 8,
 *   verify: true,
 *   onProgress: (stats) => {
 *     console.log(`${stats.downloadedBundles}/${stats.totalBundles}`);
 *   }
 * });
 * ```
 * 
 * @example Process with callback
 * ```ts
 * await bundle.processBundles(1, 10, (op, pos, num) => {
 *   if (op.did.startsWith('did:plc:')) {
 *     console.log(`Found DID: ${op.did}`);
 *   }
 * }, {
 *   threads: 4,
 *   onProgress: (stats) => console.log(`${stats.totalOps} ops`)
 * });
 * ```
 */
export class PLCBundle {
  private dir: string;
  private indexPath: string;
  private cachedIndex?: BundleIndex;

    /**
   * Create a new PLCBundle instance.
   * 
   * @param dir - Directory containing bundle files (default: './')
   * @param indexPath - Path to the index file (default: `${dir}/plc_bundles.json`)
   * 
   * @example
   * ```ts
   * // Use default directory
   * const bundle1 = new PLCBundle();
   * 
   * // Specify custom directory
   * const bundle2 = new PLCBundle('./my-bundles');
   * 
   * // Custom directory and index path
   * const bundle3 = new PLCBundle('./bundles', './custom-index.json');
   * ```
   */
  constructor(dir: string = './', indexPath?: string) {
    this.dir = dir.endsWith('/') ? dir : `${dir}/`;
    this.indexPath = indexPath || `${this.dir}plc_bundles.json`;
  }

  /**
   * Load the bundle index from disk.
   * 
   * The index is cached in memory after first load. Use `refresh` parameter
   * to force reloading from disk.
   * 
   * @param refresh - If true, reload from disk even if cached (default: false)
   * @returns Promise resolving to the bundle index
   * @throws Error if index file cannot be read or parsed
   * 
   * @example
   * ```ts
   * // Load index (uses cache if available)
   * const index = await bundle.loadIndex();
   * 
   * // Force reload from disk
   * const freshIndex = await bundle.loadIndex(true);
   * ```
   */
  async loadIndex(refresh = false): Promise<BundleIndex> {
    if (!refresh && this.cachedIndex) {
      return this.cachedIndex;
    }
    
    const file = Bun.file(this.indexPath);
    this.cachedIndex = await file.json();
    return this.cachedIndex!;
  }

  /**
   * Save a bundle index to disk.
   * 
   * Writes the index as formatted JSON and updates the in-memory cache.
   * The index is written atomically using Bun's file API.
   * 
   * @param index - The bundle index to save
   * @returns Promise that resolves when save is complete
   * 
   * @example
   * ```ts
   * const index = await bundle.loadIndex();
   * index.last_bundle = 150;
   * await bundle.saveIndex(index);
   * ```
   */
  async saveIndex(index: BundleIndex): Promise<void> {
    await Bun.write(this.indexPath, JSON.stringify(index, null, 2));
    this.cachedIndex = index;
  }

  /**
   * Get metadata for a specific bundle.
   * 
   * @param bundleNum - The bundle number to retrieve metadata for
   * @returns Promise resolving to bundle metadata, or undefined if not found
   * 
   * @example
   * ```ts
   * const metadata = await bundle.getMetadata(42);
   * if (metadata) {
   *   console.log(`Bundle ${metadata.bundle_number} has ${metadata.operation_count} operations`);
   * }
   * ```
   */
  async getMetadata(bundleNum: number): Promise<BundleMetadata | undefined> {
    const index = await this.loadIndex();
    return index.bundles.find(b => b.bundle_number === bundleNum);
  }

  /**
   * Get the file path for a specific bundle.
   * 
   * Bundles are named with zero-padded 6-digit numbers (e.g., `000042.jsonl.zst`).
   * 
   * @param bundleNum - The bundle number
   * @returns Full path to the bundle file
   * 
   * @example
   * ```ts
   * const path = bundle.getBundlePath(42);
   * // Returns: "./bundles/000042.jsonl.zst"
   * ```
   */
  getBundlePath(bundleNum: number): string {
    return `${this.dir}${bundleNum.toString().padStart(6, '0')}.jsonl.zst`;
  }

  /**
   * Read and decompress a bundle file.
   * 
   * Uses Bun's native zstd decompression for optimal performance.
   * 
   * @param bundleNum - The bundle number to read
   * @returns Promise resolving to the decompressed JSONL content as a string
   * @throws Error if bundle file cannot be read or decompressed
   * 
   * @example
   * ```ts
   * const jsonl = await bundle.readBundle(1);
   * console.log(`Bundle size: ${jsonl.length} bytes`);
   * ```
   */
  async readBundle(bundleNum: number): Promise<string> {
    const path = this.getBundlePath(bundleNum);
    const compressed = await Bun.file(path).arrayBuffer();
    const decompressed = Bun.zstdDecompressSync(compressed);
    return new TextDecoder().decode(decompressed);
  }

  /**
   * Parse operations from JSONL content.
   * 
   * @param content - JSONL string with one operation per line
   * @returns Array of parsed operations
   * 
   * @example
   * ```ts
   * const jsonl = await bundle.readBundle(1);
   * const operations = bundle.parseOperations(jsonl);
   * console.log(`Parsed ${operations.length} operations`);
   * ```
   */
  parseOperations(content: string): Operation[] {
    return content
      .split('\n')
      .filter(line => line.trim())
      .map(line => JSON.parse(line));
  }

  /**
   * Stream operations from a bundle (memory efficient).
   * 
   * This async generator yields operations one at a time, which is more
   * memory efficient than loading all operations at once.
   * 
   * @param bundleNum - The bundle number to stream from
   * @yields Operations from the bundle
   * 
   * @example
   * ```ts
   * for await (const op of bundle.streamOperations(1)) {
   *   console.log(op.did);
   *   if (someCondition) break; // Can stop early
   * }
   * ```
   */
  async *streamOperations(bundleNum: number): AsyncGenerator<{ op: Operation; line: string }> {
    const content = await this.readBundle(bundleNum);
    const lines = content.split('\n');
    
    for (const line of lines) {
      if (line.trim()) {
        yield { op: JSON.parse(line), line };
      }
    }
  }

  /**
   * Process multiple bundles with a callback or module.
   * 
   * Two modes:
   * 1. **Direct callback** (single-threaded): Pass callback function
   * 2. **Module path** (multi-threaded): Pass module path in options
   * 
   * @param start - First bundle number
   * @param end - Last bundle number  
   * @param callbackOrOptions - Callback function OR options object with module path
   * @param options - Processing options (only if callback is provided)
   * @returns Promise resolving to processing statistics
   * 
   * @example Single-threaded with callback
   * ```ts
   * await bundle.processBundles(1, 10, (op, pos, num, line) => {
   *   console.log(op.did);
   * });
   * ```
   * 
   * @example Multi-threaded with module
   * ```ts
   * await bundle.processBundles(1, 100, {
   *   module: './detect.ts',
   *   threads: 4,
   *   onProgress: (stats) => console.log(stats.totalOps)
   * });
   * ```
   */
  async processBundles(
    start: number,
    end: number,
    callbackOrOptions: ProcessCallback | ProcessOptions,
    options?: ProcessOptions
  ): Promise<ProcessStats & { matches?: any[] }> {
    let callback: ProcessCallback | undefined;
    let processOptions: ProcessOptions;
    
    if (typeof callbackOrOptions === 'function') {
      callback = callbackOrOptions;
      processOptions = options || {};
    } else {
      processOptions = callbackOrOptions;
    }
    
    const { threads = 1, module, silent = false, flush = false, onProgress, onMatch } = processOptions;
    
    // Validation: multi-threading requires module
    if (threads > 1 && !module) {
      throw new Error('Multi-threading requires module path. Use: processBundles(start, end, { module: "./detect.ts", threads: 4 })');
    }
    
    // Determine mode based on what function is exported
    let mode: 'detect' | 'process' = 'detect';
    let mod: any;
    if (module) {
      try {
        mod = await import(module);
        // If module has 'process' function, use process mode
        if (mod.process) {
          mode = 'process';
        } else if (mod.detect) {
          mode = 'detect';
        }
      } catch (e) {
        // Default to detect
      }
    }
    
    // Use workers for multi-threading with module
    if (threads > 1 && module) {
      return await this.processBundlesWorkers(
        start, 
        end, 
        module, 
        threads, 
        silent, 
        flush, 
        mode, // Pass mode
        onProgress, 
        onMatch
      );
    }

    // Load module if provided but single-threaded
    if (mod && !callback) {
      const userFn = mode === 'detect' ? (mod.detect || mod.default) : (mod.process || mod.default);
      
      callback = (op, position, bundleNum, line) => {
        if (mode === 'detect') {
          userFn({ op });
        } else {
          userFn({ op, position, bundle: bundleNum, line });
        }
      };
    }
    
    if (!callback) {
      throw new Error('Either callback function or module path must be provided');
    }
    
    // Single-threaded fast path
    return await this.processBundlesFast(start, end, callback, onProgress);
  }

  /**
   * Multi-threaded processing using workers (optimized)
   */
  private async processBundlesWorkers(
    start: number,
    end: number,
    modulePath: string,
    threads: number,
    silent: boolean,
    flush: boolean,
    mode: 'detect' | 'process', // Add mode parameter
    onProgress?: (stats: ProcessStats) => void,
    onMatch?: (match: any) => void
  ): Promise<ProcessStats & { matches?: any[] }> {
    const totalBundles = end - start + 1;
    const bundlesPerThread = Math.ceil(totalBundles / threads);
    
    const workerPath = new URL('./worker.ts', import.meta.url).pathname;
    const workers: Worker[] = [];
    const workerStats: Array<{ totalOps: number; totalBytes: number }> = [];
    
    let aggregatedOps = 0;
    let aggregatedBytes = 0;
    const allMatches: any[] = [];
    
    const workerPromises = [];
    
    for (let i = 0; i < threads; i++) {
      const threadStart = start + i * bundlesPerThread;
      const threadEnd = Math.min(threadStart + bundlesPerThread - 1, end);
      
      if (threadStart > end) break;
      
      const worker = new Worker(workerPath);
      workers.push(worker);
      
      workerStats[i] = { totalOps: 0, totalBytes: 0 };
      
      const promise = new Promise<any>((resolve) => {
        worker.onmessage = (event) => {
          const msg = event.data;
          
          if (msg.type === 'progress') {
            const oldStats = workerStats[i];
            aggregatedOps += msg.totalOps - oldStats.totalOps;
            aggregatedBytes += msg.totalBytes - oldStats.totalBytes;
            workerStats[i] = { totalOps: msg.totalOps, totalBytes: msg.totalBytes };
            
            if (onProgress) {
              onProgress({
                totalOps: aggregatedOps,
                matchCount: 0,
                totalBytes: aggregatedBytes,
                matchedBytes: 0,
              });
            }
          } else if (msg.type === 'match') {
            // Handle flushed match - call callback immediately
            if (onMatch) {
              onMatch(msg);
            }
          } else if (msg.type === 'result') {
            resolve(msg);
          }
        };
      });
      
      workerPromises.push(promise);
      
      worker.postMessage({
        dir: this.dir,
        start: threadStart,
        end: threadEnd,
        modulePath,
        silent,
        flush,
        mode, // Pass mode to worker
      });
    }
    
    // Wait for all workers
    const results = await Promise.all(workerPromises);
    
    // Cleanup
    workers.forEach(w => w.terminate());

    if (modulePath) {
      const mod = await import(modulePath);
      if (mod.finalize) {
        await mod.finalize(results, { aggregate: this.aggregate });
      }
    }
    
    // Aggregate results
    let totalOps = 0;
    let totalBytes = 0;
    
    for (const result of results) {
      totalOps += result.totalOps;
      totalBytes += result.totalBytes;
      if (!flush) {
        allMatches.push(...result.matches);
      }
    }
    
    // Sort matches if not flushed
    if (!flush && mode === 'detect') {
      allMatches.sort((a, b) => {
        if (a.bundle !== b.bundle) return a.bundle - b.bundle;
        return a.position - b.position;
      });
    }
    
    return {
      totalOps,
      matchCount: 0,
      totalBytes,
      matchedBytes: 0,
      matches: flush || mode === 'process' ? undefined : allMatches,
    };
  }

  private aggregate(objects: Array<{ [key: string]: number }>): { [key: string]: number } {
    const aggregatedDict: { [key: string]: number } = {};

    for (const currentObj of objects) {
      for (const key in currentObj) {
        if (Object.prototype.hasOwnProperty.call(currentObj, key)) {
          aggregatedDict[key] = (aggregatedDict[key] || 0) + currentObj[key];
        }
      }
    }

    return aggregatedDict;
  }


  /**
   * Fast single-threaded processing (optimized)
   */
  private async processBundlesFast(
    start: number,
    end: number,
    callback: ProcessCallback,
    onProgress?: (stats: ProcessStats) => void
  ): Promise<ProcessStats> {
    const stats: ProcessStats = {
      totalOps: 0,
      matchCount: 0,
      totalBytes: 0,
      matchedBytes: 0,
    };
    
    for (let bundleNum = start; bundleNum <= end; bundleNum++) {
      const content = await this.readBundle(bundleNum);
      const lines = content.split('\n');
      
      for (let position = 0; position < lines.length; position++) {
        const line = lines[position];
        if (!line.trim()) continue;
        
        stats.totalOps++;
        stats.totalBytes += line.length;
        
        const op = JSON.parse(line);
        await callback(op, position, bundleNum, line);
        
        if (onProgress && stats.totalOps % 10000 === 0) {
          onProgress({ ...stats });
        }
      }
    }
    
    return stats;
  }

  /**
   * Clone bundles from a remote repository.
   * 
   * Downloads bundles via HTTP, verifies hashes, and saves progress periodically.
   * Supports resuming interrupted downloads - bundles that already exist and
   * pass verification will be skipped.
   * 
   * Progress is automatically saved every 5 seconds and on completion.
   * 
   * @param remoteUrl - Base URL of the remote bundle repository
   * @param options - Clone options (bundles, threads, verification, callbacks)
   * @returns Promise resolving to clone statistics
   * @throws Error if remote is unreachable or bundle range is invalid
   * 
   * @example Clone all bundles
   * ```ts
   * await bundle.clone('https://plcbundle.atscan.net', {
   *   threads: 8,
   *   verify: true
   * });
   * ```
   * 
   * @example Clone specific range with progress
   * ```ts
   * await bundle.clone('https://plcbundle.atscan.net', {
   *   bundles: '1-100',
   *   threads: 4,
   *   onProgress: (stats) => {
   *     const pct = (stats.downloadedBytes / stats.totalBytes * 100).toFixed(1);
   *     console.log(`${pct}% complete`);
   *   }
   * });
   * ```
   * 
   * @example Resume interrupted download
   * ```ts
   * // First run - interrupted
   * await bundle.clone('https://plcbundle.atscan.net', { bundles: '1-1000' });
   * 
   * // Second run - automatically resumes
   * await bundle.clone('https://plcbundle.atscan.net', { bundles: '1-1000' });
   * ```
   */
  async clone(
    remoteUrl: string,
    options: CloneOptions = {}
  ): Promise<CloneStats> {
    const { threads = 4, bundles, verify = true, shouldStop, onProgress } = options;
    
    // Ensure remote URL doesn't end with /
    const baseUrl = remoteUrl.endsWith('/') ? remoteUrl.slice(0, -1) : remoteUrl;
    
    // Ensure local directory exists
    await Bun.write(Bun.file(this.dir + '.keep'), '');
    
    // Try to load existing local index (for resume)
    let localIndex: BundleIndex | null = null;
    const alreadyDownloaded = new Set<number>();
    
    try {
      localIndex = await this.loadIndex();
      // Track what's already downloaded
      for (const bundle of localIndex.bundles) {
        alreadyDownloaded.add(bundle.bundle_number);
      }
    } catch (error) {
      // No local index yet, that's fine
    }
    
    // Download remote index
    const indexUrl = `${baseUrl}/index.json`;
    const indexResponse = await fetch(indexUrl);
    
    if (!indexResponse.ok) {
      throw new Error(`Failed to fetch index: ${indexResponse.statusText}`);
    }
    
    const remoteIndex: BundleIndex = await indexResponse.json();
    
    // Parse bundle selection
    let start: number, end: number;
    
    if (bundles) {
      if (bundles.includes('-')) {
        const [startStr, endStr] = bundles.split('-');
        start = parseInt(startStr.trim());
        end = parseInt(endStr.trim());
      } else {
        start = parseInt(bundles);
        end = start;
      }
    } else {
      start = 1;
      end = remoteIndex.last_bundle;
    }
    
    // Validate range
    if (start < 1 || end > remoteIndex.last_bundle || start > end) {
      throw new Error(`Invalid bundle range ${start}-${end} (available: 1-${remoteIndex.last_bundle})`);
    }
    
    // Get all bundles in range
    const allBundlesInRange = remoteIndex.bundles.filter(
      b => b.bundle_number >= start && b.bundle_number <= end
    );
    
    // Filter out already downloaded bundles (that still exist and are valid)
    const bundlesToCheck: BundleMetadata[] = [];
    const bundlesToDownload: BundleMetadata[] = [];
    
    for (const bundle of allBundlesInRange) {
      if (alreadyDownloaded.has(bundle.bundle_number)) {
        bundlesToCheck.push(bundle);
      } else {
        bundlesToDownload.push(bundle);
      }
    }
    
    // Initialize stats
    const stats: CloneStats = {
      totalBundles: allBundlesInRange.length,
      downloadedBundles: 0,
      skippedBundles: 0,
      failedBundles: 0,
      totalBytes: allBundlesInRange.reduce((sum, b) => sum + b.compressed_size, 0),
      downloadedBytes: 0,
    };
    
    // Track downloaded bundle numbers (start with already downloaded)
    const downloadedBundleNumbers = new Set<number>(alreadyDownloaded);
    
    // Quick verification of already downloaded bundles
    if (bundlesToCheck.length > 0) {
      for (const metadata of bundlesToCheck) {
        const bundlePath = this.getBundlePath(metadata.bundle_number);
        const bundleFile = Bun.file(bundlePath);
        
        if (await bundleFile.exists()) {
          const existingSize = bundleFile.size;
          
          if (existingSize === metadata.compressed_size) {
            // File exists with correct size
            stats.skippedBundles++;
            stats.downloadedBytes += metadata.compressed_size;
            continue;
          }
        }
        
        // File missing or corrupt, need to re-download
        downloadedBundleNumbers.delete(metadata.bundle_number);
        bundlesToDownload.push(metadata);
      }
      
      if (bundlesToCheck.length > 0) {
        const validCount = stats.skippedBundles;
        const invalidCount = bundlesToCheck.length - validCount;
        
        if (validCount > 0) {
          console.error(`Resuming: found ${validCount} valid bundles, re-downloading ${invalidCount} corrupted bundles\n`);
        }
      }
    }
    
    // If nothing to download, we're done
    if (bundlesToDownload.length === 0) {
      // Save index anyway to make sure it's up to date
      await this.saveIndex(remoteIndex);
      return stats;
    }
    
    console.error(`Downloading ${bundlesToDownload.length} bundles...\n`);
    
    // Function to save partial index
    const savePartialIndex = async () => {
      const partialBundles = remoteIndex.bundles.filter(b => 
        downloadedBundleNumbers.has(b.bundle_number)
      );
      
      if (partialBundles.length === 0) return;
      
      const partialIndex: BundleIndex = {
        ...remoteIndex,
        last_bundle: Math.max(...Array.from(downloadedBundleNumbers)),
        bundles: partialBundles,
      };
      
      await this.saveIndex(partialIndex);
    };
    
    // Download bundle function
    const downloadBundle = async (metadata: BundleMetadata): Promise<void> => {
      // Check if we should stop
      if (shouldStop && shouldStop()) {
        return;
      }
      
      const bundlePath = this.getBundlePath(metadata.bundle_number);
      
      // Download bundle
      try {
        const bundleUrl = `${baseUrl}/data/${metadata.bundle_number}`;
        const response = await fetch(bundleUrl);
        
        if (!response.ok) {
          throw new Error(`HTTP ${response.status}: ${response.statusText}`);
        }
        
        const data = await response.arrayBuffer();
        
        // Verify hash
        if (verify) {
          const downloadedHash = sha256(new Uint8Array(data));
          
          if (downloadedHash !== metadata.compressed_hash) {
            throw new Error(`Hash mismatch: ${downloadedHash} != ${metadata.compressed_hash}`);
          }
        }
        
        // Write to file
        await Bun.write(bundlePath, data);
        
        stats.downloadedBundles++;
        stats.downloadedBytes += metadata.compressed_size;
        downloadedBundleNumbers.add(metadata.bundle_number);
        
        if (onProgress) {
          onProgress({ ...stats });
        }
      } catch (error) {
        stats.failedBundles++;
        throw new Error(`Failed to download bundle ${metadata.bundle_number}: ${error}`);
      }
    };
    
    // Setup periodic index saving (every 5 seconds)
    const saveInterval = setInterval(async () => {
      try {
        await savePartialIndex();
      } catch (error) {
        console.error('Error saving partial index:', error);
      }
    }, 5000);
    
    try {
      // Download in parallel batches
      for (let i = 0; i < bundlesToDownload.length; i += threads) {
        // Check if we should stop before starting new batch
        if (shouldStop && shouldStop()) {
          break;
        }
        
        const batch = bundlesToDownload.slice(i, i + threads);
        await Promise.allSettled(batch.map(downloadBundle));
      }
      
      // Save final index (complete if not stopped, partial if stopped)
      if (shouldStop && shouldStop()) {
        await savePartialIndex();
      } else {
        await this.saveIndex(remoteIndex);
      }
    } finally {
      // Cleanup interval and ensure final save
      clearInterval(saveInterval);
      await savePartialIndex();
    }
    
    return stats;
  }

  /**
   * Verify the integrity of a bundle.
   * 
   * Checks both the compressed file hash and the content hash against
   * the values stored in the bundle index.
   * 
   * Uses Bun's native SHA-256 hasher for optimal performance.
   * 
   * @param bundleNum - The bundle number to verify
   * @returns Promise resolving to verification result
   * 
   * @example
   * ```ts
   * const result = await bundle.verifyBundle(42);
   * if (result.valid) {
   *   console.log('Bundle is valid');
   * } else {
   *   console.error('Verification failed:');
   *   result.errors.forEach(err => console.error(`  - ${err}`));
   * }
   * ```
   */
  async verifyBundle(bundleNum: number): Promise<{ valid: boolean; errors: string[] }> {
    const metadata = await this.getMetadata(bundleNum);
    if (!metadata) {
      return { valid: false, errors: [`Bundle ${bundleNum} not found in index`] };
    }

    const errors: string[] = [];
    const path = this.getBundlePath(bundleNum);
    
    // Verify compressed hash
    const compressed = await Bun.file(path).arrayBuffer();
    const compressedHash = sha256(new Uint8Array(compressed));
    
    if (compressedHash !== metadata.compressed_hash) {
      errors.push(`Compressed hash mismatch: ${compressedHash} != ${metadata.compressed_hash}`);
    }
    
    // Verify content hash
    const decompressed = Bun.zstdDecompressSync(compressed);
    const contentHash = sha256(decompressed);
    
    if (contentHash !== metadata.content_hash) {
      errors.push(`Content hash mismatch: ${contentHash} != ${metadata.content_hash}`);
    }
    
    return { valid: errors.length === 0, errors };
  }

  /**
   * Calculate a chain hash linking bundles together.
   * 
   * The chain hash ensures bundles form an unbroken chain and haven't
   * been tampered with. Genesis bundles use a special hash format.
   * 
   * @param parentHash - Hash of the parent bundle (empty for genesis)
   * @param contentHash - Hash of this bundle's content
   * @param isGenesis - Whether this is the first bundle in the chain
   * @returns The calculated chain hash as a hex string
   * 
   * @example
   * ```ts
   * // Genesis bundle
   * const genesisHash = bundle.calculateChainHash('', contentHash, true);
   * 
   * // Subsequent bundle
   * const chainHash = bundle.calculateChainHash(parentHash, contentHash, false);
   * ```
   */
  calculateChainHash(parentHash: string, contentHash: string, isGenesis: boolean): string {
    const input = isGenesis 
      ? `plcbundle:genesis:${contentHash}`
      : `${parentHash}:${contentHash}`;
    
    return sha256(input);
  }

  /**
   * Get repository statistics.
   * 
   * Provides a quick overview of the bundle repository without loading
   * all bundle metadata.
   * 
   * @returns Promise resolving to repository statistics
   * 
   * @example
   * ```ts
   * const stats = await bundle.getStats();
   * console.log(`Version: ${stats.version}`);
   * console.log(`Bundles: ${stats.totalBundles}`);
   * console.log(`Size: ${(stats.totalSize / 1e9).toFixed(2)} GB`);
   * console.log(`Updated: ${stats.updatedAt}`);
   * ```
   */
  async getStats(): Promise<{
    version: string;
    lastBundle: number;
    totalBundles: number;
    totalSize: number;
    updatedAt: string;
  }> {
    const index = await this.loadIndex();
    return {
      version: index.version,
      lastBundle: index.last_bundle,
      totalBundles: index.bundles.length,
      totalSize: index.total_size_bytes,
      updatedAt: index.updated_at,
    };
  }

    /**
   * Verify the integrity of the entire bundle chain.
   * 
   * This method validates:
   * - Each bundle's compressed and content hashes
   * - The chain hash linking each bundle to its parent
   * - The continuity of the chain (no missing bundles)
   * - The genesis bundle has correct initial hash
   * 
   * @param options - Verification options
   * @param options.start - First bundle to verify (default: 1)
   * @param options.end - Last bundle to verify (default: last available bundle)
   * @param options.onProgress - Callback for progress updates
   * @returns Promise resolving to chain verification result
   * 
   * @example Verify entire chain
   * ```ts
   * const result = await bundle.verifyChain();
   * 
   * if (result.valid) {
   *   console.log(`✓ All ${result.totalBundles} bundles verified`);
   * } else {
   *   console.error(`✗ Chain invalid: ${result.invalidBundles} errors`);
   *   result.errors.forEach(({ bundleNum, errors }) => {
   *     console.error(`Bundle ${bundleNum}:`);
   *     errors.forEach(e => console.error(`  - ${e}`));
   *   });
   * }
   * ```
   * 
   * @example Verify range with progress
   * ```ts
   * const result = await bundle.verifyChain({
   *   start: 1,
   *   end: 100,
   *   onProgress: (current, total) => {
   *     console.log(`Verified ${current}/${total} bundles`);
   *   }
   * });
   * ```
   */
  async verifyChain(options: {
    start?: number;
    end?: number;
    onProgress?: (current: number, total: number) => void;
  } = {}): Promise<ChainVerificationResult> {
    const index = await this.loadIndex();
    
    const start = options.start || 1;
    const end = options.end || index.last_bundle;
    
    // Validate range
    if (start < 1 || end > index.last_bundle || start > end) {
      throw new Error(`Invalid bundle range ${start}-${end} (available: 1-${index.last_bundle})`);
    }
    
    const result: ChainVerificationResult = {
      valid: true,
      totalBundles: end - start + 1,
      validBundles: 0,
      invalidBundles: 0,
      errors: [],
    };
    
    let previousHash = '';
    
    for (let bundleNum = start; bundleNum <= end; bundleNum++) {
      const metadata = index.bundles.find(b => b.bundle_number === bundleNum);
      
      if (!metadata) {
        result.valid = false;
        result.invalidBundles++;
        result.errors.push({
          bundleNum,
          errors: ['Bundle missing from index'],
        });
        continue;
      }
      
      const bundleErrors: string[] = [];
      
      // Verify bundle file hashes
      const verification = await this.verifyBundle(bundleNum);
      if (!verification.valid) {
        bundleErrors.push(...verification.errors);
      }
      
      // Verify chain linkage
      if (bundleNum === 1) {
        // Genesis bundle should have empty parent
        if (metadata.parent !== '') {
          bundleErrors.push(`Genesis bundle should have empty parent, got: ${metadata.parent}`);
        }
        
        // Verify genesis hash format
        const expectedHash = this.calculateChainHash('', metadata.content_hash, true);
        if (metadata.hash !== expectedHash) {
          bundleErrors.push(`Invalid genesis chain hash: ${metadata.hash} != ${expectedHash}`);
        }
      } else {
        // Verify parent reference
        if (metadata.parent !== previousHash) {
          bundleErrors.push(`Parent hash mismatch: expected ${previousHash}, got ${metadata.parent}`);
        }
        
        // Verify chain hash
        const expectedHash = this.calculateChainHash(metadata.parent, metadata.content_hash, false);
        if (metadata.hash !== expectedHash) {
          bundleErrors.push(`Invalid chain hash: ${metadata.hash} != ${expectedHash}`);
        }
      }
      
      // Record results
      if (bundleErrors.length > 0) {
        result.valid = false;
        result.invalidBundles++;
        result.errors.push({
          bundleNum,
          errors: bundleErrors,
        });
      } else {
        result.validBundles++;
      }
      
      previousHash = metadata.hash;
      
      // Report progress
      if (options.onProgress) {
        options.onProgress(bundleNum - start + 1, result.totalBundles);
      }
    }
    
    return result;
  }

}