@veraxhq/verax 0.1.0 → 0.2.1

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

@@ -1,498 +1,933 @@
 /**
- * WAVE 4: CONFIDENCE ENGINE
+ * WAVE 4: CONFIDENCE ENGINE (PRODUCTION GRADE)
  * 
- * Evidence-based scoring for findings (0-100). No heuristics, no AI.
- * Confidence computed strictly from:
- * - Expectation proof strength (PROVEN_EXPECTATION required)
- * - Runtime sensor evidence (network/console/ui-signals)
- * - Deterministic observation signals (url/dom/screenshot changes)
+ * Deterministic, evidence-based scoring for findings.
+ * Output: { score, level, explain, factors }
+ * 
+ * MANDATORY RULES:
+ * 1. Same inputs always produce same score and explanations
+ * 2. HIGH level requires PROVEN expectation AND sensors present WITH DATA
+ * 3. All scores clamped to [0, 100]
+ * 4. Explanations ordered by importance, max 8 items
+ * 
+ * PHASE 3: EVIDENCE INTEGRITY
+ * - Sensors must contain NON-TRIVIAL data to count as "present"
+ * - Empty/placeholder sensor data does NOT count
+ * - Sensor failures tracked as silence events
+ */
+
+/**
+ * Check if network sensor contains non-trivial data.
+ * STRICT: Must have actual network activity captured.
+ */
+function hasNetworkData(networkSummary) {
+  if (!networkSummary || typeof networkSummary !== 'object') return false;
+  
+  // Check for any actual network activity
+  const hasRequests = (networkSummary.totalRequests || 0) > 0;
+  const hasFailures = (networkSummary.failedRequests || 0) > 0;
+  const hasSlow = (networkSummary.slowRequests || 0) > 0;
+  const hasFailedUrls = Array.isArray(networkSummary.topFailedUrls) && networkSummary.topFailedUrls.length > 0;
+  const hasSlowUrls = Array.isArray(networkSummary.topSlowUrls) && networkSummary.topSlowUrls.length > 0;
+  
+  return hasRequests || hasFailures || hasSlow || hasFailedUrls || hasSlowUrls;
+}
+
+/**
+ * Check if console sensor contains non-trivial data.
+ * STRICT: Must have actual console messages captured.
+ */
+function hasConsoleData(consoleSummary) {
+  if (!consoleSummary || typeof consoleSummary !== 'object') return false;
+  
+  // Check for any actual console activity
+  const hasMessages = (consoleSummary.totalMessages || 0) > 0;
+  const hasErrors = (consoleSummary.errors || 0) > 0;
+  const hasWarnings = (consoleSummary.warnings || 0) > 0;
+  const hasEntries = Array.isArray(consoleSummary.entries) && consoleSummary.entries.length > 0;
+  
+  return hasMessages || hasErrors || hasWarnings || hasEntries;
+}
+
+/**
+ * Check if UI sensor contains non-trivial data.
+ * STRICT: Must have meaningful UI changes captured.
  */
+function hasUiData(uiSignals) {
+  if (!uiSignals || typeof uiSignals !== 'object') return false;
+  
+  // Check diff object if it exists
+  const diff = uiSignals.diff || uiSignals;
+  
+  // Check for any meaningful UI changes
+  const hasAnyDelta = diff.hasAnyDelta === true || diff.changed === true;
+  const hasDomChange = diff.domChanged === true;
+  const hasVisibleChange = diff.visibleChanged === true;
+  const hasAriaChange = diff.ariaChanged === true;
+  const hasFocusChange = diff.focusChanged === true;
+  const hasTextChange = diff.textChanged === true;
+  
+  return hasAnyDelta || hasDomChange || hasVisibleChange || hasAriaChange || hasFocusChange || hasTextChange;
+}
 
 const BASE_SCORES = {
   network_silent_failure: 70,
-  validation_silent_failure: 60,
+  validation_silent_failure: 60, // VALIDATION INTELLIGENCE v1
   missing_feedback_failure: 55,
-   no_effect_silent_failure: 50,
-   missing_network_action: 65,
-   missing_state_action: 60
-};
-
-const CONFIDENCE_LEVELS = {
-  HIGH: 80,
-  MEDIUM: 60
+  no_effect_silent_failure: 50,
+  missing_network_action: 65,
+  missing_state_action: 60,
+  navigation_silent_failure: 75, // NAVIGATION INTELLIGENCE v2
+  partial_navigation_failure: 65, // NAVIGATION INTELLIGENCE v2
+  flow_silent_failure: 70, // FLOW INTELLIGENCE v1
+  observed_break: 50 // OBSERVED expectations (runtime-derived, lower confidence)
 };
 
