@veraxhq/verax 0.2.1 → 0.4.0

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

@@ -0,0 +1,230 @@
+/**
+ * PHASE 21.3 — Observe Runner
+ * 
+ * Extracted main traversal/interaction loop from observe/index.js
+ * Handles page traversal, interaction discovery, and execution
+ * 
+ * NO file I/O - all artifacts written by caller
+ */
+
+import { navigateToPage, discoverPageLinks, isAlreadyOnPage, markPageVisited } from './observers/navigation-observer.js';
+import { discoverInteractions, checkAndSkipInteraction, executeInteraction } from './observers/interaction-observer.js';
+import { checkBudget } from './observers/budget-observer.js';
+import { createObserveContext } from './observe-context.js';
+
+/**
+ * Run main traversal/interaction loop
+ * 
+ * @param {Object} params - Parameters object
+ * @param {import('playwright').Page} params.page - Playwright page instance
+ * @param {string} params.url - Page URL
+ * @param {string} params.baseOrigin - Base origin for relative URLs
+ * @param {Object} params.scanBudget - Scan budget configuration
+ * @param {number} params.startTime - Scan start time
+ * @param {Object} params.frontier - Page frontier (URL queue)
+ * @param {Object|null} params.manifest - Manifest file data
+ * @param {Object|null} params.expectationResults - Expectation results
+ * @param {boolean} params.incrementalMode - Incremental mode flag
+ * @param {Object|null} params.oldSnapshot - Old snapshot data
+ * @param {Object|null} params.snapshotDiff - Snapshot diff
+ * @param {string} params.currentUrl - Current page URL
+ * @param {string} params.screenshotsDir - Screenshots directory
+ * @param {number} params.timestamp - Current timestamp
+ * @param {Object} params.decisionRecorder - DecisionRecorder instance
+ * @param {Object} params.silenceTracker - SilenceTracker instance
+ * @param {Array} params.traces - Interaction traces array
+ * @param {Array} params.skippedInteractions - Skipped interactions array
+ * @param {Array} params.observedExpectations - Observed expectations array
+ * @param {number} params.totalInteractionsDiscovered - Total discovered interactions
+ * @param {number} params.totalInteractionsExecuted - Total executed interactions
+ * @param {Array} params.remainingInteractionsGaps - Remaining interaction gaps
+ * @param {boolean} [params.allowWrites=false] - Allow file writes
+ * @param {boolean} [params.allowRiskyActions=false] - Allow risky actions
+ * @returns {Promise<Object>} { traces, skippedInteractions, observedExpectations, totalInteractionsDiscovered, totalInteractionsExecuted, remainingInteractionsGaps }
+ */
+export async function runTraversalLoop(params) {
+  const {
+    page,
+    url: _url,
+    baseOrigin,
+    scanBudget,
+    startTime,
+    frontier,
+    manifest,
+    expectationResults,
+    incrementalMode,
+    oldSnapshot,
+    snapshotDiff,
+    currentUrl: _initialCurrentUrl,
+    screenshotsDir,
+    timestamp,
+    decisionRecorder,
+    silenceTracker,
+    traces,
+    skippedInteractions,
+    observedExpectations,
+    totalInteractionsDiscovered: initialTotalInteractionsDiscovered,
+    totalInteractionsExecuted: initialTotalInteractionsExecuted,
+    remainingInteractionsGaps,
+    allowWrites = false,
+    allowRiskyActions = false
+  } = params;
+  
+  let totalInteractionsDiscovered = initialTotalInteractionsDiscovered;
+  let totalInteractionsExecuted = initialTotalInteractionsExecuted;
+  let nextPageUrl = frontier.getNextUrl();
+  
+  // PHASE 21.3: Create observe context once (updated per page)
+  const baseContext = {
+    page,
+    baseOrigin,
+    scanBudget,
+    startTime,
+    frontier,
+    manifest,
+    expectationResults,
+    incrementalMode,
+    oldSnapshot,
+    snapshotDiff,
+    screenshotsDir,
+    timestamp,
+    decisionRecorder,
+    silenceTracker,
+    safetyFlags: { allowWrites, allowRiskyActions },
+    routeBudget: scanBudget // Updated per page
+  };
+  
+  const runState = {
+    traces,
+    skippedInteractions,
+    observedExpectations,
+    totalInteractionsDiscovered,
+    totalInteractionsExecuted,
+    remainingInteractionsGaps,
+    navigatedToNewPage: false,
+    navigatedPageUrl: null
+  };
+
+  while (nextPageUrl && Date.now() - startTime < scanBudget.maxScanDurationMs) {
+    const currentUrl = page.url();
+    const context = createObserveContext({ ...baseContext, currentUrl, routeBudget: baseContext.routeBudget });
+    
+    // PHASE 21.3: Check page limit using budget-observer
+    const pageLimitCheck = checkBudget(context, runState, { 
+      remainingInteractions: 0,
+      currentTotalExecuted: 0,
+      limitType: 'pages' 
+    });
+    if (pageLimitCheck.exceeded) break;
+
+    // Check if we're already on the target page (from navigation via link click)
+    const alreadyOnPageFlag = isAlreadyOnPage({ page, frontier }, nextPageUrl);
+
+    if (!alreadyOnPageFlag) {
+      // Navigate to next page
+      const navigated = await navigateToPage({ page, scanBudget, frontier, silenceTracker }, nextPageUrl);
+      if (!navigated) {
+        nextPageUrl = frontier.getNextUrl();
+        continue;
+      }
+    }
+
+    // Mark as visited and increment counter
+    markPageVisited({ frontier }, nextPageUrl, alreadyOnPageFlag);
+
+    // Discover ALL links on this page and add to frontier BEFORE executing interactions
+    await discoverPageLinks({ page, baseOrigin, frontier, silenceTracker });
+
+    // PHASE 21.3: Discover interactions using interaction-observer
+    const discoveryResult = await discoverInteractions({
+      page,
+      baseOrigin,
+      scanBudget,
+      manifest,
+      currentUrl
+    });
+    const { interactions: sortedInteractions, routeBudget } = discoveryResult;
+    runState.totalInteractionsDiscovered = totalInteractionsDiscovered += discoveryResult.totalDiscovered;
+    baseContext.routeBudget = routeBudget;
+    context.routeBudget = routeBudget;
+
+    // Execute discovered interactions on this page (sorted for determinism)
+    let navigatedToNewPage = false;
+    let navigatedPageUrl = null;
+    let remainingInteractionsStartIndex = 0;
+    let currentTotalInteractionsExecuted = totalInteractionsExecuted;
+
+    for (let i = 0; i < sortedInteractions.length; i++) {
+      // PHASE 21.3: Check budget limits using budget-observer
+      const remaining = sortedInteractions.length - i;
+      const budgetChecks = ['time', 'per_page', 'total'].map(limitType => 
+        checkBudget(context, runState, { limitType, remainingInteractions: remaining, currentTotalExecuted: currentTotalInteractionsExecuted })
+      );
+      if (budgetChecks.find(check => check.exceeded)) {
+        remainingInteractionsStartIndex = i;
+        break;
+      }
+
+      const interaction = sortedInteractions[i];
+      
+      // PHASE 21.3: Check if interaction should be skipped
+      const skipResult = await checkAndSkipInteraction(
+        { page }, interaction, currentUrl, traces, skippedInteractions, silenceTracker,
+        frontier, incrementalMode, manifest, oldSnapshot, snapshotDiff, allowWrites, allowRiskyActions
+      );
+      if (skipResult.skip) continue;
+
+      // PHASE 21.3: Execute interaction
+      const executionResult = await executeInteraction(
+        { page, timestamp, screenshotsDir, routeBudget, silenceTracker },
+        interaction, currentTotalInteractionsExecuted, page.url(),
+        traces, observedExpectations, remainingInteractionsGaps, frontier, baseOrigin,
+        incrementalMode, expectationResults, startTime, scanBudget
+      );
+      
+      // Update counters and handle navigation
+      if (executionResult.trace) currentTotalInteractionsExecuted++;
+      if (executionResult.repeatTrace) currentTotalInteractionsExecuted++;
+      runState.totalInteractionsExecuted = currentTotalInteractionsExecuted;
+      
+      if (executionResult.navigated) {
+        navigatedToNewPage = true;
+        navigatedPageUrl = executionResult.navigatedUrl;
+        runState.navigatedToNewPage = true;
+        runState.navigatedPageUrl = executionResult.navigatedUrl;
+        break;
+      }
+    }
+
+    // Mark remaining interactions as COVERAGE_GAP if we stopped early
+    if (remainingInteractionsStartIndex > 0 && remainingInteractionsStartIndex < sortedInteractions.length && !navigatedToNewPage) {
+      const reason = currentTotalInteractionsExecuted >= scanBudget.maxTotalInteractions ? 'budget_exceeded' : 
+                    (currentTotalInteractionsExecuted >= routeBudget.maxInteractionsPerPage ? 'route_budget_exceeded' : 'budget_exceeded');
+      for (let j = remainingInteractionsStartIndex; j < sortedInteractions.length; j++) {
+        remainingInteractionsGaps.push({
+          interaction: { type: sortedInteractions[j].type, selector: sortedInteractions[j].selector, label: sortedInteractions[j].label },
+          reason, url: currentUrl
+        });
+      }
+    }
+
+    // If we navigated to a new page, stay on it and continue
+    if (navigatedToNewPage && navigatedPageUrl) {
+      nextPageUrl = navigatedPageUrl;
+      continue;
+    }
+    nextPageUrl = frontier.getNextUrl();
+  }
+
+  return {
+    traces: runState.traces,
+    skippedInteractions: runState.skippedInteractions,
+    observedExpectations: runState.observedExpectations,
+    totalInteractionsDiscovered: runState.totalInteractionsDiscovered,
+    totalInteractionsExecuted: runState.totalInteractionsExecuted,
+    remainingInteractionsGaps: runState.remainingInteractionsGaps
+  };
+}
+
+// PHASE 21.3: repeatObservedInteraction moved to interaction-observer.js
+

