@veraxhq/verax 0.2.0 → 0.3.0

package/src/verax/core/determinism/engine.js

@@ -0,0 +1,221 @@
+/**
+ * PHASE 18 — Determinism Engine
+ * PHASE 21.2 — Determinism Truth Lock: Enforces HARD verdict
+ * 
+ * Runs the same scan multiple times and compares results for determinism.
+ * PHASE 21.2: Also checks DecisionRecorder for adaptive events that break determinism.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join, resolve } from 'path';
+import { normalizeArtifact } from './normalize.js';
+import { diffArtifacts } from './diff.js';
+import { computeFindingIdentity } from './finding-identity.js';
+import { ARTIFACT_REGISTRY } from '../artifacts/registry.js';
+import { computeDeterminismVerdict, DETERMINISM_VERDICT, DETERMINISM_REASON } from './contract.js';
+import { DecisionRecorder } from '../determinism-model.js';
+
+/**
+ * PHASE 18: Determinism verdict (re-exported from contract for backward compatibility)
+ */
+export { DETERMINISM_VERDICT, DETERMINISM_REASON } from './contract.js';
+
+/**
+ * PHASE 18: Run determinism check
+ * 
+ * @param {Function} runFn - Function that executes a scan and returns artifact paths or in-memory artifacts
+ * @param {Object} options - Options
+ * @param {number} options.runs - Number of runs (default: 2)
+ * @param {Object} options.config - Configuration for runs
+ * @param {boolean} options.normalize - Whether to normalize artifacts (default: true)
+ * @returns {Object} { verdict, summary, diffs, runsMeta }
+ */
+export async function runDeterminismCheck(runFn, options = {}) {
+  const { runs = 2, config = {}, normalize = true } = options;
+  
+  const runsMeta = [];
+  const runArtifacts = [];
+  
+  // Execute runs
+  for (let i = 0; i < runs; i++) {
+    const runResult = await runFn(config);
+    runsMeta.push({
+      runIndex: i + 1,
+      runId: runResult.runId || null,
+      timestamp: new Date().toISOString(),
+      artifactPaths: runResult.artifactPaths || {},
+      artifacts: runResult.artifacts || {},
+    });
+    
+    // Load artifacts if paths provided
+    const artifacts = {};
+    if (runResult.artifactPaths) {
+      for (const [key, path] of Object.entries(runResult.artifactPaths)) {
+        try {
+          const content = readFileSync(path, 'utf-8');
+          artifacts[key] = JSON.parse(content);
+        } catch (error) {
+          // Artifact not found or invalid
+        }
+      }
+    } else if (runResult.artifacts) {
+      Object.assign(artifacts, runResult.artifacts);
+    }
+    
+    runArtifacts.push(artifacts);
+  }
+  
+  // Compare runs
+  const diffs = [];
+  const allArtifacts = new Set();
+  
+  // Collect all artifact names
+  for (const artifacts of runArtifacts) {
+    for (const key of Object.keys(artifacts)) {
+      allArtifacts.add(key);
+    }
+  }
+  
+  // Compare each artifact across runs
+  for (const artifactName of allArtifacts) {
+    const artifacts = runArtifacts.map(run => run[artifactName]);
+    
+    // Normalize if requested
+    const normalizedArtifacts = normalize
+      ? artifacts.map(art => art ? normalizeArtifact(artifactName, art) : null)
+      : artifacts;
+    
+    // Compare first run with all subsequent runs
+    for (let i = 1; i < normalizedArtifacts.length; i++) {
+      const artifactA = normalizedArtifacts[0];
+      const artifactB = normalizedArtifacts[i];
+      
+      // Build finding identity map for findings artifacts
+      let findingIdentityMap = null;
+      if (artifactName === 'findings' && artifactA && artifactB) {
+        findingIdentityMap = buildFindingIdentityMap(artifactA, artifactB);
+      }
+      
+      const artifactDiffs = diffArtifacts(artifactA, artifactB, artifactName, findingIdentityMap);
+      
+      // Add run context to diffs
+      for (const diff of artifactDiffs) {
+        diff.runA = 1;
+        diff.runB = i + 1;
+      }
+      
+      diffs.push(...artifactDiffs);
+    }
+  }
+  
+  // PHASE 21.2: Check for adaptive events in DecisionRecorder (if available)
+  // HARD RULE: If adaptive events exist → verdict MUST be NON_DETERMINISTIC
+  let adaptiveVerdict = null;
+  let adaptiveReasons = [];
+  let adaptiveEvents = [];
+  
+  // Try to load decisions.json from first run
+  if (runsMeta.length > 0 && runsMeta[0].artifactPaths?.runDir) {
+    const runDir = runsMeta[0].artifactPaths.runDir;
+    const decisionsPath = resolve(runDir, 'decisions.json');
+    
+    if (existsSync(decisionsPath)) {
+      try {
+        const decisionsData = JSON.parse(readFileSync(decisionsPath, 'utf-8'));
+        const decisionRecorder = DecisionRecorder.fromExport(decisionsData);
+        const adaptiveCheck = computeDeterminismVerdict(decisionRecorder);
+        
+        adaptiveVerdict = adaptiveCheck.verdict;
+        adaptiveReasons = adaptiveCheck.reasons;
+        adaptiveEvents = adaptiveCheck.adaptiveEvents;
+      } catch (error) {
+        // Ignore errors reading decisions
+      }
+    }
+  }
+  
+  // PHASE 21.2: Determine verdict
+  // HARD RULE: If adaptive events exist → verdict MUST be NON_DETERMINISTIC (even if artifacts match)
+  const blockerDiffs = diffs.filter(d => d.severity === 'BLOCKER');
+  const artifactVerdict = blockerDiffs.length === 0 ? DETERMINISM_VERDICT.DETERMINISTIC : DETERMINISM_VERDICT.NON_DETERMINISTIC;
+  
+  // PHASE 21.2: Final verdict - adaptive events override artifact comparison
+  const verdict = (adaptiveVerdict === DETERMINISM_VERDICT.NON_DETERMINISTIC) 
+    ? DETERMINISM_VERDICT.NON_DETERMINISTIC 
+    : artifactVerdict;
+  
+  // Build summary
+  const summary = buildSummary(diffs, runsMeta);
+  
+  // PHASE 21.2: Include adaptive event information in summary
+  if (adaptiveVerdict === DETERMINISM_VERDICT.NON_DETERMINISTIC) {
+    summary.adaptiveEventsDetected = true;
+    summary.adaptiveEventCount = adaptiveEvents.length;
+    summary.adaptiveReasons = adaptiveReasons;
+  }
+  
+  return {
+    verdict,
+    summary,
+    diffs,
+    runsMeta,
+    // PHASE 21.2: Include adaptive event information
+    adaptiveVerdict,
+    adaptiveReasons,
+    adaptiveEvents
+  };
+}
+
+/**
+ * Build finding identity map for matching findings across runs
+ */
+function buildFindingIdentityMap(artifactA, artifactB) {
+  const map = new Map();
+  
+  const findingsA = artifactA.findings || [];
+  const findingsB = artifactB.findings || [];
+  
+  // Build identity for findings in both runs
+  for (const finding of [...findingsA, ...findingsB]) {
+    const identity = computeFindingIdentity(finding);
+    map.set(finding, identity);
+  }
+  
+  return map;
+}
+
+/**
+ * Build summary from diffs
+ */
+function buildSummary(diffs, runsMeta) {
+  const blockerCount = diffs.filter(d => d.severity === 'BLOCKER').length;
+  const warnCount = diffs.filter(d => d.severity === 'WARN').length;
+  const infoCount = diffs.filter(d => d.severity === 'INFO').length;
+  
+  // Group by reason code
+  const reasonCounts = {};
+  for (const diff of diffs) {
+    const code = diff.reasonCode || 'UNKNOWN';
+    reasonCounts[code] = (reasonCounts[code] || 0) + 1;
+  }
+  
+  // Top reasons
+  const topReasons = Object.entries(reasonCounts)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 5)
+    .map(([code, count]) => ({ code, count }));
+  
+  // Stability score (0..1)
+  const totalDiffs = diffs.length;
+  const stabilityScore = totalDiffs === 0 ? 1.0 : Math.max(0, 1.0 - (blockerCount * 0.5 + warnCount * 0.2 + infoCount * 0.1) / Math.max(1, totalDiffs));
+  
+  return {
+    totalDiffs,
+    blockerCount,
+    warnCount,
+    infoCount,
+    topReasons,
+    stabilityScore,
+  };
+}
+