-const LONG_ACTION_MS = 2000; // Threshold for slow requests
+/**
+ * Get base score from expectation strength.
+ */
+function getBaseScoreFromExpectationStrength(expectationStrength) {
+  if (expectationStrength === 'PROVEN') {
+    return 70;
+  }
+  if (expectationStrength === 'OBSERVED') {
+    return 55;
+  }
+  if (expectationStrength === 'WEAK') {
+    return 50;
+  }
+  return 0; // UNKNOWN
+}
 
 /**
- * Compute confidence score for a finding.
- * 
- * @param {Object} params
- * @param {string} params.findingType - Type of finding
- * @param {Object} params.expectation - Expectation with proof status
- * @param {Object} params.sensors - Sensor data (network, console, uiSignals)
- * @param {Object} params.comparisons - Comparison results (hasUrlChange, hasDomChange, hasVisibleChange)
- * @param {Object} params.attemptMeta - Metadata about the interaction attempt
- * @returns {Object} { score, level, reasons, breakdown }
+ * Main confidence computation function.
+ * @param {Object} params - { findingType, expectation, sensors, comparisons, attemptMeta }
+ * @returns {Object} - { score, level, explain, factors }
  */
 export function computeConfidence({ findingType, expectation, sensors = {}, comparisons = {}, attemptMeta = {} }) {
-  const baseScore = BASE_SCORES[findingType] || 50;
-  const points = { plus: {}, minus: {} };
-  const reasons = [];
+  const boosts = [];
+  const penalties = [];
   
+  // Extract sensor data (with defaults for missing sensors)
   const networkSummary = sensors.network || {};
   const consoleSummary = sensors.console || {};
   const uiSignals = sensors.uiSignals || {};
   
-  // Extract signals
-  const hasErrorFeedback = detectErrorFeedback(uiSignals);
-  const hasLoadingFeedback = detectLoadingFeedback(uiSignals);
-  const hasAnyFeedback = hasErrorFeedback || hasLoadingFeedback || detectStatusFeedback(uiSignals);
+  // === STEP 1: DETERMINE EXPECTATION STRENGTH ===
+  const expectationStrength = determineExpectationStrength(expectation);
+  
+  // === STEP 1B: SET BASE SCORE FROM EXPECTATION STRENGTH ===
+  let baseScore = BASE_SCORES[findingType] || 50;
+  // Override with expectation-strength-based score if available
+  const strengthBasedScore = getBaseScoreFromExpectationStrength(expectationStrength);
+  if (strengthBasedScore > 0) {
+    baseScore = strengthBasedScore;
+  }
+  
+  // === STEP 2: EXTRACT EVIDENCE SIGNALS ===
+  const evidenceSignals = extractEvidenceSignals({
+    networkSummary,
+    consoleSummary,
+    uiSignals,
+    comparisons
+  });
+  
+  // === STEP 3: SENSOR PRESENCE CHECK (STRICT - must contain data) ===
+  // PHASE 3: Sensors only count as "present" if they contain non-trivial data
+  const sensorsPresent = {
+    network: hasNetworkData(networkSummary),
+    console: hasConsoleData(consoleSummary),
+    ui: hasUiData(uiSignals)
+  };
+  
+  const allSensorsPresent = sensorsPresent.network && sensorsPresent.console && sensorsPresent.ui;
+  
+  // === STEP 4: COMPUTE BOOSTS AND PENALTIES (TYPE-SPECIFIC) ===
+  let totalBoosts = 0;
+  let totalPenalties = 0;
+  
+  const typeResults = scoreByFindingType({
+    findingType,
+    expectation,
+    expectationStrength,
+    networkSummary,
+    consoleSummary,
+    uiSignals,
+    evidenceSignals,
+    comparisons,
+    attemptMeta,
+    boosts,
+    penalties
+  });
+  
+  totalBoosts = typeResults.totalBoosts;
+  totalPenalties = typeResults.totalPenalties;
+  
+  // === STEP 5: APPLY GLOBAL PENALTIES ===
+  
+  // -15 if sensors missing (can't trust silent failure claim without sensors)
+  if (!allSensorsPresent) {
+    const missingSensors = [];
+    if (!sensorsPresent.network) missingSensors.push('network');
+    if (!sensorsPresent.console) missingSensors.push('console');
+    if (!sensorsPresent.ui) missingSensors.push('ui');
+    
+    const penalty = 15;
+    totalPenalties += penalty;
+    penalties.push(`Missing sensor data: ${missingSensors.join(', ')}`);
+  }
+  
+  // -10 if expectation not proven
+  if (expectationStrength !== 'PROVEN') {
+    totalPenalties += 10;
+    penalties.push(`Expectation strength is ${expectationStrength}, not PROVEN`);
+  }
+  
+  // === STEP 6: COMPUTE FINAL SCORE ===
+  let score = baseScore + totalBoosts - totalPenalties;
+  score = Math.max(0, Math.min(100, score)); // Clamp to [0, 100]
+  
+  // === STEP 7: DETERMINE LEVEL WITH HARD RULES ===
+  let level = 'LOW';
+  let boundaryExplanation = null; // Phase 3: Track near-threshold decisions
+  
+  if (score >= 80) {
+    // HARD RULE: HIGH level requires PROVEN expectation AND all sensors present
+    if (expectationStrength === 'PROVEN' && allSensorsPresent) {
+      level = 'HIGH';
+      
+      // Phase 3: Near-threshold detection (within 2 points of boundary)
+      if (score < 82) {
+        boundaryExplanation = `Near threshold: score ${score.toFixed(1)} >= 80 threshold, assigned HIGH (proven expectation + all sensors)`;
+      }
+    } else {
+      // Cap at MEDIUM if missing evidence
+      level = 'MEDIUM';
+      score = Math.min(score, 79);
+      
+      // Phase 3: Boundary explanation for capped score
+      boundaryExplanation = `Capped at MEDIUM: score would be ${(baseScore + totalBoosts - totalPenalties).toFixed(1)} but ${expectationStrength !== 'PROVEN' ? 'expectation not proven' : 'sensors missing'}, kept score <= 79`;
+    }
+  } else if (score >= 55) {
+    level = 'MEDIUM';
+    
+    // Phase 3: Near-threshold detection
+    if (score < 57) {
+      boundaryExplanation = `Near threshold: score ${score.toFixed(1)} >= 55 threshold, assigned MEDIUM (above LOW boundary)`;
+    } else if (score > 77) {
+      boundaryExplanation = `Near threshold: score ${score.toFixed(1)} < 80 threshold, kept MEDIUM (below HIGH boundary)`;
+    }
+  } else {
+    level = 'LOW';
+    
+    // Phase 3: Near-threshold detection
+    if (score > 52) {
+      boundaryExplanation = `Near threshold: score ${score.toFixed(1)} < 55 threshold, kept LOW (below MEDIUM boundary)`;
+    }
+  }
+  
+  // === STEP 8: GENERATE EXPLANATIONS (ORDERED BY IMPORTANCE) ===
+  const explain = generateExplanations(boosts, penalties, expectationStrength, evidenceSignals);
+
+  // OBSERVED expectations are conservatively capped
+  if (expectationStrength === 'OBSERVED') {
+    if (!attemptMeta?.repeated) {
+      level = 'LOW';
+      score = Math.min(score, 49);
+    } else if (level === 'HIGH') {
+      level = 'MEDIUM';
+      score = Math.min(score, 79);
+    }
+  }
+  
+  // === STEP 9: ASSEMBLE FINAL OUTPUT ===
+  const finalExplain = explain.slice(0, 8); // Max 8 reasons
+  
+  // === STEP 10: GENERATE CONFIDENCE EXPLANATIONS (PHASE 9) ===
+  const confidenceExplanation = generateConfidenceExplanation({
+    level,
+    score: Math.round(score),
+    expectationStrength,
+    sensorsPresent,
+    allSensorsPresent,
+    evidenceSignals,
+    boosts,
+    penalties,
+    attemptMeta,
+    boundaryExplanation // Phase 3: Include boundary reasoning
+  });
+  
+  return {
+    score: Math.round(score),
+    level,
+    explain: finalExplain,
+    factors: {
+      expectationStrength,
+      sensorsPresent,
+      evidenceSignals,
+      penalties,
+      boosts
+    },
+    confidenceExplanation,
+    boundaryExplanation // Phase 3: Surface boundary reasoning in output
+  };
+}
+
+/**
+ * Determine expectation strength from proof metadata.
+ */
+function determineExpectationStrength(expectation = {}) {
+  if (!expectation || Object.keys(expectation).length === 0) {
+    return 'UNKNOWN';
+  }
+
+  if (expectation.expectationStrength === 'OBSERVED') {
+    return 'OBSERVED';
+  }
+  
+  // If expectation has PROVEN_EXPECTATION marker, it's proven
+  if (expectation.proof === 'PROVEN_EXPECTATION') {
+    return 'PROVEN';
+  }
+  
+  // If it has explicit source reference (AST analysis, TS cross-file, etc.), it's proven
+  if (expectation.explicit === true || expectation.sourceRef) {
+    return 'PROVEN';
+  }
+  
+  // Static expectations from HTML parsing are considered PROVEN if they have evidence
+  if (expectation.evidence && expectation.evidence.source) {
+    return 'PROVEN';
+  }
+  
+  // If it has some metadata but not proven, it's weak
+  return 'WEAK';
+}
+
+/**
+ * Extract deterministic evidence signals from runtime data.
+ */
+function extractEvidenceSignals({ networkSummary, consoleSummary, uiSignals, comparisons }) {
+  const signals = {
+    urlChanged: comparisons?.hasUrlChange === true,
+    domChanged: comparisons?.hasDomChange === true,
+    screenshotChanged: comparisons?.hasVisibleChange === true,
+    networkFailed: (networkSummary?.failedRequests || 0) > 0,
+    consoleErrors: (consoleSummary?.hasErrors === true),
+    uiFeedbackDetected: hasAnyFeedback(uiSignals),
+    slowRequests: (networkSummary?.slowRequestsCount || 0) > 0
+  };
+  
+  return signals;
+}
+
+/**
+ * Check if any UI feedback is present (error, loading, status, etc.).
+ */
+function hasAnyFeedback(uiSignals = {}) {
+  const before = uiSignals.before || {};
+  const after = uiSignals.after || {};
   
-  let totalPlus = 0;
-  let totalMinus = 0;
+  return (
+    before.hasErrorSignal || after.hasErrorSignal ||
+    before.hasLoadingIndicator || after.hasLoadingIndicator ||
+    before.hasStatusSignal || after.hasStatusSignal ||
+    before.hasLiveRegion || after.hasLiveRegion ||
+    before.hasDialog || after.hasDialog ||
+    (before.disabledElements?.length || 0) > 0 ||
+    (after.disabledElements?.length || 0) > 0
+  );
+}
+
+/**
+ * Type-specific scoring dispatch.
+ */
+function scoreByFindingType({
+  findingType,
+  expectation,
+  expectationStrength,
+  networkSummary,
+  consoleSummary,
+  uiSignals: _uiSignals,
+  evidenceSignals,
+  comparisons: _comparisons,
+  attemptMeta: _attemptMeta,
+  boosts,
+  penalties
+}) {
+  let totalBoosts = 0;
+  let totalPenalties = 0;
   
-  // Type-specific scoring
   switch (findingType) {
     case 'network_silent_failure':
-      totalPlus += scoreNetworkSilentFailure({
+      totalBoosts = scoreNetworkSilentFailure({
         networkSummary,
         consoleSummary,
-        hasErrorFeedback,
-        hasAnyFeedback,
-        points,
-        reasons
+        evidenceSignals,
+        boosts,
+        penalties
       });
-      totalMinus += penalizeNetworkSilentFailure({
-        hasAnyFeedback,
-        points,
-        reasons
+      totalPenalties = penalizeNetworkSilentFailure({
+        evidenceSignals,
+        penalties
       });
       break;
       
     case 'validation_silent_failure':
-      totalPlus += scoreValidationSilentFailure({
+      totalBoosts = scoreValidationSilentFailure({
         networkSummary,
         consoleSummary,
-        hasErrorFeedback,
-        attemptMeta,
-        points,
-        reasons
+        evidenceSignals,
+        boosts,
+        penalties
       });
-      totalMinus += penalizeValidationSilentFailure({
-        hasErrorFeedback,
-        points,
-        reasons
+      totalPenalties = penalizeValidationSilentFailure({
+        evidenceSignals,
+        penalties
       });
       break;
       
     case 'missing_feedback_failure':
-      totalPlus += scoreMissingFeedbackFailure({
+      totalBoosts = scoreMissingFeedbackFailure({
         networkSummary,
-        hasLoadingFeedback,
-        points,
-        reasons
+        evidenceSignals,
+        boosts,
+        penalties
       });
-      totalMinus += penalizeMissingFeedbackFailure({
-        hasLoadingFeedback,
-        points,
-        reasons
+      totalPenalties = penalizeMissingFeedbackFailure({
+        evidenceSignals,
+        penalties
       });
       break;
       
     case 'no_effect_silent_failure':
-      totalPlus += scoreNoEffectSilentFailure({
+      totalBoosts = scoreNoEffectSilentFailure({
         expectation,
-        comparisons,
-        networkSummary,
-        hasAnyFeedback,
-        points,
-        reasons
+        evidenceSignals,
+        boosts,
+        penalties
       });
-      totalMinus += penalizeNoEffectSilentFailure({
-        networkSummary,
-        hasAnyFeedback,
-        points,
-        reasons
+      totalPenalties = penalizeNoEffectSilentFailure({
+        evidenceSignals,
+        penalties
       });
       break;
-   
-     case 'missing_network_action':
-       totalPlus += scoreMissingNetworkAction({
-         expectation,
-         attemptMeta,
-         consoleSummary,
-         networkSummary,
-         points,
-         reasons
-       });
-       totalMinus += penalizeMissingNetworkAction({
-         networkSummary,
-         points,
-         reasons
-       });
-       break;
-
+      
+    case 'missing_network_action':
+      totalBoosts = scoreMissingNetworkAction({
+        expectation,
+        expectationStrength,
+        evidenceSignals,
+        boosts,
+        penalties
+      });
+      totalPenalties = penalizeMissingNetworkAction({
+        evidenceSignals,
+        penalties
+      });
+      break;
+      
     case 'missing_state_action':
-      totalPlus += scoreMissingStateAction({
+      totalBoosts = scoreMissingStateAction({
         expectation,
-        attemptMeta,
-        sensors,
-        comparisons,
-        points,
-        reasons
+        expectationStrength,
+        evidenceSignals,
+        boosts,
+        penalties
       });
-      totalMinus += penalizeMissingStateAction({
-        sensors,
-        networkSummary,
-        points,
-        reasons
+      totalPenalties = penalizeMissingStateAction({
+        evidenceSignals,
+        penalties
+      });
+      break;
+      
+    case 'navigation_silent_failure':
+      totalBoosts = scoreNavigationSilentFailure({
+        expectation,
+        expectationStrength,
+        evidenceSignals,
+        boosts,
+        penalties
+      });
+      totalPenalties = penalizeNavigationSilentFailure({
+        evidenceSignals,
+        penalties
+      });
+      break;
+      
+    case 'partial_navigation_failure':
+      totalBoosts = scorePartialNavigationFailure({
+        expectation,
+        expectationStrength,
+        evidenceSignals,
+        boosts,
+        penalties
+      });
+      totalPenalties = penalizePartialNavigationFailure({
+        evidenceSignals,
+        penalties
       });
       break;
   }
   
-  // Compute final score
-  let score = baseScore + totalPlus - totalMinus;
-  score = Math.max(0, Math.min(100, score)); // Cap to [0, 100]
+  return { totalBoosts, totalPenalties };
+}
+
+// ============================================================
+// TYPE-SPECIFIC SCORING FUNCTIONS
+// ============================================================
+
+function scoreNetworkSilentFailure({ networkSummary: _networkSummary, consoleSummary: _consoleSummary, evidenceSignals, boosts, penalties: _penalties }) {
+  let total = 0;
   
-  // Determine level
-  let level = 'LOW';
-  if (score >= CONFIDENCE_LEVELS.HIGH) {
-    level = 'HIGH';
-  } else if (score >= CONFIDENCE_LEVELS.MEDIUM) {
-    level = 'MEDIUM';
+  // +10 if network failed
+  if (evidenceSignals.networkFailed) {
+    total += 10;
+    boosts.push('Network request failed');
   }
   
-  // Limit reasons to 6 most important
-  const limitedReasons = reasons.slice(0, 6);
+  // +8 if console errors
+  if (evidenceSignals.consoleErrors) {
+    total += 8;
+    boosts.push('Console errors present');
+  }
   
-  return {
-    score: Math.round(score),
-    level,
-    reasons: limitedReasons,
-    breakdown: {
-      base: baseScore,
-      plus: points.plus,
-      minus: points.minus
-    }
-  };
+  // +6 if network failed AND no UI feedback
+  if (evidenceSignals.networkFailed && !evidenceSignals.uiFeedbackDetected) {
+    total += 6;
+    boosts.push('Silent failure: no user feedback on network error');
+  }
+  
+  return total;
 }
 
-// === NETWORK SILENT FAILURE SCORING ===
+function penalizeNetworkSilentFailure({ evidenceSignals, penalties }) {
+  let total = 0;
+  
+  // -10 if UI feedback present (shouldn't be silent failure)
+  if (evidenceSignals.uiFeedbackDetected) {
+    total += 10;
+    penalties.push('UI feedback detected (suggests not silent)');
+  }
+  
+  return total;
+}
 
-function scoreNetworkSilentFailure({ networkSummary, consoleSummary, hasErrorFeedback, hasAnyFeedback, points, reasons }) {
+function scoreValidationSilentFailure({ networkSummary: _networkSummary, consoleSummary: _consoleSummary, evidenceSignals, boosts, penalties: _penalties }) {
   let total = 0;
   
-  // +15 if server error (5xx)
-  if (networkSummary.failedRequests >= 1) {
-    const has5xxError = Object.keys(networkSummary.failedByStatus || {}).some(status => parseInt(status) >= 500);
-    if (has5xxError) {
-      points.plus.serverError = 15;
-      total += 15;
-      reasons.push('Server error (5xx) detected');
-    } else {
-      // Client error (4xx)
-      points.plus.networkFailure = 10;
-      total += 10;
-      reasons.push('Network request failed');
-    }
+  // +10 if console errors (validation errors logged)
+  if (evidenceSignals.consoleErrors) {
+    total += 10;
+    if (boosts) boosts.push('Validation errors in console');
   }
   
-  // +10 if request explicitly failed (requestfailed event)
-  if (networkSummary.failedRequests > 0) {
-    const hasExplicitFailure = networkSummary.topFailedUrls?.length > 0;
-    if (hasExplicitFailure) {
-      points.plus.explicitFailure = 10;
-      total += 10;
-      reasons.push('Request failure event captured');
-    }
+  // +8 if no UI feedback with console errors
+  if (evidenceSignals.consoleErrors && !evidenceSignals.uiFeedbackDetected) {
+    total += 8;
+    if (boosts) boosts.push('Silent validation: errors logged but no visible feedback');
   }
   
-  // +10 if console shows page error or unhandled rejection
-  if ((consoleSummary.pageErrorCount || 0) > 0 || (consoleSummary.unhandledRejectionCount || 0) > 0) {
-    points.plus.jsError = 10;
+  return total;
+}
+
+function penalizeValidationSilentFailure({ evidenceSignals, penalties }) {
+  let total = 0;
+  
+  // -10 if error feedback visible
+  if (evidenceSignals.uiFeedbackDetected) {
     total += 10;
-    reasons.push('JavaScript error or unhandled rejection logged');
+    penalties.push('Error feedback visible (not silent)');
   }
   
-  // +10 if NO user feedback at all
-  if (!hasAnyFeedback) {
-    points.plus.noFeedback = 10;
+  return total;
+}
+
+function scoreMissingFeedbackFailure({ networkSummary: _networkSummary, evidenceSignals, boosts, penalties: _penalties }) {
+  let total = 0;
+  
+  // +10 if slow/pending requests
+  if (evidenceSignals.slowRequests) {
     total += 10;
-    reasons.push('No user-visible error feedback');
+    boosts.push('Slow requests detected');
+  }
+  
+  // +8 if network activity without loading feedback
+  if (evidenceSignals.networkFailed && !evidenceSignals.uiFeedbackDetected) {
+    total += 8;
+    boosts.push('Network activity without user feedback');
   }
   
   return total;
 }
 
-function penalizeNetworkSilentFailure({ hasAnyFeedback, points, reasons }) {
+function penalizeMissingFeedbackFailure({ evidenceSignals, penalties }) {
   let total = 0;
   
-  // -20 if any feedback exists (shouldn't be classified as silent failure)
-  if (hasAnyFeedback) {
-    points.minus.hasFeedback = 20;
-    total += 20;
-    reasons.push('User feedback detected (reduces confidence)');
+  // -10 if loading feedback detected
+  if (evidenceSignals.uiFeedbackDetected) {
+    total += 10;
+    penalties.push('Loading indicator detected');
   }
   
   return total;
 }
 
-// === VALIDATION SILENT FAILURE SCORING ===
-
-function scoreValidationSilentFailure({ networkSummary, consoleSummary, hasErrorFeedback, attemptMeta, points, reasons }) {
+function scoreNoEffectSilentFailure({ expectation: _expectation, evidenceSignals, boosts, penalties: _penalties }) {
   let total = 0;
   
-  // +15 if invalid fields detected
-  const invalidFieldsCount = attemptMeta.invalidFieldsCount || 0;
-  if (invalidFieldsCount >= 1) {
-    points.plus.invalidFields = 15;
-    total += 15;
-    reasons.push(`${invalidFieldsCount} invalid form field(s) detected`);
+  // +10 if URL should have changed but didn't
+  if (!evidenceSignals.urlChanged) {
+    total += 10;
+    boosts.push('Expected URL change did not occur');
   }
   
-  // +10 if console errors logged
-  if ((consoleSummary.consoleErrorCount || 0) >= 1) {
-    points.plus.consoleError = 10;
-    total += 10;
-    reasons.push('Validation errors logged to console');
+  // +6 if DOM unchanged
+  if (!evidenceSignals.domChanged) {
+    total += 6;
+    boosts.push('DOM state unchanged');
   }
   
-  // +10 if no validation feedback visible
-  if (!hasErrorFeedback) {
-    points.plus.noValidationFeedback = 10;
-    total += 10;
-    reasons.push('No visible validation error message');
+  // +5 if screenshot unchanged
+  if (!evidenceSignals.screenshotChanged) {
+    total += 5;
+    boosts.push('No visible changes');
   }
   
   return total;
 }
 
-function penalizeValidationSilentFailure({ hasErrorFeedback, points, reasons }) {
+function penalizeNoEffectSilentFailure({ evidenceSignals, penalties }) {
   let total = 0;
   
-  // -15 if error feedback exists
-  if (hasErrorFeedback) {
-    points.minus.hasErrorFeedback = 15;
-    total += 15;
-    reasons.push('Error feedback visible (reduces confidence)');
+  // -10 if network activity (might be a real effect)
+  if (evidenceSignals.networkFailed) {
+    total += 10;
+    penalties.push('Network activity detected (potential effect)');
+  }
+  
+  // -8 if UI feedback changed
+  if (evidenceSignals.uiFeedbackDetected) {
+    total += 8;
+    penalties.push('UI feedback changed (potential effect)');
   }
   
   return total;
 }
 
-// === MISSING FEEDBACK FAILURE SCORING ===
+function scoreMissingNetworkAction({ expectation, expectationStrength, evidenceSignals, boosts, penalties: _penalties }) {
+  let total = 0;
+  
+  // +10 if PROVEN expectation
+  if (expectationStrength === 'PROVEN') {
+    total += 10;
+    boosts.push('Code promise verified via AST analysis');
+  }
+  
+  // +8 if zero network activity (strong evidence of missing action)
+  if (!evidenceSignals.networkFailed && (expectation?.totalRequests || 0) === 0) {
+    total += 8;
+    boosts.push('Zero network activity despite code promise');
+  }
+  
+  // +6 if console errors may explain why action didn't fire
+  if (evidenceSignals.consoleErrors) {
+    total += 6;
+    boosts.push('Console errors may have prevented action');
+  }
+  
+  return total;
+}
 
-function scoreMissingFeedbackFailure({ networkSummary, hasLoadingFeedback, points, reasons }) {
+function penalizeMissingNetworkAction({ evidenceSignals, penalties }) {
   let total = 0;
   
-  // +15 if slow requests detected
-  if ((networkSummary.slowRequestsCount || 0) >= 1) {
-    const slowestDuration = networkSummary.slowRequests?.[0]?.duration || 0;
-    points.plus.slowRequest = 15;
+  // -15 if there WAS network activity (promise may be fulfilled differently)
+  if (evidenceSignals.networkFailed) {
     total += 15;
-    reasons.push(`Slow request detected (${slowestDuration}ms)`);
+    penalties.push('Other network requests occurred');
   }
   
-  // +10 if significant network activity
-  if ((networkSummary.totalRequests || 0) >= 1 && (networkSummary.durationMs || 0) >= LONG_ACTION_MS) {
-    points.plus.longAction = 10;
+  return total;
+}
+
+function scoreMissingStateAction({ expectation: _expectation, expectationStrength, evidenceSignals, boosts, penalties: _penalties }) {
+  let total = 0;
+  
+  // +10 if PROVEN expectation
+  if (expectationStrength === 'PROVEN') {
     total += 10;
-    reasons.push('Long-running network activity');
+    boosts.push('State mutation proven via cross-file analysis');
   }
   
-  // +10 if no loading feedback
-  if (!hasLoadingFeedback) {
-    points.plus.noLoadingFeedback = 10;
-    total += 10;
-    reasons.push('No loading indicator shown');
+  // +8 if no DOM changes
+  if (!evidenceSignals.domChanged) {
+    total += 8;
+    boosts.push('DOM unchanged (no state mutation visible)');
   }
   
   return total;
 }
 
-function penalizeMissingFeedbackFailure({ hasLoadingFeedback, points, reasons }) {
+function penalizeMissingStateAction({ evidenceSignals, penalties }) {
   let total = 0;
   
-  // -10 if loading indicator detected
-  if (hasLoadingFeedback) {
-    points.minus.hasLoadingFeedback = 10;
+  // -10 if network activity (async state update possible)
+  if (evidenceSignals.networkFailed) {
     total += 10;
-    reasons.push('Loading indicator detected (reduces confidence)');
+    penalties.push('Network activity (deferred state update possible)');
+  }
+  
+  // -8 if UI feedback
+  if (evidenceSignals.uiFeedbackDetected) {
+    total += 8;
+    penalties.push('UI feedback suggests state managed differently');
   }
   
   return total;
 }
 
-// === NO EFFECT SILENT FAILURE SCORING ===
-
-function scoreNoEffectSilentFailure({ expectation, comparisons, networkSummary, hasAnyFeedback, points, reasons }) {
+// NAVIGATION INTELLIGENCE v2: Navigation failure scoring
+function scoreNavigationSilentFailure({ expectation: _expectation, expectationStrength: _expectationStrength, evidenceSignals, boosts, penalties: _penalties }) {
   let total = 0;
   
-  // +15 if expected navigation but no URL change
-  const expectsNavigation = expectation?.expectationType === 'navigation' || 
-                           expectation?.expectationType === 'spa_navigation' ||
-                           expectation?.expectationType === 'form_submission';
-  if (expectsNavigation && !comparisons.hasUrlChange) {
-    points.plus.expectedNavNoUrl = 15;
-    total += 15;
-    reasons.push('Expected navigation did not occur');
+  // +10 if URL should have changed but didn't
+  if (!evidenceSignals.urlChanged) {
+    total += 10;
+    boosts.push('Expected URL change did not occur');
   }
   
-  // +10 if no DOM change at all
-  if (!comparisons.hasDomChange) {
-    points.plus.noDomChange = 10;
-    total += 10;
-    reasons.push('No DOM changes detected');
+  // +8 if no UI feedback
+  if (!evidenceSignals.uiFeedbackDetected) {
+    total += 8;
+    boosts.push('No user-visible feedback on navigation failure');
   }
   
-  // +10 if screenshot unchanged (if available)
-  if (comparisons.hasVisibleChange === false) {
-    points.plus.noVisibleChange = 10;
-    total += 10;
-    reasons.push('No visible changes in screenshot');
+  // +6 if console errors (navigation errors logged)
+  if (evidenceSignals.consoleErrors) {
+    total += 6;
+    boosts.push('Navigation errors in console');
   }
   
   return total;
 }
 
-function penalizeNoEffectSilentFailure({ networkSummary, hasAnyFeedback, points, reasons }) {
+function penalizeNavigationSilentFailure({ evidenceSignals, penalties }) {
   let total = 0;
   
-  // -10 if network activity occurred (might be effect without visible change)
-  if ((networkSummary.totalRequests || 0) > 0) {
-    points.minus.hasNetworkActivity = 10;
+  // -10 if UI feedback present (shouldn't be silent failure)
+  if (evidenceSignals.uiFeedbackDetected) {
     total += 10;
-    reasons.push('Network activity detected (potential hidden effect)');
+    penalties.push('UI feedback detected (suggests navigation feedback provided)');
   }
   
-  // -10 if UI signal changed
-  if (hasAnyFeedback) {
-    points.minus.uiSignalChanged = 10;
-    total += 10;
-    reasons.push('UI signal changed (potential effect)');
+  // -5 if URL changed (navigation might have succeeded)
+  if (evidenceSignals.urlChanged) {
+    total += 5;
+    penalties.push('URL changed (navigation may have succeeded)');
   }
   
   return total;
 }
 
-// === HELPER FUNCTIONS ===
-
-function detectErrorFeedback(uiSignals) {
-  const before = uiSignals.before || {};
-  const after = uiSignals.after || {};
-  const changes = uiSignals.changes || {};
+function scorePartialNavigationFailure({ expectation: _expectation, expectationStrength: _expectationStrength, evidenceSignals, boosts, penalties: _penalties }) {
+  let total = 0;
   
-  // Check if error signal appeared after interaction
-  return (after.hasErrorSignal && !before.hasErrorSignal) || 
-         (changes.changed && after.hasErrorSignal);
-}
-
-function detectLoadingFeedback(uiSignals) {
-  const before = uiSignals.before || {};
-  const after = uiSignals.after || {};
+  // +10 if history changed but target not reached
+  if (evidenceSignals.urlChanged && !evidenceSignals.uiFeedbackDetected) {
+    total += 10;
+    boosts.push('Navigation started but target not reached');
+  }
+  
+  // +8 if no UI feedback
+  if (!evidenceSignals.uiFeedbackDetected) {
+    total += 8;
+    boosts.push('No user-visible feedback on partial navigation');
+  }
   
-  // Check if loading indicator appeared or changed
-  return after.hasLoadingIndicator || 
-         (before.hasLoadingIndicator !== after.hasLoadingIndicator);
+  return total;
 }
 
-function detectStatusFeedback(uiSignals) {
-  const after = uiSignals.after || {};
+function penalizePartialNavigationFailure({ evidenceSignals, penalties }) {
+  let total = 0;
   
-  // Check for any status/live region updates
-  return after.hasStatusSignal || after.hasLiveRegion || after.hasDialog;
+  // -10 if UI feedback present (shouldn't be partial failure)
+  if (evidenceSignals.uiFeedbackDetected) {
+    total += 10;
+    penalties.push('UI feedback detected (suggests navigation feedback provided)');
+  }
+  
+  return total;
 }
 
-  // === MISSING NETWORK ACTION SCORING ===
+// ============================================================
+// EXPLANATION GENERATION (ORDERED BY IMPORTANCE)
+// ============================================================
 
-  function scoreMissingNetworkAction({ expectation, attemptMeta, consoleSummary, networkSummary, points, reasons }) {
-    let total = 0;
+function generateExplanations(boosts, penalties, expectationStrength, _evidenceSignals) {
+  const explain = [];
   
-    // +15 if PROVEN expectation with source attribution (high certainty of broken promise)
-    if (expectation?.proof === 'PROVEN_EXPECTATION' && attemptMeta.sourceRef) {
-      points.plus.provenContract = 15;
-      total += 15;
-      reasons.push('Code contract proven via AST analysis');
-    }
+  // Add penalties first (most important negatives)
+  if (penalties.length > 0) {
+    explain.push(...penalties);
+  }
   
-    // +10 if console has errors (might explain why request didn't fire)
-    if ((consoleSummary.consoleErrorCount || 0) > 0 || (consoleSummary.pageErrorCount || 0) > 0) {
-      points.plus.consoleError = 10;
-      total += 10;
-      reasons.push('JavaScript errors may have prevented request');
-    }
+  // Add boosts (evidence in favor)
+  if (boosts.length > 0) {
+    explain.push(...boosts);
+  }
   
-    // +10 if absolutely zero network activity (not even unrelated requests)
-    if ((networkSummary.totalRequests || 0) === 0) {
-      points.plus.zeroNetworkActivity = 10;
-      total += 10;
-      reasons.push('Zero network activity despite code promise');
-    }
+  // Add expectation strength note if not proven
+  if (expectationStrength !== 'PROVEN') {
+    explain.push(`Expectation: ${expectationStrength}`);
+  }
   
-    return total;
+  // Remove duplicates while preserving order
+  const seen = new Set();
+  const unique = [];
+  for (const item of explain) {
+    if (!seen.has(item)) {
+      seen.add(item);
+      unique.push(item);
+    }
   }
+  
+  return unique;
+}
 
-  function penalizeMissingNetworkAction({ networkSummary, points, reasons }) {
-    let total = 0;
+/**
+ * Generate confidence explanation for Phase 9: Reality Confidence & Explanation Layer.
+ * Provides whyThisConfidence, whatWouldIncreaseConfidence, whatWouldReduceConfidence.
+ * Phase 3: Also includes boundaryExplanation for near-threshold decisions.
+ */
+function generateConfidenceExplanation({
+  level,
+  score: _score,
+  expectationStrength,
+  sensorsPresent,
+  allSensorsPresent,
+  evidenceSignals: _evidenceSignals,
+  boosts,
+  penalties,
+  attemptMeta,
+  boundaryExplanation = null // Phase 3: Optional boundary reasoning
+}) {
+  const whyThisConfidence = [];
+  const whatWouldIncreaseConfidence = [];
+  const whatWouldReduceConfidence = [];
+  
+  // Phase 3: If near threshold, include boundary reasoning first
+  if (boundaryExplanation) {
+    whyThisConfidence.push(boundaryExplanation);
+  }
   
-    // -15 if there WAS network activity (maybe promise fulfilled differently)
-    if ((networkSummary.totalRequests || 0) > 0) {
-      points.minus.hadNetworkActivity = 15;
-      total += 15;
-      reasons.push('Other network requests occurred (may be fulfilling contract)');
+  // WHY THIS CONFIDENCE: Explain current level
+  if (level === 'HIGH') {
+    whyThisConfidence.push('High confidence: expectation is proven and all sensors captured evidence');
+    if (expectationStrength === 'PROVEN') {
+      whyThisConfidence.push('Expectation is proven from source code');
+    }
+    if (allSensorsPresent) {
+      whyThisConfidence.push('All sensors (network, console, UI) were active');
     }
+    if (boosts.length > 0) {
+      whyThisConfidence.push(`Strong evidence: ${boosts.length} positive signal(s)`);
+    }
+  } else if (level === 'MEDIUM') {
+    whyThisConfidence.push('Medium confidence: some evidence suggests a failure, but uncertainty remains');
+    if (expectationStrength === 'PROVEN') {
+      whyThisConfidence.push('Expectation is proven from source code');
+    } else {
+      whyThisConfidence.push(`Expectation strength: ${expectationStrength} (not proven)`);
+    }
+    if (!allSensorsPresent) {
+      const missing = [];
+      if (!sensorsPresent.network) missing.push('network');
+      if (!sensorsPresent.console) missing.push('console');
+      if (!sensorsPresent.ui) missing.push('UI');
+      whyThisConfidence.push(`Missing sensor data: ${missing.join(', ')}`);
+    }
+    if (penalties.length > 0) {
+      whyThisConfidence.push(`Reducing factors: ${penalties.length} uncertainty signal(s)`);
+    }
+  } else {
+    whyThisConfidence.push('Low confidence: limited evidence or expectation not proven');
+    if (expectationStrength !== 'PROVEN') {
+      whyThisConfidence.push(`Expectation strength: ${expectationStrength} (not proven from code)`);
+    }
+    if (!allSensorsPresent) {
+      whyThisConfidence.push('Some sensors were not active, reducing confidence');
+    }
+    if (attemptMeta && !attemptMeta.repeated) {
+      whyThisConfidence.push('Not repeated (single observation may be unreliable)');
+    }
+  }
   
-    return total;
+  // WHAT WOULD INCREASE CONFIDENCE
+  if (level !== 'HIGH') {
+    if (expectationStrength !== 'PROVEN') {
+      whatWouldIncreaseConfidence.push('Make the expectation proven by adding explicit code that promises the behavior');
+    }
+    if (!allSensorsPresent) {
+      const missing = [];
+      if (!sensorsPresent.network) missing.push('network monitoring');
+      if (!sensorsPresent.console) missing.push('console error detection');
+      if (!sensorsPresent.ui) missing.push('UI change detection');
+      whatWouldIncreaseConfidence.push(`Enable missing sensors: ${missing.join(', ')}`);
+    }
+    if (attemptMeta && !attemptMeta.repeated && level === 'LOW') {
+      whatWouldIncreaseConfidence.push('Repeat the interaction multiple times to confirm consistency');
+    }
+    if (boosts.length === 0) {
+      whatWouldIncreaseConfidence.push('Add stronger evidence signals (network requests, console errors, UI changes)');
+    }
   }
-
-  // === MISSING STATE ACTION SCORING ===
-
-  function scoreMissingStateAction({ expectation, attemptMeta, sensors, comparisons, points, reasons }) {
-    let total = 0;
-
-    // +15 if PROVEN expectation with handlerRef (TS cross-file proof)
-    if (expectation?.proof === 'PROVEN_EXPECTATION' && attemptMeta.handlerRef) {
-      points.plus.provenHandlerRef = 15;
-      total += 15;
-      reasons.push('State mutation proven via TS cross-file analysis');
+  
+  // WHAT WOULD REDUCE CONFIDENCE
+  if (level !== 'LOW') {
+    if (expectationStrength === 'PROVEN') {
+      whatWouldReduceConfidence.push('If expectation becomes unproven (code changes, expectation removed)');
     }
-
-    // +10 if state UI did not change (explicit signal)
-    const stateUI = sensors.stateUI || {};
-    if (stateUI.changed === false) {
-      points.plus.noStateChange = 10;
-      total += 10;
-      reasons.push('State UI signals show no change');
+    if (allSensorsPresent) {
+      whatWouldReduceConfidence.push('If sensors become unavailable or disabled');
     }
-
-    // +5 if DOM did not change (supports missing state mutation theory)
-    if (comparisons.hasDomChange === false) {
-      points.plus.noDomChange = 5;
-      total += 5;
-      reasons.push('DOM unchanged despite promised state mutation');
+    if (boosts.length > 0) {
+      whatWouldReduceConfidence.push('If positive evidence signals disappear (network succeeds, UI feedback appears)');
     }
-
-    return total;
   }
+  if (penalties.length === 0 && level === 'HIGH') {
+    whatWouldReduceConfidence.push('If uncertainty factors appear (URL changes, partial effects, missing data)');
+  }
+  
+  return {
+    whyThisConfidence: whyThisConfidence.length > 0 ? whyThisConfidence : ['Confidence based on available evidence'],
+    whatWouldIncreaseConfidence: whatWouldIncreaseConfidence.length > 0 ? whatWouldIncreaseConfidence : ['Already at maximum confidence for available evidence'],
+    whatWouldReduceConfidence: whatWouldReduceConfidence.length > 0 ? whatWouldReduceConfidence : ['No factors would reduce confidence further']
+  };
+}
 
-  function penalizeMissingStateAction({ sensors, networkSummary, points, reasons }) {
-    let total = 0;
+// ============================================================
+// LEGACY EXPORTS (FOR BACKWARD COMPATIBILITY)
+// ============================================================
 
-    // -10 if there IS network activity (may be causing state change asynchronously)
-    if ((networkSummary.totalRequests || 0) > 0) {
-      points.minus.hadNetworkActivity = 10;
-      total += 10;
-      reasons.push('Network activity may be causing deferred state update');
-    }
+// PHASE 3: Export sensor validation functions for testing
+export { hasNetworkData, hasConsoleData, hasUiData };
 
-    // -10 if UI feedback changed (may indicate state managed differently)
-    const uiSignals = sensors.uiSignals || {};
-    if (uiSignals.changes?.changed === true) {
-      points.minus.hadUIFeedback = 10;
-      total += 10;
-      reasons.push('UI feedback changed (state may be managed via feedback rather than direct mutation)');
-    }
+// Detect error feedback (legacy helper)
+function _detectErrorFeedback(uiSignals) {
+  const before = uiSignals?.before || {};
+  const after = uiSignals?.after || {};
+  return after.hasErrorSignal && !before.hasErrorSignal;
+}
 
-    return total;
-  }
+// Detect loading feedback (legacy helper)
+function _detectLoadingFeedback(uiSignals) {
+  const after = uiSignals?.after || {};
+  return after.hasLoadingIndicator;
+}
+
+// Detect status feedback (legacy helper)
+function _detectStatusFeedback(uiSignals) {
+  const after = uiSignals?.after || {};
+  return after.hasStatusSignal || after.hasLiveRegion || after.hasDialog;
+}