@veraxhq/verax 0.3.0 → 0.4.0

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

@@ -1,196 +1,156 @@
 import { resolve } from 'path';
 import { mkdirSync, writeFileSync } from 'fs';
 import { CANONICAL_OUTCOMES } from '../core/canonical-outcomes.js';
-import { enforceContractsOnFindings, FINDING_STATUS } from '../core/contracts/index.js';
-import { ARTIFACT_REGISTRY, getArtifactVersions } from '../core/artifacts/registry.js';
-import { buildAndEnforceEvidencePackage, EvidenceBuildError, validateEvidencePackageStrict } from '../core/evidence-builder.js';
-import { writeEvidenceIntentLedger } from '../core/evidence/evidence-intent-ledger.js';
+import { ARTIFACT_REGISTRY } from '../core/artifacts/registry.js';
 
-/**
- * Write findings to canonical artifact root.
- * Writes to .verax/runs/<runId>/findings.json.
- * 
- * PHASE 0 ENFORCEMENT: Applies contracts enforcement
- * - Downgrades findings without evidence from CONFIRMED to SUSPECTED
- * - Drops findings that violate critical contracts
- * 
- * 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
- * @returns {Object} findings report with enforcement metadata
- */
-export function writeFindings(projectDir, url, findings, coverageGaps = [], runDirOpt) {
-  if (!runDirOpt) {
-    throw new Error('runDirOpt is required');
-  }
-  mkdirSync(runDirOpt, { recursive: true });
-  const findingsPath = resolve(runDirOpt, ARTIFACT_REGISTRY.findings.filename);
+const DEFAULT_CLOCK = () => new Date().toISOString();
 
-  // ARCHITECTURAL HARDENING: Evidence capture failures downgrade findings, never drop them
-  // A finding must NEVER disappear. If evidence capture fails, downgrade explicitly.
-  const findingsWithEvidence = [];
-  const evidenceBuildFailures = [];
-  
-  for (const finding of (findings || [])) {
-    // If evidencePackage already exists, validate it strictly for CONFIRMED findings
-    if (finding.evidencePackage) {
-      const severity = finding.severity || finding.status || 'SUSPECTED';
-      if (severity === 'CONFIRMED') {
-        try {
-          validateEvidencePackageStrict(finding.evidencePackage, severity);
-          findingsWithEvidence.push(finding);
-        } catch (error) {
-          // CONFIRMED finding with incomplete evidencePackage → DOWNGRADE to SUSPECTED
-          const downgradedFinding = {
-            ...finding,
-            severity: 'SUSPECTED',
-            status: 'SUSPECTED',
-            evidenceCompleteness: {
-              downgraded: true,
-              reason: `Evidence package incomplete: ${error.message}`,
-              originalSeverity: 'CONFIRMED'
-            }
-          };
-          findingsWithEvidence.push(downgradedFinding);
-          evidenceBuildFailures.push({
-            finding: { type: finding.type || 'unknown', id: finding.findingId || finding.id },
-            reason: `EVIDENCE_VALIDATION_FAILED: ${error.message}`,
-            errorCode: error.code || 'EVIDENCE_VALIDATION_FAILED',
-            action: 'DOWNGRADED'
-          });
-        }
-      } else {
-        findingsWithEvidence.push(finding);
-      }
+// 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;
+  });
+
+  const promiseSummary = {};
+
+  // 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;
     }
