@veraxhq/verax 0.2.1 → 0.3.0

package/src/verax/core/contracts/validators.js

@@ -0,0 +1,381 @@
+/**
+ * VERAX Validators - Runtime contract enforcement
+ * 
+ * Implements the Evidence Law:
+ * "A finding cannot be marked CONFIRMED without sufficient evidence."
+ * 
+ * All validators follow the pattern:
+ * @returns {Object} { ok: boolean, errors: string[], downgrade?: string }
+ * 
+ * If a finding violates contracts, it should be downgraded to SUSPECTED
+ * or dropped from the report if it's critical.
+ */
+
+import {
+  CONFIDENCE_LEVEL,
+  FINDING_STATUS,
+  FINDING_TYPE,
+  IMPACT,
+  USER_RISK,
+  OWNERSHIP,
+  EVIDENCE_TYPE
+} from './types.js';
+
+/**
+ * Validate a Finding object against contracts
+ * 
+ * Evidence Law Enforcement:
+ * - If confidence.level === CONFIRMED, evidence must be substantive
+ * - If evidence is missing or empty, finding cannot be CONFIRMED
+ * - Returns { ok, errors, shouldDowngrade, suggestedStatus }
+ * 
+ * @param {Object} finding - Finding object to validate
+ * @returns {Object} Validation result with enforcement recommendation
+ */
+export function validateFinding(finding) {
+  const errors = [];
+  let shouldDowngrade = false;
+  let suggestedStatus = null;
+
+  // Contract 1: Required top-level fields
+  if (!finding) {
+    return {
+      ok: false,
+      errors: ['Finding is null or undefined'],
+      shouldDowngrade: false
+    };
+  }
+
+  if (!finding.type) {
+    errors.push('Missing required field: type');
+  } else if (!Object.values(FINDING_TYPE).includes(finding.type)) {
+    errors.push(`Invalid type: ${finding.type}. Must be one of: ${Object.values(FINDING_TYPE).join(', ')}`);
+  }
+
+  if (!finding.interaction || typeof finding.interaction !== 'object') {
+    errors.push('Missing or invalid required field: interaction (must be object)');
+  }
+
+  if (!finding.what_happened || typeof finding.what_happened !== 'string') {
+    errors.push('Missing or invalid required field: what_happened (must be non-empty string)');
+  }
+
+  if (!finding.what_was_expected || typeof finding.what_was_expected !== 'string') {
+    errors.push('Missing or invalid required field: what_was_expected (must be non-empty string)');
+  }
+
+  if (!finding.what_was_observed || typeof finding.what_was_observed !== 'string') {
+    errors.push('Missing or invalid required field: what_was_observed (must be non-empty string)');
+  }
+
+  // Contract 2: Evidence validation (CRITICAL for Evidence Law)
+  const evidenceValidation = validateEvidence(finding.evidence);
+  if (!evidenceValidation.ok) {
+    errors.push(`Invalid evidence: ${evidenceValidation.errors.join('; ')}`);
+    shouldDowngrade = true;
+    suggestedStatus = FINDING_STATUS.SUSPECTED;
+  }
+
+  // Contract 3: Confidence validation
+  const confidenceValidation = validateConfidence(finding.confidence);
+  if (!confidenceValidation.ok) {
+    errors.push(`Invalid confidence: ${confidenceValidation.errors.join('; ')}`);
+    shouldDowngrade = true;
+    suggestedStatus = FINDING_STATUS.SUSPECTED;
+  }
+
+  // Contract 4: Signals validation
+  if (!finding.signals || typeof finding.signals !== 'object') {
+    errors.push('Missing or invalid required field: signals (must be object)');
+  } else {
+    const signalsValidation = validateSignals(finding.signals);
+    if (!signalsValidation.ok) {
+      errors.push(`Invalid signals: ${signalsValidation.errors.join('; ')}`);
+    }
+  }
+
+  // *** EVIDENCE LAW ENFORCEMENT ***
+  // PHASE 16: Check evidencePackage completeness for CONFIRMED findings
+  // PHASE 21.1: HARD LOCK - CONFIRMED without complete evidencePackage is IMPOSSIBLE
+  if (finding.status === FINDING_STATUS.CONFIRMED || finding.severity === 'CONFIRMED') {
+    // PHASE 21.1: Strict invariant - CONFIRMED findings MUST have complete evidencePackage
+    if (finding.evidencePackage) {
+      const missingFields = finding.evidencePackage.missingEvidence || [];
+      const isComplete = finding.evidencePackage.isComplete === true;
+      
+      if (!isComplete || missingFields.length > 0) {
+        // PHASE 21.1: HARD FAILURE - do not downgrade, fail validation
+        errors.push(
+          `Evidence Law Violation (CRITICAL): Finding marked CONFIRMED but evidencePackage is incomplete. ` +
+          `Missing fields: ${missingFields.join(', ')}. ` +
+          `evidencePackage.isComplete=${isComplete}. ` +
+          `This finding MUST be dropped, not downgraded.`
+        );
+        // Do not set shouldDowngrade - this is a critical failure that should drop the finding
+        return {
+          ok: false,
+          errors,
+          shouldDowngrade: false, // Fail closed - drop, don't downgrade
+          suggestedStatus: null
+        };
+      }
+    } else if (!isEvidenceSubstantive(finding.evidence)) {
+      // PHASE 21.1: CONFIRMED finding without evidencePackage and without substantive evidence → CRITICAL FAILURE
+      errors.push(
+        `Evidence Law Violation (CRITICAL): Finding marked CONFIRMED but lacks evidencePackage and evidence is insufficient. ` +
+        `This finding MUST be dropped, not downgraded.`
+      );
+      // Do not set shouldDowngrade - this is a critical failure that should drop the finding
+      return {
+        ok: false,
+        errors,
+        shouldDowngrade: false, // Fail closed - drop, don't downgrade
+        suggestedStatus: null
+      };
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    shouldDowngrade,
+    suggestedStatus
+  };
+}
+
+/**
+ * Validate an Evidence object
+ * Evidence is REQUIRED for any CONFIRMED finding.
+ * 
+ * @param {Object} evidence - Evidence object to validate
+ * @returns {Object} { ok: boolean, errors: string[] }
+ */
+export function validateEvidence(evidence) {
+  const errors = [];
+
+  if (!evidence) {
+    errors.push('Evidence object is missing');
+    return { ok: false, errors };
+  }
+
+  if (typeof evidence !== 'object') {
+    errors.push('Evidence must be an object');
+    return { ok: false, errors };
+  }
+
+  // Evidence should contain at least one substantive field
+  const substantiveFields = [
+    'hasDomChange',
+    'hasUrlChange',
+    'hasNetworkActivity',
+    'hasStateChange',
+    'networkRequests',
+    'consoleLogs',
+    'before',
+    'after',
+    'beforeDom',
+    'afterDom'
+  ];
+
+  const hasAtLeastOneField = substantiveFields.some(
+    field => evidence[field] !== undefined && evidence[field] !== null
+  );
+
+  if (!hasAtLeastOneField && !evidence.sensors) {
+    errors.push(
+      'Evidence object is empty. Must contain at least one of: ' +
+      substantiveFields.join(', ') + ', or sensors data'
+    );
+  }
+
+  // Optional: validate specific evidence fields if present
+  if (evidence.type && !Object.values(EVIDENCE_TYPE).includes(evidence.type)) {
+    errors.push(`Invalid evidence type: ${evidence.type}`);
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors
+  };
+}
+
+/**
+ * Validate a Confidence object
+ * 
+ * @param {Object} confidence - Confidence object to validate
+ * @returns {Object} { ok: boolean, errors: string[] }
+ */
+export function validateConfidence(confidence) {
+  const errors = [];
+
+  if (!confidence || typeof confidence !== 'object') {
+    errors.push('Confidence must be a non-empty object');
+    return { ok: false, errors };
+  }
+
+  if (!confidence.level) {
+    errors.push('Missing required field: confidence.level');
+  } else if (!Object.values(CONFIDENCE_LEVEL).includes(confidence.level)) {
+    errors.push(
+      `Invalid confidence level: ${confidence.level}. ` +
+      `Must be one of: ${Object.values(CONFIDENCE_LEVEL).join(', ')}`
+    );
+  }
+
+  if (confidence.score === undefined || confidence.score === null) {
+    errors.push('Missing required field: confidence.score');
+  } else if (typeof confidence.score !== 'number' || confidence.score < 0 || confidence.score > 100) {
+    errors.push(`Invalid confidence.score: ${confidence.score}. Must be a number 0-100`);
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors
+  };
+}
+
+/**
+ * Validate a Signals object
+ * 
+ * @param {Object} signals - Signals object to validate
+ * @returns {Object} { ok: boolean, errors: string[] }
+ */
+export function validateSignals(signals) {
+  const errors = [];
+
+  if (!signals || typeof signals !== 'object') {
+    errors.push('Signals must be a non-empty object');
+    return { ok: false, errors };
+  }
+
+  if (!signals.impact) {
+    errors.push('Missing required field: signals.impact');
+  } else if (!Object.values(IMPACT).includes(signals.impact)) {
+    errors.push(
+      `Invalid impact: ${signals.impact}. ` +
+      `Must be one of: ${Object.values(IMPACT).join(', ')}`
+    );
+  }
+
+  if (!signals.userRisk) {
+    errors.push('Missing required field: signals.userRisk');
+  } else if (!Object.values(USER_RISK).includes(signals.userRisk)) {
+    errors.push(
+      `Invalid userRisk: ${signals.userRisk}. ` +
+      `Must be one of: ${Object.values(USER_RISK).join(', ')}`
+    );
+  }
+
+  if (!signals.ownership) {
+    errors.push('Missing required field: signals.ownership');
+  } else if (!Object.values(OWNERSHIP).includes(signals.ownership)) {
+    errors.push(
+      `Invalid ownership: ${signals.ownership}. ` +
+      `Must be one of: ${Object.values(OWNERSHIP).join(', ')}`
+    );
+  }
+
+  if (!signals.grouping || typeof signals.grouping !== 'object') {
+    errors.push('Missing or invalid required field: signals.grouping (must be object)');
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors
+  };
+}
+
+/**
+ * EVIDENCE LAW: Determine if evidence is sufficient for CONFIRMED status
+ * 
+ * Substantive evidence means:
+ * - At least one positive signal (dom change, url change, network activity, etc.)
+ * - OR concrete sensor data from interaction
+ * - NOT just empty object or missing evidence
+ * 
+ * @param {Object} evidence - Evidence object to evaluate
+ * @returns {boolean} True if evidence is substantive enough for CONFIRMED status
+ */
+export function isEvidenceSubstantive(evidence) {
+  if (!evidence || typeof evidence !== 'object') {
+    return false;
+  }
+
+  // Check for positive signal indicators
+  const hasPositiveSignal = 
+    evidence.hasDomChange === true ||
+    evidence.hasUrlChange === true ||
+    evidence.hasNetworkActivity === true ||
+    evidence.hasStateChange === true ||
+    (Array.isArray(evidence.networkRequests) && evidence.networkRequests.length > 0) ||
+    (Array.isArray(evidence.consoleLogs) && evidence.consoleLogs.length > 0) ||
+    (evidence.before && evidence.after);
+
+  if (hasPositiveSignal) {
+    return true;
+  }
+
+  // Check for sensor data
+  if (evidence.sensors && typeof evidence.sensors === 'object' && Object.keys(evidence.sensors).length > 0) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Enforce contracts on a finding array
+ * 
+ * Returns findings with status downgraded if necessary, filters out
+ * findings that violate critical contracts.
+ * 
+ * @param {Array} findings - Array of findings to validate
+ * @returns {Object} { valid: Array, dropped: Array, downgrades: Array }
+ */
+export function enforceContractsOnFindings(findings) {
+  if (!Array.isArray(findings)) {
+    return { valid: [], dropped: [], downgrades: [] };
+  }
+
+  const valid = [];
+  const dropped = [];
+  const downgrades = [];
+
+  for (const finding of findings) {
+    const validation = validateFinding(finding);
+
+    if (!validation.ok && !validation.shouldDowngrade) {
+      // Critical contract violation - drop
+      dropped.push({
+        finding,
+        reason: validation.errors.join('; ')
+      });
+      continue;
+    }
+
+    if (validation.shouldDowngrade && validation.suggestedStatus) {
+      // Downgrade the finding
+      const downgraded = { ...finding, status: validation.suggestedStatus };
+      downgrades.push({
+        original: finding,
+        downgraded,
+        reason: validation.errors.join('; ')
+      });
+      valid.push(downgraded);
+    } else {
+      // Valid finding
+      valid.push(finding);
+    }
+  }
+
+  return { valid, dropped, downgrades };
+}
+
+export default {
+  validateFinding,
+  validateEvidence,
+  validateConfidence,
+  validateSignals,
+  isEvidenceSubstantive,
+  enforceContractsOnFindings
+};

package/src/verax/core/decision-snapshot.js

@@ -176,9 +176,11 @@ function extractUnverified(detectTruth, observeTruth) {
  * @param {Object} detectTruth - Detect phase truth
  * @param {Object} observeTruth - Observe phase truth
  * @param {Object} _silences - Silence data (unused parameter, kept for API compatibility)
- * @returns {Object} - Decision snapshot answering 6 mandatory questions
+ * @param {Object} options - Additional options { executionMode, executionModeCeiling }
+ * @returns {Object} - Decision snapshot answering 6 mandatory questions + execution mode info
  */
-export function computeDecisionSnapshot(findings, detectTruth, observeTruth, _silences) {
+export function computeDecisionSnapshot(findings, detectTruth, observeTruth, _silences, options = {}) {
+  const { executionMode = null, executionModeCeiling = 1.0 } = options;
   // Question 1: Do we have confirmed SILENT FAILURES?
   const confirmedFailures = findings.filter(f => 
     f.outcome === 'broken' || f.type === 'silent_failure'
@@ -264,10 +266,35 @@ export function computeDecisionSnapshot(findings, detectTruth, observeTruth, _si
       score: confidence.score,
       coverageRatio: confidence.coverageRatio,
       factors: confidence.factors
-    }
+    },
+    
+    // EXECUTION MODE
+    executionMode: executionMode,
+    executionModeCeiling: executionModeCeiling,
+    executionModeExplanation: generateExecutionModeExplanation(executionMode, executionModeCeiling)
   };
 }
 
+/**
+ * Generate explanation for execution mode awareness
+ * @param {string} mode - Execution mode (PROJECT_SCAN or WEB_SCAN_LIMITED)
+ * @param {number} ceiling - Confidence ceiling (0..1)
+ * @returns {string} - Human-readable explanation
+ */
+function generateExecutionModeExplanation(mode, ceiling) {
+  if (!mode) {
+    return null;
+  }
+  
+  if (mode === 'WEB_SCAN_LIMITED') {
+    return `Analysis limited to runtime behavior observation (no source code). Confidence capped at ${Math.round(ceiling * 100)}%. Use source code scanning for fuller analysis.`;
+  } else if (mode === 'PROJECT_SCAN') {
+    return `Full project analysis with source code. Confidence unrestricted based on evidence quality.`;
+  }
+  
+  return null;
+}
+
 /**
  * Format decision snapshot for human reading
  * @param {Object} snapshot - Decision snapshot

package/src/verax/core/decisions/decision.trace.js

@@ -0,0 +1,276 @@
+/**
+ * PHASE 21.10 — Decision Trace
+ * 
+ * Traces why each finding was detected, which signals contributed,
+ * which guardrails applied, and why confidence/status decisions were made.
+ */
+
+import { readFileSync, existsSync, writeFileSync } from 'fs';
+import { resolve } from 'path';
+
+/**
+ * Build decision trace for findings
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run ID
+ * @returns {Object} Decision trace
+ */
+export function buildDecisionTrace(projectDir, runId) {
+  const runDir = resolve(projectDir, '.verax', 'runs', runId);
+  
+  if (!existsSync(runDir)) {
+    return null;
+  }
+  
+  const findingsPath = resolve(runDir, 'findings.json');
+  if (!existsSync(findingsPath)) {
+    return null;
+  }
+  
+  const findings = JSON.parse(readFileSync(findingsPath, 'utf-8'));
+  const traces = [];
+  
+  if (!Array.isArray(findings.findings)) {
+    return {
+      runId,
+      findings: [],
+      summary: { total: 0 },
+      generatedAt: new Date().toISOString()
+    };
+  }
+  
+  for (const finding of findings.findings) {
+    const findingId = finding.findingId || finding.id || `finding-${traces.length}`;
+    
+    // Why detected?
+    const detectionReasons = [];
+    if (finding.type) {
+      detectionReasons.push({
+        code: 'FINDING_TYPE',
+        reason: `Finding type: ${finding.type}`,
+        value: finding.type
+      });
+    }
+    if (finding.outcome) {
+      detectionReasons.push({
+        code: 'OUTCOME_CLASSIFICATION',
+        reason: `Outcome: ${finding.outcome}`,
+        value: finding.outcome
+      });
+    }
+    if (finding.promise?.type) {
+      detectionReasons.push({
+        code: 'PROMISE_TYPE',
+        reason: `Promise type: ${finding.promise.type}`,
+        value: finding.promise.type
+      });
+    }
+    
+    // Which signals contributed?
+    const signals = [];
+    if (finding.evidence?.sensors) {
+      const sensors = finding.evidence.sensors;
+      
+      if (sensors.network) {
+        signals.push({
+          type: 'NETWORK',
+          contributed: sensors.network.totalRequests > 0 || sensors.network.failedRequests > 0,
+          data: {
+            totalRequests: sensors.network.totalRequests || 0,
+            failedRequests: sensors.network.failedRequests || 0
+          }
+        });
+      }
+      
+      if (sensors.console) {
+        signals.push({
+          type: 'CONSOLE',
+          contributed: (sensors.console.errors || 0) > 0 || (sensors.console.warnings || 0) > 0,
+          data: {
+            errors: sensors.console.errors || 0,
+            warnings: sensors.console.warnings || 0
+          }
+        });
+      }
+      
+      if (sensors.uiSignals) {
+        signals.push({
+          type: 'UI_SIGNALS',
+          contributed: sensors.uiSignals.diff?.changed === true,
+          data: {
+            changed: sensors.uiSignals.diff?.changed || false
+          }
+        });
+      }
+    }
+    
+    // Which guardrails applied?
+    const guardrailsApplied = [];
+    if (finding.guardrails?.appliedRules) {
+      for (const rule of finding.guardrails.appliedRules) {
+        guardrailsApplied.push({
+          ruleId: rule.id || rule,
+          category: rule.category || null,
+          action: rule.action || null,
+          matched: rule.matched || true
+        });
+      }
+    }
+    
+    // Why confidence = X?
+    const confidenceReasons = [];
+    if (finding.confidenceLevel) {
+      confidenceReasons.push({
+        code: 'CONFIDENCE_LEVEL',
+        reason: `Confidence level: ${finding.confidenceLevel}`,
+        value: finding.confidenceLevel
+      });
+    }
+    if (finding.confidence !== undefined) {
+      confidenceReasons.push({
+        code: 'CONFIDENCE_SCORE',
+        reason: `Confidence score: ${finding.confidence}`,
+        value: finding.confidence
+      });
+    }
+    if (finding.confidenceReasons && Array.isArray(finding.confidenceReasons)) {
+      for (const reason of finding.confidenceReasons) {
+        confidenceReasons.push({
+          code: 'CONFIDENCE_FACTOR',
+          reason: reason,
+          value: reason
+        });
+      }
+    }
+    
+    // Why status = CONFIRMED / SUSPECTED / DROPPED?
+    const statusReasons = [];
+    const status = finding.severity || finding.status || 'SUSPECTED';
+    
+    statusReasons.push({
+      code: 'STATUS_ASSIGNED',
+      reason: `Status: ${status}`,
+      value: status
+    });
+    
+    if (finding.evidencePackage) {
+      if (finding.evidencePackage.isComplete) {
+        statusReasons.push({
+          code: 'EVIDENCE_COMPLETE',
+          reason: 'Evidence package is complete',
+          value: true
+        });
+      } else {
+        statusReasons.push({
+          code: 'EVIDENCE_INCOMPLETE',
+          reason: 'Evidence package is incomplete',
+          value: false
+        });
+      }
+    }
+    
+    if (finding.guardrails?.finalDecision) {
+      statusReasons.push({
+        code: 'GUARDRAILS_DECISION',
+        reason: `Guardrails decision: ${finding.guardrails.finalDecision}`,
+        value: finding.guardrails.finalDecision
+      });
+    }
+    
+    if (status === 'CONFIRMED' && finding.evidencePackage && !finding.evidencePackage.isComplete) {
+      statusReasons.push({
+        code: 'EVIDENCE_LAW_VIOLATION',
+        reason: 'CONFIRMED finding with incomplete evidence violates Evidence Law',
+        value: 'VIOLATION'
+      });
+    }
+    
+    traces.push({
+      findingId,
+      detection: {
+        why: detectionReasons,
+        signals: signals.filter(s => s.contributed),
+        expectationId: finding.expectationId || null,
+        interactionId: finding.interaction?.selector || null
+      },
+      guardrails: {
+        applied: guardrailsApplied,
+        finalDecision: finding.guardrails?.finalDecision || null,
+        contradictions: finding.guardrails?.contradictions || []
+      },
+      confidence: {
+        level: finding.confidenceLevel || null,
+        score: finding.confidence !== undefined ? finding.confidence : null,
+        why: confidenceReasons
+      },
+      status: {
+        value: status,
+        why: statusReasons
+      },
+      evidence: {
+        packageId: finding.evidencePackage?.id || null,
+        isComplete: finding.evidencePackage?.isComplete || false,
+        files: finding.evidencePackage?.files || []
+      }
+    });
+  }
+  
+  return {
+    runId,
+    findings: traces,
+    summary: {
+      total: traces.length,
+      byStatus: traces.reduce((acc, t) => {
+        const status = t.status.value;
+        acc[status] = (acc[status] || 0) + 1;
+        return acc;
+      }, {}),
+      byConfidence: traces.reduce((acc, t) => {
+        const level = t.confidence.level || 'UNKNOWN';
+        acc[level] = (acc[level] || 0) + 1;
+        return acc;
+      }, {}),
+      withGuardrails: traces.filter(t => t.guardrails.applied.length > 0).length,
+      withCompleteEvidence: traces.filter(t => t.evidence.isComplete).length
+    },
+    generatedAt: new Date().toISOString()
+  };
+}
+
+/**
+ * Write decision trace to file
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run ID
+ * @param {Object} trace - Decision trace
+ * @returns {string} Path to written file
+ */
+export function writeDecisionTrace(projectDir, runId, trace) {
+  const runDir = resolve(projectDir, '.verax', 'runs', runId);
+  const outputPath = resolve(runDir, 'decisions.trace.json');
+  writeFileSync(outputPath, JSON.stringify(trace, null, 2), 'utf-8');
+  return outputPath;
+}
+
+/**
+ * Load decision trace from file
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run ID
+ * @returns {Object|null} Decision trace or null
+ */
+export function loadDecisionTrace(projectDir, runId) {
+  const runDir = resolve(projectDir, '.verax', 'runs', runId);
+  const tracePath = resolve(runDir, 'decisions.trace.json');
+  
+  if (!existsSync(tracePath)) {
+    return null;
+  }
+  
+  try {
+    return JSON.parse(readFileSync(tracePath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+