@veraxhq/verax 0.2.1 → 0.3.0

package/src/verax/index.js

@@ -9,8 +9,29 @@ import SilenceTracker from './core/silence-model.js';
 import { generateRunId, getRunArtifactDir, getArtifactPath } from './core/run-id.js';
 import { createRunManifest, updateRunManifestHashes } from './core/run-manifest.js';
 import { computeArtifactHashes } from './core/run-id.js';
+import { FailureLedger } from './core/failures/failure.ledger.js';
+import { errorToFailure, createIOFailure, createInternalFailure } from './core/failures/failure.factory.js';
+import { FAILURE_CODE, EXECUTION_PHASE } from './core/failures/failure.types.js';
+import { createPerformanceMonitor } from './core/perf/perf.monitor.js';
+import { generatePerformanceReport, writePerformanceReport } from './core/perf/perf.report.js';
+import { recordPerformanceViolations } from './core/perf/perf.enforcer.js';
+import { PipelineTracker, PIPELINE_STAGES } from './core/pipeline-tracker.js';
+import { verifyRun } from './core/artifacts/verifier.js';
+import { getArtifactVersions } from './core/artifacts/registry.js';
 
 export async function scan(projectDir, url, manifestPath = null, scanBudgetOverride = null, safetyFlags = {}) {
+  // PHASE 21.5: Initialize failure ledger (runId will be set after learn)
+  const scanBudget = scanBudgetOverride || createScanBudgetWithProfile();
+  const failureLedger = new FailureLedger(null, projectDir);
+  
+  // PHASE 21.9: Initialize performance monitor
+  const perfMonitor = createPerformanceMonitor();
+  perfMonitor.startPhase('LEARN');
+  
+  // ARCHITECTURAL HARDENING: Initialize pipeline tracker early (before runId is known)
+  // We'll set runId on the tracker once it's generated
+  let pipelineTracker = null;
+  
   // If manifestPath is provided, read it first before learn() overwrites it
   let loadedManifest = null;
   if (manifestPath) {
@@ -19,26 +40,62 @@ export async function scan(projectDir, url, manifestPath = null, scanBudgetOverr
       const manifestContent = JSON.parse(readFileSync(manifestPath, 'utf-8'));
       loadedManifest = manifestContent;
     } catch (e) {
-      // Fall through to learn if we can't read the manifest
+      // PHASE 21.5: Record I/O failure
+      const failure = createIOFailure(
+        FAILURE_CODE.IO_READ_FAILED,
+        `Failed to read manifest: ${e.message}`,
+        'scan',
+        { manifestPath, error: e.message },
+        true // Recoverable - will fall through to learn
+      );
+      failureLedger.record(failure);
     }
   }
   
+  // ARCHITECTURAL HARDENING: Track LEARN stage
+  // Note: We can't track LEARN yet because we don't have runId, but we'll track it retroactively
+  const learnStartTime = Date.now();
   const learnedManifest = await learn(projectDir);
+  const learnEndTime = Date.now();
+  perfMonitor.endPhase('LEARN');
   
-  // Merge: prefer loaded manifest for routes, but use learned for project type and truth
+  // ARCHITECTURAL HARDENING: Explicit manifest merging with deterministic precedence
+  // Rule: Loaded manifest routes take precedence, but learned manifest provides truth and project type
   let manifest;
   if (loadedManifest) {
+    // Explicit merge: loaded manifest routes override learned, but learned provides truth
     manifest = {
       ...learnedManifest,
+      // Routes from loaded manifest (if present) override learned routes
+      publicRoutes: loadedManifest.publicRoutes || learnedManifest.publicRoutes || [],
+      routes: loadedManifest.routes || learnedManifest.routes || [],
+      internalRoutes: loadedManifest.internalRoutes || learnedManifest.internalRoutes || [],
+      staticExpectations: loadedManifest.staticExpectations || learnedManifest.staticExpectations || [],
+      // Project type: prefer loaded, fallback to learned
       projectType: loadedManifest.projectType || learnedManifest.projectType,
-      publicRoutes: loadedManifest.publicRoutes || learnedManifest.publicRoutes,
-      routes: loadedManifest.routes || learnedManifest.routes,
-      internalRoutes: loadedManifest.internalRoutes || learnedManifest.internalRoutes,
-      staticExpectations: loadedManifest.staticExpectations || learnedManifest.staticExpectations,
-      manifestPath: manifestPath
+      // Always preserve learned truth (this is the source of truth)
+      learnTruth: learnedManifest.learnTruth || {},
+      // Track manifest source for auditability
+      manifestSource: 'merged',
+      manifestPath: manifestPath,
+      mergeMetadata: {
+        loadedManifestProvided: true,
+        learnedManifestProvided: true,
+        routesSource: loadedManifest.routes ? 'loaded' : 'learned',
+        projectTypeSource: loadedManifest.projectType ? 'loaded' : 'learned'
+      }
     };
   } else {
-    manifest = learnedManifest;
+    manifest = {
+      ...learnedManifest,
+      manifestSource: 'learned',
+      mergeMetadata: {
+        loadedManifestProvided: false,
+        learnedManifestProvided: true,
+        routesSource: 'learned',
+        projectTypeSource: 'learned'
+      }
+    };
   }
   
   if (!url) {
@@ -53,18 +110,8 @@ export async function scan(projectDir, url, manifestPath = null, scanBudgetOverr
     manifestPath: manifest.manifestPath
   };
   
-  let validation = await validateRoutes(manifestForValidation, url);
-  
-  if (!validation) {
-    // validateRoutes might return null if routes cannot be validated
-    validation = { 
-      routesValidated: 0, 
-      routesReachable: 0, 
-      routesUnreachable: 0, 
-      details: [], 
-      warnings: []
-    };
-  }
+  // ARCHITECTURAL HARDENING: validateRoutes now always returns explicit validation object
+  const validation = await validateRoutes(manifestForValidation, url);
   if (validation.warnings && validation.warnings.length > 0) {
     if (!manifest.learnTruth.warnings) {
       manifest.learnTruth.warnings = [];
@@ -72,9 +119,6 @@ export async function scan(projectDir, url, manifestPath = null, scanBudgetOverr
     manifest.learnTruth.warnings.push(...validation.warnings);
   }
   
-  // Use budget profile if no override provided
-  const scanBudget = scanBudgetOverride || createScanBudgetWithProfile();
-  
   // PHASE 5: Generate deterministic runId and create run manifest
   const { getBaseOrigin } = await import('./observe/domain-boundary.js');
   const baseOrigin = getBaseOrigin(url);
@@ -86,6 +130,41 @@ export async function scan(projectDir, url, manifestPath = null, scanBudgetOverr
     manifestPath
   });
   
+  // PHASE 21.5: Set runId in failure ledger
+  failureLedger.runId = runId;
+
+  // ARCHITECTURAL HARDENING: Initialize pipeline tracker now that we have runId
+  // PHASE 25: Pass runFingerprint params to PipelineTracker
+  const runFingerprintParams = url ? {
+    url,
+    projectDir,
+    manifestPath: null,
+    fixtureId: null
+  } : null;
+  pipelineTracker = new PipelineTracker(projectDir, runId, runFingerprintParams);
+  
+  // Record LEARN stage retroactively (it completed before we had runId)
+  try {
+    pipelineTracker.stages[PIPELINE_STAGES.LEARN] = {
+      name: PIPELINE_STAGES.LEARN,
+      startedAt: new Date(learnStartTime).toISOString(),
+      completedAt: new Date(learnEndTime).toISOString(),
+      durationMs: learnEndTime - learnStartTime,
+      status: 'COMPLETE'
+    };
+    pipelineTracker.completedStages.push(PIPELINE_STAGES.LEARN);
+    pipelineTracker._writeMeta();
+  } catch (error) {
+    const failure = createInternalFailure(
+      FAILURE_CODE.INTERNAL_UNEXPECTED_ERROR,
+      `Failed to record LEARN stage: ${error.message}`,
+      'scan',
+      { error: error.message },
+      error.stack
+    );
+    failureLedger.record(failure);
+  }
+
   // Create run manifest at start of execution
   const runManifest = createRunManifest(projectDir, runId, {
     url,
@@ -97,15 +176,61 @@ export async function scan(projectDir, url, manifestPath = null, scanBudgetOverr
   });
   
   const usedManifestPath = manifestPath || manifest.manifestPath;
-  const observation = await observe(url, usedManifestPath, scanBudget, safetyFlags, projectDir, runId);
+  
+  // ARCHITECTURAL HARDENING: Track OBSERVE stage
+  pipelineTracker.startStage(PIPELINE_STAGES.OBSERVE);
+  perfMonitor.startPhase('OBSERVE');
+  let observation;
+  try {
+    observation = await observe(url, usedManifestPath, scanBudget, safetyFlags, projectDir, runId);
+    perfMonitor.endPhase('OBSERVE');
+    pipelineTracker.completeStage(PIPELINE_STAGES.OBSERVE, {
+      pagesVisited: observation.observeTruth?.pagesVisited || 0,
+      interactionsExecuted: observation.observeTruth?.interactionsExecuted || 0
+    });
+  } catch (error) {
+    perfMonitor.endPhase('OBSERVE');
+    pipelineTracker.failStage(PIPELINE_STAGES.OBSERVE, error);
+    const failure = errorToFailure(
+      error,
+      FAILURE_CODE.OBSERVE_EXECUTION_FAILED,
+      'OBSERVE',
+      EXECUTION_PHASE.OBSERVE,
+      'observe',
+      { manifestPath: usedManifestPath }
+    );
+    failureLedger.record(failure);
+    throw error;
+  }
+  
+  // Update performance monitor with observed metrics
+  if (observation.observeTruth) {
+    const pagesVisited = observation.observeTruth.pagesVisited || 0;
+    const interactionsExecuted = observation.observeTruth.interactionsExecuted || observation.observeTruth.candidatesSelected || 0;
+    
+    for (let i = 0; i < pagesVisited; i++) {
+      perfMonitor.incrementPages();
+    }
+    for (let i = 0; i < interactionsExecuted; i++) {
+      perfMonitor.incrementInteractions();
+    }
+  }
 
   // Write a copy of the manifest into canonical run directory for replay integrity
   try {
     const { writeFileSync } = await import('fs');
     const manifestCopyPath = getArtifactPath(projectDir, runId, 'manifest.json');
     writeFileSync(manifestCopyPath, JSON.stringify(manifest, null, 2));
-  } catch {
-    // Ignore write errors
+  } catch (error) {
+    // PHASE 21.5: Record I/O failure (WARNING - recoverable)
+    const failure = createIOFailure(
+      FAILURE_CODE.IO_WRITE_FAILED,
+      `Failed to write manifest copy: ${error.message}`,
+      'scan',
+      { manifestPath, error: error.message },
+      true
+    );
+    failureLedger.record(failure);
   }
   
   // Create silence tracker from observation silences
@@ -114,27 +239,69 @@ export async function scan(projectDir, url, manifestPath = null, scanBudgetOverr
     silenceTracker.recordBatch(observation.silences.entries);
   }
   
-  const findings = await detect(usedManifestPath, observation.tracesPath, validation, observation.expectationCoverageGaps || [], silenceTracker);
+  // ARCHITECTURAL HARDENING: Track DETECT stage
+  pipelineTracker.startStage(PIPELINE_STAGES.DETECT);
+  perfMonitor.startPhase('DETECT');
+  let findings;
+  try {
+    findings = await detect(usedManifestPath, observation.tracesPath, validation, observation.expectationCoverageGaps || [], silenceTracker);
+    perfMonitor.endPhase('DETECT');
+    pipelineTracker.completeStage(PIPELINE_STAGES.DETECT, {
+      findingsCount: findings.findings?.length || 0,
+      coverageGapsCount: findings.coverageGaps?.length || 0
+    });
+  } catch (error) {
+    perfMonitor.endPhase('DETECT');
+    pipelineTracker.failStage(PIPELINE_STAGES.DETECT, error);
+    const failure = errorToFailure(
+      error,
+      FAILURE_CODE.DETECT_FINDING_PROCESSING_FAILED,
+      'DETECT',
+      EXECUTION_PHASE.DETECT,
+      'detect',
+      { manifestPath: usedManifestPath }
+    );
+    failureLedger.record(failure);
+    throw error; // Re-throw BLOCKING failures
+  }
   
   const learnTruthWithValidation = {
     ...manifest.learnTruth,
     validation: validation
   };
   
+  // ARCHITECTURAL HARDENING: Track WRITE stage
+  pipelineTracker.startStage(PIPELINE_STAGES.WRITE);
   const runDir = getRunArtifactDir(projectDir, runId);
-  const scanSummary = writeScanSummary(
-    projectDir,
-    url,
-    manifest.projectType,
-    learnTruthWithValidation,
-    observation.observeTruth,
-    findings.detectTruth,
-    manifest.manifestPath,
-    observation.tracesPath,
-    findings.findingsPath,
-    runDir,
-    findings.findings // PHASE 7: Pass findings array for decision snapshot
-  );
+  let scanSummary;
+  try {
+    scanSummary = await writeScanSummary(
+      projectDir,
+      url,
+      manifest.projectType,
+      learnTruthWithValidation,
+      observation.observeTruth,
+      findings.detectTruth,
+      manifest.manifestPath,
+      observation.tracesPath,
+      findings.findingsPath,
+      runDir,
+      findings.findings // PHASE 7: Pass findings array for decision snapshot
+    );
+    pipelineTracker.completeStage(PIPELINE_STAGES.WRITE);
+  } catch (error) {
+    pipelineTracker.failStage(PIPELINE_STAGES.WRITE, error);
+    const failure = errorToFailure(
+      error,
+      FAILURE_CODE.IO_WRITE_FAILED,
+      'WRITE',
+      EXECUTION_PHASE.WRITE,
+      'writeScanSummary',
+      { runDir }
+    );
+    failureLedger.record(failure);
+    throw error;
+  }
   
   // Compute observation summary from scan results (not a verdict)
   // Pass observation object (which includes traces) to observation engine
@@ -163,9 +330,204 @@ export async function scan(projectDir, url, manifestPath = null, scanBudgetOverr
   );
   observationSummary.evidenceIndexPath = evidenceIndexPath;
   
-  // PHASE 5: Compute artifact hashes and update run manifest
-  const artifactHashes = computeArtifactHashes(projectDir, runId);
-  updateRunManifestHashes(projectDir, runId, artifactHashes);
+  // PHASE 21.4: Write policy artifacts
+  try {
+    const { writeFileSync } = await import('fs');
+    const { loadGuardrailsPolicy, getPolicyReport: getGuardrailsPolicyReport } = await import('./core/guardrails/policy.loader.js');
+    const { loadConfidencePolicy, getPolicyReport: getConfidencePolicyReport } = await import('./core/confidence/confidence.loader.js');
+    
+    const guardrailsPolicy = loadGuardrailsPolicy();
+    const confidencePolicy = loadConfidencePolicy();
+    
+    const guardrailsPolicyPath = getArtifactPath(projectDir, failureLedger.runId, 'guardrails.policy.json');
+    const confidencePolicyPath = getArtifactPath(projectDir, failureLedger.runId, 'confidence.policy.json');
+    
+    writeFileSync(guardrailsPolicyPath, JSON.stringify({
+      ...getGuardrailsPolicyReport(guardrailsPolicy),
+      rules: guardrailsPolicy.rules.map(r => ({
+        id: r.id,
+        category: r.category,
+        action: r.action,
+        mandatory: r.mandatory
+      }))
+    }, null, 2));
+    
+    writeFileSync(confidencePolicyPath, JSON.stringify(getConfidencePolicyReport(confidencePolicy), null, 2));
+  } catch (error) {
+    // PHASE 21.5: Record I/O failure (WARNING - recoverable)
+    const failure = createIOFailure(
+      FAILURE_CODE.IO_WRITE_FAILED,
+      `Failed to write policy artifacts: ${error.message}`,
+      'scan',
+      { error: error.message },
+      true
+    );
+    failureLedger.record(failure);
+  }
+  
+  
+  // ARCHITECTURAL HARDENING: Write failure ledger with fallback to run.status.json
+  let ledgerPath;
+  try {
+    ledgerPath = failureLedger.write();
+  } catch (error) {
+    // If ledger write fails, write fallback entry to run.status.json
+    const failure = createInternalFailure(
+      FAILURE_CODE.INTERNAL_UNEXPECTED_ERROR,
+      `Failed to write failure ledger: ${error.message}`,
+      'scan',
+      { error: error.message },
+      error.stack
+    );
+    failureLedger.record(failure);
+    
+    // Write fallback failure entry to run.status.json
+    try {
+      const { writeFileSync, readFileSync } = await import('fs');
+      const runStatusPath = getArtifactPath(projectDir, runId, 'run.status.json');
+      let runStatus = { status: 'FAILED', failures: [] };
+      try {
+        const existing = readFileSync(runStatusPath, 'utf-8');
+        runStatus = JSON.parse(existing);
+      } catch {
+        // File doesn't exist or is invalid, use defaults
+      }
+      runStatus.failures = runStatus.failures || [];
+      runStatus.failures.push({
+        code: FAILURE_CODE.INTERNAL_UNEXPECTED_ERROR,
+        message: `Failed to write failure ledger: ${error.message}`,
+        timestamp: new Date().toISOString(),
+        recoverable: false
+      });
+      runStatus.ledgerWriteFailed = true;
+      runStatus.ledgerWriteError = error.message;
+      writeFileSync(runStatusPath, JSON.stringify(runStatus, null, 2) + '\n', 'utf-8');
+    } catch (fallbackError) {
+      // Even fallback write failed - log only
+      console.error('CRITICAL: Failed to write failure ledger and fallback:', error.message, fallbackError.message);
+    }
+  }
+  
+  // PHASE 21.9: Generate and write performance report
+  try {
+    perfMonitor.stop();
+    const monitorReport = perfMonitor.getFinalReport();
+    const profileName = process.env.VERAX_BUDGET_PROFILE || 'STANDARD';
+    const perfReport = generatePerformanceReport(projectDir, runId, monitorReport, profileName);
+    writePerformanceReport(projectDir, runId, perfReport);
+    
+    // Record performance violations in failure ledger
+    recordPerformanceViolations(projectDir, runId, failureLedger);
+  } catch (error) {
+    // Record performance report failure (WARNING - recoverable)
+    const failure = createIOFailure(
+      FAILURE_CODE.IO_WRITE_FAILED,
+      `Failed to write performance report: ${error.message}`,
+      'scan',
+      { error: error.message },
+      true
+    );
+    failureLedger.record(failure);
+  }
+  
+  // ARCHITECTURAL HARDENING: Track VERIFY stage
+  pipelineTracker.startStage(PIPELINE_STAGES.VERIFY);
+  let verification = null;
+  try {
+    const artifactVersions = getArtifactVersions();
+    verification = verifyRun(runDir, artifactVersions);
+    pipelineTracker.completeStage(PIPELINE_STAGES.VERIFY, {
+      ok: verification.ok,
+      errorsCount: verification.errors.length,
+      warningsCount: verification.warnings.length
+    });
+  } catch (error) {
+    pipelineTracker.failStage(PIPELINE_STAGES.VERIFY, error);
+    const failure = errorToFailure(
+      error,
+      FAILURE_CODE.VERIFICATION_FAILED,
+      'VERIFY',
+      EXECUTION_PHASE.VERIFY,
+      'verifyRun',
+      { runDir }
+    );
+    failureLedger.record(failure);
+    // Verification failure is not blocking, but we record it
+    verification = {
+      ok: false,
+      errors: [error.message],
+      warnings: [],
+      verifiedAt: new Date().toISOString()
+    };
+  }
+
+  // ARCHITECTURAL HARDENING: Track VERDICT stage (only after verification completes)
+  pipelineTracker.startStage(PIPELINE_STAGES.VERDICT);
+  try {
+    // PHASE 5: Compute artifact hashes and update run manifest
+    const artifactHashes = computeArtifactHashes(projectDir, runId);
+    updateRunManifestHashes(projectDir, runId, artifactHashes);
+    
+    // Verdict computation (determinism and evidence law checks)
+    let determinismVerdict = null;
+    let evidenceLawViolated = false;
+    try {
+      const decisionsPath = getArtifactPath(projectDir, runId, 'decisions.json');
+      const { readFileSync, existsSync } = await import('fs');
+      if (existsSync(decisionsPath)) {
+        const decisions = JSON.parse(readFileSync(decisionsPath, 'utf-8'));
+        const { DecisionRecorder } = await import('./core/determinism-model.js');
+        const recorder = DecisionRecorder.fromExport(decisions);
+        const { computeDeterminismVerdict } = await import('./core/determinism/contract.js');
+        const verdict = computeDeterminismVerdict(recorder);
+        determinismVerdict = verdict.verdict;
+      }
+      
+      // Check for Evidence Law violations (incomplete evidence with CONFIRMED findings)
+      if (findings.findings) {
+        for (const finding of findings.findings) {
+          if ((finding.severity === 'CONFIRMED' || finding.status === 'CONFIRMED') &&
+              finding.evidencePackage && !finding.evidencePackage.isComplete) {
+            evidenceLawViolated = true;
+            break;
+          }
+        }
+      }
+    } catch (error) {
+      // Record failure but don't block
+      const failure = createInternalFailure(
+        FAILURE_CODE.INTERNAL_UNEXPECTED_ERROR,
+        `Failed to compute determinism verdict: ${error.message}`,
+        'scan',
+        { error: error.message },
+        error.stack
+      );
+      failureLedger.record(failure);
+    }
+    
+    pipelineTracker.completeStage(PIPELINE_STAGES.VERDICT, {
+      determinismVerdict,
+      evidenceLawViolated,
+      verificationOk: verification?.ok || false
+    });
+  } catch (error) {
+    pipelineTracker.failStage(PIPELINE_STAGES.VERDICT, error);
+    const failure = errorToFailure(
+      error,
+      FAILURE_CODE.VERDICT_COMPUTATION_FAILED,
+      'VERDICT',
+      EXECUTION_PHASE.VERDICT,
+      'computeVerdict',
+      {}
+    );
+    failureLedger.record(failure);
+    throw error;
+  }
+
+  // Extract verdict data from pipeline tracker
+  const verdictStage = pipelineTracker.getStage(PIPELINE_STAGES.VERDICT);
+  const determinismVerdict = verdictStage?.determinismVerdict || null;
+  const evidenceLawViolated = verdictStage?.evidenceLawViolated || false;
 
   return { 
     manifest, 
@@ -175,8 +537,14 @@ export async function scan(projectDir, url, manifestPath = null, scanBudgetOverr
     validation, 
     coverageGaps: findings.coverageGaps || [],
     observationSummary,
-    runId,
-    runManifest
+    runId: failureLedger.runId,
+    runManifest,
+    failureLedger: failureLedger.export(),
+    ledgerPath,
+    determinismVerdict,
+    evidenceLawViolated,
+    verification,
+    pipelineStages: pipelineTracker.getAllStages()
   };
 }