package/src/verax/observe/observers/budget-observer.js

@@ -0,0 +1,185 @@
+/**
+ * PHASE 21.3 — Budget Observer
+ * 
+ * Responsibilities:
+ * - Budget limit checking
+ * - Truncation decision recording
+ * - Budget-related silence tracking
+ * 
+ * NO file I/O
+ * NO side effects outside its scope
+ */
+
+import { recordTruncation } from '../../core/determinism-model.js';
+
+/**
+ * Check if budget limits are exceeded
+ * 
+ * @param {Object} context - Observe context
+ * @param {Object} runState - Current run state
+ * @param {Object} options - Additional options
+ * @param {number} options.remainingInteractions - Remaining interactions count
+ * @param {number} options.currentTotalExecuted - Current total executed
+ * @param {string} options.limitType - Type of limit to check ('time', 'per_page', 'total', 'pages')
+ * @returns {Object} { exceeded: boolean, reason?: string, observation?: Object }
+ */
+export function checkBudget(context, runState, options) {
+  const { scanBudget, startTime, routeBudget, decisionRecorder, silenceTracker, frontier, page } = context;
+  const { remainingInteractions = 0, currentTotalExecuted = 0, limitType } = options;
+  const now = Date.now();
+  
+  if (limitType === 'time' && now - startTime > scanBudget.maxScanDurationMs) {
+    // PHASE 6: Record truncation decision
+    recordTruncation(decisionRecorder, 'time', {
+      limit: scanBudget.maxScanDurationMs,
+      elapsed: now - startTime
+    });
+    
+    // Mark remaining interactions as COVERAGE_GAP
+    silenceTracker.record({
+      scope: 'interaction',
+      reason: 'scan_time_exceeded',
+      description: `Scan time limit (${scanBudget.maxScanDurationMs}ms) exceeded`,
+      context: { 
+        elapsed: now - startTime,
+        maxDuration: scanBudget.maxScanDurationMs,
+        remainingInteractions
+      },
+      impact: 'blocks_nav',
+      count: remainingInteractions
+    });
+    
+    return {
+      exceeded: true,
+      reason: 'scan_time_exceeded',
+      observation: {
+        type: 'budget_exceeded',
+        scope: 'scan',
+        data: {
+          limitType: 'time',
+          limit: scanBudget.maxScanDurationMs,
+          elapsed: now - startTime,
+          remainingInteractions
+        },
+        timestamp: now,
+        url: page.url()
+      }
+    };
+  }
+  
+  if (limitType === 'per_page' && currentTotalExecuted >= routeBudget.maxInteractionsPerPage) {
+    // PHASE 6: Record truncation decision
+    recordTruncation(decisionRecorder, 'interactions', {
+      limit: routeBudget.maxInteractionsPerPage,
+      reached: currentTotalExecuted,
+      scope: 'per_page'
+    });
+    
+    // Route-specific budget exceeded
+    silenceTracker.record({
+      scope: 'interaction',
+      reason: 'route_interaction_limit_exceeded',
+      description: `Reached max ${routeBudget.maxInteractionsPerPage} interactions per page`,
+      context: {
+        currentPage: page.url(),
+        executed: currentTotalExecuted,
+        maxPerPage: routeBudget.maxInteractionsPerPage,
+        remainingInteractions
+      },
+      impact: 'affects_expectations',
+      count: remainingInteractions
+    });
+    
+    return {
+      exceeded: true,
+      reason: 'route_interaction_limit_exceeded',
+      observation: {
+        type: 'budget_exceeded',
+        scope: 'page',
+        data: {
+          limitType: 'per_page',
+          limit: routeBudget.maxInteractionsPerPage,
+          reached: currentTotalExecuted,
+          remainingInteractions
+        },
+        timestamp: now,
+        url: page.url()
+      }
+    };
+  }
+  
+  if (limitType === 'total' && currentTotalExecuted >= scanBudget.maxTotalInteractions) {
+    // PHASE 6: Record truncation decision
+    recordTruncation(decisionRecorder, 'interactions', {
+      limit: scanBudget.maxTotalInteractions,
+      reached: currentTotalExecuted,
+      scope: 'total'
+    });
+    
+    // Mark remaining interactions as COVERAGE_GAP with reason 'budget_exceeded'
+    silenceTracker.record({
+      scope: 'interaction',
+      reason: 'interaction_limit_exceeded',
+      description: `Reached max ${scanBudget.maxTotalInteractions} total interactions`,
+      context: {
+        executed: currentTotalExecuted,
+        maxTotal: scanBudget.maxTotalInteractions,
+        remainingInteractions
+      },
+      impact: 'blocks_nav',
+      count: remainingInteractions
+    });
+    
+    return {
+      exceeded: true,
+      reason: 'interaction_limit_exceeded',
+      observation: {
+        type: 'budget_exceeded',
+        scope: 'scan',
+        data: {
+          limitType: 'total',
+          limit: scanBudget.maxTotalInteractions,
+          reached: currentTotalExecuted,
+          remainingInteractions
+        },
+        timestamp: now,
+        url: page.url()
+      }
+    };
+  }
+  
+  if (limitType === 'pages' && frontier.isPageLimitExceeded()) {
+    // PHASE 6: Record truncation decision
+    recordTruncation(decisionRecorder, 'pages', {
+      limit: scanBudget.maxPages,
+      reached: frontier.pagesVisited
+    });
+    
+    silenceTracker.record({
+      scope: 'page',
+      reason: 'page_limit_exceeded',
+      description: `Reached maximum of ${scanBudget.maxPages} pages visited`,
+      context: { pagesVisited: frontier.pagesVisited, maxPages: scanBudget.maxPages },
+      impact: 'blocks_nav'
+    });
+    
+    return {
+      exceeded: true,
+      reason: 'page_limit_exceeded',
+      observation: {
+        type: 'budget_exceeded',
+        scope: 'page',
+        data: {
+          limitType: 'pages',
+          limit: scanBudget.maxPages,
+          reached: frontier.pagesVisited
+        },
+        timestamp: now,
+        url: page.url()
+      }
+    };
+  }
+  
+  return { exceeded: false };
+}
+

