@veraxhq/verax 0.2.0 → 0.2.1

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

@@ -222,10 +222,12 @@ export class DecisionRecorder {
  * @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}`
@@ -233,6 +235,7 @@ export function recordBudgetProfile(recorder, profileName, budget) {
     {
       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`
@@ -240,6 +243,7 @@ export function recordBudgetProfile(recorder, profileName, budget) {
     {
       decision_id: DECISION_IDS.BUDGET_MAX_PAGES,
       category: 'BUDGET',
+      timestamp: now,
       inputs: { profile: profileName },
       chosen_value: budget.maxPages,
       reason: `Max pages from ${profileName} profile`
@@ -247,6 +251,7 @@ export function recordBudgetProfile(recorder, profileName, budget) {
     {
       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`
@@ -260,10 +265,12 @@ export function recordBudgetProfile(recorder, profileName, budget) {
  * @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'
@@ -271,6 +278,7 @@ export function recordTimeoutConfig(recorder, budget) {
     {
       decision_id: DECISION_IDS.TIMEOUT_INTERACTION,
       category: 'TIMEOUT',
+      timestamp: now,
       inputs: { budget_config: true },
       chosen_value: budget.interactionTimeoutMs,
       reason: 'Interaction timeout from budget configuration'
@@ -278,6 +286,7 @@ export function recordTimeoutConfig(recorder, budget) {
     {
       decision_id: DECISION_IDS.TIMEOUT_SETTLE,
       category: 'TIMEOUT',
+      timestamp: now,
       inputs: { budget_config: true },
       chosen_value: budget.settleTimeoutMs,
       reason: 'Settle timeout from budget configuration'
@@ -285,6 +294,7 @@ export function recordTimeoutConfig(recorder, budget) {
     {
       decision_id: DECISION_IDS.TIMEOUT_STABILIZATION,
       category: 'TIMEOUT',
+      timestamp: now,
       inputs: { budget_config: true },
       chosen_value: budget.stabilizationWindowMs,
       reason: 'Stabilization window from budget configuration'
@@ -301,9 +311,11 @@ export function recordTimeoutConfig(recorder, budget) {
  * @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'
@@ -313,6 +325,7 @@ export function recordAdaptiveStabilization(recorder, enabled, wasExtended = fal
     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`
@@ -333,10 +346,12 @@ export function recordRetryAttempt(recorder, operationType, attemptNumber, delay
     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}`
@@ -344,6 +359,7 @@ export function recordRetryAttempt(recorder, operationType, attemptNumber, delay
     {
       decision_id: DECISION_IDS.RETRY_BACKOFF_DELAY,
       category: 'RETRY',
+      timestamp: now,
       inputs: { attempt: attemptNumber },
       chosen_value: delayMs,
       reason: `Exponential backoff delay: ${delayMs}ms`
@@ -355,22 +371,32 @@ export function recordRetryAttempt(recorder, operationType, attemptNumber, delay
  * Record budget truncation
  * @param {DecisionRecorder} recorder
  * @param {string} truncationType - 'interactions' | 'pages' | 'scan_time'
- * @param {number} limit
- * @param {number} actual
+ * @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, limit, actual) {
+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',
-    inputs: { limit, actual },
-    chosen_value: actual,
-    reason: `Budget exceeded: ${truncationType} capped at ${limit} (attempted ${actual})`
+    timestamp: Date.now(),
+    inputs: { limit, actual: actualValue },
+    chosen_value: actualValue,
+    reason: `Budget exceeded: ${truncationType} capped at ${limit} (attempted ${actualValue})`
   });
 }
 
@@ -381,11 +407,13 @@ export function recordTruncation(recorder, truncationType, limit, actual) {
  */
 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}`
@@ -393,6 +421,7 @@ export function recordEnvironment(recorder, environment) {
     {
       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}`

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

@@ -9,8 +9,9 @@
  */
 
 import { createHash } from 'crypto';
-import { resolve, dirname } from 'path';
+import { resolve } from 'path';
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { getRunArtifactDir } from './run-id.js';
 
 /**
  * Compute deterministic hash/signature for a route
@@ -39,8 +40,12 @@ export function computeInteractionSignature(interaction, url) {
 /**
  * Load previous snapshot if it exists
  */
-export function loadPreviousSnapshot(projectDir) {
-  const snapshotPath = resolve(projectDir, '.veraxverax', 'incremental-snapshot.json');
+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;
   }
@@ -56,10 +61,13 @@ export function loadPreviousSnapshot(projectDir) {
 /**
  * Save current snapshot
  */
-export function saveSnapshot(projectDir, snapshot) {
-  const snapshotDir = resolve(projectDir, '.veraxverax');
-  mkdirSync(snapshotDir, { recursive: true });
-  const snapshotPath = resolve(snapshotDir, 'incremental-snapshot.json');
+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));
 }

package/src/verax/core/replay-validator.js

@@ -13,7 +13,7 @@
  * - Categorize deviations: truncation_difference, timeout_difference, environment_difference
  */
 
-import { DecisionRecorder, DECISION_IDS } from './determinism-model.js';
+import { DecisionRecorder } from './determinism-model.js';
 
 /**
  * Compare two decision values and determine if they're equivalent
@@ -47,10 +47,10 @@ function areValuesEquivalent(value1, value2) {
 /**
  * Categorize a decision deviation
  * @param {Object} baseline - Baseline decision
- * @param {Object} current - Current decision
+ * @param {Object} _current - Current decision (unused parameter, kept for API compatibility)
  * @returns {string} - Deviation category
  */
-function categorizeDeviation(baseline, current) {
+function categorizeDeviation(baseline, _current) {
   const category = baseline.category;
   
   switch (category) {
@@ -78,7 +78,7 @@ function categorizeDeviation(baseline, current) {
  * @returns {string} - Human-readable explanation
  */
 function explainDeviation(baseline, current) {
-  const category = baseline.category;
+  const _category = baseline.category;
   const devCategory = categorizeDeviation(baseline, current);
   
   // Build explanation based on decision type

package/src/verax/core/replay.js

@@ -141,7 +141,7 @@ export function loadRunArtifacts(runDir) {
  * Replay a previous run from artifacts
  * 
  * @param {string} runDir - Path to run directory
- * @returns {Object} Replay result with observation summary
+ * @returns {Promise<any>} Replay result with observation summary
  */
 export async function replayRun(runDir) {
   // Load artifacts

package/src/verax/core/silence-impact.js

@@ -335,7 +335,7 @@ export function createImpactSummary(silences) {
  * @returns {string} Human-readable interpretation
  */
 function generateConfidenceInterpretation(aggregated) {
-  const { coverage, promise_verification, overall } = aggregated;
+  const { coverage: _coverage, promise_verification: _promise_verification, overall } = aggregated;
 
   if (overall === 0) {
     return 'No silence events - observation confidence is complete within evaluated scope';

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

@@ -18,8 +18,10 @@ import { mapSilenceReasonToOutcome } from './canonical-outcomes.js';
  * 
  * PHASE 4: Enhanced with lifecycle model
  * 
+ * Note: Fields marked as optional are auto-inferred by record() if not provided
+ * 
  * @typedef {Object} SilenceEntry
- * @property {string} outcome - Canonical outcome: SILENT_FAILURE | COVERAGE_GAP | UNPROVEN_INTERACTION | SAFETY_BLOCK | INFORMATIONAL
+ * @property {string} [outcome] - Canonical outcome: SILENT_FAILURE | COVERAGE_GAP | UNPROVEN_INTERACTION | SAFETY_BLOCK | INFORMATIONAL (auto-inferred if missing)
  * @property {string} scope - What was not evaluated: page | interaction | expectation | sensor | navigation | settle
  * @property {string} reason - Why it wasn't evaluated: timeout | cap | budget_exceeded | incremental_reuse | safety_skip | no_expectation | discovery_failed | sensor_failed
  * @property {string} description - Human-readable description of what wasn't observed
@@ -28,12 +30,12 @@ import { mapSilenceReasonToOutcome } from './canonical-outcomes.js';
  * @property {number} [count] - Number of items affected by this silence (optional)
  * @property {string} [evidenceUrl] - URL where this silence occurred (optional)
  * 
- * PHASE 4 Lifecycle Fields:
- * @property {string} silence_type - Technical classification: interaction_not_executed | promise_not_evaluated | sensor_failure | timeout | budget_limit | safety_block | discovery_failure
+ * PHASE 4 Lifecycle Fields (all auto-inferred if missing):
+ * @property {string} [silence_type] - Technical classification: interaction_not_executed | promise_not_evaluated | sensor_failure | timeout | budget_limit | safety_block | discovery_failure (auto-inferred)
  * @property {Object} [related_promise] - Promise that could not be evaluated (if applicable) or null with reason
- * @property {string} trigger - What triggered this silence: user_action_blocked | navigation_timeout | budget_exhausted | safety_policy | selector_not_found | etc
- * @property {string} evaluation_status - blocked | ambiguous | skipped | timed_out | incomplete
- * @property {Object} confidence_impact - Which confidence metrics are affected: { coverage: -X%, promise_verification: -Y%, overall: -Z% }
+ * @property {string} [trigger] - What triggered this silence: user_action_blocked | navigation_timeout | budget_exhausted | safety_policy | selector_not_found | etc (auto-inferred)
+ * @property {string} [evaluation_status] - blocked | ambiguous | skipped | timed_out | incomplete (auto-inferred)
+ * @property {Object} [confidence_impact] - Which confidence metrics are affected: { coverage: -X%, promise_verification: -Y%, overall: -Z% } (auto-inferred)
  */
 
 /**
@@ -272,7 +274,7 @@ export class SilenceTracker {
   /**
    * PHASE 4: Infer confidence impact from reason and scope
    */
-  _inferConfidenceImpact(reason, scope) {
+  _inferConfidenceImpact(reason, _scope) {
     // Map reason to which confidence metric(s) are affected
     const impact = {
       coverage: 0,

package/src/verax/detect/comparison.js

@@ -1,5 +1,6 @@
 import { resolve } from 'path';
 import { getUrlPath, getScreenshotHash } from './evidence-validator.js';
+import { getScreenshotDir } from '../core/run-id.js';
 
 export function hasMeaningfulUrlChange(beforeUrl, afterUrl) {
   const beforePath = getUrlPath(beforeUrl);
@@ -15,9 +16,13 @@ export function hasMeaningfulUrlChange(beforeUrl, afterUrl) {
   return beforeNormalized !== afterNormalized;
 }
 
-export function hasVisibleChange(beforeScreenshot, afterScreenshot, projectDir) {
-  const beforePath = resolve(projectDir, '.veraxverax', 'observe', beforeScreenshot);
-  const afterPath = resolve(projectDir, '.veraxverax', 'observe', afterScreenshot);
+export function hasVisibleChange(beforeScreenshot, afterScreenshot, projectDir, runId) {
+  if (!runId) {
+    throw new Error('runId is required for hasVisibleChange');
+  }
+  const screenshotsDir = getScreenshotDir(projectDir, runId);
+  const beforePath = resolve(screenshotsDir, beforeScreenshot);
+  const afterPath = resolve(screenshotsDir, afterScreenshot);
   
   const beforeHash = getScreenshotHash(beforePath);
   const afterHash = getScreenshotHash(afterPath);

package/src/verax/detect/confidence-engine.js

@@ -348,10 +348,10 @@ function scoreByFindingType({
   expectationStrength,
   networkSummary,
   consoleSummary,
-  uiSignals,
+  uiSignals: _uiSignals,
   evidenceSignals,
-  comparisons,
-  attemptMeta,
+  comparisons: _comparisons,
+  attemptMeta: _attemptMeta,
   boosts,
   penalties
 }) {
@@ -477,7 +477,7 @@ function scoreByFindingType({
 // TYPE-SPECIFIC SCORING FUNCTIONS
 // ============================================================
 
-function scoreNetworkSilentFailure({ networkSummary, consoleSummary, evidenceSignals, boosts, penalties }) {
+function scoreNetworkSilentFailure({ networkSummary: _networkSummary, consoleSummary: _consoleSummary, evidenceSignals, boosts, penalties: _penalties }) {
   let total = 0;
   
   // +10 if network failed
@@ -513,7 +513,7 @@ function penalizeNetworkSilentFailure({ evidenceSignals, penalties }) {
   return total;
 }
 
-function scoreValidationSilentFailure({ networkSummary, consoleSummary, evidenceSignals, boosts, penalties }) {
+function scoreValidationSilentFailure({ networkSummary: _networkSummary, consoleSummary: _consoleSummary, evidenceSignals, boosts, penalties: _penalties }) {
   let total = 0;
   
   // +10 if console errors (validation errors logged)
@@ -543,7 +543,7 @@ function penalizeValidationSilentFailure({ evidenceSignals, penalties }) {
   return total;
 }
 
-function scoreMissingFeedbackFailure({ networkSummary, evidenceSignals, boosts, penalties }) {
+function scoreMissingFeedbackFailure({ networkSummary: _networkSummary, evidenceSignals, boosts, penalties: _penalties }) {
   let total = 0;
   
   // +10 if slow/pending requests
@@ -573,7 +573,7 @@ function penalizeMissingFeedbackFailure({ evidenceSignals, penalties }) {
   return total;
 }
 
-function scoreNoEffectSilentFailure({ expectation, evidenceSignals, boosts, penalties }) {
+function scoreNoEffectSilentFailure({ expectation: _expectation, evidenceSignals, boosts, penalties: _penalties }) {
   let total = 0;
   
   // +10 if URL should have changed but didn't
@@ -615,7 +615,7 @@ function penalizeNoEffectSilentFailure({ evidenceSignals, penalties }) {
   return total;
 }
 
-function scoreMissingNetworkAction({ expectation, expectationStrength, evidenceSignals, boosts, penalties }) {
+function scoreMissingNetworkAction({ expectation, expectationStrength, evidenceSignals, boosts, penalties: _penalties }) {
   let total = 0;
   
   // +10 if PROVEN expectation
@@ -651,7 +651,7 @@ function penalizeMissingNetworkAction({ evidenceSignals, penalties }) {
   return total;
 }
 
-function scoreMissingStateAction({ expectation, expectationStrength, evidenceSignals, boosts, penalties }) {
+function scoreMissingStateAction({ expectation: _expectation, expectationStrength, evidenceSignals, boosts, penalties: _penalties }) {
   let total = 0;
   
   // +10 if PROVEN expectation
@@ -688,7 +688,7 @@ function penalizeMissingStateAction({ evidenceSignals, penalties }) {
 }
 
 // NAVIGATION INTELLIGENCE v2: Navigation failure scoring
-function scoreNavigationSilentFailure({ expectation, expectationStrength, evidenceSignals, boosts, penalties }) {
+function scoreNavigationSilentFailure({ expectation: _expectation, expectationStrength: _expectationStrength, evidenceSignals, boosts, penalties: _penalties }) {
   let total = 0;
   
   // +10 if URL should have changed but didn't
@@ -730,7 +730,7 @@ function penalizeNavigationSilentFailure({ evidenceSignals, penalties }) {
   return total;
 }
 
-function scorePartialNavigationFailure({ expectation, expectationStrength, evidenceSignals, boosts, penalties }) {
+function scorePartialNavigationFailure({ expectation: _expectation, expectationStrength: _expectationStrength, evidenceSignals, boosts, penalties: _penalties }) {
   let total = 0;
   
   // +10 if history changed but target not reached
@@ -764,7 +764,7 @@ function penalizePartialNavigationFailure({ evidenceSignals, penalties }) {
 // EXPLANATION GENERATION (ORDERED BY IMPORTANCE)
 // ============================================================
 
-function generateExplanations(boosts, penalties, expectationStrength, evidenceSignals) {
+function generateExplanations(boosts, penalties, expectationStrength, _evidenceSignals) {
   const explain = [];
   
   // Add penalties first (most important negatives)
@@ -802,11 +802,11 @@ function generateExplanations(boosts, penalties, expectationStrength, evidenceSi
  */
 function generateConfidenceExplanation({
   level,
-  score,
+  score: _score,
   expectationStrength,
   sensorsPresent,
   allSensorsPresent,
-  evidenceSignals,
+  evidenceSignals: _evidenceSignals,
   boosts,
   penalties,
   attemptMeta,
@@ -914,20 +914,20 @@ function generateConfidenceExplanation({
 export { hasNetworkData, hasConsoleData, hasUiData };
 
 // Detect error feedback (legacy helper)
-function detectErrorFeedback(uiSignals) {
+function _detectErrorFeedback(uiSignals) {
   const before = uiSignals?.before || {};
   const after = uiSignals?.after || {};
   return after.hasErrorSignal && !before.hasErrorSignal;
 }
 
 // Detect loading feedback (legacy helper)
-function detectLoadingFeedback(uiSignals) {
+function _detectLoadingFeedback(uiSignals) {
   const after = uiSignals?.after || {};
   return after.hasLoadingIndicator;
 }
 
 // Detect status feedback (legacy helper)
-function detectStatusFeedback(uiSignals) {
+function _detectStatusFeedback(uiSignals) {
   const after = uiSignals?.after || {};
   return after.hasStatusSignal || after.hasLiveRegion || after.hasDialog;
 }

package/src/verax/detect/detection-engine.js

@@ -77,7 +77,7 @@ class DetectionEngine {
    * Classify a single expectation against observations
    * @private
    */
-  _classifyExpectation(expectation, observationMap, allObservations) {
+  _classifyExpectation(expectation, observationMap, _allObservations) {
     const expectationId = expectation.id;
     const promise = expectation.promise || {};
 

package/src/verax/detect/evidence-index.js

@@ -8,18 +8,15 @@
  * with scope='evidence', reason='evidence_missing', preserving full context.
  */
 
-import fs from 'fs';
-import path from 'path';
+// fs and path imports removed - currently unused
 
 /**
  * Build evidence index from observation traces with validation.
  * 
  * @param {Array} traces - Observation traces from observe phase
- * @param {string|null} projectDir - Project directory for file validation (null to skip validation)
- * @param {Object|null} silenceTracker - Silence tracker instance (null to skip silence tracking)
  * @returns {Object} { evidenceIndex, expectationEvidenceMap, findingEvidenceMap }
  */
-export function buildEvidenceIndex(traces, projectDir = null, silenceTracker = null) {
+export function buildEvidenceIndex(traces, _projectDir = null, _silenceTracker = null) {
   const evidenceIndex = [];
   const expectationEvidenceMap = new Map();
   const findingEvidenceMap = new Map();
@@ -29,13 +26,13 @@ export function buildEvidenceIndex(traces, projectDir = null, silenceTracker = n
     return { evidenceIndex, expectationEvidenceMap, findingEvidenceMap };
   }
 
-  // Use fs/path for evidence validation if projectDir provided
-  let existsSync = null;
-  let resolvePath = null;
-  if (projectDir && fs && path) {
-    existsSync = fs.existsSync;
-    resolvePath = path.resolve;
-  }
+  // Use fs/path for evidence validation if projectDir provided (currently unused)
+  // let existsSync = null;
+  // let resolvePath = null;
+  // if (projectDir && fs && path) {
+  //   existsSync = fs.existsSync;
+  //   resolvePath = path.resolve;
+  // }
 
   for (const trace of traces) {
     // Prefer modern trace schema: trace.before/trace.after
@@ -44,56 +41,7 @@ export function buildEvidenceIndex(traces, projectDir = null, silenceTracker = n
     let beforeScreenshot = trace.before?.screenshot ?? trace.evidence?.beforeScreenshot ?? null;
     let afterScreenshot = trace.after?.screenshot ?? trace.evidence?.afterScreenshot ?? null;
 
-    // PHASE 3: Validate evidence file existence
-    if (existsSync && resolvePath && projectDir) {
-      const veraxDir = resolvePath(projectDir, '.veraxverax');
-      
-      // Check beforeScreenshot exists
-      if (beforeScreenshot) {
-        const beforePath = resolvePath(veraxDir, 'observe', beforeScreenshot);
-        const fileExists = existsSync(beforePath);
-        
-        if (!fileExists) {
-          // Track missing evidence as silence
-          if (silenceTracker) {
-            silenceTracker.record({
-              scope: 'evidence',
-              reason: 'evidence_missing',
-              description: `Screenshot evidence file not found: ${beforeScreenshot}`,
-              context: {
-                expectationId: trace.expectationId,
-                interaction: trace.interaction?.label,
-                expectedPath: beforePath
-              },
-              impact: 'incomplete_check'
-            });
-          }
-          beforeScreenshot = null; // Remove invalid evidence reference
-        }
-      }
-      
-      // Check afterScreenshot exists
-      if (afterScreenshot) {
-        const afterPath = resolvePath(veraxDir, 'observe', afterScreenshot);
-        if (!existsSync(afterPath)) {
-          // Track missing evidence as silence
-          if (silenceTracker) {
-            silenceTracker.record({
-              scope: 'evidence',
-              reason: 'evidence_missing',
-              description: `Screenshot evidence file not found: ${afterScreenshot}`,
-              context: {
-                expectationId: trace.expectationId,
-                interaction: trace.interaction?.label,
-                expectedPath: afterPath
-              },
-              impact: 'incomplete_check'
-            });
-          }
-          afterScreenshot = null; // Remove invalid evidence reference
-        }
-      }
-    }
+    // PHASE 3: Evidence file validation removed - screenshots stored in .verax/runs/<runId>/evidence/
 
     const entry = {
       id: `ev-${id}`,
@@ -135,12 +83,14 @@ export function buildEvidenceIndex(traces, projectDir = null, silenceTracker = n
  * @param {string} findingsPath - Path to findings.json
  * @returns {Promise<string>} Path to written evidence-index.json
  */
-export async function writeEvidenceIndex(projectDir, evidenceIndex, tracesPath, findingsPath, runDirOpt = null) {
+export async function writeEvidenceIndex(projectDir, evidenceIndex, tracesPath, findingsPath, runDirOpt) {
   const { resolve } = await import('path');
   const { mkdirSync, writeFileSync } = await import('fs');
 
-  // Prefer canonical run directory when provided
-  const artifactsDir = runDirOpt ? resolve(runDirOpt) : resolve(projectDir, '.veraxverax', 'artifacts');
+  if (!runDirOpt) {
+    throw new Error('runDirOpt is required');
+  }
+  const artifactsDir = resolve(runDirOpt, 'evidence');
   mkdirSync(artifactsDir, { recursive: true });
 
   const evidenceIndexPath = resolve(artifactsDir, 'evidence-index.json');

package/src/verax/detect/expectation-model.js

@@ -38,7 +38,7 @@ function normalizeExpectationType(expectationType) {
  */
 function normalizeSelector(selector) {
   if (!selector) return '';
-  return selector.replace(/[\[\]()]/g, '').trim();
+  return selector.replace(/[[\]()]/g, '').trim();
 }
 
 /**
@@ -114,7 +114,7 @@ export function matchExpectation(expectation, interaction, beforeUrl) {
   return null;
 }
 
-function matchesStaticExpectation(expectation, interaction, afterUrl) {
+function _matchesStaticExpectation(expectation, interaction, afterUrl) {
   if (interaction.type !== 'link') return false;
   
   const afterPath = getUrlPath(afterUrl);
@@ -129,7 +129,7 @@ function matchesStaticExpectation(expectation, interaction, afterUrl) {
   
   const selectorHint = expectation.evidence.selectorHint || '';
   const interactionSelector = interaction.selector || '';
-  const interactionLabel = (interaction.label || '').toLowerCase().trim();
+  const _interactionLabel = (interaction.label || '').toLowerCase().trim();
   
   if (selectorHint && interactionSelector) {
     if (selectorHint.includes(interactionSelector) || interactionSelector.includes(selectorHint.replace(/[\]()]/g, ''))) {
@@ -224,3 +224,54 @@ export function expectsNavigation(manifest, interaction, beforeUrl) {
   return false;
 }
 
+/**
+ * Get expectation for interaction from manifest (unified API for static and action contracts)
+ * @param {Object} manifest - Project manifest
+ * @param {Object} interaction - Interaction object
+ * @param {string} beforeUrl - URL before interaction
+ * @param {Object} [attemptMeta] - Optional metadata about the interaction attempt
+ * @returns {Object} { hasExpectation: boolean, proof: string, ...expectationData }
+ */
+export function getExpectation(manifest, interaction, beforeUrl, attemptMeta = {}) {
+  // Check static expectations first (for static sites)
+  if (manifest.staticExpectations && manifest.staticExpectations.length > 0) {
+    for (const expectation of manifest.staticExpectations) {
+      const matched = matchExpectation(expectation, interaction, beforeUrl);
+      if (matched) {
+        return {
+          hasExpectation: true,
+          proof: expectation.proof || 'PROVEN_EXPECTATION',
+          expectationType: expectation.type,
+          expectedTargetPath: expectation.targetPath,
+          ...expectation
+        };
+      }
+    }
+  }
+  
+  // Check action contracts (for apps with source-level contracts)
+  if (manifest.actionContracts && manifest.actionContracts.length > 0) {
+    const sourceRef = attemptMeta?.sourceRef;
+    if (sourceRef) {
+      for (const contract of manifest.actionContracts) {
+        if (contract.source === sourceRef) {
+          const expectationType = contract.kind === 'NETWORK_ACTION' ? 'network_action' : 'action';
+          return {
+            hasExpectation: true,
+            proof: 'PROVEN_EXPECTATION',
+            expectationType,
+            method: contract.method,
+            urlPath: contract.urlPath,
+            ...contract
+          };
+        }
+      }
+    }
+  }
+  
+  return {
+    hasExpectation: false,
+    proof: 'UNKNOWN_EXPECTATION'
+  };
+}
+