@veraxhq/verax 0.2.1 → 0.3.0

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

@@ -0,0 +1,209 @@
+/**
+ * PHASE 21.9 — Performance Monitor
+ * 
+ * Monitors runtime, memory, event loop delay, and execution counters.
+ * Records timestamped samples and peak values.
+ */
+
+import { performance } from 'perf_hooks';
+
+/**
+ * Performance Monitor
+ */
+export class PerformanceMonitor {
+  constructor() {
+    this.startTime = performance.now();
+    this.startMemory = process.memoryUsage();
+    this.samples = [];
+    this.peakMemoryRSS = this.startMemory.rss;
+    this.peakMemoryHeapUsed = this.startMemory.heapUsed;
+    this.peakMemoryHeapTotal = this.startMemory.heapTotal;
+    this.peakEventLoopDelay = 0;
+    
+    // Counters
+    this.pagesVisited = 0;
+    this.interactionsExecuted = 0;
+    
+    // Phase tracking
+    this.phaseStartTimes = {};
+    this.phaseDurations = {};
+    
+    // Event loop monitoring
+    this.eventLoopMonitor = null;
+    this.lastEventLoopCheck = performance.now();
+    this.eventLoopDelays = [];
+    
+    this.startEventLoopMonitoring();
+  }
+  
+  /**
+   * Start event loop delay monitoring
+   */
+  startEventLoopMonitoring() {
+    const checkInterval = 100; // Check every 100ms
+    
+    this.eventLoopMonitor = setInterval(() => {
+      const now = performance.now();
+      const delay = now - this.lastEventLoopCheck - checkInterval;
+      
+      if (delay > 0) {
+        this.eventLoopDelays.push(delay);
+        if (delay > this.peakEventLoopDelay) {
+          this.peakEventLoopDelay = delay;
+        }
+      }
+      
+      this.lastEventLoopCheck = now;
+    }, checkInterval);
+  }
+  
+  /**
+   * Record a sample
+   */
+  sample(phase = null) {
+    const now = performance.now();
+    const memory = process.memoryUsage();
+    
+    // Update peaks
+    if (memory.rss > this.peakMemoryRSS) {
+      this.peakMemoryRSS = memory.rss;
+    }
+    if (memory.heapUsed > this.peakMemoryHeapUsed) {
+      this.peakMemoryHeapUsed = memory.heapUsed;
+    }
+    if (memory.heapTotal > this.peakMemoryHeapTotal) {
+      this.peakMemoryHeapTotal = memory.heapTotal;
+    }
+    
+    // Calculate average event loop delay
+    const avgEventLoopDelay = this.eventLoopDelays.length > 0
+      ? this.eventLoopDelays.reduce((a, b) => a + b, 0) / this.eventLoopDelays.length
+      : 0;
+    
+    this.samples.push({
+      timestamp: now,
+      elapsedMs: now - this.startTime,
+      phase,
+      memory: {
+        rss: memory.rss,
+        heapUsed: memory.heapUsed,
+        heapTotal: memory.heapTotal,
+        external: memory.external
+      },
+      eventLoopDelay: avgEventLoopDelay,
+      pagesVisited: this.pagesVisited,
+      interactionsExecuted: this.interactionsExecuted
+    });
+    
+    // Keep only last 1000 samples to avoid memory bloat
+    if (this.samples.length > 1000) {
+      this.samples.shift();
+    }
+    
+    // Reset event loop delays array periodically
+    if (this.eventLoopDelays.length > 100) {
+      this.eventLoopDelays = this.eventLoopDelays.slice(-50);
+    }
+  }
+  
+  /**
+   * Start a phase
+   */
+  startPhase(phaseName) {
+    this.phaseStartTimes[phaseName] = performance.now();
+  }
+  
+  /**
+   * End a phase
+   */
+  endPhase(phaseName) {
+    if (this.phaseStartTimes[phaseName]) {
+      const duration = performance.now() - this.phaseStartTimes[phaseName];
+      this.phaseDurations[phaseName] = (this.phaseDurations[phaseName] || 0) + duration;
+      delete this.phaseStartTimes[phaseName];
+    }
+  }
+  
+  /**
+   * Increment pages visited
+   */
+  incrementPages() {
+    this.pagesVisited++;
+    this.sample('PAGE_VISIT');
+  }
+  
+  /**
+   * Increment interactions executed
+   */
+  incrementInteractions() {
+    this.interactionsExecuted++;
+    this.sample('INTERACTION');
+  }
+  
+  /**
+   * Get current metrics
+   */
+  getCurrentMetrics() {
+    const now = performance.now();
+    const memory = process.memoryUsage();
+    const avgEventLoopDelay = this.eventLoopDelays.length > 0
+      ? this.eventLoopDelays.reduce((a, b) => a + b, 0) / this.eventLoopDelays.length
+      : 0;
+    
+    return {
+      runtimeMs: now - this.startTime,
+      memoryRSS: memory.rss,
+      memoryHeapUsed: memory.heapUsed,
+      memoryHeapTotal: memory.heapTotal,
+      peakMemoryRSS: this.peakMemoryRSS,
+      peakMemoryHeapUsed: this.peakMemoryHeapUsed,
+      peakEventLoopDelay: this.peakEventLoopDelay,
+      avgEventLoopDelay: avgEventLoopDelay,
+      pagesVisited: this.pagesVisited,
+      interactionsExecuted: this.interactionsExecuted,
+      phaseDurations: { ...this.phaseDurations }
+    };
+  }
+  
+  /**
+   * Get final report
+   */
+  getFinalReport() {
+    const metrics = this.getCurrentMetrics();
+    
+    // Find slow phases
+    const slowPhases = Object.entries(this.phaseDurations)
+      .filter(([_, duration]) => duration > 5000) // Phases > 5s
+      .map(([phase, duration]) => ({
+        phase,
+        durationMs: duration,
+        percentage: (duration / metrics.runtimeMs) * 100
+      }))
+      .sort((a, b) => b.durationMs - a.durationMs);
+    
+    return {
+      ...metrics,
+      slowPhases,
+      sampleCount: this.samples.length,
+      samples: this.samples.slice(-100) // Last 100 samples only
+    };
+  }
+  
+  /**
+   * Stop monitoring
+   */
+  stop() {
+    if (this.eventLoopMonitor) {
+      clearInterval(this.eventLoopMonitor);
+      this.eventLoopMonitor = null;
+    }
+  }
+}
+
+/**
+ * Create a performance monitor instance
+ */
+export function createPerformanceMonitor() {
+  return new PerformanceMonitor();
+}
+

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