package/src/verax/observe/observers/console-observer.js

@@ -0,0 +1,102 @@
+/**
+ * PHASE 21.3 — Console Observer
+ * 
+ * Responsibilities:
+ * - Console error / warning capture
+ * - JS runtime error signals
+ * 
+ * NO file I/O
+ * NO side effects outside its scope
+ */
+
+import { ConsoleSensor } from '../console-sensor.js';
+
+/**
+ * Observe console errors and warnings on current page
+ * 
+ * @param {Object} context - Observe context
+ * @param {Object} _runState - Current run state
+ * @returns {Promise<Array<Object>>} Array of console observations
+ */
+export async function observe(context, _runState) {
+  const { page, currentUrl, timestamp, silenceTracker } = context;
+  const observations = [];
+  
+  try {
+    // Create a console sensor to observe current state
+    const consoleSensor = new ConsoleSensor();
+    const windowId = consoleSensor.startWindow(page);
+    
+    // Wait a short time to capture any console messages
+    await page.waitForTimeout(100);
+    
+    // Stop monitoring and get summary
+    const summary = consoleSensor.stopWindow(windowId, page);
+    
+    // Create observation for console state
+    if (summary.hasErrors) {
+      observations.push({
+        type: 'console_errors',
+        scope: 'page',
+        data: {
+          errorCount: summary.errorCount,
+          consoleErrorCount: summary.consoleErrorCount,
+          pageErrorCount: summary.pageErrorCount,
+          unhandledRejectionCount: summary.unhandledRejectionCount,
+          lastErrors: summary.lastErrors
+        },
+        timestamp,
+        url: currentUrl
+      });
+      
+      // Record console errors as silence
+      if (summary.consoleErrorCount > 0) {
+        silenceTracker.record({
+          scope: 'console',
+          reason: 'console_error',
+          description: `Console errors detected on page`,
+          context: {
+            errorCount: summary.consoleErrorCount,
+            pageUrl: currentUrl
+          },
+          impact: 'unknown_behavior',
+          count: summary.consoleErrorCount
+        });
+      }
+      
+      if (summary.pageErrorCount > 0) {
+        silenceTracker.record({
+          scope: 'console',
+          reason: 'page_error',
+          description: `Page errors detected`,
+          context: {
+            errorCount: summary.pageErrorCount,
+            pageUrl: currentUrl
+          },
+          impact: 'unknown_behavior',
+          count: summary.pageErrorCount
+        });
+      }
+      
+      if (summary.unhandledRejectionCount > 0) {
+        silenceTracker.record({
+          scope: 'console',
+          reason: 'unhandled_rejection',
+          description: `Unhandled promise rejections detected`,
+          context: {
+            errorCount: summary.unhandledRejectionCount,
+            pageUrl: currentUrl
+          },
+          impact: 'unknown_behavior',
+          count: summary.unhandledRejectionCount
+        });
+      }
+    }
+  } catch (error) {
+    // Propagate error - no silent catch
+    throw new Error(`Console observer failed: ${error.message}`);
+  }
+  
+  return observations;
+}
+

