@veraxhq/verax 0.3.0 → 0.4.0

package/src/verax/detect/confidence-helper.js

@@ -14,6 +14,7 @@ import { computeConfidenceForFinding } from '../core/confidence-engine.js';
  * @returns {Object} Finding with unified confidence fields
  */
 export function addUnifiedConfidence(finding, params) {
+  // @ts-expect-error - Optional params structure
   const unifiedConfidence = computeConfidenceForFinding({
     findingType: finding.type || 'unknown',
     expectation: params.expectation || null,

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

@@ -2,19 +2,11 @@
  * Detection Engine: Core of VERAX
  * Compares learn.json and observe.json to produce evidence-backed findings
  * with deterministic classification and confidence calculation
- * 
- * PHASE 11: EXPECTATION CONTINUITY
- * - Detects journey-level stalls (individual steps OK, overall journey stalls)
- * - Tracks interaction sequences and infers expected progression signals
- * - Emits "journey-stall-silent-failure" findings with high-confidence context
  */
 
-import JourneyStallDetector from './journey-stall-detector.js';
-
 class DetectionEngine {
   constructor(options = {}) {
     this.options = options;
-    this.journeyStallDetector = new JourneyStallDetector(options.journeyStall || {});
   }
 
   /**
@@ -30,7 +22,6 @@ class DetectionEngine {
 
     const expectations = learnData.expectations || [];
     const observations = observeData.observations || [];
-    const traces = observeData.traces || [];
 
     // Index observations for fast lookup
     const observationMap = this._indexObservations(observations);
@@ -40,10 +31,6 @@ class DetectionEngine {
       return this._classifyExpectation(expectation, observationMap, observations);
     });
 
-    // PHASE 11: Detect journey-level stalls
-    const journeyStallFindings = this.journeyStallDetector.detectStalls(traces);
-    findings.push(...journeyStallFindings);
-
     // Calculate stats
     const stats = this._calculateStats(findings);
 
@@ -51,11 +38,7 @@ class DetectionEngine {
       findings,
       stats,
       detectedAt: new Date().toISOString(),
-      version: '1.1.0',
-      phaseFeatures: {
-        expectationContinuity: true,
-        journeyStallDetection: true
-      }
+      version: '1.0.0'
     };
   }
 

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

@@ -24,10 +24,11 @@ import { applyGuardrails } from '../core/guardrails-engine.js';
  * 
  * @param {Array} traces - Interaction traces
  * @param {Object} manifest - Project manifest with routes and expectations
- * @param {Array} findings - Findings array to append to
+ * @param {Array} _findings - Findings array to append to
+ * @ts-expect-error - JSDoc param documented but unused
  * @returns {Object} { findings: Array, skips: Array }
  */
-export function detectDynamicRouteFindings(traces, manifest, findings) {
+export function detectDynamicRouteFindings(traces, manifest, _findings) {
   const dynamicRouteFindings = [];
   const skips = [];
   
@@ -117,6 +118,7 @@ export function detectDynamicRouteFindings(traces, manifest, findings) {
         
         // Build evidence
         const evidence = buildDynamicRouteEvidence(expectation, matchingRoute, correlation, trace);
+        const classificationReason = classification.reason || correlation.reason || null;
         
         // PHASE 14: Evidence Law - require sufficient evidence for CONFIRMED
         const hasSufficientEvidence = evidence.beforeAfter.beforeUrl &&
@@ -126,6 +128,14 @@ export function detectDynamicRouteFindings(traces, manifest, findings) {
                                        evidence.signals.uiFeedback !== 'FEEDBACK_MISSING' ||
                                        evidence.signals.domChanged);
         
+        // Determine finding type early (before use in confidence call)
+        let findingType = 'dynamic_route_silent_failure';
+        if (correlation.verdict === ROUTE_VERDICT.ROUTE_MISMATCH) {
+          findingType = 'dynamic_route_mismatch';
+        } else if (correlation.verdict === ROUTE_VERDICT.AMBIGUOUS) {
+          findingType = 'dynamic_route_ambiguous';
+        }
+        
         // PHASE 15: Compute unified confidence
         const unifiedConfidence = computeConfidenceForFinding({
           findingType: findingType,
@@ -133,10 +143,11 @@ export function detectDynamicRouteFindings(traces, manifest, findings) {
           sensors: trace.sensors || {},
           comparisons: {},
           evidence,
+          options: {}
         });
         
         // Legacy confidence for backward compatibility
-        const confidence = computeConfidence({
+        const _confidence = computeConfidence({
           findingType: 'dynamic_route_silent_failure',
           expectation,
           sensors: trace.sensors || {},
@@ -146,26 +157,18 @@ export function detectDynamicRouteFindings(traces, manifest, findings) {
         
         // Determine severity based on evidence and verdict
         let severity = 'SUSPECTED';
-        if (hasSufficientEvidence && correlation.verdict === ROUTE_VERDICT.SILENT_FAILURE && unifiedConfidence.score >= 0.8) {
+        if (hasSufficientEvidence && correlation.verdict === ROUTE_VERDICT.SILENT_FAILURE && (unifiedConfidence.score01 || unifiedConfidence.score || 0) >= 0.8) {
           severity = 'CONFIRMED';
         } else if (correlation.verdict === ROUTE_VERDICT.ROUTE_MISMATCH && hasSufficientEvidence) {
           severity = 'CONFIRMED';
         }
         
-        // Determine finding type
-        let findingType = 'dynamic_route_silent_failure';
-        if (correlation.verdict === ROUTE_VERDICT.ROUTE_MISMATCH) {
-          findingType = 'dynamic_route_mismatch';
-        } else if (correlation.verdict === ROUTE_VERDICT.AMBIGUOUS) {
-          findingType = 'dynamic_route_ambiguous';
-        }
-        
         const finding = {
           type: findingType,
           severity,
-          confidence: unifiedConfidence.score, // PHASE 15: Use unified confidence score (0..1)
+          confidence: unifiedConfidence.score01 || unifiedConfidence.score || 0, // Contract v1: score01 canonical
           confidenceLevel: unifiedConfidence.level, // PHASE 15: Add confidence level
-          confidenceReasons: unifiedConfidence.reasons, // PHASE 15: Add stable reason codes
+          confidenceReasons: unifiedConfidence.topReasons || unifiedConfidence.reasons || [], // Contract v1: topReasons
           interaction: {
             type: interaction.type,
             selector: interaction.selector,

package/src/verax/detect/expectation-chain-detector.js

@@ -125,7 +125,7 @@ export class ExpectationChainDetector {
     // Check each step in the chain
     for (let i = 0; i < chain.length; i++) {
       const step = chain[i];
-      const stepType = step.type;
+      const _stepType = step.type;
 
       // Find matching trace for this step
       const matchingTrace = traces.find(trace =>

package/src/verax/detect/expectation-model.js

@@ -93,10 +93,10 @@ export function matchExpectation(expectation, interaction, beforeUrl) {
   if (!beforePath) return null;
   
   const normalizedBefore = beforePath.replace(/\/$/, '') || '/';
-  const normalizedFrom = expectation.fromPath.replace(/\/$/, '') || '/';
+  const normalizedFrom = expectation.fromPath ? expectation.fromPath.replace(/\/$/, '') || '/' : normalizedBefore;
   const normalizedType = normalizeExpectationType(expectation.type);
   
-  if (normalizedFrom !== normalizedBefore) return null;
+  if (expectation.fromPath && normalizedFrom !== normalizedBefore) return null;
   
   if (!typesCompatible(normalizedType, interaction.type)) return null;
   
@@ -256,11 +256,9 @@ export function getExpectation(manifest, interaction, beforeUrl, attemptMeta = {
       for (const contract of manifest.actionContracts) {
         if (contract.source === sourceRef) {
           const expectationType = contract.kind === 'NETWORK_ACTION' ? 'network_action' : 'action';
-          // Dynamic URLs never produce PROVEN_EXPECTATION (truth boundary)
-          const proof = contract.isDynamic ? 'UNPROVEN_EXPECTATION' : 'PROVEN_EXPECTATION';
           return {
             hasExpectation: true,
-            proof,
+            proof: 'PROVEN_EXPECTATION',
             expectationType,
             method: contract.method,
             urlPath: contract.urlPath,

package/src/verax/detect/failure-cause-inference.js

@@ -0,0 +1,293 @@
+/**
+ * Failure Cause Inference (FCI) - Evidence-backed cause attribution
+ * 
+ * Pure, deterministic module that infers likely causes from confirmed findings.
+ * Each cause has explicit evidence conditions and is never guessed.
+ * 
+ * Rules:
+ * 1) No evidence -> no cause
+ * 2) Causes phrased as "Likely cause:" statements
+ * 3) Internal errors never reported as user bugs
+ * 4) Deterministic output: same input => same causes, ordering, wording
+ * 5) Confidence: LOW|MEDIUM only (never HIGH)
+ */
+
+/**
+ * Catalog order: causes are sorted by this order first, then by id as tie-breaker.
+ * This ensures stable, predictable cause ordering across all scenarios.
+ */
+const CATALOG_ORDER = ['C1_SELECTOR_MISMATCH', 'C2_STATE_MUTATION_NO_UI', 'C3_DEAD_CLICK', 'C4_NAVIGATION_NO_RENDER', 'C5_FORM_NO_FEEDBACK', 'C6_VALIDATION_NOT_SHOWN', 'C7_NETWORK_SILENT'];
+
+/**
+ * Catalog of detectable causes with evidence conditions
+ * Ordered by catalog position, then id for deterministic processing
+ */
+const CAUSE_CATALOG = [
+  {
+    id: 'C1_SELECTOR_MISMATCH',
+    title: 'Element not found or selector mismatch',
+    condition: (finding) => {
+      const ev = finding.evidence || {};
+      return (
+        (ev.targetElementMissing === true) ||
+        (ev.staleHandle === true) ||
+        (ev.clickAttempted === true && ev.targetElement === false) ||
+        (ev.locatorResolution === 0) ||
+        (ev.domSnapshotMissing && 
+          (ev.domSnapshotMissing.includes('id') || ev.domSnapshotMissing.includes('class') || ev.domSnapshotMissing.includes('text')))
+      );
+    },
+    statement: () => 
+      'Likely cause: The UI element being interacted with could not be found or was stale at interaction time.',
+    evidence_refs: (finding) => {
+      const refs = [];
+      if (finding.evidence?.targetElementMissing === true) refs.push('evidence.targetElementMissing=true');
+      if (finding.evidence?.staleHandle === true) refs.push('evidence.staleHandle=true');
+      if (finding.evidence?.locatorResolution === 0) refs.push('evidence.locatorResolution=0');
+      if (finding.evidence?.domSnapshotMissing) refs.push('evidence.domSnapshotMissing');
+      return refs;
+    },
+    confidenceScore: (finding) => {
+      // MEDIUM if multiple signals, LOW otherwise
+      const count = [
+        finding.evidence?.targetElementMissing,
+        finding.evidence?.staleHandle,
+        finding.evidence?.locatorResolution === 0
+      ].filter(Boolean).length;
+      return count >= 2 ? 'MEDIUM' : 'LOW';
+    }
+  },
+  
+  {
+    id: 'C2_STATE_MUTATION_NO_UI',
+    title: 'State changed but UI did not update',
+    condition: (finding) => {
+      const ev = finding.evidence || {};
+      return (
+        ev.stateMutation === true &&
+        ev.domChanged === false &&
+        ev.navigationOccurred !== true &&
+        ev.uiFeedback === false
+      );
+    },
+    statement: () => 
+      'Likely cause: Application state changed internally, but the UI did not re-render or reflect the change.',
+    evidence_refs: (_finding) => 
+      ['evidence.stateMutation=true', 'evidence.domChanged=false', 'evidence.uiFeedback=false'],
+    confidenceScore: () => 'MEDIUM'
+  },
+  
+  {
+    id: 'C3_DEAD_CLICK',
+    title: 'Interaction ran but produced no observable outcome',
+    condition: (finding) => {
+      const ev = finding.evidence || {};
+      return (
+        ev.interactionPerformed === true &&
+        ev.networkActivity === false &&
+        ev.navigationOccurred !== true &&
+        ev.domChanged === false &&
+        ev.userFeedback === false
+      );
+    },
+    statement: () => 
+      'Likely cause: The interaction ran but had no handler or the handler did nothing (dead/no-op click).',
+    evidence_refs: (_finding) => 
+      ['evidence.interactionPerformed=true', 'evidence.networkActivity=false', 'evidence.domChanged=false', 'evidence.userFeedback=false'],
+    confidenceScore: () => 'MEDIUM'
+  },
+  
+  {
+    id: 'C4_NAVIGATION_NO_RENDER',
+    title: 'Navigation attempted but content did not load',
+    condition: (finding) => {
+      const ev = finding.evidence || {};
+      return (
+        (ev.navigationAttempted === true || ev.urlChangeAttempted === true || ev.linkClicked === true) &&
+        (ev.urlChanged === false || (ev.urlChanged === true && ev.contentStillLoading === true)) &&
+        (ev.mainContentChanged === false || ev.mainContentBlank === true)
+      );
+    },
+    statement: () => 
+      'Likely cause: Navigation was triggered but the target route either did not change or did not render visible content.',
+    evidence_refs: (finding) => {
+      const refs = [];
+      if (finding.evidence?.navigationAttempted || finding.evidence?.urlChangeAttempted || finding.evidence?.linkClicked) {
+        refs.push('evidence.navigationAttempted|urlChangeAttempted|linkClicked=true');
+      }
+      if (finding.evidence?.urlChanged === false) refs.push('evidence.urlChanged=false');
+      if (finding.evidence?.mainContentChanged === false) refs.push('evidence.mainContentChanged=false');
+      return refs;
+    },
+    confidenceScore: () => 'MEDIUM'
+  },
+  
+  {
+    id: 'C5_FORM_NO_FEEDBACK',
+    title: 'Form submitted but no success or error message shown',
+    condition: (finding) => {
+      const ev = finding.evidence || {};
+      return (
+        ev.submitInteraction === true &&
+        (ev.networkRequestOccurred === true || ev.submitEventDetected === true) &&
+        ev.successFeedback === false &&
+        ev.errorFeedback === false &&
+        ev.navigationAfterSubmit !== true
+      );
+    },
+    statement: () => 
+      'Likely cause: Form submission was sent to the server, but the UI did not show a success or error message.',
+    evidence_refs: (_finding) => 
+      ['evidence.submitInteraction=true', 'evidence.successFeedback=false', 'evidence.errorFeedback=false'],
+    confidenceScore: () => 'MEDIUM'
+  },
+  
+  {
+    id: 'C6_VALIDATION_NOT_SHOWN',
+    title: 'Validation expected but feedback not displayed',
+    condition: (finding) => {
+      const ev = finding.evidence || {};
+      return (
+        ev.formOrValidationPromise === true &&
+        ev.invalidSubmitAttempted === true &&
+        ev.inlineValidationFeedback === false
+      );
+    },
+    statement: () => 
+      'Likely cause: Form field validation was expected to show inline feedback, but no error message appeared.',
+    evidence_refs: (_finding) => 
+      ['evidence.formOrValidationPromise=true', 'evidence.invalidSubmitAttempted=true', 'evidence.inlineValidationFeedback=false'],
+    confidenceScore: () => 'LOW'
+  },
+  
+  {
+    id: 'C7_NETWORK_SILENT',
+    title: 'Network request failed silently without user feedback',
+    condition: (finding) => {
+      const ev = finding.evidence || {};
+      return (
+        (ev.networkFailure === true || ev.httpError === true || ev.fetchError === true) &&
+        ev.uiFeedback === false &&
+        ev.domChanged === false
+      );
+    },
+    statement: () => 
+      'Likely cause: A network request failed (4xx/5xx or connection error), but the UI showed no error message.',
+    evidence_refs: (finding) => {
+      const refs = [];
+      if (finding.evidence?.networkFailure === true) refs.push('evidence.networkFailure=true');
+      if (finding.evidence?.httpError === true) refs.push('evidence.httpError=true');
+      if (finding.evidence?.fetchError === true) refs.push('evidence.fetchError=true');
+      refs.push('evidence.uiFeedback=false');
+      return refs;
+    },
+    confidenceScore: () => 'MEDIUM'
+  }
+];
+
+/**
+ * Infer likely causes for a finding.
+ * Only returns causes where evidence conditions are met.
+ * Causes are ordered deterministically by catalog order.
+ * 
+ * @param {Object} finding - Finding object with evidence property
+ * @returns {Array} Array of cause objects, sorted by id. Empty if no evidence.
+ */
+export function inferCauses(finding) {
+  if (!finding) {
+    return [];
+  }
+  
+  // Enforce Evidence Law: no evidence -> no causes
+  if (!finding.evidence || Object.keys(finding.evidence).length === 0) {
+    return [];
+  }
+  
+  const detectedCauses = [];
+  
+  for (const causeDef of CAUSE_CATALOG) {
+    if (causeDef.condition(finding)) {
+      const cause = {
+        id: causeDef.id,
+        title: causeDef.title,
+        statement: causeDef.statement(),
+        evidence_refs: causeDef.evidence_refs(finding),
+        confidence: causeDef.confidenceScore(finding)
+      };
+      detectedCauses.push(cause);
+    }
+  }
+  
+  // Sort deterministically by catalog order, then by id
+  detectedCauses.sort((a, b) => {
+    const aPos = CATALOG_ORDER.indexOf(a.id);
+    const bPos = CATALOG_ORDER.indexOf(b.id);
+    if (aPos !== bPos) {
+      return aPos - bPos;
+    }
+    return a.id.localeCompare(b.id);
+  });
+  
+  return detectedCauses;
+}
+
+/**
+ * Batch infer causes for all findings in a report.
+ * Pure function: same input => same causes in same order.
+ * 
+ * @param {Array} findings - Array of finding objects
+ * @returns {Object} Map of finding.id -> causes array
+ */
+export function inferCausesForFindings(findings) {
+  const causesMap = {};
+  
+  if (!findings || !Array.isArray(findings)) {
+    return causesMap;
+  }
+  
+  for (const finding of findings) {
+    const causes = inferCauses(finding);
+    if (causes.length > 0) {
+      causesMap[finding.id] = causes;
+    }
+  }
+  
+  return causesMap;
+}
+
+/**
+ * Attach causes to a finding object (pure function).
+ * Returns a new finding object with causes attached.
+ * Original finding is not mutated.
+ * 
+ * @param {Object} finding - Finding to augment
+ * @returns {Object} New finding object with causes array added
+ */
+export function attachCausesToFinding(finding) {
+  if (!finding) {
+    return finding;
+  }
+  const causes = inferCauses(finding);
+  return {
+    ...finding,
+    causes
+  };
+}
+
+/**
+ * Filter findings to only those with causes.
+ * Useful for reporting only findings with explanation.
+ * 
+ * @param {Array} findings - Array of findings
+ * @returns {Array} Findings with non-empty causes array
+ */
+export function findingsWithCauses(findings) {
+  if (!findings || !Array.isArray(findings)) {
+    return [];
+  }
+  
+  return findings.filter(f => {
+    const causes = inferCauses(f);
+    return causes.length > 0;
+  });
+}