@veraxhq/verax 0.2.1 → 0.4.0

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;
+  });
+}

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

@@ -1,60 +1,156 @@
 import { resolve } from 'path';
 import { mkdirSync, writeFileSync } from 'fs';
 import { CANONICAL_OUTCOMES } from '../core/canonical-outcomes.js';
+import { ARTIFACT_REGISTRY } from '../core/artifacts/registry.js';
 
-/**
- * Write findings to canonical artifact root.
- * Writes to .verax/runs/<runId>/findings.json.
- * 
- * PHASE 2: Includes outcome classification summary.
- * PHASE 3: Includes promise type summary.
- * 
- * @param {string} projectDir
- * @param {string} url
- * @param {Array} findings
- * @param {Array} coverageGaps
- * @param {string} runDirOpt - Required absolute run directory path
- */
-export function writeFindings(projectDir, url, findings, coverageGaps = [], runDirOpt) {
-  if (!runDirOpt) {
-    throw new Error('runDirOpt is required');
-  }
-  mkdirSync(runDirOpt, { recursive: true });
-  const findingsPath = resolve(runDirOpt, 'findings.json');
+const DEFAULT_CLOCK = () => new Date().toISOString();
 
-  // PHASE 2: Compute outcome summary
+// Pure: builds deterministic report object from provided data and timestamp
+export function buildFindingsReport({ url, findings = [], coverageGaps = [], detectedAt }) {
   const outcomeSummary = {};
   Object.values(CANONICAL_OUTCOMES).forEach(outcome => {
     outcomeSummary[outcome] = 0;
   });
-  
-  // PHASE 3: Compute promise summary
+
   const promiseSummary = {};
-  
-  for (const finding of (findings || [])) {
+
+  // Contract enforcement: separate findings into valid, downgradable, and droppable
+  const downgrades = [];
+  const droppedFindingIds = [];
+  const enforcedFindings = [];
+
+  for (const finding of findings) {
+    // Check for critical missing fields (drop these)
+    const hasCriticalNarrativeFields = 
+      finding.what_happened &&
+      finding.what_was_expected &&
+      finding.what_was_observed &&
+      finding.why_it_matters;
+
+    const hasRequiredType = finding.type;
+
+    if (!hasRequiredType || !hasCriticalNarrativeFields) {
+      droppedFindingIds.push(finding.id || 'unknown');
+      continue;
+    }
+
+    // Check for Evidence Law violation (downgrade)
+    if (finding.status === 'CONFIRMED' && (!finding.evidence || Object.keys(finding.evidence).length === 0)) {
+      const downgradedFinding = {
+        ...finding,
+        status: 'SUSPECTED',
+        reason: (finding.reason || '') + ' (Evidence Law enforced - no evidence exists for CONFIRMED status)'
+      };
+      downgrades.push({
+        id: finding.id || 'unknown',
+        originalStatus: 'CONFIRMED',
+        downgradeToStatus: 'SUSPECTED',
+        reason: 'Evidence Law enforced - no evidence exists for CONFIRMED status'
+      });
+      enforcedFindings.push(downgradedFinding);
+    } else {
+      // Valid finding
+      enforcedFindings.push(finding);
+    }
+  }
+
+  // Build outcome and promise summary from enforced findings
+  for (const finding of enforcedFindings) {
     const outcome = finding.outcome || CANONICAL_OUTCOMES.SILENT_FAILURE;
     outcomeSummary[outcome] = (outcomeSummary[outcome] || 0) + 1;
-    
+
     const promiseType = finding.promise?.type || 'UNKNOWN_PROMISE';
     promiseSummary[promiseType] = (promiseSummary[promiseType] || 0) + 1;
   }
 
-  const findingsReport = {
+  // Sort findings deterministically by id
+  const sortedFindings = enforcedFindings.sort((a, b) => (a.id || '').localeCompare(b.id || ''));
+
+  // Production report: exclude enforcement metadata (Trust Lock)
+  return {
     version: 1,
-    detectedAt: new Date().toISOString(),
-    url: url,
-    outcomeSummary: outcomeSummary,  // PHASE 2
-    promiseSummary: promiseSummary,  // PHASE 3
-    findings: findings,
-    coverageGaps: coverageGaps,
+    contractVersion: ARTIFACT_REGISTRY.findings.contractVersion,
+    detectedAt: detectedAt,
+    url,
+    outcomeSummary,  // PHASE 2
+    promiseSummary,  // PHASE 3
+    findings: sortedFindings,
+    coverageGaps,
     notes: []
   };
+}
+
+// Internal helper: builds report with enforcement metadata for disk persistence
+function buildFindingsReportWithEnforcement({ url, findings = [], coverageGaps = [], detectedAt }) {
+  const report = buildFindingsReport({ url, findings, coverageGaps, detectedAt });
+  
+  const downgrades = [];
+  const droppedFindingIds = [];
 
-  writeFileSync(findingsPath, JSON.stringify(findingsReport, null, 2) + '\n');
+  for (const finding of findings) {
+    const hasCriticalNarrativeFields = 
+      finding.what_happened &&
+      finding.what_was_expected &&
+      finding.what_was_observed &&
+      finding.why_it_matters;
+
+    const hasRequiredType = finding.type;
+
+    if (!hasRequiredType || !hasCriticalNarrativeFields) {
+      droppedFindingIds.push(finding.id || 'unknown');
+      continue;
+    }
+
+    if (finding.status === 'CONFIRMED' && (!finding.evidence || Object.keys(finding.evidence).length === 0)) {
+      downgrades.push({
+        id: finding.id || 'unknown',
+        originalStatus: 'CONFIRMED',
+        downgradeToStatus: 'SUSPECTED',
+        reason: 'Evidence Law enforced - no evidence exists for CONFIRMED status'
+      });
+    }
+  }
 
   return {
-    ...findingsReport,
-    findingsPath: findingsPath
+    ...report,
+    enforcement: {
+      evidenceLawEnforced: true,
+      contractVersion: 1,
+      timestamp: detectedAt,
+      droppedCount: droppedFindingIds.length,
+      downgradedCount: downgrades.length,
+      downgrades: downgrades
+    }
   };
 }
 
+// Side-effectful: persists a fully built report to disk
+export function persistFindingsReport(runDir, report) {
+  if (!runDir) {
+    throw new Error('runDirOpt is required');
+  }
+  mkdirSync(runDir, { recursive: true });
+  const findingsPath = resolve(runDir, 'findings.json');
+  writeFileSync(findingsPath, JSON.stringify(report, null, 2) + '\n');
+  return { ...report, findingsPath };
+}
+
+/**
+ * Write findings to canonical artifact root.
+ * Writes to .verax/runs/<runId>/findings.json.
+ *
+ * PHASE 2: Includes outcome classification summary.
+ * PHASE 3: Includes promise type summary.
+ *
+ * @param {string} projectDir
+ * @param {string} url
+ * @param {Array} findings
+ * @param {Array} coverageGaps
+ * @param {string} runDirOpt - Required absolute run directory path
+ */
+export function writeFindings(projectDir, url, findings, coverageGaps = [], runDirOpt) {
+  const detectedAt = DEFAULT_CLOCK();
+  const report = buildFindingsReportWithEnforcement({ url, findings: findings || [], coverageGaps: coverageGaps || [], detectedAt });
+  return persistFindingsReport(runDirOpt, report);
+}
+

package/src/verax/detect/flow-detector.js

@@ -153,7 +153,7 @@ export function detectFlowSilentFailures(traces, manifest, findings, coverageGap
       // Check navigation expectation
       if (expectsNavigation(manifest, interaction, beforeUrl)) {
         const navExp = manifest.staticExpectations?.find(e =>
-          e.type === 'navigation' &&
+          (e.type === 'navigation' || e.type === 'spa_navigation') &&
           isProvenExpectation(e) &&
           e.fromPath && getUrlPath(beforeUrl) &&
           e.fromPath.replace(/\/$/, '') === getUrlPath(beforeUrl).replace(/\/$/, '') &&
@@ -223,7 +223,7 @@ export function detectFlowSilentFailures(traces, manifest, findings, coverageGap
       }
 
       // Also check network expectation even if navigation was matched (for step 2 of flow)
-      if (matchedExpectation && matchedExpectation.type === 'navigation' && manifest.staticExpectations) {
+      if (matchedExpectation && (matchedExpectation.type === 'navigation' || matchedExpectation.type === 'spa_navigation') && manifest.staticExpectations) {
         const networkExp = manifest.staticExpectations.find(e =>
           e.type === 'network_action' &&
           isProvenExpectation(e) &&

package/src/verax/detect/form-silent-failure.js

@@ -0,0 +1,98 @@
+/**
+ * Form Silent Failure Detection
+ * 
+ * Detects form submissions where:
+ * - Form submit handler executes
+ * - Network request completes with 2xx status
+ * - AND no success UI feedback appears (no toast, modal, or DOM change)
+ * - AND no navigation occurs
+ * 
+ * CONFIDENCE: HIGH (network + UI evidence)
+ * Note: Does NOT attempt to parse response content (unsupported)
+ */
+
+import { hasMeaningfulUrlChange, hasDomChange } from './comparison.js';
+import { enrichFindingWithExplanations } from './finding-detector.js';
+
+export function detectFormSilentFailures(traces, manifest, findings) {
+  // Parameters:
+  // traces - array of interaction traces from observation
+  // manifest - project manifest (contains expectations)
+  // findings - array to append new findings to (mutated in-place)
+
+  for (const trace of traces) {
+    const interaction = trace.interaction || {};
+    
+    // Only analyze form interactions
+    if (interaction.type !== 'form' && interaction.category !== 'form') {
+      continue;
+    }
+
+    const beforeUrl = trace.before?.url || trace.beforeUrl || '';
+    const afterUrl = trace.after?.url || trace.afterUrl || '';
+    const sensors = trace.sensors || {};
+    const network = sensors.network || {};
+    const uiSignals = sensors.uiSignals || {};
+    const uiDiff = uiSignals.diff || {};
+    
+    const urlChanged = hasMeaningfulUrlChange(beforeUrl, afterUrl);
+    const domChanged = hasDomChange(trace);
+    const uiChanged = uiDiff.changed === true;
+    
+    // Check for successful network requests (2xx)
+    const successNetworkRequest = (network.requests || []).some(req => {
+      const status = req.status || req.statusCode || 0;
+      return status >= 200 && status < 300;
+    });
+
+    // Detection logic:
+    // Form submitted with successful network response but:
+    // 1. No navigation (URL unchanged)
+    // 2. No DOM change (no new content loaded)
+    // 3. No UI feedback (no toast, modal, highlight, etc.)
+    if (successNetworkRequest && !urlChanged && !domChanged && !uiChanged) {
+      const evidence = {
+        before: trace.before?.screenshot || trace.beforeScreenshot || '',
+        after: trace.after?.screenshot || trace.afterScreenshot || '',
+        beforeUrl,
+        afterUrl,
+        networkRequests: network.requests || [],
+        successRequests: (network.requests || []).filter(r => {
+          const status = r.status || r.statusCode || 0;
+          return status >= 200 && status < 300;
+        }).length,
+        uiChanged,
+        domChanged,
+        urlChanged,
+        reason: 'Form submitted successfully but provided no visual feedback'
+      };
+
+      const finding = {
+        type: 'form_silent_failure',
+        description: `Form submission succeeded with no success feedback to user`,
+        summary: `Form submitted successfully (2xx response) but no UI feedback (no toast, message, or redirect)`,
+        explanation: `The form submission was completed by the server (2xx status code received), but the application provided no visual feedback to the user. The page remained unchanged, with no success message, toast notification, or redirect.`,
+        evidence,
+        confidence: {
+          level: 0.90, // HIGH - network + UI evidence
+          reasons: [
+            'Form submitted and network request returned 2xx (success)',
+            'No UI feedback appeared (no toast, modal, or message)',
+            'No page navigation (user stayed on same page)',
+            'No DOM change (no new content loaded)'
+          ]
+        },
+        promise: {
+          type: 'form_submission',
+          expected: 'Submit form and display success feedback',
+          actual: 'Form submitted successfully but no feedback provided'
+        },
+        capabilityNote: 'Detection based on network status and visual feedback only. Does not parse response body or validate success semantics (UNSUPPORTED).'
+      };
+
+      // Enrich with explanations
+      enrichFindingWithExplanations(finding, trace);
+      findings.push(finding);
+    }
+  }
+}