@@ -0,0 +1,198 @@
+/**
+ * PHASE 21.9 — Performance Report
+ * 
+ * Generates performance.report.json with budgets, actual usage, peaks, and violations.
+ */
+
+import { readFileSync, existsSync, writeFileSync, mkdirSync, statSync, readdirSync } from 'fs';
+import { resolve } from 'path';
+import { getPerfBudget, evaluatePerfBudget } from './perf.contract.js';
+
+/**
+ * Calculate artifacts size
+ * 
+ * @param {string} runDir - Run directory
+ * @returns {number} Size in MB
+ */
+function calculateArtifactsSize(runDir) {
+  let totalSize = 0;
+  
+  function scanDirectory(dir) {
+    try {
+      const entries = readdirSync(dir, { withFileTypes: true });
+      
+      for (const entry of entries) {
+        const fullPath = resolve(dir, entry.name);
+        
+        if (entry.isDirectory()) {
+          scanDirectory(fullPath);
+        } else if (entry.isFile()) {
+          try {
+            const stats = statSync(fullPath);
+            totalSize += stats.size;
+          } catch {
+            // Skip unreadable files
+          }
+        }
+      }
+    } catch {
+      // Skip inaccessible directories
+    }
+  }
+  
+  if (existsSync(runDir)) {
+    scanDirectory(runDir);
+  }
+  
+  return totalSize / (1024 * 1024); // Convert to MB
+}
+
+/**
+ * Load pipeline stage timings from run.meta.json
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run ID
+ * @returns {Object|null} Stage timings or null
+ */
+function loadPipelineStageTimings(projectDir, runId) {
+  const runDir = resolve(projectDir, '.verax', 'runs', runId);
+  const metaPath = resolve(runDir, 'run.meta.json');
+  
+  if (!existsSync(metaPath)) {
+    return null;
+  }
+  
+  try {
+    const meta = JSON.parse(readFileSync(metaPath, 'utf-8'));
+    return meta.pipelineStages || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Generate performance report
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run ID
+ * @param {Object} monitorReport - Monitor report from PerformanceMonitor
+ * @param {string} profile - Budget profile name
+ * @returns {Object} Performance report
+ */
+export function generatePerformanceReport(projectDir, runId, monitorReport, profile = 'STANDARD') {
+  const budget = getPerfBudget(profile);
+  const runDir = resolve(projectDir, '.verax', 'runs', runId);
+  const artifactsSizeMB = calculateArtifactsSize(runDir);
+  
+  // Load pipeline stage timings
+  const pipelineStages = loadPipelineStageTimings(projectDir, runId);
+  
+  const actual = {
+    runtimeMs: monitorReport.runtimeMs,
+    memoryRSS: monitorReport.memoryRSS,
+    pagesVisited: monitorReport.pagesVisited,
+    interactionsExecuted: monitorReport.interactionsExecuted,
+    artifactsSizeMB: artifactsSizeMB,
+    eventLoopDelayMs: monitorReport.avgEventLoopDelay || 0
+  };
+  
+  const evaluation = evaluatePerfBudget(actual, budget);
+  
+  // Extract stage timings if available
+  const stageTimings = {};
+  if (pipelineStages) {
+    for (const [stageName, stageData] of Object.entries(pipelineStages)) {
+      if (stageData.durationMs !== null && stageData.durationMs !== undefined) {
+        stageTimings[stageName] = {
+          durationMs: stageData.durationMs,
+          startedAt: stageData.startedAt,
+          completedAt: stageData.completedAt,
+          status: stageData.status
+        };
+      }
+    }
+  }
+  
+  const report = {
+    contractVersion: 1,
+    runId,
+    profile,
+    budget: {
+      maxRuntimeMs: budget.maxRuntimeMs,
+      maxMemoryRSS: budget.maxMemoryRSS,
+      maxPagesVisited: budget.maxPagesVisited,
+      maxInteractionsExecuted: budget.maxInteractionsExecuted,
+      maxArtifactsSizeMB: budget.maxArtifactsSizeMB,
+      maxEventLoopDelayMs: budget.maxEventLoopDelayMs
+    },
+    actual,
+    peaks: {
+      memoryRSS: monitorReport.peakMemoryRSS,
+      memoryHeapUsed: monitorReport.peakMemoryHeapUsed,
+      memoryHeapTotal: monitorReport.peakMemoryHeapTotal,
+      eventLoopDelay: monitorReport.peakEventLoopDelay
+    },
+    stageTimings: Object.keys(stageTimings).length > 0 ? stageTimings : null,
+    networkRequests: monitorReport.networkRequests || 0,
+    violations: evaluation.violations,
+    warnings: evaluation.warnings,
+    verdict: evaluation.verdict,
+    ok: evaluation.ok,
+    summary: {
+      ...evaluation.summary,
+      runtimeMs: actual.runtimeMs,
+      memoryRSSMB: (actual.memoryRSS / (1024 * 1024)).toFixed(2),
+      pagesVisited: actual.pagesVisited,
+      networkRequests: monitorReport.networkRequests || 0,
+      interactionsExecuted: actual.interactionsExecuted,
+      artifactsSizeMB: actual.artifactsSizeMB.toFixed(2),
+      slowPhases: monitorReport.slowPhases || []
+    },
+    generatedAt: new Date().toISOString()
+  };
+  
+  return report;
+}
+
+/**
+ * Write performance report
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run ID
+ * @param {Object} report - Performance report
+ * @returns {string} Path to written file
+ */
+export function writePerformanceReport(projectDir, runId, report) {
+  const runDir = resolve(projectDir, '.verax', 'runs', runId);
+  if (!existsSync(runDir)) {
+    mkdirSync(runDir, { recursive: true });
+  }
+  
+  const outputPath = resolve(runDir, 'performance.report.json');
+  writeFileSync(outputPath, JSON.stringify(report, null, 2), 'utf-8');
+  
+  return outputPath;
+}
+
+/**
+ * Load performance report
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run ID
+ * @returns {Object|null} Performance report or null
+ */
+export function loadPerformanceReport(projectDir, runId) {
+  const reportPath = resolve(projectDir, '.verax', 'runs', runId, 'performance.report.json');
+  
+  if (!existsSync(reportPath)) {
+    return null;
+  }
+  
+  try {
+    const content = readFileSync(reportPath, 'utf-8');
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+

package/src/verax/core/pipeline-tracker.js

@@ -0,0 +1,238 @@
+/**
+ * PHASE: Pipeline Stage Tracker
+ * 
+ * Enforces explicit, single execution path with stage-by-stage tracking.
+ * Every stage must be recorded in run.meta.json with timestamp.
+ * No stage may execute without being recorded.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { dirname } from 'path';
+import { getArtifactPath } from './run-id.js';
+import { computeRunFingerprint } from './determinism/run-fingerprint.js';
+
+const PIPELINE_STAGES = {
+  LEARN: 'LEARN',
+  OBSERVE: 'OBSERVE',
+  DETECT: 'DETECT',
+  WRITE: 'WRITE',
+  VERIFY: 'VERIFY',
+  VERDICT: 'VERDICT'
+};
+
+const STAGE_ORDER = [
+  PIPELINE_STAGES.LEARN,
+  PIPELINE_STAGES.OBSERVE,
+  PIPELINE_STAGES.DETECT,
+  PIPELINE_STAGES.WRITE,
+  PIPELINE_STAGES.VERIFY,
+  PIPELINE_STAGES.VERDICT
+];
+
+/**
+ * Pipeline Stage Tracker
+ * 
+ * Enforces single, explicit execution path with mandatory stage recording.
+ */
+export class PipelineTracker {
+  constructor(projectDir, runId, runFingerprintParams = null) {
+    this.projectDir = projectDir;
+    this.runId = runId;
+    this.stages = {};
+    this.currentStage = null;
+    this.completedStages = [];
+    this.metaPath = getArtifactPath(projectDir, runId, 'run.meta.json');
+    this.runFingerprintParams = runFingerprintParams;
+  }
+
+  /**
+   * Start a pipeline stage
+   * 
+   * @param {string} stageName - Stage name (must be from PIPELINE_STAGES)
+   * @throws {Error} If stage is invalid or out of order
+   */
+  startStage(stageName) {
+    if (!Object.values(PIPELINE_STAGES).includes(stageName)) {
+      throw new Error(`Invalid pipeline stage: ${stageName}`);
+    }
+
+    const stageIndex = STAGE_ORDER.indexOf(stageName);
+    if (stageIndex === -1) {
+      throw new Error(`Unknown pipeline stage: ${stageName}`);
+    }
+
+    if (this.currentStage !== null) {
+      throw new Error(`Cannot start ${stageName}: ${this.currentStage} is still active`);
+    }
+
+    const expectedIndex = this.completedStages.length;
+    if (stageIndex !== expectedIndex) {
+      throw new Error(`Pipeline stage out of order: expected ${STAGE_ORDER[expectedIndex]}, got ${stageName}`);
+    }
+
+    this.currentStage = stageName;
+    this.stages[stageName] = {
+      name: stageName,
+      startedAt: new Date().toISOString(),
+      completedAt: null,
+      durationMs: null,
+      status: 'RUNNING'
+    };
+
+    this._writeMeta();
+  }
+
+  /**
+   * Complete a pipeline stage
+   * 
+   * @param {string} stageName - Stage name (must match current stage)
+   * @param {Object} metadata - Optional stage metadata
+   * @throws {Error} If stage name doesn't match current stage
+   */
+  completeStage(stageName, metadata = {}) {
+    if (this.currentStage !== stageName) {
+      throw new Error(`Cannot complete ${stageName}: current stage is ${this.currentStage}`);
+    }
+
+    const completedAt = new Date().toISOString();
+    const startedAt = new Date(this.stages[stageName].startedAt);
+    const durationMs = new Date(completedAt) - startedAt;
+
+    this.stages[stageName] = {
+      ...this.stages[stageName],
+      completedAt,
+      durationMs,
+      status: 'COMPLETE',
+      ...metadata
+    };
+
+    this.completedStages.push(stageName);
+    this.currentStage = null;
+
+    this._writeMeta();
+  }
+
+  /**
+   * Fail a pipeline stage
+   * 
+   * @param {string} stageName - Stage name (must match current stage)
+   * @param {Error|string} error - Error object or message
+   * @throws {Error} If stage name doesn't match current stage
+   */
+  failStage(stageName, error) {
+    if (this.currentStage !== stageName) {
+      throw new Error(`Cannot fail ${stageName}: current stage is ${this.currentStage}`);
+    }
+
+    const completedAt = new Date().toISOString();
+    const startedAt = new Date(this.stages[stageName].startedAt);
+    const durationMs = new Date(completedAt) - startedAt;
+
+    this.stages[stageName] = {
+      ...this.stages[stageName],
+      completedAt,
+      durationMs,
+      status: 'FAILED',
+      error: error instanceof Error ? error.message : String(error),
+      errorStack: error instanceof Error ? error.stack : null
+    };
+
+    this.completedStages.push(stageName);
+    this.currentStage = null;
+
+    this._writeMeta();
+  }
+
+  /**
+   * Get current stage
+   * 
+   * @returns {string|null} Current stage name or null
+   */
+  getCurrentStage() {
+    return this.currentStage;
+  }
+
+  /**
+   * Get stage execution data
+   * 
+   * @param {string} stageName - Stage name
+   * @returns {Object|null} Stage data or null if not executed
+   */
+  getStage(stageName) {
+    return this.stages[stageName] || null;
+  }
+
+  /**
+   * Get all stages
+   * 
+   * @returns {Object} Map of stage names to stage data
+   */
+  getAllStages() {
+    return { ...this.stages };
+  }
+
+  /**
+   * Check if a stage has completed
+   * 
+   * @param {string} stageName - Stage name
+   * @returns {boolean} True if stage completed
+   */
+  hasCompleted(stageName) {
+    return this.completedStages.includes(stageName);
+  }
+
+  /**
+   * Check if verification has completed (required before verdict)
+   * 
+   * @returns {boolean} True if verification completed
+   */
+  hasVerificationCompleted() {
+    return this.hasCompleted(PIPELINE_STAGES.VERIFY);
+  }
+
+  /**
+   * Write run.meta.json with stage execution data
+   */
+  _writeMeta() {
+    // Ensure directory exists
+    try {
+      mkdirSync(dirname(this.metaPath), { recursive: true });
+    } catch {
+      // Directory might already exist, ignore
+    }
+    
+    let existingMeta = {};
+    try {
+      const content = readFileSync(this.metaPath, 'utf-8');
+      existingMeta = JSON.parse(content);
+    } catch {
+      existingMeta = {};
+    }
+
+    // PHASE 25: Compute run fingerprint if params provided
+    let runFingerprint = existingMeta.runFingerprint || null;
+    if (this.runFingerprintParams && !runFingerprint) {
+      runFingerprint = computeRunFingerprint({
+        ...this.runFingerprintParams,
+        projectDir: this.projectDir
+      });
+    }
+    
+    const updatedMeta = {
+      ...existingMeta,
+      runId: this.runId,
+      runFingerprint,
+      pipeline: {
+        stages: this.stages,
+        completedStages: this.completedStages,
+        currentStage: this.currentStage,
+        lastUpdated: new Date().toISOString()
+      }
+    };
+
+    writeFileSync(this.metaPath, JSON.stringify(updatedMeta, null, 2) + '\n', 'utf-8');
+  }
+}
+
+export { PIPELINE_STAGES, STAGE_ORDER };
+