@veraxhq/verax 0.2.1 → 0.3.0

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

@@ -0,0 +1,417 @@
+/**
+ * EXPECTATION CHAIN DETECTION
+ * 
+ * Detects silent failures where a sequence of promised user expectations breaks mid-journey.
+ * 
+ * Requirements:
+ * 1) Build expectation chains from source-derived expectations:
+ *    - navigation → content → next action
+ * 2) Track which chain steps were fulfilled vs broken
+ * 3) Emit finding type: "expectation-chain-break"
+ * 4) Include metadata:
+ *    - chainLength
+ *    - fulfilledSteps
+ *    - brokenStepIndex
+ * 5) Confidence rules:
+ *    - Longer chains + late break = higher confidence
+ */
+
+/**
+ * Expectation Chain Detector
+ * 
+ * Analyzes sequences of proven expectations to detect when they break
+ * in a predictable chain pattern.
+ */
+export class ExpectationChainDetector {
+  constructor(options = {}) {
+    this.minChainLength = options.minChainLength || 2; // Minimum 2 for a "chain"
+    this.maxChainLength = options.maxChainLength || 10; // Limit to 10 for analysis
+  }
+
+  /**
+   * Detect expectation chains that break
+   * @param {Array} expectations - Proven expectations from source analysis
+   * @param {Array} traces - Interaction traces from observe phase
+   * @returns {Array} Expectation chain break findings
+   */
+  detectChainBreaks(expectations = [], traces = []) {
+    if (!Array.isArray(expectations) || !Array.isArray(traces)) {
+      return [];
+    }
+
+    const findings = [];
+
+    // Build expectation chains from proven expectations
+    const chains = this._buildChains(expectations);
+
+    // Validate each chain against traces
+    for (const chain of chains) {
+      const chainBreak = this._validateChain(chain, traces);
+      if (chainBreak) {
+        findings.push(chainBreak);
+      }
+    }
+
+    return findings;
+  }
+
+  /**
+   * Build expectation chains from a list of expectations
+   * Chain pattern: navigation → content → interaction
+   * @private
+   */
+  _buildChains(expectations) {
+    const chains = [];
+
+    // Filter to PROVEN expectations only
+    const provenExpectations = expectations.filter(exp => this._isProven(exp));
+
+    if (provenExpectations.length < this.minChainLength) {
+      return chains;
+    }
+
+    // Group expectations by sequence/order
+    const ordered = this._orderExpectationsBySequence(provenExpectations);
+
+    // Build chains from consecutive expectations
+    let currentChain = [];
+    for (let i = 0; i < ordered.length; i++) {
+      const exp = ordered[i];
+
+      // Add to current chain
+      currentChain.push({
+        index: i,
+        expectation: exp,
+        type: this._normalizeExpectationType(exp),
+        sourceRef: exp.sourceRef || exp.filename,
+        lineNumber: exp.lineNumber
+      });
+
+      // Check if chain should end
+      const isLastExp = i === ordered.length - 1;
+      const nextExp = !isLastExp ? ordered[i + 1] : null;
+
+      // Chain ends if:
+      // 1. Gap in expectation sequence (next type is unrelated)
+      // 2. Chain is at max length
+      // 3. We're at the end
+      const shouldBreakChain =
+        currentChain.length >= this.maxChainLength ||
+        isLastExp ||
+        (nextExp && !this._isConsecutiveExpectation(exp, nextExp));
+
+      if (shouldBreakChain && currentChain.length >= this.minChainLength) {
+        chains.push(currentChain);
+        currentChain = [];
+      }
+    }
+
+    return chains;
+  }
+
+  /**
+   * Validate a chain against actual traces
+   * Returns finding if chain breaks (some steps work, later steps fail)
+   * @private
+   */
+  _validateChain(chain, traces) {
+    if (chain.length < this.minChainLength) {
+      return null;
+    }
+
+    let fulfilledSteps = 0;
+    let brokenStepIndex = -1;
+
+    // Check each step in the chain
+    for (let i = 0; i < chain.length; i++) {
+      const step = chain[i];
+      const stepType = step.type;
+
+      // Find matching trace for this step
+      const matchingTrace = traces.find(trace =>
+        this._traceMatchesExpectation(trace, step.expectation)
+      );
+
+      if (!matchingTrace) {
+        // Step not found in traces - chain breaks here
+        brokenStepIndex = i;
+        break;
+      }
+
+      // Check if step expectation was fulfilled
+      const isFulfilled = this._isExpectationFulfilled(
+        step.expectation,
+        matchingTrace
+      );
+
+      if (isFulfilled) {
+        fulfilledSteps++;
+      } else {
+        // Expectation exists but not fulfilled
+        brokenStepIndex = i;
+        break;
+      }
+    }
+
+    // Only emit finding if:
+    // 1. Chain had at least 1 fulfilled step before breaking
+    // 2. Breaking happened (not all steps fulfilled)
+    if (brokenStepIndex > 0 && fulfilledSteps > 0) {
+      return {
+        id: `expectation-chain-break-${Date.now()}-${Math.random()
+          .toString(36)
+          .slice(2, 9)}`,
+        type: 'expectation-chain-break',
+        severity: this._computeSeverity(chain.length, fulfilledSteps, brokenStepIndex),
+        evidence: {
+          chainLength: chain.length,
+          fulfilledSteps,
+          brokenStepIndex,
+          chain: chain.map(step => ({
+            type: step.type,
+            sourceRef: step.sourceRef,
+            lineNumber: step.lineNumber
+          })),
+          brokenStep: chain[brokenStepIndex]
+            ? {
+                type: chain[brokenStepIndex].type,
+                sourceRef: chain[brokenStepIndex].sourceRef,
+                lineNumber: chain[brokenStepIndex].lineNumber
+              }
+            : null,
+          description: this._describeChainBreak(
+            chain,
+            fulfilledSteps,
+            brokenStepIndex
+          )
+        },
+        expectation: {
+          proof: 'PROVEN_EXPECTATION',
+          explicit: true,
+          evidence: {
+            source: 'expectation-chain-analysis',
+            chainAnalysis: true
+          }
+        },
+        actualOutcome: 'expectation_chain_breaks_at_step',
+        impact: 'HIGH'
+      };
+    }
+
+    return null;
+  }
+
+  /**
+   * Check if trace matches expectation
+   * @private
+   */
+  _traceMatchesExpectation(trace, expectation) {
+    if (!trace || !expectation) return false;
+
+    // Match by route if available
+    if (expectation.route && trace.after?.url) {
+      const routePath = expectation.route.replace(/\/$/, '') || '/';
+      const urlPath = this._getUrlPath(trace.after.url);
+      return routePath === urlPath;
+    }
+
+    // Match by type
+    const expType = this._normalizeExpectationType(expectation);
+    if (
+      expType === 'navigation' &&
+      trace.interaction?.type === 'link'
+    ) {
+      return true;
+    }
+
+    if (
+      expType === 'form_submission' &&
+      trace.interaction?.type === 'form'
+    ) {
+      return true;
+    }
+
+    if (expType === 'interaction' && trace.interaction) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Check if expectation was fulfilled in the trace
+   * @private
+   */
+  _isExpectationFulfilled(expectation, trace) {
+    if (!trace) return false;
+
+    const expType = this._normalizeExpectationType(expectation);
+
+    // Navigation expectation: URL must change
+    if (expType === 'navigation') {
+      const urlChanged = trace.sensors?.navigation?.urlChanged === true;
+      const afterUrl = trace.after?.url;
+      return urlChanged && afterUrl !== trace.before?.url;
+    }
+
+    // Content expectation: DOM must change
+    if (expType === 'content') {
+      const domChanged = trace.sensors?.uiSignals?.diff?.domChanged === true;
+      const newContent =
+        trace.sensors?.uiFeedback?.signals?.domChange?.happened === true;
+      return domChanged || newContent;
+    }
+
+    // Interaction expectation: must have been performed
+    if (expType === 'interaction') {
+      const performed = trace.interaction?.performed === true;
+      return performed;
+    }
+
+    // Form submission: must have network request
+    if (expType === 'form_submission') {
+      const hasNetworkRequest = (trace.sensors?.network?.totalRequests || 0) > 0;
+      return hasNetworkRequest;
+    }
+
+    // Default: consider fulfilled if trace exists
+    return true;
+  }
+
+  /**
+   * Check if expectation is PROVEN
+   * @private
+   */
+  _isProven(expectation) {
+    if (!expectation) return false;
+
+    // Explicit from source code analysis
+    if (expectation.explicit === true) return true;
+
+    // Has proof marker
+    if (expectation.proof === 'PROVEN_EXPECTATION') return true;
+
+    // Has sourceRef (AST-derived)
+    if (expectation.sourceRef) return true;
+
+    // Has source evidence
+    if (expectation.evidence?.source) return true;
+
+    return false;
+  }
+
+  /**
+   * Normalize expectation type
+   * @private
+   */
+  _normalizeExpectationType(expectation) {
+    if (!expectation) return 'unknown';
+
+    const type = expectation.type || expectation.expectationType || '';
+
+    if (type.includes('navigation') || type === 'spa_navigation') {
+      return 'navigation';
+    }
+    if (type.includes('content') || type.includes('dom')) {
+      return 'content';
+    }
+    if (type.includes('form') || type === 'form_submission') {
+      return 'form_submission';
+    }
+    if (type.includes('interaction') || type.includes('action')) {
+      return 'interaction';
+    }
+
+    return type || 'unknown';
+  }
+
+  /**
+   * Order expectations by sequence (chain order)
+   * @private
+   */
+  _orderExpectationsBySequence(expectations) {
+    // If expectations have explicit order/lineNumber, use that
+    const withOrder = expectations.filter(exp => exp.lineNumber !== undefined);
+    if (withOrder.length > 0) {
+      return withOrder.sort((a, b) => a.lineNumber - b.lineNumber);
+    }
+
+    // Otherwise return in given order
+    return expectations;
+  }
+
+  /**
+   * Check if two expectations are consecutive in chain
+   * @private
+   */
+  _isConsecutiveExpectation(currentExp, nextExp) {
+    if (!currentExp || !nextExp) return false;
+
+    const currentType = this._normalizeExpectationType(currentExp);
+    const nextType = this._normalizeExpectationType(nextExp);
+
+    // Valid chain progressions:
+    // navigation → content, interaction, form_submission
+    // content → interaction, form_submission
+    // form_submission → content, navigation
+    // interaction → content, form_submission, navigation
+
+    const validProgressions = {
+      navigation: ['content', 'interaction', 'form_submission'],
+      content: ['interaction', 'form_submission', 'navigation'],
+      form_submission: ['content', 'navigation', 'interaction'],
+      interaction: ['content', 'form_submission', 'navigation']
+    };
+
+    const validNext = validProgressions[currentType] || [];
+    return validNext.includes(nextType);
+  }
+
+  /**
+   * Compute severity based on chain depth and break position
+   * @private
+   */
+  _computeSeverity(chainLength, fulfilledSteps, brokenStepIndex) {
+    // Late breaks (deeper in chain) are higher severity
+    const breakDepth = brokenStepIndex / chainLength;
+
+    if (breakDepth >= 0.7) {
+      return 'CRITICAL'; // Broke in final 30%
+    }
+    if (breakDepth >= 0.5) {
+      return 'HIGH'; // Broke in second half
+    }
+    if (breakDepth >= 0.3) {
+      return 'MEDIUM'; // Broke in second third
+    }
+    return 'LOW'; // Early break
+  }
+
+  /**
+   * Generate description of chain break
+   * @private
+   */
+  _describeChainBreak(chain, fulfilledSteps, brokenStepIndex) {
+    const chainTypes = chain.map(s => s.type).join(' → ');
+    const brokenType = chain[brokenStepIndex]?.type || 'unknown';
+
+    return `Expectation chain broke at step ${brokenStepIndex + 1}/${
+      chain.length
+    }: ${chainTypes}. Successfully completed ${fulfilledSteps} step(s) before ${brokenType} failed.`;
+  }
+
+  /**
+   * Extract URL path from full URL
+   * @private
+   */
+  _getUrlPath(url) {
+    if (!url) return '';
+    try {
+      return new URL(url).pathname;
+    } catch {
+      return url;
+    }
+  }
+}
+
+export default ExpectationChainDetector;

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

@@ -256,9 +256,11 @@ 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: 'PROVEN_EXPECTATION',
+            proof,
             expectationType,
             method: contract.method,
             urlPath: contract.urlPath,

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

@@ -1,11 +1,19 @@
 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';
 
 /**
  * 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.
  * 
@@ -14,15 +22,118 @@ import { CANONICAL_OUTCOMES } from '../core/canonical-outcomes.js';
  * @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, 'findings.json');
+  const findingsPath = resolve(runDirOpt, ARTIFACT_REGISTRY.findings.filename);
 
-  // PHASE 2: Compute outcome summary
+  // 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);
+      }
+      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';
+      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 || []
+        }
+      };
+      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'
+        });
+      }
+    }
+  }
+  
+  // 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;
@@ -31,7 +142,7 @@ export function writeFindings(projectDir, url, findings, coverageGaps = [], runD
   // PHASE 3: Compute promise summary
   const promiseSummary = {};
   
-  for (const finding of (findings || [])) {
+  for (const finding of enforcedFindings) {
     const outcome = finding.outcome || CANONICAL_OUTCOMES.SILENT_FAILURE;
     outcomeSummary[outcome] = (outcomeSummary[outcome] || 0) + 1;
     
@@ -41,20 +152,45 @@ export function writeFindings(projectDir, url, findings, coverageGaps = [], runD
 
   const findingsReport = {
     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: findings,
+    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'
+      }))
+    },
     notes: []
   };
 
   writeFileSync(findingsPath, JSON.stringify(findingsReport, null, 2) + '\n');
 
+  // PHASE 22: Write evidence intent ledger
+  const evidenceIntentPath = writeEvidenceIntentLedger(runDirOpt, enforcedFindings, captureFailuresMap);
+
   return {
     ...findingsReport,
-    findingsPath: findingsPath
+    findingsPath: findingsPath,
+    evidenceIntentPath: evidenceIntentPath
   };
 }