@veraxhq/verax 0.1.0 → 0.2.0

package/src/verax/observe/traces-writer.js

@@ -1,8 +1,36 @@
 import { resolve } from 'path';
 import { writeFileSync, mkdirSync } from 'fs';
-import { appendTrace } from '../shared/artifact-manager.js';
+import { getArtifactPath, getRunArtifactDir } from '../core/run-id.js';
 
-export function writeTraces(projectDir, url, traces, coverage = null, warnings = [], artifactPaths = null) {
+/**
+ * SILENCE TRACKING: Write observation traces with explicit silence tracking.
+ * All gaps, skips, caps, and unknowns must be recorded and surfaced.
+ * 
+ * PHASE 5: Writes to deterministic artifact path .verax/runs/<runId>/traces.json
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} url - URL observed
+ * @param {Array} traces - Execution traces
+ * @param {Object} coverage - Coverage data (if capped, this is a silence)
+ * @param {Array} warnings - Warnings (caps are silences)
+ * @param {Array} observedExpectations - Observed expectations
+ * @param {Object} silenceTracker - Silence tracker (optional)
+ * @param {string} runId - Run identifier (Phase 5)
+ */
+export function writeTraces(projectDir, url, traces, coverage = null, warnings = [], observedExpectations = [], silenceTracker = null, runId = null) {
+  // PHASE 5: Use deterministic artifact path if runId provided, otherwise fall back to old path
+  let observeDir, tracesPath;
+  if (runId) {
+    observeDir = getRunArtifactDir(projectDir, runId);
+    tracesPath = getArtifactPath(projectDir, runId, 'traces.json');
+  } else {
+    // Backwards compatibility for tests
+    observeDir = resolve(projectDir, '.veraxverax', 'observe');
+    tracesPath = resolve(observeDir, 'observation-traces.json');
+  }
+  
+  mkdirSync(observeDir, { recursive: true });
+  
   const observation = {
     version: 1,
     observedAt: new Date().toISOString(),
@@ -10,6 +38,10 @@ export function writeTraces(projectDir, url, traces, coverage = null, warnings =
     traces: traces
   };
 
+  if (observedExpectations && observedExpectations.length > 0) {
+    observation.observedExpectations = observedExpectations;
+  }
+
   if (coverage) {
     observation.coverage = coverage;
   }
@@ -17,23 +49,7 @@ export function writeTraces(projectDir, url, traces, coverage = null, warnings =
     observation.warnings = warnings;
   }
   
-  let tracesPath;
-  if (artifactPaths) {
-    // Use new artifact structure
-    // Write JSONL format (one trace per line) for artifact structure
-    traces.forEach(trace => appendTrace(artifactPaths, trace));
-    
-    // Also write full observation JSON for detect() compatibility
-    const jsonPath = resolve(artifactPaths.evidence, 'observation-traces.json');
-    writeFileSync(jsonPath, JSON.stringify(observation, null, 2) + '\n');
-    tracesPath = jsonPath;
-  } else {
-    // Legacy structure
-    const observeDir = resolve(projectDir, '.veraxverax', 'observe');
-    mkdirSync(observeDir, { recursive: true });
-    tracesPath = resolve(observeDir, 'observation-traces.json');
-    writeFileSync(tracesPath, JSON.stringify(observation, null, 2) + '\n');
-  }
+  writeFileSync(tracesPath, JSON.stringify(observation, null, 2) + '\n');
   
   let externalNavigationBlockedCount = 0;
   let timeoutsCount = 0;
@@ -63,9 +79,29 @@ export function writeTraces(projectDir, url, traces, coverage = null, warnings =
 
   if (coverage) {
     observeTruth.coverage = coverage;
+    // SILENCE TRACKING: Track budget exceeded as silence (cap = unevaluated interactions)
     if (coverage.capped) {
+      observeTruth.budgetExceeded = true;
       if (!warnings || warnings.length === 0) {
-        warnings = [{ code: 'INTERACTIONS_CAPPED', message: 'Interaction discovery reached the cap (30). Scan coverage is incomplete.' }];
+        warnings = [{ code: 'INTERACTIONS_CAPPED', message: `Interaction discovery reached the cap (${coverage.cap}). Scan coverage is incomplete.` }];
+      }
+      
+      // Record budget cap as silence
+      if (silenceTracker) {
+        const unevaluatedCount = (coverage.candidatesDiscovered || 0) - (coverage.candidatesSelected || 0);
+        silenceTracker.record({
+          scope: 'interaction',
+          reason: 'interaction_limit_exceeded',
+          description: `Budget cap reached: ${unevaluatedCount} interactions not evaluated`,
+          context: {
+            cap: coverage.cap,
+            discovered: coverage.candidatesDiscovered,
+            evaluated: coverage.candidatesSelected,
+            unevaluated: unevaluatedCount
+          },
+          impact: 'affects_expectations',
+          count: unevaluatedCount
+        });
       }
     }
   }
@@ -73,6 +109,11 @@ export function writeTraces(projectDir, url, traces, coverage = null, warnings =
     observeTruth.warnings = warnings;
   }
   
+  // SILENCE TRACKING: Attach silence entries to observation for detect phase
+  if (silenceTracker && silenceTracker.entries.length > 0) {
+    observation.silences = silenceTracker.export();
+  }
+  
   return {
     ...observation,
     tracesPath: tracesPath,

package/src/verax/observe/ui-signal-sensor.js

@@ -17,6 +17,7 @@ export class UISignalSensor {
         hasErrorSignal: false,
         hasStatusSignal: false,
         hasLiveRegion: false,
+        validationFeedbackDetected: false,
         disabledElements: [],
         explanation: []
       };
@@ -36,18 +37,22 @@ export class UISignalSensor {
         result.explanation.push('Found [data-loading]');
       }
 
-      // role=status or role=alert with aria-live
-      const statusRegions = document.querySelectorAll('[role="status"], [role="alert"]');
-      if (statusRegions.length > 0) {
+      // role=status or role=alert with aria-live (visible only)
+      const statusRegions = Array.from(document.querySelectorAll('[role="status"], [role="alert"]'));
+      const visibleStatusRegions = statusRegions.filter((el) => {
+        const style = window.getComputedStyle(el);
+        return el.offsetParent !== null && style.visibility !== 'hidden' && style.display !== 'none' && style.opacity !== '0';
+      });
+      if (visibleStatusRegions.length > 0) {
         result.hasStatusSignal = true;
-        result.explanation.push(`Found ${statusRegions.length} status/alert region(s)`);
+        result.explanation.push(`Found ${visibleStatusRegions.length} visible status/alert region(s)`);
       }
 
-      // aria-live region
-      const liveRegions = document.querySelectorAll('[aria-live]');
-      if (liveRegions.length > 0) {
+      // aria-live region (legacy check - will be checked again for visibility below)
+      const allLiveRegions = document.querySelectorAll('[aria-live]');
+      if (allLiveRegions.length > 0) {
         result.hasLiveRegion = true;
-        result.explanation.push(`Found ${liveRegions.length} aria-live region(s)`);
+        result.explanation.push(`Found ${allLiveRegions.length} aria-live region(s)`);
       }
 
       // Check for dialogs
@@ -78,8 +83,89 @@ export class UISignalSensor {
         );
       }
 
-      // Check for error signals: aria-invalid visible elements
-      const invalidElements = document.querySelectorAll('[aria-invalid="true"]');
+      // VALIDATION INTELLIGENCE v1: Detect visible validation feedback
+      // Check for aria-invalid="true" with visible error text nearby
+      const invalidElements = Array.from(document.querySelectorAll('[aria-invalid="true"]'));
+      let hasVisibleValidationError = false;
+      
+      for (const invalidEl of invalidElements) {
+        const style = window.getComputedStyle(invalidEl);
+        const isVisible = invalidEl.offsetParent !== null && 
+                         style.visibility !== 'hidden' && 
+                         style.display !== 'none' && 
+                         style.opacity !== '0';
+        
+        if (isVisible) {
+          // Check for visible error text near this input
+          // Look in parent, next sibling, or aria-describedby target
+          const describedBy = invalidEl.getAttribute('aria-describedby');
+          if (describedBy) {
+            const errorTarget = document.getElementById(describedBy);
+            if (errorTarget) {
+              const targetStyle = window.getComputedStyle(errorTarget);
+              const targetVisible = errorTarget.offsetParent !== null && 
+                                   targetStyle.visibility !== 'hidden' && 
+                                   targetStyle.display !== 'none' && 
+                                   targetStyle.opacity !== '0';
+              if (targetVisible && errorTarget.textContent.trim().length > 0) {
+                hasVisibleValidationError = true;
+                break;
+              }
+            }
+          }
+          
+          // Check parent for error text
+          const parent = invalidEl.parentElement;
+          if (parent) {
+            const errorText = Array.from(parent.querySelectorAll('[role="alert"], .error, .invalid-feedback'))
+              .find(el => {
+                const elStyle = window.getComputedStyle(el);
+                return el.offsetParent !== null && 
+                       elStyle.visibility !== 'hidden' && 
+                       elStyle.display !== 'none' && 
+                       elStyle.opacity !== '0' &&
+                       el.textContent.trim().length > 0;
+              });
+            if (errorText) {
+              hasVisibleValidationError = true;
+              break;
+            }
+          }
+        }
+      }
+      
+      // Check for visible role="alert" or role="status" regions
+      const alertRegions = Array.from(document.querySelectorAll('[role="alert"], [role="status"]'));
+      const visibleAlertRegions = alertRegions.filter((el) => {
+        const style = window.getComputedStyle(el);
+        const isVisible = el.offsetParent !== null && 
+                         style.visibility !== 'hidden' && 
+                         style.display !== 'none' && 
+                         style.opacity !== '0';
+        return isVisible && el.textContent.trim().length > 0;
+      });
+      
+      // Check for visible aria-live regions with content
+      const liveRegions = Array.from(document.querySelectorAll('[aria-live]'));
+      const visibleLiveRegions = liveRegions.filter((el) => {
+        const style = window.getComputedStyle(el);
+        const isVisible = el.offsetParent !== null && 
+                         style.visibility !== 'hidden' && 
+                         style.display !== 'none' && 
+                         style.opacity !== '0';
+        return isVisible && el.textContent.trim().length > 0;
+      });
+      
+      // VALIDATION INTELLIGENCE v1: Set validationFeedbackDetected
+      result.validationFeedbackDetected = hasVisibleValidationError || 
+                                         visibleAlertRegions.length > 0 || 
+                                         visibleLiveRegions.length > 0;
+      
+      if (result.validationFeedbackDetected) {
+        result.explanation.push('Visible validation feedback detected');
+      }
+      
+      // Legacy: Check for error signals
       if (invalidElements.length > 0) {
         result.hasErrorSignal = true;
         result.explanation.push(`Found ${invalidElements.length} invalid element(s)`);
@@ -111,16 +197,30 @@ export class UISignalSensor {
    * Returns: { changed: boolean, explanation: string[], summary: {...} }
    */
   diff(before, after) {
+    const defaults = {
+      hasLoadingIndicator: false,
+      hasDialog: false,
+      hasErrorSignal: false,
+      hasStatusSignal: false,
+      hasLiveRegion: false,
+      disabledElements: [],
+      validationFeedbackDetected: false
+    };
+
+    const safeBefore = { ...defaults, ...(before || {}) };
+    const safeAfter = { ...defaults, ...(after || {}) };
+
     const result = {
       changed: false,
       explanation: [],
       summary: {
-        loadingStateChanged: before.hasLoadingIndicator !== after.hasLoadingIndicator,
-        dialogStateChanged: before.hasDialog !== after.hasDialog,
-        errorSignalChanged: before.hasErrorSignal !== after.hasErrorSignal,
-        statusSignalChanged: before.hasStatusSignal !== after.hasStatusSignal,
-        liveRegionStateChanged: before.hasLiveRegion !== after.hasLiveRegion,
-        disabledButtonsChanged: before.disabledElements.length !== after.disabledElements.length
+        loadingStateChanged: safeBefore.hasLoadingIndicator !== safeAfter.hasLoadingIndicator,
+        dialogStateChanged: safeBefore.hasDialog !== safeAfter.hasDialog,
+        errorSignalChanged: safeBefore.hasErrorSignal !== safeAfter.hasErrorSignal,
+        statusSignalChanged: safeBefore.hasStatusSignal !== safeAfter.hasStatusSignal,
+        liveRegionStateChanged: safeBefore.hasLiveRegion !== safeAfter.hasLiveRegion,
+        disabledButtonsChanged: safeBefore.disabledElements.length !== safeAfter.disabledElements.length,
+        validationFeedbackChanged: safeBefore.validationFeedbackDetected !== safeAfter.validationFeedbackDetected // VALIDATION INTELLIGENCE v1
       }
     };
 
@@ -159,6 +259,14 @@ export class UISignalSensor {
         `Live region: ${before.hasLiveRegion} → ${after.hasLiveRegion}`
       );
     }
+    
+    // Also check if status signal content changed (text added to role=status)
+    if (!result.changed && before.hasStatusSignal && after.hasStatusSignal) {
+      // Both have status signals, but content might have changed
+      // This is a conservative check - if status signal exists and is visible, consider it feedback
+      result.changed = true;
+      result.explanation.push('Status signal content changed');
+    }
 
     if (result.summary.disabledButtonsChanged) {
       result.changed = true;
@@ -167,7 +275,18 @@ export class UISignalSensor {
       );
     }
 
-    return result;
+    // VALIDATION INTELLIGENCE v1: Check for validation feedback changes
+    if (result.summary.validationFeedbackChanged) {
+      result.changed = true;
+      result.explanation.push(
+        `Validation feedback: ${before.validationFeedbackDetected} → ${after.validationFeedbackDetected}`
+      );
+    }
+
+    return {
+      ...result,
+      explanation: result.explanation.join(' | ')
+    };
   }
 
   /**

package/src/verax/scan-summary-writer.js

@@ -1,17 +1,90 @@
 import { resolve } from 'path';
-import { writeFileSync, mkdirSync } from 'fs';
+import { writeFileSync, mkdirSync, readFileSync, existsSync } from 'fs';
+import { computeExpectationsSummary } from './shared/artifact-manager.js';
+import { createImpactSummary } from './core/silence-impact.js';
+import { computeDecisionSnapshot } from './core/decision-snapshot.js';
 
-export function writeScanSummary(projectDir, url, projectType, learnTruth, observeTruth, detectTruth, manifestPath, tracesPath, findingsPath, artifactPaths = null) {
+export function writeScanSummary(projectDir, url, projectType, learnTruth, observeTruth, detectTruth, manifestPath, tracesPath, findingsPath, runDirOpt = null, findingsArray = null) {
+  const scanDir = runDirOpt ? resolve(runDirOpt) : resolve(projectDir, '.veraxverax', 'scan');
+  mkdirSync(scanDir, { recursive: true });
+  
+  // Compute expectations summary from manifest
+  let expectationsSummary = { total: 0, navigation: 0, networkActions: 0, stateActions: 0 };
+  if (manifestPath && existsSync(manifestPath)) {
+    try {
+      const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+      expectationsSummary = computeExpectationsSummary(manifest);
+    } catch (error) {
+      // Ignore errors reading manifest
+    }
+  }
+  
+  // PHASE 4: Compute silence impact summary
+  let silenceImpactSummary = null;
+  if (detectTruth?.silences?.entries) {
+    silenceImpactSummary = createImpactSummary(detectTruth.silences.entries);
+  }
+  
+  // PHASE 6: Compute determinism summary from decisions.json
+  let determinismSummary = null;
+  if (runDirOpt && observeTruth?.runId) {
+    const decisionsPath = resolve(runDirOpt, 'decisions.json');
+    if (existsSync(decisionsPath)) {
+      try {
+        const decisions = JSON.parse(readFileSync(decisionsPath, 'utf-8'));
+        const { DecisionRecorder } = require('./core/determinism-model.js');
+        const recorder = DecisionRecorder.fromExport(decisions);
+        const summary = recorder.getSummary();
+        
+        determinismSummary = {
+          isDeterministic: summary.isDeterministic,
+          totalDecisions: summary.totalDecisions,
+          decisionsByCategory: summary.decisionsByCategory,
+          decisionsPath: decisionsPath
+        };
+      } catch (error) {
+        // Ignore errors reading decisions
+      }
+    }
+  }
+  
+  // PHASE 7: Compute decision snapshot (answers 6 mandatory questions)
+  let decisionSnapshot = null;
+  if (findingsArray && detectTruth && observeTruth) {
+    const silences = detectTruth.silences;
+    decisionSnapshot = computeDecisionSnapshot(findingsArray, detectTruth, observeTruth, silences);
+  }
+  
   const summary = {
     version: 1,
     scannedAt: new Date().toISOString(),
     url: url,
     projectType: projectType,
+    expectationsSummary: expectationsSummary,
+    // PHASE 7: Decision snapshot first (most important for human decision-making)
+    decisionSnapshot: decisionSnapshot,
+    // PHASE 7: Misinterpretation guards (explicit warnings)
+    interpretationGuards: {
+      zeroFindings: 'Zero findings does NOT mean no problems. Check unverified count and confidence level.',
+      deterministicRun: 'Deterministic run does NOT mean correct site. Only means scan was reproducible.',
+      highSilenceImpact: 'High silence impact does NOT mean failures exist. Only means unknowns affect confidence.'
+    },
     truth: {
       learn: learnTruth,
       observe: observeTruth,
       detect: detectTruth
     },
+    // PHASE 4: Add silence lifecycle and impact summary
+    silenceLifecycle: detectTruth?.silences ? {
+      total: detectTruth.silences.total || 0,
+      byType: detectTruth.silences.summary?.byType || {},
+      byEvaluationStatus: detectTruth.silences.summary?.byEvaluationStatus || {},
+      byOutcome: detectTruth.silences.summary?.byOutcome || {},
+      withPromiseAssociation: detectTruth.silences.summary?.withPromiseAssociation || 0,
+      impactSummary: silenceImpactSummary
+    } : null,
+    // PHASE 6: Add determinism summary
+    determinism: determinismSummary,
     paths: {
       manifest: manifestPath,
       traces: tracesPath,
@@ -19,19 +92,8 @@ export function writeScanSummary(projectDir, url, projectType, learnTruth, obser
     }
   };
   
-  let summaryPath;
-  if (artifactPaths) {
-    // Use new artifact structure
-    summaryPath = artifactPaths.summary;
-    // Write the scan summary with truth data
-    writeFileSync(summaryPath, JSON.stringify(summary, null, 2) + '\n');
-  } else {
-    // Legacy structure
-    const scanDir = resolve(projectDir, '.veraxverax', 'scan');
-    mkdirSync(scanDir, { recursive: true });
-    summaryPath = resolve(scanDir, 'scan-summary.json');
-    writeFileSync(summaryPath, JSON.stringify(summary, null, 2) + '\n');
-  }
+  const summaryPath = resolve(scanDir, 'scan-summary.json');
+  writeFileSync(summaryPath, JSON.stringify(summary, null, 2) + '\n');
   
   return {
     ...summary,

package/src/verax/shared/artifact-manager.js

@@ -39,6 +39,7 @@ export function initArtifactPaths(projectRoot, runId = null) {
     runDir,
     summary: resolve(runDir, 'summary.json'),
     findings: resolve(runDir, 'findings.json'),
+    expectations: resolve(runDir, 'expectations.json'),
     traces: resolve(runDir, 'traces.jsonl'),
     evidence: resolve(runDir, 'evidence'),
     flows: resolve(runDir, 'flows'),
@@ -55,23 +56,118 @@ export function initArtifactPaths(projectRoot, runId = null) {
   return paths;
 }
 
+/**
+ * Compute expectations summary from manifest
+ * @param {Object} manifest - Manifest object
+ * @returns {Object} Expectations summary
+ */
+export function computeExpectationsSummary(manifest) {
+  const staticExpectations = manifest.staticExpectations || [];
+  const spaExpectations = manifest.spaExpectations || [];
+  const actionContracts = manifest.actionContracts || [];
+  const proven = (item) => item && item.proof === 'PROVEN_EXPECTATION';
+  
+  // Count by type
+  let navigation = 0;
+  let networkActions = 0;
+  let stateActions = 0;
+  
+  // Static expectations: navigation, form_submission, network_action, state_action
+  for (const exp of staticExpectations) {
+    if (!proven(exp)) continue;
+    if (exp.type === 'navigation' || exp.type === 'spa_navigation') {
+      navigation++;
+    } else if (exp.type === 'form_submission') {
+      networkActions++; // Form submissions are network actions
+    } else if (exp.type === 'network_action') {
+      networkActions++;
+    } else if (exp.type === 'state_action') {
+      stateActions++;
+    }
+  }
+  
+  // SPA expectations: navigation
+  for (const exp of spaExpectations) {
+    if (!proven(exp)) continue;
+    if (exp.type === 'navigation') {
+      navigation++;
+    }
+  }
+  
+  // Action contracts: network and state actions
+  for (const contract of actionContracts) {
+    if (!proven(contract)) continue;
+    if (contract.kind === 'NETWORK_ACTION' || contract.kind === 'network' || contract.kind === 'fetch' || contract.kind === 'axios') {
+      networkActions++;
+    } else if (contract.kind === 'STATE_ACTION' || contract.kind === 'state' || contract.kind === 'redux' || contract.kind === 'zustand') {
+      stateActions++;
+    }
+  }
+  
+  const total = navigation + networkActions + stateActions;
+  
+  return {
+    total,
+    navigation,
+    networkActions,
+    stateActions
+  };
+}
+
 /**
  * Write summary.json with metadata and metrics.
  * @param {Object} paths - Artifact paths from initArtifactPaths
- * @param {Object} summary - Summary data { url, duration, findings, metrics }
+ * @param {Object} summary - Summary data { url, duration, findings, metrics, manifest, contextCheck }
  */
 export function writeSummary(paths, summary) {
+  const expectationsSummary = summary.manifest 
+    ? computeExpectationsSummary(summary.manifest)
+    : { total: 0, navigation: 0, networkActions: 0, stateActions: 0 };
+  
+  const contextCheck = summary.contextCheck || {
+    ran: false,
+    forced: false,
+    matchedRoutesCount: 0,
+    matchedLinksCount: 0,
+    sampleMatched: []
+  };
+  
+  const metrics = summary.metrics || {
+    learnMs: 0,
+    validateMs: 0,
+    observeMs: 0,
+    detectMs: 0,
+    totalMs: 0
+  };
+  
+  const safety = summary.safety || {
+    publicUrlConfirmed: false,
+    usedYesFlag: false
+  };
+  
   const data = {
     runId: paths.runId,
     timestamp: new Date().toISOString(),
     url: summary.url,
     projectRoot: summary.projectRoot,
-    metrics: summary.metrics || {
-      parseMs: 0,
-      resolveMs: 0,
-      observeMs: 0,
-      detectMs: 0,
-      totalMs: 0
+    expectationsSummary: expectationsSummary,
+    contextCheck: {
+      ran: contextCheck.ran,
+      forced: contextCheck.forced || false,
+      matchedRoutesCount: contextCheck.matchedRoutesCount || 0,
+      matchedLinksCount: contextCheck.matchedLinksCount || 0,
+      sampleMatched: (contextCheck.sampleMatched || []).slice(0, 5)
+    },
+    safety: {
+      publicUrlConfirmed: safety.publicUrlConfirmed || false,
+      usedYesFlag: safety.usedYesFlag || false
+    },
+    metrics: {
+      learnMs: metrics.learnMs || 0,
+      validateMs: metrics.validateMs || 0,
+      observeMs: metrics.observeMs || 0,
+      detectMs: metrics.detectMs || 0,
+      totalMs: metrics.totalMs || 0
     },
     findingsCounts: summary.findingsCounts || {
       HIGH: 0,
@@ -80,7 +176,13 @@ export function writeSummary(paths, summary) {
       UNKNOWN: 0
     },
     topFindings: summary.topFindings || [],
-    cacheStats: summary.cacheStats || {}
+    cacheStats: summary.cacheStats || {},
+    progressStats: summary.progressStats || null,
+    interactionStats: summary.interactionStats || null,
+    expectationUsageStats: summary.expectationUsageStats || null,
+    runOverview: summary.runOverview || null,
+    coverage: summary.coverage || null,
+    coverageGaps: summary.coverageGaps || []
   };
 
   writeFileSync(paths.summary, JSON.stringify(data, null, 2) + '\n');