@veraxhq/verax 0.2.1 → 0.4.0

package/src/verax/observe/network-firewall.js

@@ -0,0 +1,86 @@
+/**
+ * NETWORK SAFETY FIREWALL
+ * 
+ * Handles network request interception and blocking:
+ * - Cross-origin blocking (unless --allow-cross-origin)
+ * - Read-only mode (blocks POST/PUT/PATCH/DELETE unconditionally)
+ * - Safety tracking via SilenceTracker
+ */
+
+/**
+ * Setup network interception firewall for safety mode
+ * 
+ * @param {Object} page - Playwright page object
+ * @param {string} baseOrigin - Base origin URL for cross-origin checks
+ * @param {boolean} allowCrossOrigin - Whether to allow cross-origin requests
+ * @param {Object} silenceTracker - Silence tracker instance
+ * @returns {Promise<{blockedNetworkWrites: Array, blockedCrossOrigin: Array}>}
+ */
+export async function setupNetworkFirewall(page, baseOrigin, allowCrossOrigin, silenceTracker) {
+  const blockedNetworkWrites = [];
+  const blockedCrossOrigin = [];
+
+  await page.route('**/*', (route) => {
+    const request = route.request();
+    const method = request.method();
+    const requestUrl = request.url();
+    const resourceType = request.resourceType();
+    
+    // Check cross-origin blocking (skip for file:// URLs)
+    if (!allowCrossOrigin && !requestUrl.startsWith('file://')) {
+      try {
+        const reqOrigin = new URL(requestUrl).origin;
+        if (reqOrigin !== baseOrigin) {
+          blockedCrossOrigin.push({
+            url: requestUrl,
+            origin: reqOrigin,
+            method,
+            resourceType,
+            timestamp: Date.now()
+          });
+          
+          silenceTracker.record({
+            scope: 'safety',
+            reason: 'cross_origin_blocked',
+            description: `Cross-origin request blocked: ${method} ${requestUrl}`,
+            context: { url: requestUrl, origin: reqOrigin, method, baseOrigin },
+            impact: 'request_blocked'
+          });
+          
+          return route.abort('blockedbyclient');
+        }
+      } catch (e) {
+        // Invalid URL, allow and let browser handle
+      }
+    }
+    
+    // CONSTITUTIONAL: Block all write methods (read-only mode enforced)
+    if (['POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) {
+      // Check if it's a GraphQL mutation (best-effort)
+      const isGraphQLMutation = requestUrl.includes('/graphql') && method === 'POST';
+      
+      blockedNetworkWrites.push({
+        url: requestUrl,
+        method,
+        resourceType,
+        isGraphQLMutation,
+        timestamp: Date.now()
+      });
+      
+      silenceTracker.record({
+        scope: 'safety',
+        reason: 'blocked_network_write',
+        description: `Network write blocked: ${method} ${requestUrl}${isGraphQLMutation ? ' (GraphQL mutation)' : ''}`,
+        context: { url: requestUrl, method, resourceType, isGraphQLMutation },
+        impact: 'write_blocked'
+      });
+      
+      return route.abort('blockedbyclient');
+    }
+    
+    // Allow request
+    route.continue();
+  });
+  
+  return { blockedNetworkWrites, blockedCrossOrigin };
+}

package/src/verax/observe/observation-builder.js

@@ -0,0 +1,169 @@
+/**
+ * OBSERVATION BUILDER
+ * 
+ * Constructs observation object from traces, calculates coverage, and generates warnings.
+ */
+
+/**
+ * Build observation object from collected traces
+ * 
+ * @param {Array} traces - Array of interaction traces
+ * @param {Array} coverage - Coverage information
+ * @param {Array} warnings - Warning messages
+ * @param {Object} safetyStats - Safety mode statistics
+ * @returns {Object}
+ */
+export function buildObservation(traces, coverage, warnings, safetyStats) {
+  const observation = {
+    timestamp: new Date().toISOString(),
+    traces: traces,
+    coverage: coverage || [],
+    warnings: warnings || [],
+    safetyStats: safetyStats || {}
+  };
+
+  return observation;
+}
+
+/**
+ * Calculate coverage gaps from traces
+ * 
+ * @param {Array} traces - Array of interaction traces
+ * @param {Array} discoveredInteractions - All interactions discovered during scan
+ * @returns {Array}
+ */
+export function calculateCoverageGaps(traces, discoveredInteractions) {
+  if (!discoveredInteractions || discoveredInteractions.length === 0) {
+    return [];
+  }
+
+  const executedSelectors = new Set(
+    traces
+      .filter(t => t.interaction && t.interaction.selector)
+      .map(t => t.interaction.selector)
+  );
+
+  const gaps = discoveredInteractions
+    .filter(interaction => !executedSelectors.has(interaction.selector))
+    .map(interaction => ({
+      selector: interaction.selector,
+      type: interaction.type,
+      reason: 'budget_exhausted_or_skipped'
+    }));
+
+  return gaps;
+}
+
+/**
+ * Generate warnings from observation data
+ * 
+ * @param {Object} frontier - Page frontier
+ * @param {Array} coverage - Coverage data
+ * @param {Object} safetyStats - Safety statistics
+ * @returns {Array}
+ */
+export function generateWarnings(frontier, coverage, safetyStats) {
+  const warnings = [];
+
+  // Warn if frontier has unexplored pages
+  if (frontier && frontier.queue && frontier.queue.length > 0) {
+    warnings.push({
+      type: 'unexplored_pages',
+      count: frontier.queue.length,
+      message: `${frontier.queue.length} pages in queue were not explored due to budget constraints`
+    });
+  }
+
+  // Warn if safety mode blocked actions
+  if (safetyStats && safetyStats.blockedNetworkWrites > 0) {
+    warnings.push({
+      type: 'safety_mode_active',
+      blockedWrites: safetyStats.blockedNetworkWrites,
+      message: `Safety mode prevented ${safetyStats.blockedNetworkWrites} write operations`
+    });
+  }
+
+  if (safetyStats && safetyStats.blockedCrossOrigin > 0) {
+    warnings.push({
+      type: 'cross_origin_blocked',
+      count: safetyStats.blockedCrossOrigin,
+      message: `${safetyStats.blockedCrossOrigin} cross-origin requests were blocked`
+    });
+  }
+
+  return warnings;
+}
+
+/**
+ * Build safety statistics object
+ * 
+ * @param {number} blockedNetworkWrites - Number of blocked write operations
+ * @param {number} blockedCrossOrigin - Number of blocked cross-origin requests
+ * @param {Array} skippedInteractions - Interactions that were skipped
+ * @returns {Object}
+ */
+export function buildSafetyStatistics(blockedNetworkWrites, blockedCrossOrigin, skippedInteractions) {
+  return {
+    safetyModeEnabled: true,
+    blockedNetworkWrites: blockedNetworkWrites || 0,
+    blockedCrossOrigin: blockedCrossOrigin || 0,
+    skippedInteractions: skippedInteractions ? skippedInteractions.length : 0,
+    skippedReasons: skippedInteractions ? countSkipReasons(skippedInteractions) : {}
+  };
+}
+
+/**
+ * Count reasons for skipped interactions
+ * 
+ * @param {Array} skippedInteractions - Skipped interactions
+ * @returns {Object}
+ */
+function countSkipReasons(skippedInteractions) {
+  const reasons = {};
+  for (const skip of skippedInteractions) {
+    const reason = skip.reason || 'unknown';
+    reasons[reason] = (reasons[reason] || 0) + 1;
+  }
+  return reasons;
+}
+
+/**
+ * Extract observedExpectations from traces
+ * 
+ * @param {Array} traces - Array of interaction traces
+ * @returns {Array}
+ */
+export function extractObservedExpectations(traces) {
+  const expectations = [];
+  
+  for (const trace of traces) {
+    if (trace.observedExpectation) {
+      expectations.push({
+        ...trace.observedExpectation,
+        traceId: trace.id,
+        executionTimestamp: trace.timestamp
+      });
+    }
+  }
+
+  return expectations;
+}
+
+/**
+ * Build skipped interactions summary
+ * 
+ * @param {Array} interactions - Skipped interactions
+ * @returns {Array}
+ */
+export function buildSkippedInteractionsSummary(interactions) {
+  if (!interactions || interactions.length === 0) {
+    return [];
+  }
+
+  return interactions.map(skip => ({
+    selector: skip.selector,
+    type: skip.type,
+    reason: skip.reason,
+    element: skip.element
+  }));
+}

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,192 @@
+/**
+ * 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: _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');
+  // @ts-expect-error - readFileSync with encoding returns string
+      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);
+}
+