@veraxhq/verax 0.2.1 → 0.4.0

package/src/verax/core/integrity/transaction.js

@@ -0,0 +1,140 @@
+/**
+ * PHASE 6A: Transactional Artifact System
+ * 
+ * Provides ALL-OR-NOTHING artifact writes with staging directory.
+ * Ensures atomic finalization of complete artifact sets.
+ */
+
+import { mkdirSync, renameSync, existsSync, rmSync, readdirSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Create staging directory for transactional writes
+ * 
+ * @param {string} runDir - Run directory path
+ * @returns {{ ok: boolean, stagingDir?: string, error?: Error }} Result
+ */
+export function createStagingDir(runDir) {
+  try {
+    const stagingDir = join(runDir, '.staging');
+    
+    // Clean up any existing staging directory from previous crash
+    if (existsSync(stagingDir)) {
+      rmSync(stagingDir, { recursive: true, force: true });
+    }
+    
+    mkdirSync(stagingDir, { recursive: true });
+    
+    return { ok: true, stagingDir };
+  } catch (error) {
+    return { ok: false, error };
+  }
+}
+
+/**
+ * Commit staging directory to final location (atomic rename)
+ * 
+ * @param {string} runDir - Run directory path
+ * @returns {{ ok: boolean, error?: Error }} Result
+ */
+export function commitStagingDir(runDir) {
+  try {
+    const stagingDir = join(runDir, '.staging');
+    const artifactsDir = join(runDir, 'artifacts');
+    
+    if (!existsSync(stagingDir)) {
+      return {
+        ok: false,
+        error: new Error('Staging directory does not exist'),
+      };
+    }
+    
+    // Ensure parent directory exists
+    mkdirSync(runDir, { recursive: true });
+    
+    // Clean up existing artifacts directory if present
+    if (existsSync(artifactsDir)) {
+      rmSync(artifactsDir, { recursive: true, force: true });
+    }
+    
+    // Atomic rename
+    renameSync(stagingDir, artifactsDir);
+    
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, error };
+  }
+}
+
+/**
+ * Rollback staging directory (cleanup on failure)
+ * 
+ * @param {string} runDir - Run directory path
+ * @returns {{ ok: boolean, error?: Error }} Result
+ */
+export function rollbackStagingDir(runDir) {
+  try {
+    const stagingDir = join(runDir, '.staging');
+    
+    if (existsSync(stagingDir)) {
+      rmSync(stagingDir, { recursive: true, force: true });
+    }
+    
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, error };
+  }
+}
+
+/**
+ * Get staging artifact path
+ * 
+ * @param {string} runDir - Run directory path
+ * @param {string} artifactName - Artifact filename
+ * @returns {string} Path to artifact in staging directory
+ */
+export function getStagingPath(runDir, artifactName) {
+  return join(runDir, '.staging', artifactName);
+}
+
+/**
+ * Get final artifact path
+ * 
+ * @param {string} runDir - Run directory path
+ * @param {string} artifactName - Artifact filename
+ * @returns {string} Path to artifact in final location
+ */
+export function getFinalPath(runDir, artifactName) {
+  return join(runDir, 'artifacts', artifactName);
+}
+
+/**
+ * Check if staging directory exists
+ * 
+ * @param {string} runDir - Run directory path
+ * @returns {boolean} True if staging exists
+ */
+export function hasStagingDir(runDir) {
+  const stagingDir = join(runDir, '.staging');
+  return existsSync(stagingDir);
+}
+
+/**
+ * List files in staging directory
+ * 
+ * @param {string} runDir - Run directory path
+ * @returns {string[]} List of filenames in staging
+ */
+export function listStagingFiles(runDir) {
+  try {
+    const stagingDir = join(runDir, '.staging');
+    
+    if (!existsSync(stagingDir)) {
+      return [];
+    }
+    
+    return readdirSync(stagingDir);
+  } catch (error) {
+    return [];
+  }
+}

package/src/verax/core/observe/run-timeline.js

