@veraxhq/verax 0.2.1 → 0.3.0

package/src/verax/observe/interaction-runner.js

@@ -12,6 +12,7 @@ import { FocusSensor } from './focus-sensor.js';
 import { AriaSensor } from './aria-sensor.js';
 import { TimingSensor } from './timing-sensor.js';
 import { HumanBehaviorDriver } from './human-driver.js';
+import { UIFeedbackDetector } from './ui-feedback-detector.js';
 
 // Import CLICK_TIMEOUT_MS from human-driver (re-export needed)
 const CLICK_TIMEOUT_MS = 2000;
@@ -131,6 +132,7 @@ export async function runInteraction(page, interaction, timestamp, i, screenshot
     freezeLikeThresholdMs: 3000
   });
   const humanDriver = new HumanBehaviorDriver({}, scanBudget);
+  const uiFeedbackDetector = new UIFeedbackDetector();
   
   let networkWindowId = null;
   let consoleWindowId = null;
@@ -175,7 +177,11 @@ export async function runInteraction(page, interaction, timestamp, i, screenshot
     }
     trace.page.beforeTitle = beforeTitle;
     
-    uiBefore = await uiSignalSensor.snapshot(page).catch(() => ({}));
+    const interactionTimestamp = timestamp || Date.now();
+    uiBefore = await uiSignalSensor.snapshot(page, interactionTimestamp, null).catch(() => ({}));
+    
+    // UI FEEDBACK INTELLIGENCE: Capture before state for feedback detection
+    await uiFeedbackDetector.captureBefore(page, { targetSelector: interaction.selector });
     
     // A11Y INTELLIGENCE: Capture focus and ARIA state before interaction
     await focusSensor.captureBefore(page);
