@veraxhq/verax 0.2.1 → 0.3.0

package/src/verax/detect/route-findings.js

@@ -0,0 +1,218 @@
+/**
+ * PHASE 12 — Route Intelligence Findings Detector
+ * 
+ * Detects route-related silent failures by correlating navigation promises
+ * with route definitions and evaluating outcomes.
+ */
+
+import {
+  buildRouteModels,
+  correlateNavigationWithRoute,
+  evaluateRouteNavigation,
+  buildRouteEvidence,
+  isRouteChangeFalsePositive,
+} from '../core/route-intelligence.js';
+import { computeConfidence } from './confidence-engine.js';
+import { computeConfidenceForFinding } from '../core/confidence-engine.js';
+import { buildAndEnforceEvidencePackage } from '../core/evidence-builder.js';
+import { applyGuardrails } from '../core/guardrails-engine.js';
+
+/**
+ * PHASE 12: Detect route-related findings
+ * 
+ * @param {Array} traces - Interaction traces
+ * @param {Object} manifest - Project manifest with routes and expectations
+ * @param {Array} findings - Findings array to append to
+ * @returns {Array} Route-related findings
+ */
+export function detectRouteFindings(traces, manifest, findings) {
+  const routeFindings = [];
+  
+  // Build route models from manifest routes
+  const routeModels = buildRouteModels(manifest.routes || []);
+  
+  // Process each trace
+  for (const trace of traces) {
+    const interaction = trace.interaction || {};
+    const beforeUrl = trace.before?.url || trace.sensors?.navigation?.beforeUrl || '';
+    const afterUrl = trace.after?.url || trace.sensors?.navigation?.afterUrl || '';
+    
+    // Find navigation expectations for this interaction
+    const navigationExpectations = findNavigationExpectations(manifest, interaction, beforeUrl);
+    
+    for (const expectation of navigationExpectations) {
+      const navigationTarget = expectation.targetPath || expectation.expectedTarget || '';
+      
+      if (!navigationTarget) continue;
+      
+      // Correlate navigation promise with route
+      const correlation = correlateNavigationWithRoute(navigationTarget, routeModels);
+      
+      // Check for false positives
+      if (isRouteChangeFalsePositive(trace, correlation)) {
+        continue;
+      }
+      
+      // Evaluate route navigation outcome
+      const evaluation = evaluateRouteNavigation(correlation, trace, beforeUrl, afterUrl);
+      
+      // Generate finding if needed
+      if (evaluation.outcome === 'SILENT_FAILURE' || 
+          evaluation.outcome === 'ROUTE_MISMATCH' ||
+          (evaluation.outcome === 'SUSPECTED' && evaluation.confidence >= 0.6)) {
+        
+        // Build evidence
+        const evidence = buildRouteEvidence(correlation, expectation, evaluation, trace);
+        
+        // Determine finding type
+        let findingType = 'route_silent_failure';
+        let reason = evaluation.reason || 'Route navigation promise not fulfilled';
+        
+        if (evaluation.outcome === 'ROUTE_MISMATCH') {
+          findingType = 'route_mismatch';
+          reason = `Navigation occurred but target route does not match. Expected: ${correlation?.route?.path}, Actual: ${evidence.beforeAfter.afterUrl}`;
+        } else if (evaluation.outcome === 'SUSPECTED') {
+          findingType = 'route_ambiguous';
+          reason = 'Dynamic route cannot be deterministically validated';
+        }
+        
+        // PHASE 15: Compute unified confidence
+        const unifiedConfidence = computeConfidenceForFinding({
+          findingType: findingType,
+          expectation,
+          sensors: trace.sensors || {},
+          comparisons: {
+            urlChanged: evidence.signals.urlChanged,
+            domChanged: evidence.signals.domChanged,
+          },
+          evidence,
+        });
+        
+        // PHASE 12: Evidence Law - require sufficient evidence for CONFIRMED
+        const hasSufficientEvidence = evidence.beforeAfter.beforeUrl && 
+                                      evidence.beforeAfter.afterUrl &&
+                                      (evidence.signals.urlChanged || 
+                                       evidence.signals.routerStateChanged || 
+                                       evidence.signals.uiChanged || 
+                                       evidence.signals.domChanged);
+        
+        const severity = hasSufficientEvidence && unifiedConfidence.score >= 0.8 ? 'CONFIRMED' : 'SUSPECTED';
+        
+        const finding = {
+          type: findingType,
+          severity,
+          confidence: unifiedConfidence.score, // PHASE 15: Use unified confidence score (0..1)
+          confidenceLevel: unifiedConfidence.level, // PHASE 15: Add confidence level
+          confidenceReasons: unifiedConfidence.reasons, // PHASE 15: Add stable reason codes
+          interaction: {
+            type: interaction.type,
+            selector: interaction.selector,
+            label: interaction.label,
+          },
+          reason,
+          evidence,
+          source: {
+            file: expectation.source?.file || null,
+            line: expectation.source?.line || null,
+            column: expectation.source?.column || null,
+            context: expectation.source?.context || null,
+            astSource: expectation.source?.astSource || expectation.metadata?.astSource || null,
+          },
+        };
+        
+        // PHASE 16: Build and enforce evidence package
+        const findingWithEvidence = buildAndEnforceEvidencePackage(finding, {
+          expectation,
+          trace,
+          evidence,
+          confidence: unifiedConfidence,
+        });
+        
+        // PHASE 17: Apply guardrails (AFTER evidence builder)
+        const context = {
+          evidencePackage: findingWithEvidence.evidencePackage,
+          signals: findingWithEvidence.evidencePackage?.signals || evidence.signals || {},
+          confidenceReasons: unifiedConfidence.reasons || [],
+          promiseType: expectation?.type || null,
+        };
+        const { finding: findingWithGuardrails } = applyGuardrails(findingWithEvidence, context);
+        
+        routeFindings.push(findingWithGuardrails);
+      }
+    }
+  }
+  
+  return routeFindings;
+}
+
+/**
+ * Find navigation expectations matching the interaction
+ */
+function findNavigationExpectations(manifest, interaction, beforeUrl) {
+  const expectations = [];
+  
+  // Check static expectations
+  if (manifest.staticExpectations) {
+    const beforePath = extractPathFromUrl(beforeUrl);
+    if (beforePath) {
+      const normalizedBefore = beforePath.replace(/\/$/, '') || '/';
+      
+      for (const expectation of manifest.staticExpectations) {
+        if (expectation.type !== 'navigation' && expectation.type !== 'spa_navigation') {
+          continue;
+        }
+        
+        const normalizedFrom = (expectation.fromPath || '').replace(/\/$/, '') || '/';
+        if (normalizedFrom === normalizedBefore) {
+          // Check selector match
+          const selectorHint = expectation.selectorHint || '';
+          const interactionSelector = interaction.selector || '';
+          
+          if (!selectorHint || !interactionSelector || 
+              selectorHint === interactionSelector ||
+              selectorHint.includes(interactionSelector) ||
+              interactionSelector.includes(selectorHint)) {
+            expectations.push(expectation);
+          }
+        }
+      }
+    }
+  }
+  
+  // Check expectations from intel (AST-based)
+  if (manifest.expectations) {
+    for (const expectation of manifest.expectations) {
+      if (expectation.type === 'navigation' || expectation.type === 'spa_navigation') {
+        // Match by selector or label
+        const selectorHint = expectation.selectorHint || '';
+        const interactionSelector = interaction.selector || '';
+        const interactionLabel = (interaction.label || '').toLowerCase();
+        const expectationLabel = (expectation.promise?.value || '').toLowerCase();
+        
+        if (selectorHint === interactionSelector ||
+            (expectationLabel && interactionLabel && expectationLabel.includes(interactionLabel))) {
+          expectations.push(expectation);
+        }
+      }
+    }
+  }
+  
+  return expectations;
+}
+
+/**
+ * Extract path from URL
+ */
+function extractPathFromUrl(url) {
+  if (!url || typeof url !== 'string') return '';
+  
+  try {
+    const urlObj = new URL(url);
+    return urlObj.pathname;
+  } catch {
+    // Relative URL
+    const pathMatch = url.match(/^([^?#]+)/);
+    return pathMatch ? pathMatch[1] : url;
+  }
+}
+

package/src/verax/detect/ui-feedback-findings.js

@@ -0,0 +1,207 @@
+/**
+ * PHASE 13 — UI Feedback Findings Detector
+ * 
+ * Detects UI feedback-related silent failures by correlating promises
+ * with feedback signals and evaluating outcomes.
+ */
+
+import {
+  detectUIFeedbackSignals,
+  scoreUIFeedback,
+  correlatePromiseWithFeedback,
+  buildUIFeedbackEvidence,
+  FEEDBACK_SCORE,
+} from '../core/ui-feedback-intelligence.js';
+import { computeConfidence } from './confidence-engine.js';
+import { computeConfidenceForFinding } from '../core/confidence-engine.js';
+import { buildAndEnforceEvidencePackage } from '../core/evidence-builder.js';
+import { applyGuardrails } from '../core/guardrails-engine.js';
+
+/**
+ * PHASE 13: Detect UI feedback-related findings
+ * 
+ * @param {Array} traces - Interaction traces
+ * @param {Object} manifest - Project manifest with expectations
+ * @param {Array} findings - Findings array to append to
+ * @returns {Array} UI feedback-related findings
+ */
+export function detectUIFeedbackFindings(traces, manifest, findings) {
+  const feedbackFindings = [];
+  
+  // Process each trace
+  for (const trace of traces) {
+    const interaction = trace.interaction || {};
+    
+    // Find expectations for this interaction
+    const expectations = findExpectationsForInteraction(manifest, interaction, trace);
+    
+    for (const expectation of expectations) {
+      // Detect UI feedback signals
+      const signals = detectUIFeedbackSignals(trace);
+      
+      // Score feedback presence/absence
+      const feedbackScore = scoreUIFeedback(signals, expectation, trace);
+      
+      // Correlate promise with feedback
+      const correlation = correlatePromiseWithFeedback(expectation, feedbackScore, trace);
+      
+      // Generate finding if correlation indicates silent failure
+      if (correlation.outcome === 'CONFIRMED' || correlation.outcome === 'SUSPECTED') {
+        // Build evidence
+        const evidence = buildUIFeedbackEvidence(feedbackScore, correlation, trace, expectation);
+        
+        // PHASE 13: Evidence Law - require sufficient evidence for CONFIRMED
+        const hasSufficientEvidence = evidence.beforeAfter.beforeScreenshot &&
+                                      evidence.beforeAfter.afterScreenshot &&
+                                      (evidence.feedback.signals.length > 0 || 
+                                       evidence.feedback.score === FEEDBACK_SCORE.MISSING);
+        
+        // PHASE 15: Compute unified confidence
+        const unifiedConfidence = computeConfidenceForFinding({
+          findingType: findingType,
+          expectation,
+          sensors: trace.sensors || {},
+          comparisons: {},
+          evidence,
+        });
+        
+        // Legacy confidence for backward compatibility
+        const confidence = computeConfidence({
+          findingType: 'ui_feedback_silent_failure',
+          expectation,
+          sensors: trace.sensors || {},
+          comparisons: {},
+          attemptMeta: {},
+        });
+        
+        // Determine severity based on evidence
+        const severity = hasSufficientEvidence && correlation.outcome === 'CONFIRMED' && unifiedConfidence.score >= 0.8
+          ? 'CONFIRMED'
+          : 'SUSPECTED';
+        
+        // Determine finding type
+        let findingType = 'ui_feedback_silent_failure';
+        if (expectation.type === 'network_action' || expectation.type === 'network') {
+          findingType = 'network_feedback_missing';
+        } else if (expectation.type === 'navigation' || expectation.type === 'spa_navigation') {
+          findingType = 'navigation_feedback_missing';
+        } else if (expectation.type === 'validation' || expectation.type === 'form_submission') {
+          findingType = 'validation_feedback_missing';
+        } else if (expectation.type === 'state_action' || expectation.type === 'state') {
+          findingType = 'state_feedback_missing';
+        }
+        
+        const finding = {
+          type: findingType,
+          severity,
+          confidence: unifiedConfidence.score, // PHASE 15: Use unified confidence score (0..1)
+          confidenceLevel: unifiedConfidence.level, // PHASE 15: Add confidence level
+          confidenceReasons: unifiedConfidence.reasons, // PHASE 15: Add stable reason codes
+          interaction: {
+            type: interaction.type,
+            selector: interaction.selector,
+            label: interaction.label,
+          },
+          reason: correlation.reason || feedbackScore.explanation,
+          evidence,
+          source: {
+            file: expectation.source?.file || null,
+            line: expectation.source?.line || null,
+            column: expectation.source?.column || null,
+            context: expectation.source?.context || null,
+            astSource: expectation.source?.astSource || null,
+          },
+        };
+        
+        // PHASE 16: Build and enforce evidence package
+        const findingWithEvidence = buildAndEnforceEvidencePackage(finding, {
+          expectation,
+          trace,
+          evidence,
+          confidence: unifiedConfidence,
+        });
+        
+        // PHASE 17: Apply guardrails (AFTER evidence builder)
+        const context = {
+          evidencePackage: findingWithEvidence.evidencePackage,
+          signals: findingWithEvidence.evidencePackage?.signals || evidence.signals || {},
+          confidenceReasons: unifiedConfidence.reasons || [],
+          promiseType: expectation?.type || null,
+        };
+        const { finding: findingWithGuardrails } = applyGuardrails(findingWithEvidence, context);
+        
+        feedbackFindings.push(findingWithGuardrails);
+      }
+    }
+  }
+  
+  return feedbackFindings;
+}
+
+/**
+ * Find expectations matching the interaction
+ */
+function findExpectationsForInteraction(manifest, interaction, trace) {
+  const expectations = [];
+  
+  // Check static expectations
+  if (manifest.staticExpectations) {
+    const beforeUrl = trace.before?.url || trace.sensors?.navigation?.beforeUrl || '';
+    const beforePath = extractPathFromUrl(beforeUrl);
+    
+    if (beforePath) {
+      const normalizedBefore = beforePath.replace(/\/$/, '') || '/';
+      
+      for (const expectation of manifest.staticExpectations) {
+        const normalizedFrom = (expectation.fromPath || '').replace(/\/$/, '') || '/';
+        if (normalizedFrom === normalizedBefore) {
+          // Check selector match
+          const selectorHint = expectation.selectorHint || '';
+          const interactionSelector = interaction.selector || '';
+          
+          if (!selectorHint || !interactionSelector || 
+              selectorHint === interactionSelector ||
+              selectorHint.includes(interactionSelector) ||
+              interactionSelector.includes(selectorHint)) {
+            expectations.push(expectation);
+          }
+        }
+      }
+    }
+  }
+  
+  // Check expectations from intel (AST-based)
+  if (manifest.expectations) {
+    for (const expectation of manifest.expectations) {
+      // Match by selector or label
+      const selectorHint = expectation.selectorHint || '';
+      const interactionSelector = interaction.selector || '';
+      const interactionLabel = (interaction.label || '').toLowerCase();
+      const expectationLabel = (expectation.promise?.value || '').toLowerCase();
+      
+      if (selectorHint === interactionSelector ||
+          (expectationLabel && interactionLabel && expectationLabel.includes(interactionLabel))) {
+        expectations.push(expectation);
+      }
+    }
+  }
+  
+  return expectations;
+}
+
+/**
+ * Extract path from URL
+ */
+function extractPathFromUrl(url) {
+  if (!url || typeof url !== 'string') return '';
+  
+  try {
+    const urlObj = new URL(url);
+    return urlObj.pathname;
+  } catch {
+    // Relative URL
+    const pathMatch = url.match(/^([^?#]+)/);
+    return pathMatch ? pathMatch[1] : url;
+  }
+}
+

package/src/verax/detect/verdict-engine.js

@@ -55,19 +55,20 @@ export function computeObservationSummary(findings, observeTruth, learnTruth, co
   );
   const skippedCount = coverage.skippedInteractions || 0;
 
-  // Count findings by confidence (for transparency, not judgment)
+  // PHASE 15: Count findings by unified confidence level
   const findingsByConfidence = {
     HIGH: 0,
     MEDIUM: 0,
     LOW: 0,
-    UNKNOWN: 0
+    UNPROVEN: 0  // PHASE 15: Changed from UNKNOWN to UNPROVEN
   };
   const findingsByType = {};
   const findingsByOutcome = {};  // PHASE 2: Added outcome tracking
   const findingsByPromise = {};  // PHASE 3: Added promise tracking
   
   for (const finding of (findings || [])) {
-    const confidence = finding.confidence?.level || 'UNKNOWN';
+    // PHASE 15: Use unified confidence level
+    const confidence = finding.confidenceLevel || finding.confidence?.level || 'UNPROVEN';
     const type = finding.type || 'unknown';
     const outcome = finding.outcome || CANONICAL_OUTCOMES.SILENT_FAILURE;  // Default for legacy findings
     const promiseType = finding.promise?.type || 'UNKNOWN_PROMISE';  // PHASE 3
@@ -78,6 +79,39 @@ export function computeObservationSummary(findings, observeTruth, learnTruth, co
     findingsByType[type] = (findingsByType[type] || 0) + 1;
     findingsByOutcome[outcome] = (findingsByOutcome[outcome] || 0) + 1;  // PHASE 2
     findingsByPromise[promiseType] = (findingsByPromise[promiseType] || 0) + 1;  // PHASE 3
+    
+    // PHASE 16: Track evidence completeness
+    evidenceCompleteness.totalFindings++;
+    if (finding.evidencePackage) {
+      if (finding.evidencePackage.isComplete) {
+        evidenceCompleteness.completeEvidence++;
+      } else {
+        evidenceCompleteness.incompleteEvidence++;
+      }
+    }
+    if (finding.evidenceCompleteness?.downgraded) {
+      evidenceCompleteness.downgradedCount++;
+    }
+    
+    // PHASE 17: Track guardrails
+    if (finding.guardrails) {
+      guardrailsSummary.totalFindingsProcessed++;
+      if (finding.guardrails.appliedRules) {
+        guardrailsSummary.appliedRulesCount += finding.guardrails.appliedRules.length;
+      }
+      if (finding.guardrails.contradictions) {
+        guardrailsSummary.contradictionsCount += finding.guardrails.contradictions.length;
+      }
+      if (finding.guardrails.finalDecision === 'SUSPECTED' && finding.severity === 'CONFIRMED') {
+        guardrailsSummary.downgradedCount++;
+      }
+      if (finding.guardrails.finalDecision === 'INFORMATIONAL') {
+        guardrailsSummary.informationalCount++;
+      }
+      if (finding.guardrails.recommendedStatus !== finding.severity && finding.severity === 'CONFIRMED') {
+        guardrailsSummary.preventedConfirmedCount++;
+      }
+    }
   }
 
   // Calculate ratios (factual, not judgmental)
@@ -94,6 +128,24 @@ export function computeObservationSummary(findings, observeTruth, learnTruth, co
     unprovenResults: unprovenTraces.length
   };
 
+  // PHASE 16: Track evidence completeness summary
+  const evidenceCompleteness = {
+    totalFindings: 0,
+    completeEvidence: 0,
+    incompleteEvidence: 0,
+    downgradedCount: 0,
+  };
+  
+  // PHASE 17: Track guardrails summary
+  const guardrailsSummary = {
+    totalFindingsProcessed: 0,
+    preventedConfirmedCount: 0,
+    downgradedCount: 0,
+    informationalCount: 0,
+    appliedRulesCount: 0,
+    contradictionsCount: 0,
+  };
+  
   // Build gap details
   const gapDetails = [];
   if (isBudgetExceeded) {
@@ -150,6 +202,8 @@ export function computeObservationSummary(findings, observeTruth, learnTruth, co
       discrepanciesByPromise: findingsByPromise,  // PHASE 3: Promise types
       findings: findings || []
     },
+    evidenceCompleteness: evidenceCompleteness,  // PHASE 16: Evidence completeness summary
+    guardrailsSummary: guardrailsSummary,  // PHASE 17: Guardrails summary
     coverage: {
       pagesEvaluated,
       pagesDiscovered,