-    
-    // Build evidence package from finding data
-    // If building fails → DOWNGRADE finding (never drop)
-    try {
-      const findingWithEvidence = buildAndEnforceEvidencePackage(finding, {
-        expectation: finding.expectation || null,
-        trace: {
-          interaction: finding.interaction || {},
-          before: finding.evidence?.before ? { screenshot: finding.evidence.before, url: finding.evidence.beforeUrl } : null,
-          after: finding.evidence?.after ? { screenshot: finding.evidence.after, url: finding.evidence.afterUrl } : null,
-          sensors: finding.evidence?.sensors || {},
-          dom: finding.evidence?.dom || {},
-        },
-        evidence: finding.evidence || {},
-        confidence: finding.confidenceLevel ? {
-          level: finding.confidenceLevel,
-          score: finding.confidence,
-          reasons: finding.confidenceReasons || [],
-        } : null,
-      });
-      findingsWithEvidence.push(findingWithEvidence);
-    } catch (error) {
-      // Evidence building failure → DOWNGRADE finding (never drop)
-      const originalSeverity = finding.severity || finding.status || 'SUSPECTED';
+
+    // Check for Evidence Law violation (downgrade)
+    if (finding.status === 'CONFIRMED' && (!finding.evidence || Object.keys(finding.evidence).length === 0)) {
       const downgradedFinding = {
         ...finding,
-        severity: 'SUSPECTED',
         status: 'SUSPECTED',
-        evidenceCompleteness: {
-          downgraded: true,
-          reason: `Evidence capture failed: ${error.message}`,
-          originalSeverity: originalSeverity,
-          errorCode: error.code || 'EVIDENCE_BUILD_FAILED',
-          missingFields: error.missingFields || []
-        }
+        reason: (finding.reason || '') + ' (Evidence Law enforced - no evidence exists for CONFIRMED status)'
       };
-      findingsWithEvidence.push(downgradedFinding);
-      
-      if (error instanceof EvidenceBuildError) {
-        evidenceBuildFailures.push({
-          finding: { type: finding.type || 'unknown', id: finding.findingId || finding.id },
-          reason: `EVIDENCE_BUILD_FAILED: ${error.message}`,
-          errorCode: error.code || 'EVIDENCE_BUILD_FAILED',
-          missingFields: error.missingFields || [],
-          action: 'DOWNGRADED'
-        });
-      } else {
-        evidenceBuildFailures.push({
-          finding: { type: finding.type || 'unknown', id: finding.findingId || finding.id },
-          reason: `EVIDENCE_BUILD_FAILED: Unexpected error: ${error.message}`,
-          errorCode: 'EVIDENCE_BUILD_FAILED',
-          action: 'DOWNGRADED'
-        });
-      }
+      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);
     }
   }
-  
-  // PHASE 0: Enforce contracts on all findings (Evidence Law)
-  const { valid: enforcedFindings, dropped, downgrades } = enforceContractsOnFindings(findingsWithEvidence);
-  
-  // ARCHITECTURAL HARDENING: Track evidence build failures separately (they result in downgrades, not drops)
-  // Only contract violations result in drops
-  const allDropped = dropped;
-  
-  // PHASE 2: Compute outcome summary (using enforced findings)
-  const outcomeSummary = {};
-  Object.values(CANONICAL_OUTCOMES).forEach(outcome => {
-    outcomeSummary[outcome] = 0;
-  });
-  
-  // PHASE 3: Compute promise summary
-  const promiseSummary = {};
-  
+
+  // 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,
-    contractVersion: 1,  // Track schema changes from contracts enforcement
-    artifactVersions: getArtifactVersions(),
-    detectedAt: new Date().toISOString(),
-    url: url,
-    outcomeSummary: outcomeSummary,  // PHASE 2
-    promiseSummary: promiseSummary,  // PHASE 3
-    findings: enforcedFindings,
-    coverageGaps: coverageGaps,
-    // PHASE 0: Enforcement metadata
-    // PHASE 21.1: Include evidence build failures in dropped count
-    enforcement: {
-      droppedCount: allDropped.length,
-      downgradedCount: downgrades.length,
-      downgrades: downgrades.map(d => ({
-        reason: d.reason,
-        originalStatus: d.original.status,
-        downgradeToStatus: d.downgraded.status
-      })),
-      evidenceBuildFailures: evidenceBuildFailures.map(f => ({
-        reason: f.reason,
-        errorCode: f.errorCode,
-        findingType: f.finding.type || 'unknown',
-        findingId: f.finding.id || null,
-        missingFields: f.missingFields || [],
-        action: f.action || 'DOWNGRADED'
-      }))
-    },
+    contractVersion: ARTIFACT_REGISTRY.findings.contractVersion,
+    detectedAt: detectedAt,
+    url,
+    outcomeSummary,  // PHASE 2
+    promiseSummary,  // PHASE 3
+    findings: sortedFindings,
+    coverageGaps,
     notes: []
   };
+}
 
-  writeFileSync(findingsPath, JSON.stringify(findingsReport, null, 2) + '\n');
+// 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 = [];
 
-  // PHASE 22: Write evidence intent ledger
-  const evidenceIntentPath = writeEvidenceIntentLedger(runDirOpt, enforcedFindings, captureFailuresMap);
+  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,
-    evidenceIntentPath: evidenceIntentPath
+    ...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);
+    }
+  }
+}