@veraxhq/verax 0.2.0 → 0.3.0

package/src/cli/util/determinism-runner.js

@@ -0,0 +1,123 @@
+/**
+ * PHASE 18 — Determinism Runner
+ * 
+ * Wraps a scan execution to run it multiple times and compare results.
+ */
+
+import { resolve } from 'path';
+import { readFileSync, existsSync } from 'fs';
+import { runDeterminismCheck } from '../../verax/core/determinism/engine.js';
+import { verifyRun } from '../../verax/core/artifacts/verifier.js';
+import { writeDeterminismReport } from './determinism-writer.js';
+
+/**
+ * PHASE 18: Run scan with determinism checking
+ * 
+ * @param {Function} scanFn - Function that executes a scan and returns { runId }
+ * @param {Object} options - Options
+ * @param {number} options.runs - Number of runs (default: 2)
+ * @param {string} options.out - Output directory
+ * @returns {Promise<Object>} Determinism check results
+ */
+export async function runWithDeterminism(scanFn, options = {}) {
+  const { runs = 2, out = '.verax' } = options;
+  
+  // Wrap scan function to return artifact paths
+  const runFn = async (runConfig) => {
+    const result = await scanFn({ ...options, ...runConfig });
+    
+    // Extract artifact paths from result
+    const artifactPaths = {};
+    if (result.runId) {
+      const runDir = resolve(out, 'runs', result.runId);
+      
+      // Map artifact keys to paths
+      const artifactMap = {
+        findings: resolve(runDir, 'findings.json'),
+        runStatus: resolve(runDir, 'run.status.json'),
+        summary: resolve(runDir, 'summary.json'),
+        learn: resolve(runDir, 'learn.json'),
+        observe: resolve(runDir, 'observe.json'),
+      };
+      
+      for (const [key, path] of Object.entries(artifactMap)) {
+        if (existsSync(path)) {
+          artifactPaths[key] = path;
+        }
+      }
+    }
+    
+    return {
+      runId: result.runId,
+      artifactPaths,
+    };
+  };
+  
+  // PHASE 25: Load run fingerprints from run.meta.json
+  const loadRunFingerprints = async (runMeta) => {
+    if (runMeta.runId) {
+      const runDir = resolve(out, 'runs', runMeta.runId);
+      const metaPath = resolve(runDir, 'run.meta.json');
+      if (existsSync(metaPath)) {
+        try {
+          const metaContent = readFileSync(metaPath, 'utf-8');
+          const meta = JSON.parse(metaContent);
+          return meta.runFingerprint || null;
+        } catch {
+          return null;
+        }
+      }
+    }
+    return null;
+  };
+  
+  // Run determinism check
+  const determinismResult = await runDeterminismCheck(runFn, {
+    runs,
+    config: options,
+    normalize: true,
+  });
+  
+  // PHASE 25: Load run fingerprints for each run
+  for (const runMeta of determinismResult.runsMeta) {
+    runMeta.runFingerprint = await loadRunFingerprints(runMeta);
+  }
+  
+  // Verify each run
+  const verificationResults = [];
+  for (const runMeta of determinismResult.runsMeta) {
+    if (runMeta.runId) {
+      const runDir = resolve(out, 'runs', runMeta.runId);
+      if (existsSync(runDir)) {
+        try {
+          const { getArtifactVersions } = await import('../../verax/core/artifacts/registry.js');
+          const verification = verifyRun(runDir, getArtifactVersions());
+          verificationResults.push({
+            runId: runMeta.runId,
+            verification,
+          });
+        } catch (error) {
+          // Verification failed
+          verificationResults.push({
+            runId: runMeta.runId,
+            verification: { ok: false, errors: [error.message] },
+          });
+        }
+      }
+    }
+  }
+  
+  // Write determinism report
+  const reportPath = await writeDeterminismReport(
+    determinismResult,
+    verificationResults,
+    out
+  );
+  
+  return {
+    ...determinismResult,
+    verificationResults,
+    reportPath,
+  };
+}
+

package/src/cli/util/determinism-writer.js