package/src/verax/core/determinism/finding-identity.js

@@ -0,0 +1,148 @@
+/**
+ * PHASE 18 — Stable Finding Identity
+ * 
+ * Computes stable identity keys for findings that are consistent across runs.
+ * Used for matching findings between runs for comparison.
+ */
+
+import { createHash } from 'crypto';
+
+/**
+ * PHASE 18: Compute stable finding identity
+ * 
+ * Uses type + promise signature + route/network target + interaction selector/context chain
+ * Includes evidence trigger source signature where available (AST snippet hash or location)
+ * Must NOT include runId/timestamps
+ * 
+ * @param {Object} finding - Finding object
+ * @returns {string} Stable identity key
+ */
+export function computeFindingIdentity(finding) {
+  const parts = [];
+  
+  // Part 1: Finding type
+  parts.push(`type:${finding.type || 'unknown'}`);
+  
+  // Part 2: Interaction signature
+  const interaction = finding.interaction || {};
+  if (interaction.type && interaction.selector) {
+    parts.push(`interaction:${interaction.type}:${normalizeSelector(interaction.selector)}`);
+  }
+  if (interaction.label) {
+    parts.push(`label:${interaction.label}`);
+  }
+  
+  // Part 3: Promise signature
+  const expectation = finding.expectation || {};
+  const promise = finding.promise || {};
+  
+  if (expectation.type) {
+    parts.push(`promiseType:${expectation.type}`);
+  }
+  if (expectation.targetPath) {
+    parts.push(`targetPath:${normalizePath(expectation.targetPath)}`);
+  }
+  if (expectation.urlPath) {
+    parts.push(`urlPath:${normalizePath(expectation.urlPath)}`);
+  }
+  if (promise.type) {
+    parts.push(`promise:${promise.type}`);
+  }
+  
+  // Part 4: Route/network target
+  if (finding.route) {
+    const route = finding.route;
+    if (route.path) {
+      parts.push(`route:${normalizePath(route.path)}`);
+    }
+    if (route.originalPattern) {
+      parts.push(`routePattern:${normalizePath(route.originalPattern)}`);
+    }
+  }
+  
+  if (finding.evidence?.networkRequest?.url) {
+    parts.push(`networkUrl:${normalizeUrl(finding.evidence.networkRequest.url)}`);
+  }
+  
+  // Part 5: Evidence trigger source signature
+  const source = finding.source || expectation.source || {};
+  if (source.file) {
+    parts.push(`sourceFile:${normalizePath(source.file)}`);
+  }
+  if (source.line) {
+    parts.push(`sourceLine:${source.line}`);
+  }
+  if (source.astSource) {
+    // Hash AST source for stability
+    const astHash = hashString(source.astSource);
+    parts.push(`astHash:${astHash}`);
+  }
+  
+  // Part 6: Evidence trigger from evidencePackage
+  if (finding.evidencePackage?.trigger?.astSource) {
+    const triggerHash = hashString(finding.evidencePackage.trigger.astSource);
+    parts.push(`triggerHash:${triggerHash}`);
+  }
+  if (finding.evidencePackage?.trigger?.source?.file) {
+    parts.push(`triggerFile:${normalizePath(finding.evidencePackage.trigger.source.file)}`);
+  }
+  if (finding.evidencePackage?.trigger?.source?.line) {
+    parts.push(`triggerLine:${finding.evidencePackage.trigger.source.line}`);
+  }
+  
+  // Part 7: Context chain (if available)
+  if (finding.contextChain && Array.isArray(finding.contextChain)) {
+    const contextSig = finding.contextChain.map(c => `${c.type}:${c.name || ''}`).join('>');
+    parts.push(`context:${contextSig}`);
+  }
+  
+  // Combine all parts into stable identity
+  const identity = parts.join('|');
+  
+  // Return hash for compactness and stability
+  return hashString(identity);
+}
+
+/**
+ * Normalize selector (remove volatile parts)
+ */
+function normalizeSelector(selector) {
+  if (!selector || typeof selector !== 'string') return '';
+  // Remove any dynamic IDs or classes that might change
+  return selector.replace(/\[data-[^\]]+\]/g, '').replace(/\.\w+-\d+/g, '');
+}
+
+/**
+ * Normalize path (remove absolute paths, normalize separators)
+ */
+function normalizePath(path) {
+  if (!path || typeof path !== 'string') return '';
+  // Normalize separators
+  let normalized = path.replace(/\\/g, '/');
+  // Remove absolute path prefixes (keep relative structure)
+  normalized = normalized.replace(/^[A-Z]:\/[^\/]+/, '');
+  normalized = normalized.replace(/^\/[^\/]+/, '');
+  return normalized;
+}
+
+/**
+ * Normalize URL (remove query params, hash, normalize domain)
+ */
+function normalizeUrl(url) {
+  if (!url || typeof url !== 'string') return '';
+  try {
+    const urlObj = new URL(url);
+    // Keep only pathname for comparison
+    return urlObj.pathname;
+  } catch {
+    return url;
+  }
+}
+
+/**
+ * Hash string for stable identity
+ */
+function hashString(str) {
+  return createHash('sha256').update(str).digest('hex').substring(0, 16);
+}
+