package/src/verax/observe/observers/coverage-observer.js

@@ -0,0 +1,107 @@
+/**
+ * PHASE 21.3 — Coverage Observer
+ * 
+ * Responsibilities:
+ * - Track coverage gaps
+ * - Build coverage summary
+ * - Track skipped interactions
+ * - NO file I/O
+ * - NO side effects outside its scope
+ */
+
+import { recordTruncation as _recordTruncation } from '../../core/determinism-model.js';
+
+/**
+ * Create coverage gap for remaining interactions
+ * 
+ * @param {Object} context - Observe context
+ * @param {Array} remainingInteractions - Remaining interactions
+ * @param {number} startIndex - Start index of remaining interactions
+ * @param {string} reason - Reason for gap
+ * @returns {Array} Coverage gaps
+ */
+export function createCoverageGaps(context, remainingInteractions, startIndex, reason) {
+  const { currentUrl } = context;
+  const gaps = [];
+  
+  for (let j = startIndex; j < remainingInteractions.length; j++) {
+    gaps.push({
+      interaction: {
+        type: remainingInteractions[j].type,
+        selector: remainingInteractions[j].selector,
+        label: remainingInteractions[j].label
+      },
+      reason: reason,
+      url: currentUrl
+    });
+  }
+  
+  return gaps;
+}
+
+/**
+ * Build coverage summary
+ * 
+ * @param {Object} context - Observe context
+ * @param {number} totalDiscovered - Total interactions discovered
+ * @param {number} totalExecuted - Total interactions executed
+ * @param {number} skippedCount - Number of skipped interactions
+ * @param {Array} remainingGaps - Remaining interaction gaps
+ * @returns {Object} Coverage summary
+ */
+export function buildCoverageSummary(context, totalDiscovered, totalExecuted, skippedCount, remainingGaps) {
+  const { scanBudget, frontier } = context;
+  
+  return {
+    candidatesDiscovered: totalDiscovered,
+    candidatesSelected: totalExecuted,
+    cap: scanBudget.maxTotalInteractions,
+    capped: totalExecuted >= scanBudget.maxTotalInteractions || remainingGaps.length > 0,
+    pagesVisited: frontier.pagesVisited,
+    pagesDiscovered: frontier.pagesDiscovered,
+    skippedInteractions: skippedCount,
+    interactionsDiscovered: totalDiscovered,
+    interactionsExecuted: totalExecuted
+  };
+}
+
+/**
+ * Create coverage gap for frontier capping
+ * 
+ * @param {Object} context - Observe context
+ * @returns {Object} Coverage gap
+ */
+export function createFrontierCappedGap(context) {
+  const { page, scanBudget } = context;
+  
+  return {
+    expectationId: null,
+    type: 'navigation',
+    reason: 'frontier_capped',
+    fromPath: page.url(),
+    source: null,
+    evidence: {
+      message: `Frontier capped at ${scanBudget.maxUniqueUrls || 'unlimited'} unique URLs`
+    }
+  };
+}
+
+/**
+ * Convert remaining interaction gaps to expectation coverage gaps
+ * 
+ * @param {Array} remainingGaps - Remaining interaction gaps
+ * @returns {Array} Expectation coverage gaps
+ */
+export function convertToExpectationCoverageGaps(remainingGaps) {
+  return remainingGaps.map(gap => ({
+    expectationId: null,
+    type: gap.interaction.type,
+    reason: gap.reason,
+    fromPath: gap.url,
+    source: null,
+    evidence: {
+      interaction: gap.interaction
+    }
+  }));
+}
+