@@ -0,0 +1,129 @@
+/**
+ * PHASE 18 — Determinism Report Writer
+ * 
+ * Writes determinism check results to artifact.
+ */
+
+import { resolve } from 'path';
+import { mkdirSync, writeFileSync } from 'fs';
+import { ARTIFACT_REGISTRY, getArtifactVersions } from '../../verax/core/artifacts/registry.js';
+
+/**
+ * PHASE 18: Write determinism report
+ * PHASE 25: Enhanced with runFingerprint, contract validation, and structured verdicts
+ * 
+ * @param {Object} determinismResult - Result from runDeterminismCheck
+ * @param {Array} verificationResults - Verification results for each run
+ * @param {string} outDir - Output directory
+ * @returns {Promise<string>} Path to determinism report
+ */
+export async function writeDeterminismReport(determinismResult, verificationResults, outDir) {
+  const reportsDir = resolve(outDir, 'determinism');
+  mkdirSync(reportsDir, { recursive: true });
+  
+  const reportId = `determinism-${Date.now()}`;
+  const reportPath = resolve(reportsDir, `${reportId}.json`);
+  
+  // PHASE 25: Check run fingerprints
+  const runFingerprints = [];
+  const runFingerprintMismatches = [];
+  for (const runMeta of determinismResult.runsMeta) {
+    if (runMeta.runFingerprint) {
+      runFingerprints.push(runMeta.runFingerprint);
+    }
+  }
+  if (runFingerprints.length > 1) {
+    const firstFingerprint = runFingerprints[0];
+    for (let i = 1; i < runFingerprints.length; i++) {
+      if (runFingerprints[i] !== firstFingerprint) {
+        runFingerprintMismatches.push({
+          runIndex: i + 1,
+          expected: firstFingerprint,
+          actual: runFingerprints[i]
+        });
+      }
+    }
+  }
+  
+  // PHASE 25: Check verifier errors
+  const verifierErrors = [];
+  for (const verification of verificationResults) {
+    if (verification.verification && !verification.verification.ok) {
+      verifierErrors.push({
+        runId: verification.runId,
+        errors: verification.verification.errors || [],
+        verdictStatus: verification.verification.verdictStatus
+      });
+    }
+  }
+  
+  // PHASE 25: Determine final verdict with expected/unexpected distinction
+  let finalVerdict = determinismResult.verdict;
+  if (runFingerprintMismatches.length > 0) {
+    finalVerdict = 'NON_DETERMINISTIC_UNEXPECTED';
+  } else if (verifierErrors.length > 0) {
+    finalVerdict = 'NON_DETERMINISTIC_UNEXPECTED';
+  } else if (determinismResult.adaptiveEvents && determinismResult.adaptiveEvents.length > 0) {
+    finalVerdict = 'NON_DETERMINISTIC_EXPECTED';
+  } else if (determinismResult.diffs && determinismResult.diffs.length > 0) {
+    const blockerDiffs = determinismResult.diffs.filter(d => d.severity === 'BLOCKER');
+    if (blockerDiffs.length > 0) {
+      finalVerdict = 'NON_DETERMINISTIC_UNEXPECTED';
+    } else {
+      finalVerdict = 'NON_DETERMINISTIC_EXPECTED';
+    }
+  }
+  
+  // PHASE 25: Build top reasons
+  const topReasons = [];
+  if (runFingerprintMismatches.length > 0) {
+    topReasons.push({ code: 'RUN_FINGERPRINT_MISMATCH', count: runFingerprintMismatches.length });
+  }
+  if (verifierErrors.length > 0) {
+    topReasons.push({ code: 'VERIFIER_ERRORS_DETECTED', count: verifierErrors.length });
+  }
+  if (determinismResult.adaptiveEvents && determinismResult.adaptiveEvents.length > 0) {
+    topReasons.push({ code: 'EXPECTED_ADAPTIVE_BEHAVIOR', count: determinismResult.adaptiveEvents.length });
+  }
+  if (determinismResult.diffs && determinismResult.diffs.length > 0) {
+    const blockerCount = determinismResult.diffs.filter(d => d.severity === 'BLOCKER').length;
+    if (blockerCount > 0) {
+      topReasons.push({ code: 'ARTIFACT_DIFF_DETECTED', count: blockerCount });
+    }
+  }
+  
+  const report = {
+    version: 2, // PHASE 25: Bump version
+    contractVersion: 1,
+    artifactVersions: getArtifactVersions(),
+    generatedAt: new Date().toISOString(),
+    verdict: finalVerdict,
+    summary: {
+      ...determinismResult.summary,
+      runFingerprintMismatches: runFingerprintMismatches.length,
+      verifierErrors: verifierErrors.length,
+      topReasons: topReasons.slice(0, 10)
+    },
+    runsMeta: determinismResult.runsMeta,
+    runFingerprints,
+    runFingerprintMismatches,
+    verificationResults,
+    verifierErrors,
+    normalizationRulesApplied: [
+      'Stripped timestamps (startedAt, completedAt, detectedAt, etc.)',
+      'Stripped runId fields',
+      'Normalized absolute paths to relative',
+      'Normalized floating scores to 3 decimals',
+      'Sorted arrays by stable keys',
+      'Normalized evidence paths but preserved presence/absence',
+    ],
+    diffs: determinismResult.diffs,
+    adaptiveEvents: determinismResult.adaptiveEvents || [],
+    stabilityScore: determinismResult.summary.stabilityScore,
+  };
+  
+  writeFileSync(reportPath, JSON.stringify(report, null, 2) + '\n');
+  
+  return reportPath;
+}
+

