qa360 2.1.7 → 2.2.0

package/core/src/vault/index.ts

@@ -0,0 +1,1361 @@
+/**
+ * QA360 Evidence Vault Engine
+ * SQLite WAL-based storage with idempotence and CAS integration
+ */
+
+import sqlite3pkg from 'sqlite3';
+const { Database } = sqlite3pkg;
+import { promisify } from 'util';
+import { existsSync, mkdirSync } from 'fs';
+import { join, resolve } from 'path';
+import { randomUUID } from 'crypto';
+import { createHash } from 'crypto';
+import { ContentAddressableStorage, CASArtifact } from './cas.js';
+import { SecurityRedactor } from '../security/redactor.js';
+
+export interface VaultConfig {
+  baseDir: string;
+  enableWAL?: boolean;
+  maxConnections?: number;
+  retentionDays?: number;
+}
+
+export interface RunRecord {
+  id: string;
+  run_key?: string;
+  started_at: number;
+  ended_at?: number;
+  pack_hash: string;
+  pack_path: string;
+  status: 'running' | 'passed' | 'failed' | 'cancelled' | 'error';
+  trust_score?: number;
+  weights_json?: string;
+  sign_alg?: string;
+  signature_hex?: string;
+  proof_pdf_path?: string;
+  pinned: number;
+  created_at: number;
+  updated_at: number;
+}
+
+export interface GateRecord {
+  id?: number;
+  run_id: string;
+  name: string;
+  status: 'passed' | 'failed' | 'skipped' | 'warn';
+  duration_ms?: number;
+  metrics_json?: string;
+  budgets_json?: string;
+  started_at?: number;
+  ended_at?: number;
+  created_at: number;
+}
+
+export interface FindingRecord {
+  id?: number;
+  run_id: string;
+  gate: string;
+  severity: 'info' | 'low' | 'medium' | 'high' | 'critical';
+  rule: string;
+  location?: string;
+  message: string;
+  raw_output?: string;
+  fingerprint?: string;
+  created_at: number;
+}
+
+/**
+ * Flakiness history record - tracks test reliability over time
+ */
+export interface FlakinessRecord {
+  id?: number;
+  run_id: string;
+  test_id: string;  // Hashed test identifier
+  test_name: string;
+  gate: string;
+  file_path: string;
+  score: number;  // 0-100 flakiness score
+  category: 'legendary' | 'solid' | 'good' | 'shaky' | 'unstable';
+  total_runs: number;
+  successful_runs: number;
+  avg_duration_ms: number;
+  pattern_type?: string;
+  suggested_fix?: string;
+  confidence?: number;
+  first_seen: number;
+  last_seen: number;
+  current_streak?: number;
+  streak_type?: 'pass' | 'fail';
+  created_at: number;
+}
+
+/**
+ * Flakiness pattern detection record
+ */
+export interface FlakinessPatternRecord {
+  id?: number;
+  test_id: string;  // Hashed test identifier
+  test_name: string;
+  pattern_type: 'timing' | 'race_condition' | 'external_dependency' | 'environment_specific' | 'selector_issue' | 'unknown';
+  description: string;
+  suggested_fix: string;
+  confidence: number;  // 0-1
+  auto_fix_possible: boolean;
+  first_detected: number;
+  last_detected: number;
+  detection_count: number;
+  created_at: number;
+  updated_at: number;
+}
+
+/**
+ * Flakiness quarantine record
+ */
+export interface QuarantineRecord {
+  id?: number;
+  test_id: string;  // Hashed test identifier
+  test_name: string;
+  gate: string;
+  file_path: string;
+  reason: string;
+  score: number;  // Score at time of quarantine
+  category: 'shaky' | 'unstable';
+  quarantined_at: number;
+  quarantined_by: string;  // 'auto' or user_id
+  resolved_at?: number;
+  resolved_by?: string;
+  notes?: string;
+  created_at: number;
+  updated_at: number;
+}
+
+export interface ArtifactRecord {
+  sha256: string;
+  mime_type: string;
+  size_bytes: number;
+  cas_path: string;
+  original_name?: string;
+  created_at: number;
+  last_accessed: number;
+}
+
+export interface RunArtifactLink {
+  run_id: string;
+  sha256: string;
+  label: string;
+  created_at: number;
+}
+
+export interface BeginRunOptions {
+  run_key?: string;
+  pack_path: string;
+  pack_hash: string;
+  weights?: Record<string, any>;
+  started_at?: number;  // Optional: use pre-existing timestamp (e.g., from run start)
+}
+
+export interface FinishRunOptions {
+  status: 'passed' | 'failed' | 'cancelled' | 'error';
+  trust_score?: number;
+  signature?: string;
+  proof_pdf_sha?: string;
+  weights?: Record<string, any>;
+}
+
+export interface RunFilters {
+  status?: string[];
+  since?: Date;
+  until?: Date;
+  pack_hash?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export interface VaultStats {
+  totalRuns: number;
+  totalGates: number;
+  totalFindings: number;
+  totalArtifacts: number;
+  vaultSizeBytes: number;
+  oldestRun?: Date;
+  newestRun?: Date;
+}
+
+export class EvidenceVault {
+  private db!: InstanceType<typeof Database>;
+  private cas: ContentAddressableStorage;
+  private redactor: SecurityRedactor;
+  private readonly dbPath: string;
+  private readonly baseDir: string;
+
+  constructor(config: VaultConfig) {
+    this.baseDir = resolve(config.baseDir);
+    this.dbPath = join(this.baseDir, 'vault.db');
+    this.cas = new ContentAddressableStorage(join(this.baseDir, 'runs'));
+    this.redactor = SecurityRedactor.forReports();
+    
+    this.ensureDirectories();
+    this.initializeDatabase(config);
+  }
+
+  /**
+   * Open vault connection and initialize schema
+   */
+  static async open(baseDir: string, config?: Partial<VaultConfig>): Promise<EvidenceVault> {
+    const fullConfig: VaultConfig = {
+      baseDir,
+      enableWAL: true,
+      maxConnections: 10,
+      retentionDays: 90,
+      ...config
+    };
+
+    const vault = new EvidenceVault(fullConfig);
+    await vault.initializeSchema();
+    return vault;
+  }
+
+  /**
+   * Begin a new run with idempotence support
+   */
+  async beginRun(options: BeginRunOptions): Promise<{ runId: string; isReused: boolean }> {
+    // Check for existing run with same run_key
+    if (options.run_key) {
+      const existing = await this.getRunByKey(options.run_key);
+      if (existing) {
+        console.log(`[VAULT] RUN_IDEMPOTENT_REUSED: ${existing.id} (key: ${options.run_key})`);
+        return { runId: existing.id, isReused: true };
+      }
+    }
+
+    const runId = randomUUID();
+    const now = options.started_at ?? Date.now();  // Use provided timestamp or current time
+
+    const run: Partial<RunRecord> = {
+      id: runId,
+      run_key: options.run_key,
+      started_at: now,
+      pack_hash: options.pack_hash,
+      pack_path: options.pack_path,
+      status: 'running',
+      weights_json: options.weights ? JSON.stringify(options.weights) : undefined,
+      pinned: 0,
+      created_at: now,
+      updated_at: now
+    };
+
+    await this.insertRun(run);
+    console.log(`[VAULT] RUN_STARTED: ${runId} (key: ${options.run_key || 'none'})`);
+    
+    return { runId, isReused: false };
+  }
+
+  /**
+   * Finish a run with final status and signature
+   */
+  async finishRun(runId: string, options: FinishRunOptions): Promise<void> {
+    const now = Date.now();
+    
+    const updates: Partial<RunRecord> = {
+      ended_at: now,
+      status: options.status,
+      trust_score: options.trust_score,
+      signature_hex: options.signature,
+      updated_at: now
+    };
+
+    if (options.weights) {
+      updates.weights_json = JSON.stringify(options.weights);
+    }
+
+    if (options.proof_pdf_sha) {
+      const artifact = await this.getArtifact(options.proof_pdf_sha);
+      if (artifact) {
+        updates.proof_pdf_path = artifact.cas_path;
+        await this.attachArtifact(runId, { sha256: options.proof_pdf_sha, label: 'proof_pdf' });
+      }
+    }
+
+    await this.updateRun(runId, updates);
+    console.log(`[VAULT] RUN_FINISHED: ${runId} (status: ${options.status}, trust: ${options.trust_score})`);
+  }
+
+  /**
+   * Record gate execution result
+   */
+  async recordGate(runId: string, gate: Omit<GateRecord, 'id' | 'run_id' | 'created_at'>): Promise<number> {
+    const gateRecord: Omit<GateRecord, 'id'> = {
+      run_id: runId,
+      created_at: Date.now(),
+      ...gate
+    };
+
+    const gateId = await this.insertGate(gateRecord);
+    console.log(`[VAULT] GATE_RECORDED: ${runId}/${gate.name} (status: ${gate.status}, duration: ${gate.duration_ms}ms)`);
+    
+    return gateId;
+  }
+
+  /**
+   * Record security/quality finding
+   */
+  async recordFinding(runId: string, finding: Omit<FindingRecord, 'id' | 'run_id' | 'created_at'>): Promise<number> {
+    // Redact sensitive information
+    const redactedFinding: Omit<FindingRecord, 'id'> = {
+      run_id: runId,
+      created_at: Date.now(),
+      ...finding,
+      message: this.redactor.redact(finding.message),
+      raw_output: finding.raw_output ? this.redactor.redact(finding.raw_output) : undefined,
+      fingerprint: finding.fingerprint || this.generateFindingFingerprint(finding)
+    };
+
+    const findingId = await this.insertFinding(redactedFinding);
+    console.log(`[VAULT] FINDING_RECORDED: ${runId}/${finding.gate} (severity: ${finding.severity}, rule: ${finding.rule})`);
+
+    return findingId;
+  }
+
+  /**
+   * Record flakiness analysis result
+   */
+  async recordFlakiness(runId: string, flakiness: Omit<FlakinessRecord, 'id' | 'created_at' | 'run_id'>): Promise<number> {
+    const flakinessRecord: Omit<FlakinessRecord, 'id'> = {
+      run_id: runId,
+      created_at: Date.now(),
+      ...flakiness
+    };
+
+    const flakinessId = await this.insertFlakiness(flakinessRecord);
+    console.log(`[VAULT] FLAKINESS_RECORDED: ${runId}/${flakiness.test_name} (score: ${flakiness.score}, category: ${flakiness.category})`);
+
+    return flakinessId;
+  }
+
+  /**
+   * Record detected flakiness pattern
+   */
+  async recordFlakinessPattern(pattern: Omit<FlakinessPatternRecord, 'id' | 'created_at' | 'updated_at' | 'first_detected' | 'last_detected' | 'detection_count'>): Promise<number> {
+    const now = Date.now();
+
+    // Check if pattern already exists for this test
+    const existing = await this.getFlakinessPattern(pattern.test_id, pattern.pattern_type);
+
+    if (existing) {
+      // Update existing pattern
+      await this.updateFlakinessPattern(existing.id!, {
+        last_detected: now,
+        detection_count: (existing.detection_count || 0) + 1,
+        updated_at: now
+      });
+      console.log(`[VAULT] FLAKY_PATTERN_UPDATED: ${pattern.test_name} (${pattern.pattern_type})`);
+      return existing.id!;
+    }
+
+    // Insert new pattern
+    const patternRecord: Omit<FlakinessPatternRecord, 'id'> = {
+      first_detected: now,
+      last_detected: now,
+      detection_count: 1,
+      created_at: now,
+      updated_at: now,
+      ...pattern
+    };
+
+    const patternId = await this.insertFlakinessPattern(patternRecord);
+    console.log(`[VAULT] FLAKY_PATTERN_DETECTED: ${pattern.test_name} (${pattern.pattern_type})`);
+
+    return patternId;
+  }
+
+  /**
+   * Add test to quarantine
+   */
+  async addToQuarantine(quarantine: Omit<QuarantineRecord, 'id' | 'created_at' | 'updated_at'>): Promise<number> {
+    const now = Date.now();
+
+    // Check if already in quarantine
+    const existing = await this.getQuarantine(quarantine.test_id);
+
+    if (existing && !existing.resolved_at) {
+      console.log(`[VAULT] ALREADY_IN_QUARANTINE: ${quarantine.test_name}`);
+      return existing.id!;
+    }
+
+    const quarantineRecord: Omit<QuarantineRecord, 'id'> = {
+      created_at: now,
+      updated_at: now,
+      ...quarantine
+    };
+
+    const quarantineId = await this.insertQuarantine(quarantineRecord);
+    console.log(`[VAULT] QUARANTINED: ${quarantine.test_name} (${quarantine.category})`);
+
+    return quarantineId;
+  }
+
+  /**
+   * Remove test from quarantine
+   */
+  async removeFromQuarantine(testId: string, resolvedBy: string, notes?: string): Promise<void> {
+    await this.updateQuarantine(testId, {
+      resolved_at: Date.now(),
+      resolved_by: resolvedBy,
+      notes,
+      updated_at: Date.now()
+    });
+    console.log(`[VAULT] QUARANTINE_REMOVED: ${testId} (by: ${resolvedBy})`);
+  }
+
+  /**
+   * Get flakiness history for a test
+   */
+  async getFlakinessHistory(testId: string, limit: number = 50): Promise<FlakinessRecord[]> {
+    return new Promise((resolve, reject) => {
+      this.db.all(
+        `SELECT * FROM flakiness_history WHERE test_id = ? ORDER BY created_at DESC LIMIT ?`,
+        [testId, limit],
+        (err: Error | null, rows: any) => {
+          if (err) reject(err);
+          else resolve(rows as FlakinessRecord[]);
+        }
+      );
+    });
+  }
+
+  /**
+   * Get flakiness history for a run
+   */
+  async getRunFlakiness(runId: string): Promise<FlakinessRecord[]> {
+    return new Promise((resolve, reject) => {
+      this.db.all(
+        `SELECT * FROM flakiness_history WHERE run_id = ? ORDER BY score ASC`,
+        [runId],
+        (err: Error | null, rows: any) => {
+          if (err) reject(err);
+          else resolve(rows as FlakinessRecord[]);
+        }
+      );
+    });
+  }
+
+  /**
+   * Get all quarantined tests
+   */
+  async getQuarantinedTests(includeResolved: boolean = false): Promise<QuarantineRecord[]> {
+    let query = 'SELECT * FROM flakiness_quarantine WHERE 1=1';
+    const params: any[] = [];
+
+    if (!includeResolved) {
+      query += ' AND resolved_at IS NULL';
+    }
+
+    query += ' ORDER BY quarantined_at DESC';
+
+    return new Promise((resolve, reject) => {
+      this.db.all(query, params, (err: Error | null, rows: any) => {
+        if (err) reject(err);
+        else resolve(rows as QuarantineRecord[]);
+      });
+    });
+  }
+
+  /**
+   * Get quarantine record for a test
+   */
+  async getQuarantine(testId: string): Promise<QuarantineRecord | null> {
+    return new Promise((resolve, reject) => {
+      this.db.get(
+        'SELECT * FROM flakiness_quarantine WHERE test_id = ? ORDER BY created_at DESC LIMIT 1',
+        [testId],
+        (err: Error | null, row: any) => {
+          if (err) reject(err);
+          else resolve(row as QuarantineRecord || null);
+        }
+      );
+    });
+  }
+
+  /**
+   * Get flakiness pattern for a test
+   */
+  async getFlakinessPattern(testId: string, patternType: string): Promise<FlakinessPatternRecord | null> {
+    return new Promise((resolve, reject) => {
+      this.db.get(
+        'SELECT * FROM flakiness_patterns WHERE test_id = ? AND pattern_type = ?',
+        [testId, patternType],
+        (err: Error | null, row: any) => {
+          if (err) reject(err);
+          else resolve(row as FlakinessPatternRecord || null);
+        }
+      );
+    });
+  }
+
+  /**
+   * Get flakiness trends for a test
+   */
+  async getFlakinessTrends(testId: string, days: number = 30): Promise<{
+    testId: string;
+    currentScore: number;
+    averageScore: number;
+    trend: 'improving' | 'stable' | 'degrading';
+    dataPoints: Array<{ date: number; score: number }>;
+  }> {
+    const cutoff = Date.now() - (days * 24 * 60 * 60 * 1000);
+
+    return new Promise((resolve, reject) => {
+      this.db.all(
+        `SELECT created_at, score FROM flakiness_history WHERE test_id = ? AND created_at >= ? ORDER BY created_at ASC`,
+        [testId, cutoff],
+        (err: Error | null, rows: any[]) => {
+          if (err) {
+            reject(err);
+          } else {
+            const rawPoints = rows as Array<{ created_at: number; score: number }>;
+            // Convert to expected format with 'date' property
+            const dataPoints = rawPoints.map(p => ({ date: p.created_at, score: p.score }));
+
+            if (dataPoints.length === 0) {
+              resolve({
+                testId,
+                currentScore: 100,
+                averageScore: 100,
+                trend: 'stable',
+                dataPoints: []
+              });
+              return;
+            }
+
+            const currentScore = dataPoints[dataPoints.length - 1].score;
+            const averageScore = Math.round(dataPoints.reduce((sum, p) => sum + p.score, 0) / dataPoints.length);
+
+            // Calculate trend
+            let trend: 'improving' | 'stable' | 'degrading' = 'stable';
+            if (dataPoints.length >= 3) {
+              const recent = dataPoints.slice(-3);
+              const older = dataPoints.slice(0, -3);
+              const recentAvg = recent.reduce((sum, p) => sum + p.score, 0) / recent.length;
+              const olderAvg = older.reduce((sum, p) => sum + p.score, 0) / older.length;
+
+              if (recentAvg > olderAvg + 5) trend = 'improving';
+              else if (recentAvg < olderAvg - 5) trend = 'degrading';
+            }
+
+            resolve({
+              testId,
+              currentScore,
+              averageScore,
+              trend,
+              dataPoints
+            });
+          }
+        }
+      );
+    });
+  }
+
+  /**
+   * Store artifact in CAS and link to run
+   */
+  async storeArtifact(runId: string, content: Buffer, mimeType: string, label: string, originalName?: string): Promise<CASArtifact> {
+    const casArtifact = await this.cas.saveArtifact(content, mimeType, originalName);
+    
+    // Store artifact metadata
+    const artifact: ArtifactRecord = {
+      sha256: casArtifact.sha256,
+      mime_type: mimeType,
+      size_bytes: casArtifact.size,
+      cas_path: casArtifact.path,
+      original_name: originalName,
+      created_at: Date.now(),
+      last_accessed: Date.now()
+    };
+
+    await this.insertArtifact(artifact);
+    await this.attachArtifact(runId, { sha256: casArtifact.sha256, label });
+
+    console.log(`[VAULT] ARTIFACT_STORED: ${runId}/${label} (sha256: ${casArtifact.sha256.substring(0, 8)}..., size: ${casArtifact.size})`);
+    
+    return casArtifact;
+  }
+
+  /**
+   * Attach existing artifact to run
+   */
+  async attachArtifact(runId: string, link: { sha256: string; label: string }): Promise<void> {
+    const linkRecord: RunArtifactLink = {
+      run_id: runId,
+      sha256: link.sha256,
+      label: link.label,
+      created_at: Date.now()
+    };
+
+    await this.insertRunArtifact(linkRecord);
+  }
+
+  /**
+   * Get run by ID
+   */
+  async getRun(runId: string): Promise<RunRecord | null> {
+    return new Promise((resolve, reject) => {
+      this.db.get(
+        'SELECT * FROM runs WHERE id = ?',
+        [runId],
+        (err: Error | null, row: any) => {
+          if (err) reject(err);
+          else resolve(row as RunRecord || null);
+        }
+      );
+    });
+  }
+
+  /**
+   * Get run by ID prefix (e.g., "6ce422f7" for shortened display)
+   * Returns null if multiple or no runs match the prefix
+   */
+  async getRunByPrefix(prefix: string): Promise<RunRecord | null> {
+    const allRuns = await this.listRuns({});
+    const matching = allRuns.filter(r => r.id.startsWith(prefix));
+
+    if (matching.length === 0) {
+      return null;
+    }
+    if (matching.length > 1) {
+      // Ambiguous prefix - return null to indicate error
+      return null;
+    }
+    return matching[0];
+  }
+
+  /**
+   * Get run by run_key
+   */
+  async getRunByKey(runKey: string): Promise<RunRecord | null> {
+    return new Promise((resolve, reject) => {
+      this.db.get(
+        'SELECT * FROM runs WHERE run_key = ?',
+        [runKey],
+        (err: Error | null, row: any) => {
+          if (err) reject(err);
+          else resolve(row as RunRecord || null);
+        }
+      );
+    });
+  }
+
+  /**
+   * List runs with filters
+   */
+  async listRuns(filters?: RunFilters): Promise<RunRecord[]> {
+    let query = 'SELECT * FROM runs WHERE 1=1';
+    const params: any[] = [];
+
+    if (filters?.status?.length) {
+      query += ` AND status IN (${filters.status.map(() => '?').join(',')})`;
+      params.push(...filters.status);
+    }
+
+    if (filters?.since) {
+      query += ' AND started_at >= ?';
+      params.push(filters.since.getTime());
+    }
+
+    if (filters?.until) {
+      query += ' AND started_at <= ?';
+      params.push(filters.until.getTime());
+    }
+
+    if (filters?.pack_hash) {
+      query += ' AND pack_hash = ?';
+      params.push(filters.pack_hash);
+    }
+
+    query += ' ORDER BY started_at DESC';
+
+    if (filters?.limit) {
+      query += ' LIMIT ?';
+      params.push(filters.limit);
+      
+      if (filters?.offset) {
+        query += ' OFFSET ?';
+        params.push(filters.offset);
+      }
+    }
+
+    return new Promise((resolve, reject) => {
+      this.db.all(query, params, (err: Error | null, rows: any) => {
+        if (err) reject(err);
+        else resolve(rows as RunRecord[]);
+      });
+    });
+  }
+
+  /**
+   * Get gates for a run
+   */
+  async getGates(runId: string): Promise<GateRecord[]> {
+    return new Promise((resolve, reject) => {
+      this.db.all(
+        'SELECT * FROM gates WHERE run_id = ? ORDER BY created_at',
+        [runId],
+        (err: Error | null, rows: any) => {
+          if (err) reject(err);
+          else resolve(rows as GateRecord[]);
+        }
+      );
+    });
+  }
+
+  /**
+   * Get findings for a run
+   */
+  async getFindings(runId: string, gate?: string): Promise<FindingRecord[]> {
+    let query = 'SELECT * FROM findings WHERE run_id = ?';
+    const params = [runId];
+
+    if (gate) {
+      query += ' AND gate = ?';
+      params.push(gate);
+    }
+
+    query += ' ORDER BY severity DESC, created_at';
+
+    return new Promise((resolve, reject) => {
+      this.db.all(query, params, (err: Error | null, rows: any) => {
+        if (err) reject(err);
+        else resolve(rows as FindingRecord[]);
+      });
+    });
+  }
+
+  /**
+   * Get artifacts for a run
+   */
+  async getRunArtifacts(runId: string): Promise<Array<ArtifactRecord & { label: string }>> {
+    return new Promise((resolve, reject) => {
+      this.db.all(`
+        SELECT a.*, ra.label 
+        FROM artifacts a
+        JOIN run_artifacts ra ON a.sha256 = ra.sha256
+        WHERE ra.run_id = ?
+        ORDER BY ra.created_at
+      `, [runId], (err: Error | null, rows: any) => {
+        if (err) reject(err);
+        else resolve(rows as Array<ArtifactRecord & { label: string }>);
+      });
+    });
+  }
+
+  /**
+   * Get artifact by SHA256
+   */
+  async getArtifact(sha256: string): Promise<ArtifactRecord | null> {
+    return new Promise((resolve, reject) => {
+      this.db.get(
+        'SELECT * FROM artifacts WHERE sha256 = ?',
+        [sha256],
+        (err: Error | null, row: any) => {
+          if (err) reject(err);
+          else resolve(row as ArtifactRecord || null);
+        }
+      );
+    });
+  }
+
+  /**
+   * Pin/unpin run to protect from GC
+   */
+  async pinRun(runId: string, pinned: boolean = true): Promise<void> {
+    await this.updateRun(runId, { pinned: pinned ? 1 : 0 });
+    console.log(`[VAULT] RUN_${pinned ? 'PINNED' : 'UNPINNED'}: ${runId}`);
+  }
+
+  /**
+   * Calculate pack hash for idempotence
+   */
+  static calculatePackHash(packContent: string): string {
+    // Normalize pack content (remove comments, sort keys, etc.)
+    const normalized = packContent
+      .split('\n')
+      .filter(line => !line.trim().startsWith('#'))
+      .join('\n')
+      .trim();
+    
+    return createHash('sha256').update(normalized).digest('hex');
+  }
+
+  /**
+   * Get vault statistics
+   */
+  async getStats(): Promise<VaultStats> {
+    const queries = [
+      'SELECT COUNT(*) as count FROM runs',
+      'SELECT COUNT(*) as count FROM gates',
+      'SELECT COUNT(*) as count FROM findings',
+      'SELECT COUNT(*) as count FROM artifacts',
+      'SELECT MIN(started_at) as oldest, MAX(started_at) as newest FROM runs'
+    ];
+
+    const results = await Promise.all(
+      queries.map(query => new Promise<any>((resolve, reject) => {
+        this.db.get(query, (err: Error | null, row: any) => {
+          if (err) reject(err);
+          else resolve(row);
+        });
+      }))
+    );
+
+    const casStats = await this.cas.getStats();
+
+    return {
+      totalRuns: results[0].count,
+      totalGates: results[1].count,
+      totalFindings: results[2].count,
+      totalArtifacts: results[3].count,
+      vaultSizeBytes: casStats.totalBytes,
+      oldestRun: results[4].oldest ? new Date(results[4].oldest) : undefined,
+      newestRun: results[4].newest ? new Date(results[4].newest) : undefined
+    };
+  }
+
+  // Private helper methods
+
+  private async insertRun(run: Partial<RunRecord>): Promise<void> {
+    const fields = Object.keys(run).join(', ');
+    const placeholders = Object.keys(run).map(() => '?').join(', ');
+    const values = Object.values(run);
+
+    return new Promise((resolve, reject) => {
+      this.db.run(
+        `INSERT INTO runs (${fields}) VALUES (${placeholders})`,
+        values,
+        (err: Error | null) => {
+          if (err) reject(err);
+          else resolve();
+        }
+      );
+    });
+  }
+
+  private async updateRun(runId: string, updates: Partial<RunRecord>): Promise<void> {
+    const fields = Object.keys(updates).map(key => `${key} = ?`).join(', ');
+    const values = [...Object.values(updates), runId];
+
+    return new Promise((resolve, reject) => {
+      this.db.run(
+        `UPDATE runs SET ${fields} WHERE id = ?`,
+        values,
+        (err: Error | null) => {
+          if (err) reject(err);
+          else resolve();
+        }
+      );
+    });
+  }
+
+  private async insertGate(gate: Omit<GateRecord, 'id'>): Promise<number> {
+    const fields = Object.keys(gate).join(', ');
+    const placeholders = Object.keys(gate).map(() => '?').join(', ');
+    const values = Object.values(gate);
+
+    return new Promise((resolve, reject) => {
+      this.db.run(
+        `INSERT INTO gates (${fields}) VALUES (${placeholders})`,
+        values,
+        function(err) {
+          if (err) reject(err);
+          else resolve(this.lastID);
+        }
+      );
+    });
+  }
+
+  private async insertFinding(finding: Omit<FindingRecord, 'id'>): Promise<number> {
+    const fields = Object.keys(finding).join(', ');
+    const placeholders = Object.keys(finding).map(() => '?').join(', ');
+    const values = Object.values(finding);
+
+    return new Promise((resolve, reject) => {
+      this.db.run(
+        `INSERT INTO findings (${fields}) VALUES (${placeholders})`,
+        values,
+        function(err) {
+          if (err) reject(err);
+          else resolve(this.lastID);
+        }
+      );
+    });
+  }
+
+  private async insertArtifact(artifact: ArtifactRecord): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.db.run(
+        `INSERT OR IGNORE INTO artifacts (sha256, mime_type, size_bytes, cas_path, original_name, created_at, last_accessed) 
+         VALUES (?, ?, ?, ?, ?, ?, ?)`,
+        [
+          artifact.sha256,
+          artifact.mime_type,
+          artifact.size_bytes,
+          artifact.cas_path,
+          artifact.original_name,
+          artifact.created_at,
+          artifact.last_accessed
+        ],
+        (err: Error | null) => {
+          if (err) reject(err);
+          else resolve();
+        }
+      );
+    });
+  }
+
+  private async insertRunArtifact(link: RunArtifactLink): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.db.run(
+        'INSERT OR IGNORE INTO run_artifacts (run_id, sha256, label, created_at) VALUES (?, ?, ?, ?)',
+        [link.run_id, link.sha256, link.label, link.created_at],
+        (err: Error | null) => {
+          if (err) reject(err);
+          else resolve();
+        }
+      );
+    });
+  }
+
+  private async insertFlakiness(flakiness: Omit<FlakinessRecord, 'id'>): Promise<number> {
+    const fields = Object.keys(flakiness).join(', ');
+    const placeholders = Object.keys(flakiness).map(() => '?').join(', ');
+    const values = Object.values(flakiness);
+
+    return new Promise((resolve, reject) => {
+      this.db.run(
+        `INSERT INTO flakiness_history (${fields}) VALUES (${placeholders})`,
+        values,
+        function(err) {
+          if (err) reject(err);
+          else resolve(this.lastID);
+        }
+      );
+    });
+  }
+
+  private async insertFlakinessPattern(pattern: Omit<FlakinessPatternRecord, 'id'>): Promise<number> {
+    const fields = Object.keys(pattern).join(', ');
+    const placeholders = Object.keys(pattern).map(() => '?').join(', ');
+    const values = Object.values(pattern);
+
+    return new Promise((resolve, reject) => {
+      this.db.run(
+        `INSERT INTO flakiness_patterns (${fields}) VALUES (${placeholders})`,
+        values,
+        function(err) {
+          if (err) reject(err);
+          else resolve(this.lastID);
+        }
+      );
+    });
+  }
+
+  private async updateFlakinessPattern(id: number, updates: Partial<FlakinessPatternRecord>): Promise<void> {
+    const fields = Object.keys(updates).map(key => `${key} = ?`).join(', ');
+    const values = [...Object.values(updates), id];
+
+    return new Promise((resolve, reject) => {
+      this.db.run(
+        `UPDATE flakiness_patterns SET ${fields} WHERE id = ?`,
+        values,
+        (err: Error | null) => {
+          if (err) reject(err);
+          else resolve();
+        }
+      );
+    });
+  }
+
+  private async insertQuarantine(quarantine: Omit<QuarantineRecord, 'id'>): Promise<number> {
+    const fields = Object.keys(quarantine).join(', ');
+    const placeholders = Object.keys(quarantine).map(() => '?').join(', ');
+    const values = Object.values(quarantine);
+
+    return new Promise((resolve, reject) => {
+      this.db.run(
+        `INSERT INTO flakiness_quarantine (${fields}) VALUES (${placeholders})`,
+        values,
+        function(err) {
+          if (err) reject(err);
+          else resolve(this.lastID);
+        }
+      );
+    });
+  }
+
+  private async updateQuarantine(testId: string, updates: Partial<QuarantineRecord>): Promise<void> {
+    const fields = Object.keys(updates).map(key => `${key} = ?`).join(', ');
+    const values = [...Object.values(updates), testId];
+
+    return new Promise((resolve, reject) => {
+      this.db.run(
+        `UPDATE flakiness_quarantine SET ${fields} WHERE test_id = ?`,
+        values,
+        (err: Error | null) => {
+          if (err) reject(err);
+          else resolve();
+        }
+      );
+    });
+  }
+
+  private generateFindingFingerprint(finding: Omit<FindingRecord, 'id' | 'run_id' | 'created_at'>): string {
+    const content = `${finding.gate}:${finding.rule}:${finding.location || ''}:${finding.message}`;
+    return createHash('sha256').update(content).digest('hex').substring(0, 16);
+  }
+
+  /**
+   * Initialize database connection
+   */
+  private initializeDatabase(config: VaultConfig): void {
+    this.db = new Database(this.dbPath);
+    
+    if (config.enableWAL) {
+      this.db.exec('PRAGMA journal_mode = WAL');
+      this.db.exec('PRAGMA synchronous = NORMAL');
+    }
+    
+    this.db.exec('PRAGMA foreign_keys = ON');
+    this.db.exec('PRAGMA cache_size = 10000');
+    this.db.exec('PRAGMA temp_store = MEMORY');
+  }
+
+  /**
+   * Initialize database schema
+   */
+  async initializeSchema(): Promise<void> {
+    const schema = `
+-- QA360 Evidence Vault Schema
+-- SQLite WAL mode for concurrent access and performance
+
+-- Runs table: core execution records
+CREATE TABLE IF NOT EXISTS runs (
+    id TEXT PRIMARY KEY,
+    run_key TEXT UNIQUE,
+    started_at INTEGER NOT NULL,
+    ended_at INTEGER,
+    pack_hash TEXT NOT NULL,
+    pack_path TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'running',
+    trust_score INTEGER,
+    weights_json TEXT,
+    sign_alg TEXT DEFAULT 'ed25519',
+    signature_hex TEXT,
+    proof_pdf_path TEXT,
+    pinned INTEGER DEFAULT 0,
+    created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
+    updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000)
+);
+
+-- Gates table: individual test gate results
+CREATE TABLE IF NOT EXISTS gates (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    run_id TEXT NOT NULL REFERENCES runs(id) ON DELETE CASCADE,
+    name TEXT NOT NULL,
+    status TEXT NOT NULL,
+    duration_ms INTEGER,
+    metrics_json TEXT,
+    budgets_json TEXT,
+    started_at INTEGER,
+    ended_at INTEGER,
+    created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000)
+);
+
+-- Findings table: security and quality findings
+CREATE TABLE IF NOT EXISTS findings (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    run_id TEXT NOT NULL REFERENCES runs(id) ON DELETE CASCADE,
+    gate TEXT NOT NULL,
+    severity TEXT NOT NULL,
+    rule TEXT NOT NULL,
+    location TEXT,
+    message TEXT,
+    raw_output TEXT,
+    fingerprint TEXT,
+    created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000)
+);
+
+-- Artifacts table: Content-Addressable Storage metadata
+CREATE TABLE IF NOT EXISTS artifacts (
+    sha256 TEXT PRIMARY KEY,
+    mime_type TEXT NOT NULL,
+    size_bytes INTEGER NOT NULL,
+    cas_path TEXT NOT NULL,
+    original_name TEXT,
+    created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
+    last_accessed INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000)
+);
+
+-- Run artifacts table: N-N relationship between runs and artifacts
+CREATE TABLE IF NOT EXISTS run_artifacts (
+    run_id TEXT NOT NULL REFERENCES runs(id) ON DELETE CASCADE,
+    sha256 TEXT NOT NULL REFERENCES artifacts(sha256) ON DELETE CASCADE,
+    label TEXT NOT NULL,
+    created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
+    PRIMARY KEY (run_id, sha256, label)
+);
+
+-- Flakiness history table: tracks test reliability over time
+CREATE TABLE IF NOT EXISTS flakiness_history (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    run_id TEXT NOT NULL REFERENCES runs(id) ON DELETE CASCADE,
+    test_id TEXT NOT NULL,
+    test_name TEXT NOT NULL,
+    gate TEXT NOT NULL,
+    file_path TEXT NOT NULL,
+    score INTEGER NOT NULL CHECK (score >= 0 AND score <= 100),
+    category TEXT NOT NULL CHECK (category IN ('legendary', 'solid', 'good', 'shaky', 'unstable')),
+    total_runs INTEGER NOT NULL,
+    successful_runs INTEGER NOT NULL,
+    avg_duration_ms INTEGER NOT NULL,
+    pattern_type TEXT,
+    suggested_fix TEXT,
+    confidence REAL,
+    first_seen INTEGER NOT NULL,
+    last_seen INTEGER NOT NULL,
+    current_streak INTEGER,
+    streak_type TEXT CHECK (streak_type IN ('pass', 'fail')),
+    created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000)
+);
+
+-- Flakiness patterns table: detected patterns for flaky tests
+CREATE TABLE IF NOT EXISTS flakiness_patterns (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    test_id TEXT NOT NULL,
+    test_name TEXT NOT NULL,
+    pattern_type TEXT NOT NULL CHECK (pattern_type IN ('timing', 'race_condition', 'external_dependency', 'environment_specific', 'selector_issue', 'unknown')),
+    description TEXT NOT NULL,
+    suggested_fix TEXT NOT NULL,
+    confidence REAL NOT NULL CHECK (confidence >= 0 AND confidence <= 1),
+    auto_fix_possible INTEGER NOT NULL DEFAULT 0,
+    first_detected INTEGER NOT NULL,
+    last_detected INTEGER NOT NULL,
+    detection_count INTEGER NOT NULL DEFAULT 1,
+    created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
+    updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
+    UNIQUE(test_id, pattern_type)
+);
+
+-- Flakiness quarantine table: tests quarantined for flakiness
+CREATE TABLE IF NOT EXISTS flakiness_quarantine (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    test_id TEXT NOT NULL UNIQUE,
+    test_name TEXT NOT NULL,
+    gate TEXT NOT NULL,
+    file_path TEXT NOT NULL,
+    reason TEXT NOT NULL,
+    score INTEGER NOT NULL CHECK (score >= 0 AND score <= 100),
+    category TEXT NOT NULL CHECK (category IN ('shaky', 'unstable')),
+    quarantined_at INTEGER NOT NULL,
+    quarantined_by TEXT NOT NULL,
+    resolved_at INTEGER,
+    resolved_by TEXT,
+    notes TEXT,
+    created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
+    updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000)
+);
+
+-- Vault metadata table: schema version and configuration
+CREATE TABLE IF NOT EXISTS vault_metadata (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL,
+    updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000)
+);
+
+-- Indexes for performance
+CREATE INDEX IF NOT EXISTS idx_runs_started_at ON runs(started_at DESC);
+CREATE INDEX IF NOT EXISTS idx_runs_run_key ON runs(run_key) WHERE run_key IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_runs_status ON runs(status);
+CREATE INDEX IF NOT EXISTS idx_runs_pack_hash ON runs(pack_hash);
+CREATE INDEX IF NOT EXISTS idx_runs_pinned ON runs(pinned) WHERE pinned = 1;
+
+CREATE INDEX IF NOT EXISTS idx_gates_run_id ON gates(run_id);
+CREATE INDEX IF NOT EXISTS idx_gates_run_name ON gates(run_id, name);
+CREATE INDEX IF NOT EXISTS idx_gates_status ON gates(status);
+CREATE INDEX IF NOT EXISTS idx_gates_name ON gates(name);
+
+CREATE INDEX IF NOT EXISTS idx_findings_run_id ON findings(run_id);
+CREATE INDEX IF NOT EXISTS idx_findings_run_gate ON findings(run_id, gate);
+CREATE INDEX IF NOT EXISTS idx_findings_severity ON findings(severity);
+CREATE INDEX IF NOT EXISTS idx_findings_rule ON findings(rule);
+CREATE INDEX IF NOT EXISTS idx_findings_fingerprint ON findings(fingerprint);
+
+CREATE INDEX IF NOT EXISTS idx_artifacts_mime_type ON artifacts(mime_type);
+CREATE INDEX IF NOT EXISTS idx_artifacts_size ON artifacts(size_bytes);
+CREATE INDEX IF NOT EXISTS idx_artifacts_created_at ON artifacts(created_at);
+CREATE INDEX IF NOT EXISTS idx_artifacts_last_accessed ON artifacts(last_accessed);
+
+CREATE INDEX IF NOT EXISTS idx_run_artifacts_run_id ON run_artifacts(run_id);
+CREATE INDEX IF NOT EXISTS idx_run_artifacts_sha256 ON run_artifacts(sha256);
+CREATE INDEX IF NOT EXISTS idx_run_artifacts_label ON run_artifacts(label);
+
+-- Flakiness indexes
+CREATE INDEX IF NOT EXISTS idx_flakiness_run_id ON flakiness_history(run_id);
+CREATE INDEX IF NOT EXISTS idx_flakiness_test_id ON flakiness_history(test_id);
+CREATE INDEX IF NOT EXISTS idx_flakiness_score ON flakiness_history(score);
+CREATE INDEX IF NOT EXISTS idx_flakiness_category ON flakiness_history(category);
+CREATE INDEX IF NOT EXISTS idx_flakiness_created_at ON flakiness_history(created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_flaky_patterns_test_id ON flakiness_patterns(test_id);
+CREATE INDEX IF NOT EXISTS idx_flaky_patterns_pattern_type ON flakiness_patterns(pattern_type);
+CREATE INDEX IF NOT EXISTS idx_flaky_patterns_detection_count ON flakiness_patterns(detection_count DESC);
+
+CREATE INDEX IF NOT EXISTS idx_quarantine_test_id ON flakiness_quarantine(test_id);
+CREATE INDEX IF NOT EXISTS idx_quarantine_quarantined_at ON flakiness_quarantine(quarantined_at DESC);
+CREATE INDEX IF NOT EXISTS idx_quarantine_resolved_at ON flakiness_quarantine(resolved_at);
+CREATE INDEX IF NOT EXISTS idx_quarantine_category ON flakiness_quarantine(category);
+
+-- Insert initial metadata
+INSERT OR IGNORE INTO vault_metadata (key, value) VALUES
+    ('schema_version', '2.0.0'),
+    ('created_at', strftime('%s', 'now') * 1000),
+    ('vault_format', 'qa360-evidence-vault-v2');
+
+-- Triggers for updated_at timestamps
+CREATE TRIGGER IF NOT EXISTS trigger_runs_updated_at
+    AFTER UPDATE ON runs
+    BEGIN
+        UPDATE runs SET updated_at = strftime('%s', 'now') * 1000 WHERE id = NEW.id;
+    END;
+
+CREATE TRIGGER IF NOT EXISTS trigger_artifacts_last_accessed
+    AFTER UPDATE ON artifacts
+    BEGIN
+        UPDATE artifacts SET last_accessed = strftime('%s', 'now') * 1000 WHERE sha256 = NEW.sha256;
+    END;
+
+CREATE TRIGGER IF NOT EXISTS trigger_flakiness_patterns_updated_at
+    AFTER UPDATE ON flakiness_patterns
+    BEGIN
+        UPDATE flakiness_patterns SET updated_at = strftime('%s', 'now') * 1000 WHERE id = NEW.id;
+    END;
+
+CREATE TRIGGER IF NOT EXISTS trigger_quarantine_updated_at
+    AFTER UPDATE ON flakiness_quarantine
+    BEGIN
+        UPDATE flakiness_quarantine SET updated_at = strftime('%s', 'now') * 1000 WHERE id = NEW.id;
+    END;
+
+-- Views for common queries
+CREATE VIEW IF NOT EXISTS v_recent_runs AS
+SELECT 
+    r.id,
+    r.run_key,
+    r.started_at,
+    r.ended_at,
+    r.status,
+    r.trust_score,
+    r.pack_path,
+    COUNT(g.id) as gate_count,
+    COUNT(CASE WHEN g.status = 'passed' THEN 1 END) as gates_passed,
+    COUNT(CASE WHEN g.status = 'failed' THEN 1 END) as gates_failed,
+    COUNT(f.id) as finding_count,
+    COUNT(CASE WHEN f.severity IN ('high', 'critical') THEN 1 END) as critical_findings
+FROM runs r
+LEFT JOIN gates g ON r.id = g.run_id
+LEFT JOIN findings f ON r.id = f.run_id
+GROUP BY r.id
+ORDER BY r.started_at DESC;
+
+CREATE VIEW IF NOT EXISTS v_gate_trends AS
+SELECT
+    g.name,
+    g.status,
+    r.started_at,
+    r.trust_score,
+    g.duration_ms,
+    g.metrics_json
+FROM gates g
+JOIN runs r ON g.run_id = r.id
+WHERE r.status IN ('passed', 'failed')
+ORDER BY r.started_at DESC;
+
+-- Flakiness summary view: aggregate flakiness stats by test
+CREATE VIEW IF NOT EXISTS v_flakiness_summary AS
+SELECT
+    test_id,
+    test_name,
+    gate,
+    file_path,
+    MAX(score) as latest_score,
+    MIN(score) as worst_score,
+    AVG(score) as avg_score,
+    COUNT(*) as total_analyses,
+    MAX(category) as latest_category,
+    MAX(last_seen) as last_analyzed,
+    MAX(first_seen) as first_seen
+FROM flakiness_history
+GROUP BY test_id, test_name, gate, file_path
+ORDER BY latest_score ASC;
+
+-- Flakiness trends view: time series analysis
+CREATE VIEW IF NOT EXISTS v_flakiness_trends AS
+SELECT
+    DATE(created_at / 1000, 'unixepoch') as analysis_date,
+    category,
+    COUNT(*) as test_count,
+    AVG(score) as avg_score
+FROM flakiness_history
+WHERE created_at >= strftime('%s', 'now', '-30 days') * 1000
+GROUP BY analysis_date, category
+ORDER BY analysis_date DESC, category DESC;
+
+-- Quarantined tests view
+CREATE VIEW IF NOT EXISTS v_quarantined_tests AS
+SELECT
+    q.*,
+    fh.score as current_score,
+    fh.category as current_category
+FROM flakiness_quarantine q
+LEFT JOIN (
+    SELECT test_id, score, category
+    FROM flakiness_history fh1
+    WHERE fh1.created_at = (
+        SELECT MAX(fh2.created_at)
+        FROM flakiness_history fh2
+        WHERE fh2.test_id = fh1.test_id
+    )
+) fh ON q.test_id = fh.test_id
+WHERE q.resolved_at IS NULL
+ORDER BY q.quarantined_at DESC;
+`;
+    
+    return new Promise((resolve, reject) => {
+      this.db.exec(schema, (err: Error | null) => {
+        if (err) {
+          reject(new Error(`Failed to initialize schema: ${err.message}`));
+        } else {
+          resolve();
+        }
+      });
+    });
+  }
+
+  /**
+   * Ensure required directories exist
+   */
+  private ensureDirectories(): void {
+    if (!existsSync(this.baseDir)) {
+      mkdirSync(this.baseDir, { recursive: true });
+    }
+  }
+
+  /**
+   * Close database connection
+   */
+  async close(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.db.close((err: Error | null) => {
+        if (err) reject(err);
+        else resolve();
+      });
+    });
+  }
+}