@veraxhq/verax 0.1.0 → 0.2.1

package/src/verax/core/run-id.js

@@ -0,0 +1,175 @@
+/**
+ * PHASE 5: DETERMINISTIC RUN IDENTIFICATION
+ * 
+ * Generates stable, deterministic runId based on run parameters (NOT timestamps).
+ * Provides utilities for artifact path resolution.
+ */
+
+import { createHash } from 'crypto';
+import { join } from 'path';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Get VERAX version from package.json
+ */
+export function getVeraxVersion() {
+  try {
+    const packagePath = join(__dirname, '..', '..', '..', 'package.json');
+    const pkg = JSON.parse(readFileSync(packagePath, 'utf-8'));
+    return pkg.version || '0.1.0';
+  } catch (error) {
+    return '0.1.0';
+  }
+}
+
+/**
+ * Generate deterministic runId from run parameters
+ * 
+ * CRITICAL: NO timestamps, NO random values
+ * Hash must be identical for identical inputs
+ * 
+ * @param {Object} params - Run parameters
+ * @param {string} params.url - Target URL
+ * @param {Object} params.safetyFlags - Safety flags (allowWrites, allowRiskyActions, allowCrossOrigin)
+ * @param {string} params.baseOrigin - Base origin
+ * @param {Object} params.scanBudget - Scan budget configuration
+ * @param {string} params.manifestPath - Optional manifest path
+ * @returns {string} Deterministic runId (hex hash)
+ */
+export function generateRunId(params) {
+  const { url, safetyFlags = {}, baseOrigin, scanBudget, manifestPath = null } = params;
+  
+  // Sort flags deterministically
+  const sortedFlags = {
+    allowCrossOrigin: safetyFlags.allowCrossOrigin || false,
+    allowRiskyActions: safetyFlags.allowRiskyActions || false,
+    allowWrites: safetyFlags.allowWrites || false
+  };
+  
+  // Create deterministic representation
+  const runConfig = {
+    url,
+    flags: sortedFlags,
+    baseOrigin,
+    budget: {
+      maxScanDurationMs: scanBudget.maxScanDurationMs,
+      maxInteractionsPerPage: scanBudget.maxInteractionsPerPage,
+      maxUniqueUrls: scanBudget.maxUniqueUrls,
+      interactionTimeoutMs: scanBudget.interactionTimeoutMs,
+      navigationTimeoutMs: scanBudget.navigationTimeoutMs
+    },
+    manifestPath,
+    veraxVersion: getVeraxVersion()
+  };
+  
+  // Generate stable hash
+  // Sort keys at all levels for deterministic serialization
+  const configString = JSON.stringify(runConfig, (key, value) => {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      return Object.keys(value).sort().reduce((sorted, k) => {
+        sorted[k] = value[k];
+        return sorted;
+      }, {});
+    }
+    return value;
+  });
+  const hash = createHash('sha256').update(configString).digest('hex');
+  
+  // Return first 16 chars for readability (still collision-resistant)
+  return hash.substring(0, 16);
+}
+
+/**
+ * Get artifact directory for a run
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run identifier
+ * @returns {string} Absolute path to run artifact directory
+ */
+export function getRunArtifactDir(projectDir, runId) {
+  return join(projectDir, '.verax', 'runs', runId);
+}
+
+/**
+ * Get artifact file path
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run identifier
+ * @param {string} artifactName - Artifact filename (e.g., 'traces.json', 'findings.json')
+ * @returns {string} Absolute path to artifact file
+ */
+export function getArtifactPath(projectDir, runId, artifactName) {
+  return join(getRunArtifactDir(projectDir, runId), artifactName);
+}
+
+/**
+ * Get screenshot directory path
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run identifier
+ * @returns {string} Absolute path to screenshots directory
+ */
+export function getScreenshotDir(projectDir, runId) {
+  return join(getRunArtifactDir(projectDir, runId), 'evidence', 'screenshots');
+}
+
+/**
+ * Get all expected artifact paths for a run
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run identifier
+ * @returns {Object} Map of artifact names to paths
+ */
+export function getExpectedArtifacts(projectDir, runId) {
+  const runDir = getRunArtifactDir(projectDir, runId);
+  return {
+    runManifest: join(runDir, 'run-manifest.json'),
+    manifest: join(runDir, 'manifest.json'),
+    traces: join(runDir, 'traces.json'),
+    findings: join(runDir, 'findings.json'),
+    silences: join(runDir, 'silences.json'),
+    screenshotDir: join(runDir, 'evidence', 'screenshots')
+  };
+}
+
+/**
+ * Compute SHA256 hash of a file
+ * 
+ * @param {string} filePath - Path to file
+ * @returns {string} Hex hash
+ */
+export function computeFileHash(filePath) {
+  try {
+    const content = readFileSync(filePath);
+    return createHash('sha256').update(content).digest('hex');
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Compute hashes for all artifacts in a run
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run identifier
+ * @returns {Object} Map of artifact names to hashes
+ */
+export function computeArtifactHashes(projectDir, runId) {
+  const artifacts = getExpectedArtifacts(projectDir, runId);
+  const hashes = {};
+  
+  for (const [name, path] of Object.entries(artifacts)) {
+    if (name === 'screenshotDir') continue; // Directory, not file
+    const hash = computeFileHash(path);
+    if (hash) {
+      hashes[name] = hash;
+    }
+  }
+  
+  return hashes;
+}

package/src/verax/core/run-manifest.js

@@ -0,0 +1,99 @@
+/**
+ * PHASE 5: RUN MANIFEST
+ * 
+ * Single source of truth for run metadata.
+ * Written FIRST, referenced by all later stages.
+ */
+
+import { writeFileSync, mkdirSync, readFileSync } from 'fs';
+import { getRunArtifactDir, getVeraxVersion } from './run-id.js';
+
+/**
+ * Create run manifest at start of execution
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run identifier (deterministic)
+ * @param {Object} params - Run parameters
+ * @param {string} params.url - Target URL
+ * @param {Object} params.safetyFlags - Safety flags
+ * @param {string} params.baseOrigin - Base origin
+ * @param {Object} params.scanBudget - Scan budget
+ * @param {string} params.manifestPath - Optional manifest path
+ * @param {Array<string>} params.argv - Command line arguments
+ * @returns {Object} Run manifest data
+ */
+export function createRunManifest(projectDir, runId, params) {
+  const { url, safetyFlags, baseOrigin, scanBudget, manifestPath, argv = [] } = params;
+  
+  const runManifest = {
+    runId,
+    veraxVersion: getVeraxVersion(),
+    nodeVersion: process.version,
+    // Playwright version would be detected from node_modules if needed
+    playwrightVersion: 'latest',
+    url,
+    baseOrigin,
+    flags: {
+      allowWrites: safetyFlags.allowWrites || false,
+      allowRiskyActions: safetyFlags.allowRiskyActions || false,
+      allowCrossOrigin: safetyFlags.allowCrossOrigin || false
+    },
+    safeMode: {
+      enabled: !safetyFlags.allowWrites || !safetyFlags.allowRiskyActions || !safetyFlags.allowCrossOrigin,
+      writesBlocked: !safetyFlags.allowWrites,
+      riskyActionsBlocked: !safetyFlags.allowRiskyActions,
+      crossOriginBlocked: !safetyFlags.allowCrossOrigin
+    },
+    budget: {
+      maxScanDurationMs: scanBudget.maxScanDurationMs,
+      maxInteractionsPerPage: scanBudget.maxInteractionsPerPage,
+      maxUniqueUrls: scanBudget.maxUniqueUrls,
+      interactionTimeoutMs: scanBudget.interactionTimeoutMs,
+      navigationTimeoutMs: scanBudget.navigationTimeoutMs,
+      stabilizationWindowMs: scanBudget.stabilizationWindowMs,
+      stabilizationSampleMidMs: scanBudget.stabilizationSampleMidMs,
+      stabilizationSampleEndMs: scanBudget.stabilizationSampleEndMs,
+      networkWaitMs: scanBudget.networkWaitMs,
+      settleTimeoutMs: scanBudget.settleTimeoutMs,
+      settleIdleMs: scanBudget.settleIdleMs,
+      settleDomStableMs: scanBudget.settleDomStableMs,
+      navigationStableWaitMs: scanBudget.navigationStableWaitMs
+    },
+    manifestPath,
+    command: argv.join(' '),
+    argv,
+    startTime: new Date().toISOString(),
+    artifactHashes: {} // Will be populated after artifacts are written
+  };
+  
+  // Ensure run directory exists
+  const runDir = getRunArtifactDir(projectDir, runId);
+  mkdirSync(runDir, { recursive: true });
+  
+  // Write run manifest
+  const runManifestPath = `${runDir}/run-manifest.json`;
+  writeFileSync(runManifestPath, JSON.stringify(runManifest, null, 2));
+  
+  return runManifest;
+}
+
+/**
+ * Update run manifest with artifact hashes
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run identifier
+ * @param {Object} hashes - Map of artifact names to hashes
+ */
+export function updateRunManifestHashes(projectDir, runId, hashes) {
+  const runDir = getRunArtifactDir(projectDir, runId);
+  const runManifestPath = `${runDir}/run-manifest.json`;
+  
+  try {
+    const runManifest = JSON.parse(readFileSync(runManifestPath, 'utf-8'));
+    runManifest.artifactHashes = hashes;
+    runManifest.endTime = new Date().toISOString();
+    writeFileSync(runManifestPath, JSON.stringify(runManifest, null, 2));
+  } catch (error) {
+    // Run manifest not found or invalid - continue without update
+  }
+}

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

@@ -0,0 +1,369 @@
+/**
+ * SILENCE IMPACT ACCOUNTING
+ * 
+ * PHASE 4: Quantify how silence (unobserved/unevaluated states) affects confidence in our observations.
+ * 
+ * PRINCIPLES:
+ * 1. Silence is never neutral - it reduces confidence in what we claim to observe
+ * 2. Different types of silence have different confidence impacts
+ * 3. Aggregate impacts show what confidence metric is weakened and by how much
+ * 4. Confidence impact is ALWAYS negative (silence cannot increase confidence)
+ * 5. Impacts are factual: based on type/scope, not on hypothetical outcomes
+ * 
+ * Three confidence metrics affected by silence:
+ * - Coverage Confidence: How much of the codebase did we actually observe?
+ * - Promise Verification Confidence: How certain are we about promise verification?
+ * - Overall Observation Confidence: General confidence in observation completeness
+ */
+
+import { SILENCE_TYPES, EVALUATION_STATUS } from './silence-model.js';
+
+/**
+ * SILENCE_IMPACT_PROFILES - How different silence types affect confidence
+ * 
+ * Each profile defines the impact on three confidence dimensions.
+ * All values are NEGATIVE (silence reduces confidence).
+ */
+export const SILENCE_IMPACT_PROFILES = {
+  // Observation Infrastructure Failures - CRITICAL
+  // Sensor failure means we lost observability entirely for that area
+  [SILENCE_TYPES.SENSOR_FAILURE]: {
+    name: 'Sensor Failure',
+    severity: 'critical',
+    coverage: -20,              // Major reduction: lost observability
+    promise_verification: -15,  // Cannot verify promises without observation
+    overall: -18,               // Very high impact
+    reasoning: 'Observation infrastructure failure - no data collected for affected area'
+  },
+  
+  [SILENCE_TYPES.DISCOVERY_FAILURE]: {
+    name: 'Discovery Failure',
+    severity: 'critical',
+    coverage: -15,              // Major reduction: didn't find items to evaluate
+    promise_verification: -10,  // Unknown what promises existed
+    overall: -13,               // Very high impact
+    reasoning: 'Could not discover items - evaluation incomplete for unknown scope'
+  },
+
+  // Timing Failures - HIGH
+  // Timeouts mean interaction couldn't complete, promise unverified
+  [SILENCE_TYPES.NAVIGATION_TIMEOUT]: {
+    name: 'Navigation Timeout',
+    severity: 'high',
+    coverage: -10,              // Moderate reduction: page not reachable
+    promise_verification: -20,  // Complete failure for navigation promise
+    overall: -15,               // High impact
+    reasoning: 'Navigation could not complete - route unreachable or page unresponsive'
+  },
+  
+  [SILENCE_TYPES.INTERACTION_TIMEOUT]: {
+    name: 'Interaction Timeout',
+    severity: 'high',
+    coverage: -8,               // Moderate reduction
+    promise_verification: -18,  // Interaction promise verification failed
+    overall: -13,               // High impact
+    reasoning: 'Interaction did not complete within time budget - outcome unknown'
+  },
+
+  // Policy-Blocked Evaluation - MEDIUM
+  // Safety blocks prevent evaluation, but promise is known to exist
+  [SILENCE_TYPES.SAFETY_POLICY_BLOCK]: {
+    name: 'Safety Policy Block',
+    severity: 'medium',
+    coverage: -3,               // Low reduction: coverage by skipping is intentional
+    promise_verification: -25,  // Critical: promise cannot be verified due to safety policy
+    overall: -12,               // Medium-high impact
+    reasoning: 'Promise verification blocked by safety policy (logout, destructive action) - cannot assert promise due to risk'
+  },
+
+  [SILENCE_TYPES.PROMISE_VERIFICATION_BLOCKED]: {
+    name: 'Promise Verification Blocked',
+    severity: 'medium',
+    coverage: -2,               // Very low reduction: blocked verification only
+    promise_verification: -22,  // Cannot verify due to external navigation or origin mismatch
+    overall: -10,               // Medium impact
+    reasoning: 'Promise verification blocked - navigation leaves origin or enters external site'
+  },
+
+  // Resource Constraints - MEDIUM
+  // Budget limits mean we didn't finish evaluation
+  [SILENCE_TYPES.BUDGET_LIMIT_EXCEEDED]: {
+    name: 'Budget Limit Exceeded',
+    severity: 'medium',
+    coverage: -12,              // Moderate reduction: didn't evaluate all items
+    promise_verification: -8,   // Some promises verified, others not
+    overall: -10,               // Medium impact
+    reasoning: 'Evaluation terminated due to time/interaction budget - remaining items not evaluated'
+  },
+
+  // Data Reuse - LOW
+  // Incremental reuse is safe by design (previous run passed)
+  [SILENCE_TYPES.INCREMENTAL_REUSE]: {
+    name: 'Incremental Reuse',
+    severity: 'low',
+    coverage: 0,                // No impact: explicitly reusing validated baseline
+    promise_verification: 0,    // Verified in previous run
+    overall: 0,                 // Intentional optimization
+    reasoning: 'Data from previous run reused - baseline still valid'
+  },
+
+  // Ambiguous/Incomplete - LOW
+  // No expectation defined = no promise to verify anyway
+  [SILENCE_TYPES.PROMISE_NOT_EVALUATED]: {
+    name: 'Promise Not Evaluated',
+    severity: 'low',
+    coverage: 0,                // No impact: covered but no expectation
+    promise_verification: -2,   // Minor: cannot assert promise without expectation
+    overall: -1,                // Minimal impact
+    reasoning: 'Interaction found but no expectation defined - cannot verify promise'
+  },
+};
+
+/**
+ * Compute confidence impact for a single silence entry
+ * 
+ * @param {Object} silence - SilenceEntry with silence_type, evaluation_status, context
+ * @returns {Object} Impact: { coverage: number, promise_verification: number, overall: number }
+ */
+export function computeSilenceImpact(silence) {
+  if (!silence) {
+    return { coverage: 0, promise_verification: 0, overall: 0 };
+  }
+
+  const profile = SILENCE_IMPACT_PROFILES[silence.silence_type];
+  
+  if (!profile) {
+    // Unknown silence type - be conservative
+    return {
+      coverage: -5,
+      promise_verification: -5,
+      overall: -5,
+      unknown_type: silence.silence_type
+    };
+  }
+
+  // Start with base profile
+  let impact = {
+    coverage: profile.coverage,
+    promise_verification: profile.promise_verification,
+    overall: profile.overall
+  };
+
+  // Adjust for evaluation status (some statuses are worse than others)
+  if (silence.evaluation_status === EVALUATION_STATUS.BLOCKED) {
+    // Blocked state: intentional, but still reduces confidence
+    // Slightly less impact than timeout
+    impact.promise_verification = Math.max(-20, impact.promise_verification + 2);
+  } else if (silence.evaluation_status === EVALUATION_STATUS.TIMED_OUT) {
+    // Timed out: worse than blocked (unintentional failure)
+    impact.promise_verification = Math.min(-25, impact.promise_verification - 2);
+  } else if (silence.evaluation_status === EVALUATION_STATUS.AMBIGUOUS) {
+    // Ambiguous: cannot assert but also didn't try
+    impact.promise_verification = Math.max(-5, impact.promise_verification + 3);
+  }
+
+  // Clamp to reasonable ranges
+  impact.coverage = Math.max(-100, impact.coverage);
+  impact.promise_verification = Math.max(-100, impact.promise_verification);
+  impact.overall = Math.max(-100, impact.overall);
+
+  return impact;
+}
+
+/**
+ * Aggregate impacts from multiple silences
+ * 
+ * RULE: Impacts are cumulative but clamped at -100 (cannot be worse than complete loss)
+ * 
+ * @param {Array} silences - Array of SilenceEntry objects
+ * @returns {Object} Aggregated impact with clamping
+ */
+export function aggregateSilenceImpacts(silences) {
+  const total = {
+    coverage: 0,
+    promise_verification: 0,
+    overall: 0
+  };
+
+  if (!silences || silences.length === 0) {
+    return total;
+  }
+
+  for (const silence of silences) {
+    const impact = computeSilenceImpact(silence);
+    total.coverage += impact.coverage;
+    total.promise_verification += impact.promise_verification;
+    total.overall += impact.overall;
+  }
+
+  // Clamp to -100 to 0 range
+  return {
+    coverage: Math.max(-100, total.coverage),
+    promise_verification: Math.max(-100, total.promise_verification),
+    overall: Math.max(-100, total.overall)
+  };
+}
+
+/**
+ * Categorize impacts by severity
+ * 
+ * @param {Array} silences - Array of SilenceEntry objects
+ * @returns {Object} Impacts organized by severity
+ */
+export function categorizeSilencesByImpactSeverity(silences) {
+  const critical = [];
+  const high = [];
+  const medium = [];
+  const low = [];
+
+  if (!silences) return { critical, high, medium, low };
+
+  for (const silence of silences) {
+    const profile = SILENCE_IMPACT_PROFILES[silence.silence_type];
+    if (!profile) {
+      high.push(silence); // Default to high for unknown types
+      continue;
+    }
+
+    switch (profile.severity) {
+      case 'critical':
+        critical.push(silence);
+        break;
+      case 'high':
+        high.push(silence);
+        break;
+      case 'medium':
+        medium.push(silence);
+        break;
+      case 'low':
+        low.push(silence);
+        break;
+    }
+  }
+
+  return { critical, high, medium, low };
+}
+
+/**
+ * Compute impact summary for output
+ * 
+ * Shows:
+ * - Total impact by dimension
+ * - Most impactful silence types
+ * - Silences affecting each dimension
+ * 
+ * @param {Array} silences - Array of SilenceEntry objects
+ * @returns {Object} Detailed impact summary
+ */
+export function createImpactSummary(silences) {
+  if (!silences || silences.length === 0) {
+    return {
+      total_silences: 0,
+      aggregated_impact: { coverage: 0, promise_verification: 0, overall: 0 },
+      by_severity: { critical: 0, high: 0, medium: 0, low: 0 },
+      most_impactful_types: [],
+      affected_dimensions: {
+        coverage: [],
+        promise_verification: [],
+        overall: []
+      }
+    };
+  }
+
+  const aggregated = aggregateSilenceImpacts(silences);
+  const bySeverity = categorizeSilencesByImpactSeverity(silences);
+
+  // Find most impactful types
+  const typeImpacts = {};
+  for (const silence of silences) {
+    const impact = computeSilenceImpact(silence);
+    if (!typeImpacts[silence.silence_type]) {
+      typeImpacts[silence.silence_type] = { count: 0, total_impact: 0 };
+    }
+    typeImpacts[silence.silence_type].count++;
+    typeImpacts[silence.silence_type].total_impact += impact.overall;
+  }
+
+  const mostImpactful = Object.entries(typeImpacts)
+    .map(([type, data]) => ({
+      type,
+      count: data.count,
+      average_impact: Math.round(data.total_impact / data.count),
+      total_impact: data.total_impact
+    }))
+    .sort((a, b) => a.total_impact - b.total_impact)
+    .slice(0, 5);
+
+  // Find silences affecting each dimension most
+  const affectedDimensions = {
+    coverage: silences
+      .filter(s => computeSilenceImpact(s).coverage < 0)
+      .sort((a, b) => computeSilenceImpact(a).coverage - computeSilenceImpact(b).coverage)
+      .slice(0, 3)
+      .map(s => s.silence_type),
+    promise_verification: silences
+      .filter(s => computeSilenceImpact(s).promise_verification < 0)
+      .sort((a, b) => computeSilenceImpact(a).promise_verification - computeSilenceImpact(b).promise_verification)
+      .slice(0, 3)
+      .map(s => s.silence_type),
+    overall: silences
+      .filter(s => computeSilenceImpact(s).overall < 0)
+      .sort((a, b) => computeSilenceImpact(a).overall - computeSilenceImpact(b).overall)
+      .slice(0, 3)
+      .map(s => s.silence_type)
+  };
+
+  return {
+    total_silences: silences.length,
+    aggregated_impact: aggregated,
+    by_severity: {
+      critical: bySeverity.critical.length,
+      high: bySeverity.high.length,
+      medium: bySeverity.medium.length,
+      low: bySeverity.low.length
+    },
+    most_impactful_types: mostImpactful,
+    affected_dimensions: affectedDimensions,
+    confidence_interpretation: generateConfidenceInterpretation(aggregated)
+  };
+}
+
+/**
+ * Generate human-readable interpretation of confidence impacts
+ * 
+ * @param {Object} aggregated - Aggregated impact object
+ * @returns {string} Human-readable interpretation
+ */
+function generateConfidenceInterpretation(aggregated) {
+  const { coverage: _coverage, promise_verification: _promise_verification, overall } = aggregated;
+
+  if (overall === 0) {
+    return 'No silence events - observation confidence is complete within evaluated scope';
+  }
+
+  if (overall <= -80) {
+    return 'CRITICAL: Observation significantly incomplete - major silence events limit what we can assert';
+  }
+
+  if (overall <= -50) {
+    return 'SIGNIFICANT: Multiple silence events reduce observation confidence - substantial unknowns remain';
+  }
+
+  if (overall <= -25) {
+    return 'MODERATE: Some silence events reduce observation completeness - some unknowns remain';
+  }
+
+  if (overall <= -10) {
+    return 'MINOR: Few silence events slightly reduce confidence - observation mostly complete';
+  }
+
+  return 'Very minor impact from silence events';
+}
+
+export default {
+  SILENCE_IMPACT_PROFILES,
+  computeSilenceImpact,
+  aggregateSilenceImpacts,
+  categorizeSilencesByImpactSeverity,
+  createImpactSummary
+};