@@ -228,7 +234,8 @@ export async function runInteraction(page, interaction, timestamp, i, screenshot
       
       const networkSummary = networkSensor.stopWindow(networkWindowId);
       const consoleSummary = consoleSensor.stopWindow(consoleWindowId, page);
-      const uiAfter = await uiSignalSensor.snapshot(page);
+      const interactionTimestamp = timestamp || Date.now();
+      const uiAfter = await uiSignalSensor.snapshot(page, interactionTimestamp, uiBefore);
       const uiDiff = uiSignalSensor.diff(uiBefore, uiAfter);
       
       // STATE INTELLIGENCE: Capture after state and compute diff
@@ -417,7 +424,8 @@ export async function runInteraction(page, interaction, timestamp, i, screenshot
         
         // Record UI change if detected
         if (uiSignalSensor) {
-          const currentUi = await uiSignalSensor.snapshot(page).catch(() => ({}));
+          const interactionTimestamp = timestamp || Date.now();
+          const currentUi = await uiSignalSensor.snapshot(page, interactionTimestamp, uiBefore).catch(() => ({}));
           const currentDiff = uiSignalSensor.diff(uiBefore, currentUi);
           if (currentDiff.changed) {
             timingSensor.recordUiChange();
@@ -473,7 +481,8 @@ export async function runInteraction(page, interaction, timestamp, i, screenshot
           }
         }
         
-        const uiAfter = await uiSignalSensor.snapshot(page).catch(() => ({}));
+        const interactionTimestamp = timestamp || Date.now();
+        const uiAfter = await uiSignalSensor.snapshot(page, interactionTimestamp, uiBefore).catch(() => ({}));
         const uiDiff = uiSignalSensor.diff(uiBefore, uiAfter);
         
         // STATE INTELLIGENCE: Capture after state and compute diff
@@ -597,9 +606,14 @@ export async function runInteraction(page, interaction, timestamp, i, screenshot
       }
     }
     
-    const uiAfter = await uiSignalSensor.snapshot(page);
+    const interactionTimestamp = timestamp || Date.now();
+    const uiAfter = await uiSignalSensor.snapshot(page, interactionTimestamp, uiBefore);
     const uiDiff = uiSignalSensor.diff(uiBefore, uiAfter);
     
+    // UI FEEDBACK INTELLIGENCE: Capture after state and compute feedback signals
+    await uiFeedbackDetector.captureAfter(page);
+    const uiFeedbackSignals = uiFeedbackDetector.computeFeedbackSignals();
+    
     // PERFORMANCE INTELLIGENCE: Record UI change in timing sensor if detected
     if (timingSensor && uiDiff.changed) {
       timingSensor.recordUiChange();
@@ -638,7 +652,8 @@ export async function runInteraction(page, interaction, timestamp, i, screenshot
         available: stateDiff.available,
         changed: stateDiff.changed,
         storeType: storeType
-      }
+      },
+      uiFeedback: uiFeedbackSignals // UI FEEDBACK INTELLIGENCE: Add feedback detection signals
     };
 
     return trace;
@@ -661,7 +676,8 @@ export async function runInteraction(page, interaction, timestamp, i, screenshot
         trace.sensors.console = consoleSensor.getEmptySummary();
       }
       
-      const uiAfter = await uiSignalSensor.snapshot(page).catch(() => ({}));
+      const interactionTimestamp = timestamp || Date.now();
+      const uiAfter = await uiSignalSensor.snapshot(page, interactionTimestamp, uiBefore || {}).catch(() => ({}));
       const uiDiff = uiSignalSensor.diff(uiBefore || {}, uiAfter);
       
       // STATE INTELLIGENCE: Capture after state and compute diff
@@ -717,7 +733,8 @@ export async function runInteraction(page, interaction, timestamp, i, screenshot
       trace.sensors.state = { available: false, changed: [], storeType: null };
     }
 
-    const uiAfter = await uiSignalSensor.snapshot(page).catch(() => ({}));
+    const interactionTimestamp = timestamp || Date.now();
+    const uiAfter = await uiSignalSensor.snapshot(page, interactionTimestamp, uiBefore || {}).catch(() => ({}));
     const uiDiff = uiSignalSensor.diff(uiBefore || {}, uiAfter || {});
     trace.sensors.uiSignals = {
       before: uiBefore || {},

package/src/verax/observe/observe-context.js

@@ -0,0 +1,205 @@
+/**
+ * PHASE 21.3 — Observe Context Contract
+ * 
+ * HARD CONTRACT: Defines the interface between observe-runner and observers
+ * 
+ * RULES:
+ * - Observers MUST only access fields defined in this contract
+ * - Observers MUST NOT import from outside observe/*
+ * - Observers MUST NOT read files
+ * - Observers MUST NOT write artifacts directly
+ * - Observers MUST NOT mutate global state
+ * - Observers MUST propagate all errors (no silent catches)
+ * 
+ * Runtime invariant checks enforce these rules.
+ */
+
+/**
+ * ObserveContext — The context passed to all observers
+ * 
+ * @typedef {Object} ObserveContext
+ * @property {import('playwright').Page} page - Playwright page instance
+ * @property {string} baseOrigin - Base origin for same-origin checks
+ * @property {Object} scanBudget - Scan budget configuration
+ * @property {number} startTime - Start time of the scan (timestamp)
+ * @property {Object} frontier - PageFrontier instance
+ * @property {Object|null} manifest - Manifest object (if available)
+ * @property {Object|null} expectationResults - Expectation execution results
+ * @property {boolean} incrementalMode - Whether incremental mode is enabled
+ * @property {Object|null} oldSnapshot - Previous snapshot (if available)
+ * @property {Object|null} snapshotDiff - Snapshot diff (if available)
+ * @property {string} currentUrl - Current page URL
+ * @property {string} screenshotsDir - Directory for screenshots
+ * @property {number} timestamp - Timestamp for this observation
+ * @property {Object} decisionRecorder - DecisionRecorder instance
+ * @property {Object} silenceTracker - SilenceTracker instance
+ * @property {Object} safetyFlags - Safety flags { allowWrites, allowRiskyActions, allowCrossOrigin }
+ * @property {Object} routeBudget - Route-specific budget (computed)
+ */
+
+/**
+ * RunState — Mutable state passed between observers
+ * 
+ * @typedef {Object} RunState
+ * @property {Array} traces - Array of interaction traces
+ * @property {Array} skippedInteractions - Array of skipped interactions
+ * @property {Array} observedExpectations - Array of observed expectations
+ * @property {number} totalInteractionsDiscovered - Total interactions discovered
+ * @property {number} totalInteractionsExecuted - Total interactions executed
+ * @property {Array} remainingInteractionsGaps - Remaining interaction gaps
+ * @property {boolean} navigatedToNewPage - Whether navigation occurred
+ * @property {string|null} navigatedPageUrl - URL of navigated page (if any)
+ */
+
+/**
+ * Observation — Result returned by an observer
+ * 
+ * @typedef {Object} Observation
+ * @property {string} type - Type of observation (e.g., 'network_idle', 'console_error', 'ui_feedback')
+ * @property {string} scope - Scope of observation (e.g., 'page', 'interaction', 'navigation')
+ * @property {Object} data - Observation data
+ * @property {number} timestamp - Timestamp of observation
+ * @property {string} [url] - URL where observation occurred
+ */
+
+/**
+ * Forbidden imports that observers MUST NOT use
+ */
+const FORBIDDEN_IMPORTS = [
+  'fs',
+  'path',
+  '../core/determinism/report-writer',
+  '../core/scan-summary-writer',
+  './traces-writer',
+  './expectation-executor'
+];
+
+/**
+ * Forbidden context fields that observers MUST NOT access
+ */
+const FORBIDDEN_CONTEXT_FIELDS = [
+  'projectDir',
+  'runId',
+  'writeFileSync',
+  'readFileSync',
+  'mkdirSync'
+];
+
+/**
+ * Validate that an observer result is a valid Observation
+ * 
+ * @param {Object} observation - Observation to validate
+ * @param {string} observerName - Name of observer for error messages
+ * @throws {Error} If observation is invalid
+ */
+export function validateObservation(observation, observerName) {
+  if (!observation) {
+    throw new Error(`${observerName}: Observer returned null/undefined observation`);
+  }
+  
+  if (typeof observation !== 'object') {
+    throw new Error(`${observerName}: Observer returned non-object observation: ${typeof observation}`);
+  }
+  
+  if (!observation.type || typeof observation.type !== 'string') {
+    throw new Error(`${observerName}: Observation missing or invalid 'type' field`);
+  }
+  
+  if (!observation.scope || typeof observation.scope !== 'string') {
+    throw new Error(`${observerName}: Observation missing or invalid 'scope' field`);
+  }
+  
+  if (!observation.data || typeof observation.data !== 'object') {
+    throw new Error(`${observerName}: Observation missing or invalid 'data' field`);
+  }
+  
+  if (typeof observation.timestamp !== 'number') {
+    throw new Error(`${observerName}: Observation missing or invalid 'timestamp' field`);
+  }
+}
+
+/**
+ * Validate that context contains only allowed fields
+ * 
+ * @param {Object} context - Context to validate
+ * @throws {Error} If context contains forbidden fields
+ */
+export function validateContext(context) {
+  for (const field of FORBIDDEN_CONTEXT_FIELDS) {
+    if (field in context) {
+      throw new Error(`ObserveContext contains forbidden field: ${field}. Observers must not access file I/O or project directories.`);
+    }
+  }
+}
+
+/**
+ * Create a safe context for observers (removes forbidden fields)
+ * 
+ * @param {Object} rawContext - Raw context from observe-runner
+ * @returns {ObserveContext} Safe context for observers
+ */
+export function createObserveContext(rawContext) {
+  const {
+    page,
+    baseOrigin,
+    scanBudget,
+    startTime,
+    frontier,
+    manifest,
+    expectationResults,
+    incrementalMode,
+    oldSnapshot,
+    snapshotDiff,
+    currentUrl,
+    screenshotsDir,
+    timestamp,
+    decisionRecorder,
+    silenceTracker,
+    safetyFlags,
+    routeBudget
+  } = rawContext;
+  
+  return {
+    page,
+    baseOrigin,
+    scanBudget,
+    startTime,
+    frontier,
+    manifest,
+    expectationResults,
+    incrementalMode,
+    oldSnapshot,
+    snapshotDiff,
+    currentUrl,
+    screenshotsDir,
+    timestamp,
+    decisionRecorder,
+    silenceTracker,
+    safetyFlags: safetyFlags || { allowWrites: false, allowRiskyActions: false, allowCrossOrigin: false },
+    routeBudget
+  };
+}
+
+/**
+ * Observer execution order (FIXED - must not change)
+ * 
+ * This order is critical for determinism and correctness.
+ */
+export const OBSERVER_ORDER = [
+  'navigation-observer',  // 1. Navigation decisions first
+  'budget-observer',      // 2. Budget checks before interactions
+  'interaction-observer', // 3. Interaction discovery and execution
+  'network-observer',     // 4. Network state observation
+  'ui-feedback-observer', // 5. UI state observation
+  'console-observer',     // 6. Console error observation
+  'coverage-observer'     // 7. Coverage gap tracking
+];
+
+/**
+ * Get observer execution order
+ * 
+ * @returns {Array<string>} Ordered list of observer names
+ */
+export function getObserverOrder() {
+  return [...OBSERVER_ORDER];
+}

package/src/verax/observe/observe-helpers.js

@@ -0,0 +1,191 @@
+/**
+ * PHASE 21.3 — Observe Helpers
+ * 
+ * Helper functions extracted from observe/index.js to keep it slim
+ */
+
+import { resolve } from 'path';
+import { mkdirSync, writeFileSync } from 'fs';
+import { writeTraces } from './traces-writer.js';
+
+/**
+ * Setup manifest and expectations
+ */
+export async function setupManifestAndExpectations(manifestPath, projectDir, page, url, screenshotsDir, scanBudget, startTime, silenceTracker) {
+  const { readFileSync, existsSync } = await import('fs');
+  const { loadPreviousSnapshot, saveSnapshot, buildSnapshot, compareSnapshots } = await import('../core/incremental-store.js');
+  const { executeProvenExpectations } = await import('./expectation-executor.js');
+  const { isProvenExpectation } = await import('../shared/expectation-prover.js');
+  
+  let manifest = null;
+  let expectationResults = null;
+  let expectationCoverageGaps = [];
+  let incrementalMode = false;
+  let snapshotDiff = null;
+  let oldSnapshot = null;
+
+  if (manifestPath && existsSync(manifestPath)) {
+    try {
+      const manifestContent = readFileSync(manifestPath, 'utf-8');
+      manifest = JSON.parse(manifestContent);
+      
+      oldSnapshot = loadPreviousSnapshot(projectDir);
+      if (oldSnapshot) {
+        const currentSnapshot = buildSnapshot(manifest, []);
+        snapshotDiff = compareSnapshots(oldSnapshot, currentSnapshot);
+        incrementalMode = !snapshotDiff.hasChanges;
+      }
+      
+      const provenCount = (manifest.staticExpectations || []).filter(exp => isProvenExpectation(exp)).length;
+      if (provenCount > 0) {
+        expectationResults = await executeProvenExpectations(page, manifest, url, screenshotsDir, scanBudget, startTime, projectDir);
+        expectationCoverageGaps = expectationResults.coverageGaps || [];
+      }
+    } catch (err) {
+      silenceTracker.record({
+        scope: 'discovery',
+        reason: 'discovery_error',
+        description: 'Manifest load or expectation execution failed',
+        context: { error: err?.message },
+        impact: 'incomplete_check'
+      });
+    }
+  }
+
+  return { manifest, expectationResults, expectationCoverageGaps, incrementalMode, snapshotDiff, oldSnapshot };
+}
+
+/**
+ * Process traversal results and build observation
+ */
+export async function processTraversalResults(traversalResult, expectationResults, expectationCoverageGaps, remainingInteractionsGaps, frontier, scanBudget, page, url, finalTraces, finalSkippedInteractions, finalObservedExpectations, silenceTracker, manifest, incrementalMode, snapshotDiff, projectDir, runId) {
+  // Combine all coverage gaps
+  const allCoverageGaps = [...expectationCoverageGaps];
+  if (remainingInteractionsGaps.length > 0) {
+    allCoverageGaps.push(...remainingInteractionsGaps.map(gap => ({
+      expectationId: null,
+      type: gap.interaction.type,
+      reason: gap.reason,
+      fromPath: gap.url,
+      source: null,
+      evidence: { interaction: gap.interaction }
+    })));
+  }
+  
+  if (frontier.frontierCapped) {
+    allCoverageGaps.push({
+      expectationId: null,
+      type: 'navigation',
+      reason: 'frontier_capped',
+      fromPath: page.url(),
+      source: null,
+      evidence: { message: `Frontier capped at ${scanBudget.maxUniqueUrls || 'unlimited'} unique URLs` }
+    });
+  }
+
+  // Build coverage object
+  const coverage = {
+    candidatesDiscovered: traversalResult.totalInteractionsDiscovered,
+    candidatesSelected: traversalResult.totalInteractionsExecuted,
+    cap: scanBudget.maxTotalInteractions,
+    capped: traversalResult.totalInteractionsExecuted >= scanBudget.maxTotalInteractions || remainingInteractionsGaps.length > 0,
+    pagesVisited: frontier.pagesVisited,
+    pagesDiscovered: frontier.pagesDiscovered,
+    skippedInteractions: finalSkippedInteractions.length,
+    interactionsDiscovered: traversalResult.totalInteractionsDiscovered,
+    interactionsExecuted: traversalResult.totalInteractionsExecuted
+  };
+  
+  // Build warnings
+  const observeWarnings = [];
+  if (coverage.capped) {
+    observeWarnings.push({
+      code: 'INTERACTIONS_CAPPED',
+      message: `Interaction execution capped. Visited ${coverage.pagesVisited} pages, discovered ${coverage.pagesDiscovered}, executed ${coverage.candidatesSelected} of ${coverage.candidatesDiscovered} interactions. Coverage incomplete.`
+    });
+  }
+  if (finalSkippedInteractions.length > 0) {
+    observeWarnings.push({
+      code: 'INTERACTIONS_SKIPPED',
+      message: `Skipped ${finalSkippedInteractions.length} dangerous interactions`,
+      details: finalSkippedInteractions
+    });
+  }
+
+  // Append expectation traces
+  if (expectationResults?.results) {
+    for (const result of expectationResults.results) {
+      if (result.trace) {
+        result.trace.expectationDriven = true;
+        result.trace.expectationId = result.expectationId;
+        result.trace.expectationOutcome = result.outcome;
+        finalTraces.push(result.trace);
+      }
+    }
+  }
+
+  // Write traces
+  const observation = writeTraces(projectDir, url, finalTraces, coverage, observeWarnings, finalObservedExpectations, silenceTracker, runId);
+  observation.silences = silenceTracker.getDetailedSummary();
+
+  // Add expectation execution results
+  if (expectationResults) {
+    observation.expectationExecution = {
+      totalProvenExpectations: expectationResults.totalProvenExpectations,
+      executedCount: expectationResults.executedCount,
+      coverageGapsCount: allCoverageGaps.length,
+      results: expectationResults.results.map(r => ({
+        expectationId: r.expectationId,
+        type: r.type,
+        fromPath: r.fromPath,
+        outcome: r.outcome,
+        reason: r.reason
+      }))
+    };
+    observation.expectationCoverageGaps = allCoverageGaps;
+  }
+  
+  // Add incremental mode metadata
+  if (manifest) {
+    const { buildSnapshot, saveSnapshot } = await import('../core/incremental-store.js');
+    const observedInteractions = finalTraces
+      .filter(t => t.interaction && !t.incremental)
+      .map(t => ({
+        type: t.interaction?.type,
+        selector: t.interaction?.selector,
+        url: t.before?.url || url
+      }));
+    
+    const currentSnapshot = buildSnapshot(manifest, observedInteractions);
+    saveSnapshot(projectDir, currentSnapshot, runId);
+    
+    observation.incremental = {
+      enabled: incrementalMode,
+      snapshotDiff: snapshotDiff,
+      skippedInteractionsCount: finalSkippedInteractions.filter(s => s.reason === 'incremental_unchanged').length
+    };
+  }
+
+  return observation;
+}
+
+/**
+ * Write determinism artifacts
+ */
+export async function writeDeterminismArtifacts(projectDir, runId, decisionRecorder) {
+  // PHASE 25: Write determinism contract
+  const { writeDeterminismContract } = await import('../core/determinism/contract-writer.js');
+  const { getRunArtifactDir } = await import('../core/run-id.js');
+  const runDir = getRunArtifactDir(projectDir, runId);
+  writeDeterminismContract(runDir, decisionRecorder);
+  if (!runId || !projectDir) return;
+  
+  const runsDir = resolve(projectDir, '.verax', 'runs', runId);
+  mkdirSync(runsDir, { recursive: true });
+  const decisionsPath = resolve(runsDir, 'decisions.json');
+  writeFileSync(decisionsPath, JSON.stringify(decisionRecorder.export(), null, 2), 'utf-8');
+  
+  const { writeDeterminismReport } = await import('../core/determinism/report-writer.js');
+  writeDeterminismReport(runsDir, decisionRecorder);
+}
+