@veraxhq/verax 0.1.0 → 0.2.1

package/src/verax/core/determinism-model.js

@@ -0,0 +1,432 @@
+/**
+ * DETERMINISM MODEL — PHASE 6
+ * 
+ * Records all adaptive/variable decisions made during a VERAX run.
+ * Makes implicit choices explicit and enables replay trust validation.
+ * 
+ * PRINCIPLES:
+ * 1. Every decision that varies by environment/timing/budget is recorded
+ * 2. Decisions are factual: what was chosen, what inputs were considered
+ * 3. No heuristics, no guessing — only recording reality
+ * 4. Replay can verify same decisions or explain deviations
+ * 
+ * DECISION CATEGORIES:
+ * - BUDGET: Limits chosen (time, interactions, pages)
+ * - TIMEOUT: Timing windows (navigation, settle, stabilization)
+ * - RETRY: Retry attempts and backoff
+ * - ADAPTIVE_STABILIZATION: Dynamic settle extensions
+ * - TRUNCATION: Early termination due to budget
+ * - ENVIRONMENT: Browser, OS, network-dependent behavior
+ */
+
+/**
+ * @typedef {Object} AdaptiveDecision
+ * @property {string} decision_id - Unique ID: <category>_<specific_id>
+ * @property {string} category - BUDGET | TIMEOUT | RETRY | ADAPTIVE_STABILIZATION | TRUNCATION | ENVIRONMENT
+ * @property {number} timestamp - When decision was made (ms since epoch)
+ * @property {Object} inputs - What was considered (environment, state, triggers)
+ * @property {*} chosen_value - What was chosen
+ * @property {string} reason - Technical, factual explanation
+ * @property {string} [context] - Additional context (page URL, interaction ID, etc.)
+ */
+
+/**
+ * Decision IDs — Enumeration of all adaptive decision points
+ */
+export const DECISION_IDS = {
+  // Budget decisions
+  BUDGET_PROFILE_SELECTED: 'BUDGET_profile_selected',
+  BUDGET_MAX_INTERACTIONS: 'BUDGET_max_interactions',
+  BUDGET_MAX_PAGES: 'BUDGET_max_pages',
+  BUDGET_SCAN_DURATION: 'BUDGET_scan_duration_ms',
+  BUDGET_MAX_FLOWS: 'BUDGET_max_flows',
+  
+  // Timeout decisions
+  TIMEOUT_NAVIGATION: 'TIMEOUT_navigation_ms',
+  TIMEOUT_INTERACTION: 'TIMEOUT_interaction_ms',
+  TIMEOUT_SETTLE: 'TIMEOUT_settle_ms',
+  TIMEOUT_STABILIZATION: 'TIMEOUT_stabilization_window_ms',
+  
+  // Adaptive stabilization decisions
+  ADAPTIVE_STABILIZATION_ENABLED: 'ADAPTIVE_STABILIZATION_enabled',
+  ADAPTIVE_STABILIZATION_EXTENDED: 'ADAPTIVE_STABILIZATION_extended',
+  
+  // Retry decisions
+  RETRY_NAVIGATION_ATTEMPTED: 'RETRY_navigation_attempted',
+  RETRY_INTERACTION_ATTEMPTED: 'RETRY_interaction_attempted',
+  RETRY_BACKOFF_DELAY: 'RETRY_backoff_delay_ms',
+  
+  // Truncation decisions
+  TRUNCATION_BUDGET_EXCEEDED: 'TRUNCATION_budget_exceeded',
+  TRUNCATION_INTERACTIONS_CAPPED: 'TRUNCATION_interactions_capped',
+  TRUNCATION_PAGES_CAPPED: 'TRUNCATION_pages_capped',
+  TRUNCATION_SCAN_TIME_EXCEEDED: 'TRUNCATION_scan_time_exceeded',
+  
+  // Environment decisions
+  ENV_BROWSER_DETECTED: 'ENV_browser_detected',
+  ENV_NETWORK_SPEED: 'ENV_network_speed_class',
+  ENV_VIEWPORT_SIZE: 'ENV_viewport_size'
+};
+
+/**
+ * DecisionRecorder — Captures all adaptive decisions during a run
+ */
+export class DecisionRecorder {
+  constructor(runId = null) {
+    this.runId = runId;
+    this.decisions = [];
+    this.decisionIndex = {}; // decision_id -> decision for quick lookup
+  }
+
+  /**
+   * Record a single adaptive decision
+   * @param {AdaptiveDecision} decision
+   */
+  record(decision) {
+    if (!decision.decision_id || !decision.category) {
+      throw new Error(`Invalid decision: missing decision_id or category. Got: ${JSON.stringify(decision)}`);
+    }
+    
+    // Add timestamp if not provided
+    if (!decision.timestamp) {
+      decision.timestamp = Date.now();
+    }
+    
+    this.decisions.push(decision);
+    
+    // Index by decision_id for replay lookup
+    this.decisionIndex[decision.decision_id] = decision;
+  }
+
+  /**
+   * Record batch of decisions
+   * @param {AdaptiveDecision[]} decisions
+   */
+  recordBatch(decisions) {
+    decisions.forEach(d => this.record(d));
+  }
+
+  /**
+   * Get all recorded decisions
+   * @returns {AdaptiveDecision[]}
+   */
+  getAll() {
+    return this.decisions;
+  }
+
+  /**
+   * Get decisions by category
+   * @param {string} category
+   * @returns {AdaptiveDecision[]}
+   */
+  getByCategory(category) {
+    return this.decisions.filter(d => d.category === category);
+  }
+
+  /**
+   * Get decision by ID (most recent if multiple)
+   * @param {string} decisionId
+   * @returns {AdaptiveDecision|null}
+   */
+  getById(decisionId) {
+    return this.decisionIndex[decisionId] || null;
+  }
+
+  /**
+   * Get summary statistics
+   * @returns {Object}
+   */
+  getSummary() {
+    const byCategory = {};
+    const categories = ['BUDGET', 'TIMEOUT', 'RETRY', 'ADAPTIVE_STABILIZATION', 'TRUNCATION', 'ENVIRONMENT'];
+    
+    categories.forEach(cat => {
+      byCategory[cat] = this.getByCategory(cat).length;
+    });
+    
+    return {
+      total: this.decisions.length,
+      byCategory,
+      deterministic: this._isDeterministic()
+    };
+  }
+
+  /**
+   * Determine if run was fully deterministic
+   * @returns {boolean}
+   * @private
+   */
+  _isDeterministic() {
+    // A run is deterministic if:
+    // 1. No truncations occurred (budget not exceeded)
+    // 2. No retries occurred (no transient failures)
+    // 3. No adaptive stabilization extensions (timing was predictable)
+    
+    const truncations = this.getByCategory('TRUNCATION');
+    const retries = this.getByCategory('RETRY');
+    const adaptiveExtensions = this.decisions.filter(d => 
+      d.decision_id === DECISION_IDS.ADAPTIVE_STABILIZATION_EXTENDED
+    );
+    
+    return truncations.length === 0 && 
+           retries.length === 0 && 
+           adaptiveExtensions.length === 0;
+  }
+
+  /**
+   * Export decisions for serialization
+   * @returns {Object}
+   */
+  export() {
+    return {
+      runId: this.runId,
+      recordedAt: new Date().toISOString(),
+      total: this.decisions.length,
+      decisions: this.decisions.map(d => ({
+        ...d,
+        timestamp: new Date(d.timestamp).toISOString() // Convert to ISO string for readability
+      })),
+      summary: this.getSummary()
+    };
+  }
+
+  /**
+   * Load decisions from exported format (for replay)
+   * @param {Object} exported
+   * @returns {DecisionRecorder}
+   */
+  static fromExport(exported) {
+    const recorder = new DecisionRecorder(exported.runId);
+    
+    if (exported.decisions) {
+      exported.decisions.forEach(d => {
+        recorder.record({
+          ...d,
+          timestamp: new Date(d.timestamp).getTime() // Convert ISO string back to ms
+        });
+      });
+    }
+    
+    return recorder;
+  }
+}
+
+/**
+ * Create helper functions for common decision recording patterns
+ */
+
+/**
+ * Record budget profile selection
+ * @param {DecisionRecorder} recorder
+ * @param {string} profileName
+ * @param {Object} budget
+ */
+export function recordBudgetProfile(recorder, profileName, budget) {
+  const now = Date.now();
+  recorder.recordBatch([
+    {
+      decision_id: DECISION_IDS.BUDGET_PROFILE_SELECTED,
+      category: 'BUDGET',
+      timestamp: now,
+      inputs: { env_var: process.env.VERAX_BUDGET_PROFILE || 'STANDARD' },
+      chosen_value: profileName,
+      reason: `Budget profile selected: ${profileName}`
+    },
+    {
+      decision_id: DECISION_IDS.BUDGET_MAX_INTERACTIONS,
+      category: 'BUDGET',
+      timestamp: now,
+      inputs: { profile: profileName },
+      chosen_value: budget.maxInteractionsPerPage,
+      reason: `Max interactions per page from ${profileName} profile`
+    },
+    {
+      decision_id: DECISION_IDS.BUDGET_MAX_PAGES,
+      category: 'BUDGET',
+      timestamp: now,
+      inputs: { profile: profileName },
+      chosen_value: budget.maxPages,
+      reason: `Max pages from ${profileName} profile`
+    },
+    {
+      decision_id: DECISION_IDS.BUDGET_SCAN_DURATION,
+      category: 'BUDGET',
+      timestamp: now,
+      inputs: { profile: profileName },
+      chosen_value: budget.maxScanDurationMs,
+      reason: `Scan duration limit from ${profileName} profile`
+    }
+  ]);
+}
+
+/**
+ * Record timeout configuration
+ * @param {DecisionRecorder} recorder
+ * @param {Object} budget
+ */
+export function recordTimeoutConfig(recorder, budget) {
+  const now = Date.now();
+  recorder.recordBatch([
+    {
+      decision_id: DECISION_IDS.TIMEOUT_NAVIGATION,
+      category: 'TIMEOUT',
+      timestamp: now,
+      inputs: { budget_config: true },
+      chosen_value: budget.navigationTimeoutMs,
+      reason: 'Navigation timeout from budget configuration'
+    },
+    {
+      decision_id: DECISION_IDS.TIMEOUT_INTERACTION,
+      category: 'TIMEOUT',
+      timestamp: now,
+      inputs: { budget_config: true },
+      chosen_value: budget.interactionTimeoutMs,
+      reason: 'Interaction timeout from budget configuration'
+    },
+    {
+      decision_id: DECISION_IDS.TIMEOUT_SETTLE,
+      category: 'TIMEOUT',
+      timestamp: now,
+      inputs: { budget_config: true },
+      chosen_value: budget.settleTimeoutMs,
+      reason: 'Settle timeout from budget configuration'
+    },
+    {
+      decision_id: DECISION_IDS.TIMEOUT_STABILIZATION,
+      category: 'TIMEOUT',
+      timestamp: now,
+      inputs: { budget_config: true },
+      chosen_value: budget.stabilizationWindowMs,
+      reason: 'Stabilization window from budget configuration'
+    }
+  ]);
+}
+
+/**
+ * Record adaptive stabilization decision
+ * @param {DecisionRecorder} recorder
+ * @param {boolean} enabled
+ * @param {boolean} wasExtended
+ * @param {number} extensionMs
+ * @param {string} reason
+ */
+export function recordAdaptiveStabilization(recorder, enabled, wasExtended = false, extensionMs = 0, reason = '') {
+  const now = Date.now();
+  recorder.record({
+    decision_id: DECISION_IDS.ADAPTIVE_STABILIZATION_ENABLED,
+    category: 'ADAPTIVE_STABILIZATION',
+    timestamp: now,
+    inputs: { budget_config: true },
+    chosen_value: enabled,
+    reason: enabled ? 'Adaptive stabilization enabled by budget profile' : 'Adaptive stabilization disabled'
+  });
+  
+  if (wasExtended) {
+    recorder.record({
+      decision_id: DECISION_IDS.ADAPTIVE_STABILIZATION_EXTENDED,
+      category: 'ADAPTIVE_STABILIZATION',
+      timestamp: now,
+      inputs: { dom_changing: true, network_active: true },
+      chosen_value: extensionMs,
+      reason: reason || `Extended stabilization by ${extensionMs}ms due to ongoing changes`
+    });
+  }
+}
+
+/**
+ * Record retry attempt
+ * @param {DecisionRecorder} recorder
+ * @param {string} operationType - 'navigation' | 'interaction'
+ * @param {number} attemptNumber
+ * @param {number} delayMs
+ * @param {string} errorType
+ */
+export function recordRetryAttempt(recorder, operationType, attemptNumber, delayMs, errorType) {
+  const decisionId = operationType === 'navigation' ? 
+    DECISION_IDS.RETRY_NAVIGATION_ATTEMPTED : 
+    DECISION_IDS.RETRY_INTERACTION_ATTEMPTED;
+  
+  const now = Date.now();
+  recorder.recordBatch([
+    {
+      decision_id: decisionId,
+      category: 'RETRY',
+      timestamp: now,
+      inputs: { attempt: attemptNumber, error_type: errorType },
+      chosen_value: true,
+      reason: `Retry attempt ${attemptNumber} for ${operationType} due to ${errorType}`
+    },
+    {
+      decision_id: DECISION_IDS.RETRY_BACKOFF_DELAY,
+      category: 'RETRY',
+      timestamp: now,
+      inputs: { attempt: attemptNumber },
+      chosen_value: delayMs,
+      reason: `Exponential backoff delay: ${delayMs}ms`
+    }
+  ]);
+}
+
+/**
+ * Record budget truncation
+ * @param {DecisionRecorder} recorder
+ * @param {string} truncationType - 'interactions' | 'pages' | 'scan_time'
+ * @param {Object|number} limitOrOptions - Either a number (limit) or object with {limit, reached/elapsed, scope?}
+ * @param {number} [actual] - Actual value (only used if limitOrOptions is a number)
+ */
+export function recordTruncation(recorder, truncationType, limitOrOptions, actual = null) {
+  const decisionIdMap = {
+    interactions: DECISION_IDS.TRUNCATION_INTERACTIONS_CAPPED,
+    pages: DECISION_IDS.TRUNCATION_PAGES_CAPPED,
+    scan_time: DECISION_IDS.TRUNCATION_SCAN_TIME_EXCEEDED
+  };
+  
+  let limit, actualValue;
+  if (typeof limitOrOptions === 'object' && limitOrOptions !== null) {
+    limit = limitOrOptions.limit;
+    actualValue = limitOrOptions.reached || limitOrOptions.elapsed || limitOrOptions.actual || 0;
+  } else {
+    limit = limitOrOptions;
+    actualValue = actual || 0;
+  }
+  
+  recorder.record({
+    decision_id: decisionIdMap[truncationType] || DECISION_IDS.TRUNCATION_BUDGET_EXCEEDED,
+    category: 'TRUNCATION',
+    timestamp: Date.now(),
+    inputs: { limit, actual: actualValue },
+    chosen_value: actualValue,
+    reason: `Budget exceeded: ${truncationType} capped at ${limit} (attempted ${actualValue})`
+  });
+}
+
+/**
+ * Record environment detection
+ * @param {DecisionRecorder} recorder
+ * @param {Object} environment - Environment config with browserType and viewport
+ */
+export function recordEnvironment(recorder, environment) {
+  const { browserType = 'unknown', viewport = { width: 1280, height: 720 } } = environment;
+  const now = Date.now();
+  
+  recorder.recordBatch([
+    {
+      decision_id: DECISION_IDS.ENV_BROWSER_DETECTED,
+      category: 'ENVIRONMENT',
+      timestamp: now,
+      inputs: { detected: true },
+      chosen_value: browserType,
+      reason: `Browser type: ${browserType}`
+    },
+    {
+      decision_id: DECISION_IDS.ENV_VIEWPORT_SIZE,
+      category: 'ENVIRONMENT',
+      timestamp: now,
+      inputs: { default_viewport: true },
+      chosen_value: viewport,
+      reason: `Viewport size: ${viewport.width}x${viewport.height}`
+    }
+  ]);
+}
+
+export default DecisionRecorder;