package/src/cli/util/env-url.js

@@ -1,7 +1,11 @@
+import { assertExecutionBootstrapAllowed } from './bootstrap-guard.js';
+
 /**
  * Attempt to infer URL from environment variables and common dev configs
  */
 export function tryResolveUrlFromEnv() {
+  // PHASE 21.6.1: Runtime guard - crash if called during inspection
+  assertExecutionBootstrapAllowed('tryResolveUrlFromEnv');
   // Check common environment variables
   const candidates = [
     process.env.VERCEL_URL,

package/src/cli/util/events.js

@@ -5,6 +5,10 @@ export class RunEventEmitter {
   constructor() {
     this.events = [];
     this.listeners = [];
+    this.heartbeatInterval = null;
+    this.heartbeatStartTime = null;
+    this.currentPhase = null;
+    this.heartbeatIntervalMs = 2500; // 2.5 seconds
   }
   
   on(event, handler) {
@@ -31,4 +35,76 @@ export class RunEventEmitter {
   getEvents() {
     return this.events;
   }
+
+  /**
+   * Start heartbeat for a phase
+   * @param {string} phase - Current phase name
+   * @param {boolean} jsonMode - Whether in JSON output mode
+   */
+  startHeartbeat(phase, jsonMode = false) {
+    this.currentPhase = phase;
+    this.heartbeatStartTime = Date.now();
+    
+    if (this.heartbeatInterval) {
+      clearInterval(this.heartbeatInterval);
+    }
+
+    this.heartbeatInterval = setInterval(() => {
+      const elapsedMs = Date.now() - this.heartbeatStartTime;
+      const elapsedSeconds = Math.floor(elapsedMs / 1000);
+      
+      const heartbeatEvent = {
+        type: 'heartbeat',
+        phase: this.currentPhase,
+        elapsedMs,
+        elapsedSeconds,
+        timestamp: new Date().toISOString(),
+      };
+
+      // Add to events array
+      this.events.push(heartbeatEvent);
+
+      // Emit to listeners
+      this.listeners.forEach(({ event: listenEvent, handler }) => {
+        if (listenEvent === 'heartbeat' || listenEvent === '*') {
+          if (jsonMode) {
+            // In JSON mode, emit as JSON line
+            handler(heartbeatEvent);
+          } else {
+            // Human-readable format: single line, overwrite-friendly
+            process.stdout.write(`\r…still working (phase=${this.currentPhase}, elapsed=${elapsedSeconds}s)`);
+          }
+        }
+      });
+    }, this.heartbeatIntervalMs);
+    
+    // CRITICAL: Unref the interval so it doesn't keep the process alive
+    // This allows tests to exit cleanly even if stopHeartbeat() is not called
+    if (this.heartbeatInterval && this.heartbeatInterval.unref) {
+      this.heartbeatInterval.unref();
+    }
+  }
+
+  /**
+   * Stop heartbeat
+   */
+  stopHeartbeat() {
+    if (this.heartbeatInterval) {
+      clearInterval(this.heartbeatInterval);
+      this.heartbeatInterval = null;
+    }
+    // Clear the progress line in human mode
+    process.stdout.write('\r' + ' '.repeat(60) + '\r');
+    this.currentPhase = null;
+    this.heartbeatStartTime = null;
+  }
+
+  /**
+   * Update current phase for heartbeat
+   * @param {string} phase - New phase name
+   */
+  updatePhase(phase) {
+    this.currentPhase = phase;
+    this.heartbeatStartTime = Date.now();
+  }
 }