@@ -0,0 +1,318 @@
+/**
+ * PHASE 21.10 — Unified Run Timeline
+ * 
+ * Builds chronological timeline of all events in a run.
+ */
+
+import { readFileSync, existsSync, writeFileSync } from 'fs';
+import { resolve } from 'path';
+
+/**
+ * Load artifact JSON
+ */
+function loadArtifact(runDir, filename) {
+  const path = resolve(runDir, filename);
+  if (!existsSync(path)) {
+    return null;
+  }
+  try {
+  // @ts-expect-error - readFileSync with encoding returns string
+    return JSON.parse(readFileSync(path, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build timeline from run artifacts
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run ID
+ * @returns {Object} Timeline object
+ */
+export function buildRunTimeline(projectDir, runId) {
+  const runDir = resolve(projectDir, '.verax', 'runs', runId);
+  
+  if (!existsSync(runDir)) {
+    return null;
+  }
+  
+  const timeline = [];
+  
+  // Load summary for phase timestamps
+  const summary = loadArtifact(runDir, 'summary.json');
+  const runStatus = loadArtifact(runDir, 'run.status.json');
+  const decisions = loadArtifact(runDir, 'decisions.json');
+  const failureLedger = loadArtifact(runDir, 'failure.ledger.json');
+  const performanceReport = loadArtifact(runDir, 'performance.report.json');
+  const findings = loadArtifact(runDir, 'findings.json');
+  
+  // Extract timestamps
+  const startedAt = summary?.startedAt || runStatus?.startedAt;
+  const completedAt = summary?.completedAt || runStatus?.completedAt;
+  
+  // Phase events
+  if (startedAt) {
+    timeline.push({
+      timestamp: startedAt,
+      phase: 'RUN_START',
+      event: 'run_started',
+      data: {
+        runId,
+        url: summary?.url || null
+      }
+    });
+  }
+  
+  // LEARN phase
+  if (summary?.metrics?.learnMs) {
+    timeline.push({
+      timestamp: startedAt || null,
+      phase: 'LEARN',
+      event: 'phase_started',
+      data: {
+        durationMs: summary.metrics.learnMs
+      }
+    });
+    timeline.push({
+      timestamp: startedAt ? new Date(Date.parse(startedAt) + summary.metrics.learnMs).toISOString() : null,
+      phase: 'LEARN',
+      event: 'phase_completed',
+      data: {
+        durationMs: summary.metrics.learnMs,
+        expectationsFound: summary.digest?.expectationsTotal || 0
+      }
+    });
+  }
+  
+  // OBSERVE phase
+  if (summary?.metrics?.observeMs) {
+    const observeStart = startedAt ? new Date(Date.parse(startedAt) + (summary.metrics.learnMs || 0)).toISOString() : null;
+    timeline.push({
+      timestamp: observeStart,
+      phase: 'OBSERVE',
+      event: 'phase_started',
+      data: {
+        durationMs: summary.metrics.observeMs
+      }
+    });
+    timeline.push({
+      timestamp: observeStart ? new Date(Date.parse(observeStart) + summary.metrics.observeMs).toISOString() : null,
+      phase: 'OBSERVE',
+      event: 'phase_completed',
+      data: {
+        durationMs: summary.metrics.observeMs,
+        interactionsExecuted: summary.digest?.attempted || 0,
+        pagesVisited: summary.digest?.pagesVisited || 0
+      }
+    });
+  }
+  
+  // DETECT phase
+  if (summary?.metrics?.detectMs) {
+    const detectStart = startedAt ? new Date(Date.parse(startedAt) + (summary.metrics.learnMs || 0) + (summary.metrics.observeMs || 0)).toISOString() : null;
+    timeline.push({
+      timestamp: detectStart,
+      phase: 'DETECT',
+      event: 'phase_started',
+      data: {
+        durationMs: summary.metrics.detectMs
+      }
+    });
+    timeline.push({
+      timestamp: detectStart ? new Date(Date.parse(detectStart) + summary.metrics.detectMs).toISOString() : null,
+      phase: 'DETECT',
+      event: 'phase_completed',
+      data: {
+        durationMs: summary.metrics.detectMs,
+        findingsDetected: Array.isArray(findings?.findings) ? findings.findings.length : 0
+      }
+    });
+  }
+  
+  // Adaptive events from decisions
+  if (decisions?.adaptiveEvents) {
+    for (const event of decisions.adaptiveEvents) {
+      timeline.push({
+        timestamp: event.timestamp || null,
+        phase: event.phase || 'UNKNOWN',
+        event: 'adaptive_decision',
+        data: {
+          decisionId: event.decisionId,
+          reason: event.reason,
+          context: event.context || {}
+        }
+      });
+    }
+  }
+  
+  // Budget violations from performance report
+  if (performanceReport?.violations) {
+    for (const violation of performanceReport.violations) {
+      timeline.push({
+        timestamp: performanceReport.generatedAt || null,
+        phase: 'PERFORMANCE',
+        event: 'budget_violation',
+        severity: 'BLOCKING',
+        data: {
+          type: violation.type,
+          actual: violation.actual,
+          budget: violation.budget,
+          message: violation.message
+        }
+      });
+    }
+  }
+  
+  if (performanceReport?.warnings) {
+    for (const warning of performanceReport.warnings) {
+      timeline.push({
+        timestamp: performanceReport.generatedAt || null,
+        phase: 'PERFORMANCE',
+        event: 'budget_warning',
+        severity: 'DEGRADED',
+        data: {
+          type: warning.type,
+          actual: warning.actual,
+          budget: warning.budget,
+          message: warning.message
+        }
+      });
+    }
+  }
+  
+  // Guardrails applied (from findings)
+  if (findings?.findings) {
+    for (const finding of findings.findings) {
+      if (finding.guardrails?.appliedRules && finding.guardrails.appliedRules.length > 0) {
+        timeline.push({
+          timestamp: finding.timestamp || null,
+          phase: 'DETECT',
+          event: 'guardrails_applied',
+          data: {
+            findingId: finding.findingId || finding.id,
+            rules: finding.guardrails.appliedRules.map(r => r.id || r),
+            finalDecision: finding.guardrails.finalDecision
+          }
+        });
+      }
+    }
+  }
+  
+  // Evidence enforcement (from findings)
+  if (findings?.findings) {
+    for (const finding of findings.findings) {
+      if (finding.evidencePackage) {
+        timeline.push({
+          timestamp: finding.timestamp || null,
+          phase: 'DETECT',
+          event: 'evidence_enforced',
+          data: {
+            findingId: finding.findingId || finding.id,
+            isComplete: finding.evidencePackage.isComplete,
+            status: finding.severity || finding.status
+          }
+        });
+      }
+    }
+  }
+  
+  // Failures from failure ledger
+  if (failureLedger?.failures) {
+    for (const failure of failureLedger.failures) {
+      timeline.push({
+        timestamp: failure.timestamp || (startedAt ? new Date(Date.parse(startedAt) + (failure.relativeTime || 0)).toISOString() : null),
+        phase: failure.phase || 'UNKNOWN',
+        event: 'failure_recorded',
+        severity: failure.severity || 'WARNING',
+        data: {
+          code: failure.code,
+          message: failure.message,
+          category: failure.category,
+          recoverable: failure.recoverable
+        }
+      });
+    }
+  }
+  
+  // Run completion
+  if (completedAt) {
+    timeline.push({
+      timestamp: completedAt,
+      phase: 'RUN_COMPLETE',
+      event: 'run_completed',
+      data: {
+        status: summary?.status || runStatus?.status || 'UNKNOWN',
+        totalDurationMs: startedAt && completedAt ? Date.parse(completedAt) - Date.parse(startedAt) : null
+      }
+    });
+  }
+  
+  // Sort by timestamp
+  timeline.sort((a, b) => {
+    if (!a.timestamp && !b.timestamp) return 0;
+    if (!a.timestamp) return 1;
+    if (!b.timestamp) return -1;
+    return Date.parse(a.timestamp) - Date.parse(b.timestamp);
+  });
+  
+  return {
+    runId,
+    startedAt,
+    completedAt,
+    events: timeline,
+    summary: {
+      totalEvents: timeline.length,
+      byPhase: timeline.reduce((acc, e) => {
+        acc[e.phase] = (acc[e.phase] || 0) + 1;
+        return acc;
+      }, {}),
+      byEvent: timeline.reduce((acc, e) => {
+        acc[e.event] = (acc[e.event] || 0) + 1;
+        return acc;
+      }, {}),
+      blockingViolations: timeline.filter(e => e.severity === 'BLOCKING').length,
+      degradedWarnings: timeline.filter(e => e.severity === 'DEGRADED').length
+    },
+    generatedAt: new Date().toISOString()
+  };
+}
+
+/**
+ * Write timeline to file
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run ID
+ * @param {Object} timeline - Timeline object
+ * @returns {string} Path to written file
+ */
+export function writeRunTimeline(projectDir, runId, timeline) {
+  const runDir = resolve(projectDir, '.verax', 'runs', runId);
+  const outputPath = resolve(runDir, 'run.timeline.json');
+  writeFileSync(outputPath, JSON.stringify(timeline, null, 2), 'utf-8');
+  return outputPath;
+}
+
+/**
+ * Load timeline from file
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run ID
+ * @returns {Object|null} Timeline or null
+ */
+export function loadRunTimeline(projectDir, runId) {
+  const runDir = resolve(projectDir, '.verax', 'runs', runId);
+  const timelinePath = resolve(runDir, 'run.timeline.json');
+  
+  if (!existsSync(timelinePath)) {
+    return null;
+  }
+  
+  try {
+  // @ts-expect-error - readFileSync with encoding returns string
+    return JSON.parse(readFileSync(timelinePath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+

package/src/verax/core/perf/perf.contract.js

@@ -0,0 +1,186 @@
+/**
+ * PHASE 21.9 — Performance Budget Contract
+ * 
+ * Defines hard limits for runtime, memory, pages, interactions, and artifacts.
+ * Exceeding runtime or memory = BLOCKING.
+ * Exceeding interactions/pages = DEGRADED.
+ */
+
+/**
+ * Default performance budgets
+ */
+export const DEFAULT_PERF_BUDGET = {
+  // Runtime limits (ms)
+  maxRuntimeMs: 300000, // 5 minutes
+  
+  // Memory limits (bytes)
+  maxMemoryRSS: 1024 * 1024 * 1024, // 1GB
+  
+  // Page/interaction limits
+  maxPagesVisited: 100,
+  maxInteractionsExecuted: 500,
+  
+  // Artifact size limits (bytes)
+  maxArtifactsSizeMB: 500, // 500MB
+  
+  // Event loop delay threshold (ms)
+  maxEventLoopDelayMs: 100
+};
+
+/**
+ * Performance budget profiles
+ */
+export const PERF_BUDGET_PROFILES = {
+  QUICK: {
+    maxRuntimeMs: 20000, // 20s
+    maxMemoryRSS: 512 * 1024 * 1024, // 512MB
+    maxPagesVisited: 5,
+    maxInteractionsExecuted: 50,
+    maxArtifactsSizeMB: 50,
+    maxEventLoopDelayMs: 50
+  },
+  STANDARD: {
+    ...DEFAULT_PERF_BUDGET
+  },
+  THOROUGH: {
+    maxRuntimeMs: 600000, // 10 minutes
+    maxMemoryRSS: 2 * 1024 * 1024 * 1024, // 2GB
+    maxPagesVisited: 200,
+    maxInteractionsExecuted: 1000,
+    maxArtifactsSizeMB: 1000, // 1GB
+    maxEventLoopDelayMs: 200
+  },
+  EXHAUSTIVE: {
+    maxRuntimeMs: 1800000, // 30 minutes
+    maxMemoryRSS: 4 * 1024 * 1024 * 1024, // 4GB
+    maxPagesVisited: 500,
+    maxInteractionsExecuted: 5000,
+    maxArtifactsSizeMB: 2000, // 2GB
+    maxEventLoopDelayMs: 500
+  }
+};
+
+/**
+ * Get performance budget for a profile
+ * 
+ * @param {string} profileName - Profile name (QUICK, STANDARD, THOROUGH, EXHAUSTIVE)
+ * @returns {Object} Performance budget
+ */
+export function getPerfBudget(profileName = 'STANDARD') {
+  const profile = PERF_BUDGET_PROFILES[profileName.toUpperCase()];
+  return profile || PERF_BUDGET_PROFILES.STANDARD;
+}
+
+/**
+ * Evaluate performance against budget
+ * 
+ * @param {Object} actual - Actual performance metrics
+ * @param {Object} budget - Performance budget
+ * @returns {Object} Evaluation result
+ */
+export function evaluatePerfBudget(actual, budget) {
+  const violations = [];
+  const warnings = [];
+  
+  // BLOCKING violations
+  if (actual.runtimeMs > budget.maxRuntimeMs) {
+    violations.push({
+      type: 'RUNTIME_EXCEEDED',
+      severity: 'BLOCKING',
+      actual: actual.runtimeMs,
+      budget: budget.maxRuntimeMs,
+      excess: actual.runtimeMs - budget.maxRuntimeMs,
+      message: `Runtime exceeded: ${actual.runtimeMs}ms > ${budget.maxRuntimeMs}ms`
+    });
+  }
+  
+  if (actual.memoryRSS > budget.maxMemoryRSS) {
+    violations.push({
+      type: 'MEMORY_EXCEEDED',
+      severity: 'BLOCKING',
+      actual: actual.memoryRSS,
+      budget: budget.maxMemoryRSS,
+      excess: actual.memoryRSS - budget.maxMemoryRSS,
+      message: `Memory exceeded: ${formatBytes(actual.memoryRSS)} > ${formatBytes(budget.maxMemoryRSS)}`
+    });
+  }
+  
+  // DEGRADED violations
+  if (actual.pagesVisited > budget.maxPagesVisited) {
+    warnings.push({
+      type: 'PAGES_EXCEEDED',
+      severity: 'DEGRADED',
+      actual: actual.pagesVisited,
+      budget: budget.maxPagesVisited,
+      excess: actual.pagesVisited - budget.maxPagesVisited,
+      message: `Pages visited exceeded: ${actual.pagesVisited} > ${budget.maxPagesVisited}`
+    });
+  }
+  
+  if (actual.interactionsExecuted > budget.maxInteractionsExecuted) {
+    warnings.push({
+      type: 'INTERACTIONS_EXCEEDED',
+      severity: 'DEGRADED',
+      actual: actual.interactionsExecuted,
+      budget: budget.maxInteractionsExecuted,
+      excess: actual.interactionsExecuted - budget.maxInteractionsExecuted,
+      message: `Interactions executed exceeded: ${actual.interactionsExecuted} > ${budget.maxInteractionsExecuted}`
+    });
+  }
+  
+  if (actual.artifactsSizeMB > budget.maxArtifactsSizeMB) {
+    warnings.push({
+      type: 'ARTIFACTS_SIZE_EXCEEDED',
+      severity: 'DEGRADED',
+      actual: actual.artifactsSizeMB,
+      budget: budget.maxArtifactsSizeMB,
+      excess: actual.artifactsSizeMB - budget.maxArtifactsSizeMB,
+      message: `Artifacts size exceeded: ${actual.artifactsSizeMB}MB > ${budget.maxArtifactsSizeMB}MB`
+    });
+  }
+  
+  if (actual.eventLoopDelayMs > budget.maxEventLoopDelayMs) {
+    warnings.push({
+      type: 'EVENT_LOOP_DELAY_EXCEEDED',
+      severity: 'DEGRADED',
+      actual: actual.eventLoopDelayMs,
+      budget: budget.maxEventLoopDelayMs,
+      excess: actual.eventLoopDelayMs - budget.maxEventLoopDelayMs,
+      message: `Event loop delay exceeded: ${actual.eventLoopDelayMs}ms > ${budget.maxEventLoopDelayMs}ms`
+    });
+  }
+  
+  const hasBlocking = violations.length > 0;
+  const hasDegraded = warnings.length > 0;
+  
+  let verdict = 'OK';
+  if (hasBlocking) {
+    verdict = 'BLOCKED';
+  } else if (hasDegraded) {
+    verdict = 'DEGRADED';
+  }
+  
+  return {
+    verdict,
+    ok: !hasBlocking,
+    violations,
+    warnings,
+    summary: {
+      blocking: violations.length,
+      degraded: warnings.length,
+      total: violations.length + warnings.length
+    }
+  };
+}
+
+/**
+ * Format bytes to human-readable string
+ */
+function formatBytes(bytes) {
+  if (bytes === 0) return '0 B';
+  const k = 1024;
+  const sizes = ['B', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return Math.round(bytes / Math.pow(k, i) * 100) / 100 + ' ' + sizes[i];
+}
+

package/src/verax/core/perf/perf.display.js

@@ -0,0 +1,65 @@
+/**
+ * PHASE 21.9 — Performance Display
+ * 
+ * Formats performance metrics for CLI display.
+ */
+
+import { loadPerformanceReport } from './perf.report.js';
+
+/**
+ * Format performance metrics for display
+ * 
+ * @param {Object} report - Performance report
+ * @returns {string} Formatted string
+ */
+export function formatPerformanceMetrics(report) {
+  if (!report) {
+    return 'Performance: No report available';
+  }
+  
+  const lines = [];
+  lines.push('Performance:');
+  
+  // Runtime
+  const runtimeSec = (report.actual.runtimeMs / 1000).toFixed(1);
+  const runtimeBudgetSec = (report.budget.maxRuntimeMs / 1000).toFixed(0);
+  const runtimeStatus = report.actual.runtimeMs <= report.budget.maxRuntimeMs ? 'OK' : 'EXCEEDED';
+  lines.push(`  Runtime: ${runtimeSec}s / ${runtimeBudgetSec}s ${runtimeStatus}`);
+  
+  // Memory
+  const memoryMB = (report.actual.memoryRSS / (1024 * 1024)).toFixed(0);
+  const memoryBudgetMB = (report.budget.maxMemoryRSS / (1024 * 1024)).toFixed(0);
+  const memoryStatus = report.actual.memoryRSS <= report.budget.maxMemoryRSS ? 'OK' : 'EXCEEDED';
+  lines.push(`  Memory: ${memoryMB}MB / ${memoryBudgetMB}MB ${memoryStatus}`);
+  
+  // Pages
+  const pagesStatus = report.actual.pagesVisited <= report.budget.maxPagesVisited ? 'OK' : 'EXCEEDED';
+  lines.push(`  Pages: ${report.actual.pagesVisited} / ${report.budget.maxPagesVisited} ${pagesStatus}`);
+  
+  // Interactions
+  const interactionsStatus = report.actual.interactionsExecuted <= report.budget.maxInteractionsExecuted ? 'OK' : 'EXCEEDED';
+  lines.push(`  Interactions: ${report.actual.interactionsExecuted} / ${report.budget.maxInteractionsExecuted} ${interactionsStatus}`);
+  
+  // Verdict
+  const verdictSymbol = report.verdict === 'OK' ? '✅' : report.verdict === 'DEGRADED' ? '⚠️' : '❌';
+  lines.push(`Verdict: ${verdictSymbol} ${report.verdict}`);
+  
+  return lines.join('\n');
+}
+
+/**
+ * Display performance metrics in inspect command
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run ID
+ */
+export function displayPerformanceInInspect(projectDir, runId) {
+  const report = loadPerformanceReport(projectDir, runId);
+  
+  if (!report) {
+    return;
+  }
+  
+  console.log('\n' + formatPerformanceMetrics(report));
+}
+