package/src/verax/core/incremental-store.js

@@ -0,0 +1,245 @@
+/**
+ * Incremental Store
+ * Stores lightweight snapshots from previous runs for incremental execution.
+ * 
+ * Snapshot contains:
+ * - Route signatures (hash of route path + sourceRef)
+ * - Expectation signatures (hash of expectation properties)
+ * - Interaction signatures (hash of interaction selector + type)
+ */
+
+import { createHash } from 'crypto';
+import { resolve } from 'path';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { getRunArtifactDir } from './run-id.js';
+
+/**
+ * Compute deterministic hash/signature for a route
+ */
+export function computeRouteSignature(route) {
+  const key = `${route.path || ''}|${route.sourceRef || ''}|${JSON.stringify(route.isDynamic || false)}|${route.examplePath || ''}`;
+  return createHash('sha256').update(key).digest('hex').slice(0, 16);
+}
+
+/**
+ * Compute deterministic hash/signature for an expectation
+ */
+export function computeExpectationSignature(expectation) {
+  const key = `${expectation.type || ''}|${expectation.fromPath || ''}|${expectation.targetPath || ''}|${expectation.sourceRef || ''}|${expectation.proof?.sourceRef || ''}`;
+  return createHash('sha256').update(key).digest('hex').slice(0, 16);
+}
+
+/**
+ * Compute deterministic hash/signature for an interaction
+ */
+export function computeInteractionSignature(interaction, url) {
+  const key = `${interaction.type || ''}|${interaction.selector || ''}|${url || ''}`;
+  return createHash('sha256').update(key).digest('hex').slice(0, 16);
+}
+
+/**
+ * Load previous snapshot if it exists
+ */
+export function loadPreviousSnapshot(projectDir, runId) {
+  if (!runId) {
+    return null; // No runId, no snapshot
+  }
+  const runDir = getRunArtifactDir(projectDir, runId);
+  const snapshotPath = resolve(runDir, 'incremental-snapshot.json');
+  if (!existsSync(snapshotPath)) {
+    return null;
+  }
+  
+  try {
+    const content = readFileSync(snapshotPath, 'utf-8');
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Save current snapshot
+ */
+export function saveSnapshot(projectDir, snapshot, runId) {
+  if (!runId) {
+    throw new Error('runId is required for saveSnapshot');
+  }
+  const runDir = getRunArtifactDir(projectDir, runId);
+  mkdirSync(runDir, { recursive: true });
+  const snapshotPath = resolve(runDir, 'incremental-snapshot.json');
+  
+  writeFileSync(snapshotPath, JSON.stringify(snapshot, null, 2));
+}
+
+/**
+ * Build snapshot from manifest and observed interactions
+ */
+export function buildSnapshot(manifest, observedInteractions = []) {
+  const routes = manifest.routes || [];
+  const expectations = manifest.staticExpectations || [];
+  
+  const routeSignatures = routes.map(r => ({
+    path: r.path,
+    signature: computeRouteSignature(r),
+    sourceRef: r.sourceRef
+  }));
+  
+  const expectationSignatures = expectations.map(e => ({
+    type: e.type,
+    fromPath: e.fromPath,
+    targetPath: e.targetPath,
+    signature: computeExpectationSignature(e),
+    sourceRef: e.sourceRef
+  }));
+  
+  // Group interaction signatures by URL
+  const interactionSignaturesByUrl = {};
+  for (const interaction of observedInteractions) {
+    const url = interaction.url || '*';
+    if (!interactionSignaturesByUrl[url]) {
+      interactionSignaturesByUrl[url] = [];
+    }
+    interactionSignaturesByUrl[url].push({
+      type: interaction.type,
+      selector: interaction.selector,
+      signature: computeInteractionSignature(interaction, url)
+    });
+  }
+  
+  return {
+    timestamp: Date.now(),
+    routes: routeSignatures,
+    expectations: expectationSignatures,
+    interactions: interactionSignaturesByUrl,
+    manifestVersion: manifest.learnTruth?.version || '1.0'
+  };
+}
+
+/**
+ * Compare old and new snapshots to detect changes
+ */
+export function compareSnapshots(oldSnapshot, newSnapshot) {
+  if (!oldSnapshot) {
+    return {
+      hasChanges: true,
+      changedRoutes: [],
+      changedExpectations: [],
+      unchangedRoutes: [],
+      unchangedExpectations: []
+    };
+  }
+  
+  // Compare routes
+  const oldRouteSigs = new Map(oldSnapshot.routes.map(r => [r.path, r.signature]));
+  const newRouteSigs = new Map(newSnapshot.routes.map(r => [r.path, r.signature]));
+  
+  const changedRoutes = [];
+  const unchangedRoutes = [];
+  
+  for (const newRoute of newSnapshot.routes) {
+    const oldSig = oldRouteSigs.get(newRoute.path);
+    if (oldSig !== newRoute.signature) {
+      changedRoutes.push(newRoute.path);
+    } else {
+      unchangedRoutes.push(newRoute.path);
+    }
+  }
+  
+  // Check for removed routes
+  for (const oldRoute of oldSnapshot.routes) {
+    if (!newRouteSigs.has(oldRoute.path)) {
+      changedRoutes.push(oldRoute.path); // Removed route triggers re-scan
+    }
+  }
+  
+  // Compare expectations
+  const oldExpSigs = new Set(oldSnapshot.expectations.map(e => e.signature));
+  const newExpSigs = new Set(newSnapshot.expectations.map(e => e.signature));
+  
+  const changedExpectations = [];
+  const unchangedExpectations = [];
+  
+  for (const newExp of newSnapshot.expectations) {
+    if (oldExpSigs.has(newExp.signature)) {
+      unchangedExpectations.push(newExp.signature);
+    } else {
+      changedExpectations.push(newExp.signature);
+    }
+  }
+  
+  // Check for removed expectations
+  for (const oldExp of oldSnapshot.expectations) {
+    if (!newExpSigs.has(oldExp.signature)) {
+      changedExpectations.push(oldExp.signature);
+    }
+  }
+  
+  const hasChanges = changedRoutes.length > 0 || changedExpectations.length > 0;
+  
+  return {
+    hasChanges,
+    changedRoutes,
+    changedExpectations,
+    unchangedRoutes,
+    unchangedExpectations
+  };
+}
+
+/**
+ * Check if interaction should be skipped based on incremental snapshot
+ */
+export function shouldSkipInteractionIncremental(interaction, url, oldSnapshot, snapshotDiff) {
+  if (!oldSnapshot || !snapshotDiff) {
+    return false; // No snapshot, don't skip
+  }
+  
+  // If route changed, don't skip (re-scan everything on that route)
+  const urlPath = extractPathFromUrl(url);
+  const routeChanged = snapshotDiff.changedRoutes.some(routePath => {
+    const normalizedRoute = normalizePath(routePath);
+    const normalizedUrl = normalizePath(urlPath);
+    return normalizedRoute === normalizedUrl || normalizedUrl.startsWith(normalizedRoute);
+  });
+  
+  if (routeChanged) {
+    return false; // Route changed, re-scan
+  }
+  
+  // If expectations changed, don't skip (may affect this interaction)
+  if (snapshotDiff.changedExpectations.length > 0) {
+    return false; // Expectations changed, re-scan
+  }
+  
+  // Check if this exact interaction was seen before
+  const interactionSig = computeInteractionSignature(interaction, url);
+  const oldInteractions = oldSnapshot.interactions[url] || oldSnapshot.interactions['*'] || [];
+  const wasSeenBefore = oldInteractions.some(i => i.signature === interactionSig);
+  
+  // Only skip if route unchanged AND expectations unchanged AND interaction was seen
+  if (wasSeenBefore && snapshotDiff.unchangedRoutes.length > 0) {
+    return true; // Unchanged route, unchanged expectations, seen interaction
+  }
+  
+  return false; // Conservative: don't skip if uncertain
+}
+
+/**
+ * Extract path from URL
+ */
+function extractPathFromUrl(url) {
+  try {
+    const urlObj = new URL(url);
+    return urlObj.pathname;
+  } catch {
+    return url || '*';
+  }
+}
+
+/**
+ * Normalize path for comparison
+ */
+function normalizePath(path) {
+  if (!path) return '/';
+  return path.replace(/\/$/, '') || '/';
+}