@veraxhq/verax 0.2.1 → 0.4.0

package/src/verax/core/decisions/decision.trace.js

@@ -0,0 +1,278 @@
+/**
+ * PHASE 21.10 — Decision Trace
+ * 
+ * Traces why each finding was detected, which signals contributed,
+ * which guardrails applied, and why confidence/status decisions were made.
+ */
+
+import { readFileSync, existsSync, writeFileSync } from 'fs';
+import { resolve } from 'path';
+
+/**
+ * Build decision trace for findings
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run ID
+ * @returns {Object} Decision trace
+ */
+export function buildDecisionTrace(projectDir, runId) {
+  const runDir = resolve(projectDir, '.verax', 'runs', runId);
+  
+  if (!existsSync(runDir)) {
+    return null;
+  }
+  
+  const findingsPath = resolve(runDir, 'findings.json');
+  if (!existsSync(findingsPath)) {
+    return null;
+  }
+  
+  // @ts-expect-error - readFileSync with encoding returns string
+  const findings = JSON.parse(readFileSync(findingsPath, 'utf-8'));
+  const traces = [];
+  
+  if (!Array.isArray(findings.findings)) {
+    return {
+      runId,
+      findings: [],
+      summary: { total: 0 },
+      generatedAt: new Date().toISOString()
+    };
+  }
+  
+  for (const finding of findings.findings) {
+    const findingId = finding.findingId || finding.id || `finding-${traces.length}`;
+    
+    // Why detected?
+    const detectionReasons = [];
+    if (finding.type) {
+      detectionReasons.push({
+        code: 'FINDING_TYPE',
+        reason: `Finding type: ${finding.type}`,
+        value: finding.type
+      });
+    }
+    if (finding.outcome) {
+      detectionReasons.push({
+        code: 'OUTCOME_CLASSIFICATION',
+        reason: `Outcome: ${finding.outcome}`,
+        value: finding.outcome
+      });
+    }
+    if (finding.promise?.type) {
+      detectionReasons.push({
+        code: 'PROMISE_TYPE',
+        reason: `Promise type: ${finding.promise.type}`,
+        value: finding.promise.type
+      });
+    }
+    
+    // Which signals contributed?
+    const signals = [];
+    if (finding.evidence?.sensors) {
+      const sensors = finding.evidence.sensors;
+      
+      if (sensors.network) {
+        signals.push({
+          type: 'NETWORK',
+          contributed: sensors.network.totalRequests > 0 || sensors.network.failedRequests > 0,
+          data: {
+            totalRequests: sensors.network.totalRequests || 0,
+            failedRequests: sensors.network.failedRequests || 0
+          }
+        });
+      }
+      
+      if (sensors.console) {
+        signals.push({
+          type: 'CONSOLE',
+          contributed: (sensors.console.errors || 0) > 0 || (sensors.console.warnings || 0) > 0,
+          data: {
+            errors: sensors.console.errors || 0,
+            warnings: sensors.console.warnings || 0
+          }
+        });
+      }
+      
+      if (sensors.uiSignals) {
+        signals.push({
+          type: 'UI_SIGNALS',
+          contributed: sensors.uiSignals.diff?.changed === true,
+          data: {
+            changed: sensors.uiSignals.diff?.changed || false
+          }
+        });
+      }
+    }
+    
+    // Which guardrails applied?
+    const guardrailsApplied = [];
+    if (finding.guardrails?.appliedRules) {
+      for (const rule of finding.guardrails.appliedRules) {
+        guardrailsApplied.push({
+          ruleId: rule.id || rule,
+          category: rule.category || null,
+          action: rule.action || null,
+          matched: rule.matched || true
+        });
+      }
+    }
+    
+    // Why confidence = X?
+    const confidenceReasons = [];
+    if (finding.confidenceLevel) {
+      confidenceReasons.push({
+        code: 'CONFIDENCE_LEVEL',
+        reason: `Confidence level: ${finding.confidenceLevel}`,
+        value: finding.confidenceLevel
+      });
+    }
+    if (finding.confidence !== undefined) {
+      confidenceReasons.push({
+        code: 'CONFIDENCE_SCORE',
+        reason: `Confidence score: ${finding.confidence}`,
+        value: finding.confidence
+      });
+    }
+    if (finding.confidenceReasons && Array.isArray(finding.confidenceReasons)) {
+      for (const reason of finding.confidenceReasons) {
+        confidenceReasons.push({
+          code: 'CONFIDENCE_FACTOR',
+          reason: reason,
+          value: reason
+        });
+      }
+    }
+    
+    // Why status = CONFIRMED / SUSPECTED / DROPPED?
+    const statusReasons = [];
+    const status = finding.severity || finding.status || 'SUSPECTED';
+    
+    statusReasons.push({
+      code: 'STATUS_ASSIGNED',
+      reason: `Status: ${status}`,
+      value: status
+    });
+    
+    if (finding.evidencePackage) {
+      if (finding.evidencePackage.isComplete) {
+        statusReasons.push({
+          code: 'EVIDENCE_COMPLETE',
+          reason: 'Evidence package is complete',
+          value: true
+        });
+      } else {
+        statusReasons.push({
+          code: 'EVIDENCE_INCOMPLETE',
+          reason: 'Evidence package is incomplete',
+          value: false
+        });
+      }
+    }
+    
+    if (finding.guardrails?.finalDecision) {
+      statusReasons.push({
+        code: 'GUARDRAILS_DECISION',
+        reason: `Guardrails decision: ${finding.guardrails.finalDecision}`,
+        value: finding.guardrails.finalDecision
+      });
+    }
+    
+    if (status === 'CONFIRMED' && finding.evidencePackage && !finding.evidencePackage.isComplete) {
+      statusReasons.push({
+        code: 'EVIDENCE_LAW_VIOLATION',
+        reason: 'CONFIRMED finding with incomplete evidence violates Evidence Law',
+        value: 'VIOLATION'
+      });
+    }
+    
+    traces.push({
+      findingId,
+      detection: {
+        why: detectionReasons,
+        signals: signals.filter(s => s.contributed),
+        expectationId: finding.expectationId || null,
+        interactionId: finding.interaction?.selector || null
+      },
+      guardrails: {
+        applied: guardrailsApplied,
+        finalDecision: finding.guardrails?.finalDecision || null,
+        contradictions: finding.guardrails?.contradictions || []
+      },
+      confidence: {
+        level: finding.confidenceLevel || null,
+        score: finding.confidence !== undefined ? finding.confidence : null,
+        why: confidenceReasons
+      },
+      status: {
+        value: status,
+        why: statusReasons
+      },
+      evidence: {
+        packageId: finding.evidencePackage?.id || null,
+        isComplete: finding.evidencePackage?.isComplete || false,
+        files: finding.evidencePackage?.files || []
+      }
+    });
+  }
+  
+  return {
+    runId,
+    findings: traces,
+    summary: {
+      total: traces.length,
+      byStatus: traces.reduce((acc, t) => {
+        const status = t.status.value;
+        acc[status] = (acc[status] || 0) + 1;
+        return acc;
+      }, {}),
+      byConfidence: traces.reduce((acc, t) => {
+        const level = t.confidence.level || 'UNKNOWN';
+        acc[level] = (acc[level] || 0) + 1;
+        return acc;
+      }, {}),
+      withGuardrails: traces.filter(t => t.guardrails.applied.length > 0).length,
+      withCompleteEvidence: traces.filter(t => t.evidence.isComplete).length
+    },
+    generatedAt: new Date().toISOString()
+  };
+}
+
+/**
+ * Write decision trace to file
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run ID
+ * @param {Object} trace - Decision trace
+ * @returns {string} Path to written file
+ */
+export function writeDecisionTrace(projectDir, runId, trace) {
+  const runDir = resolve(projectDir, '.verax', 'runs', runId);
+  const outputPath = resolve(runDir, 'decisions.trace.json');
+  writeFileSync(outputPath, JSON.stringify(trace, null, 2), 'utf-8');
+  return outputPath;
+}
+
+/**
+ * Load decision trace from file
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run ID
+ * @returns {Object|null} Decision trace or null
+ */
+export function loadDecisionTrace(projectDir, runId) {
+  const runDir = resolve(projectDir, '.verax', 'runs', runId);
+  const tracePath = resolve(runDir, 'decisions.trace.json');
+  
+  if (!existsSync(tracePath)) {
+    return null;
+  }
+  
+  try {
+  // @ts-expect-error - readFileSync with encoding returns string
+    return JSON.parse(readFileSync(tracePath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+

package/src/verax/core/determinism/contract-writer.js

@@ -0,0 +1,89 @@
+/**
+ * PHASE 25 — Determinism Contract Writer
+ * 
+ * Writes determinism.contract.json artifact capturing adaptive events,
+ * retries, timing adjustments, and other non-deterministic behaviors.
+ */
+
+import { writeFileSync } from 'fs';
+import { resolve } from 'path';
+import { DecisionRecorder as _DecisionRecorder } from '../determinism-model.js';
+import { ARTIFACT_REGISTRY } from '../artifacts/registry.js';
+
+/**
+ * Write determinism contract artifact
+ * 
+ * @param {string} runDir - Absolute run directory path
+ * @param {Object} decisionRecorder - Decision recorder instance
+ * @returns {string} Path to written contract
+ */
+export function writeDeterminismContract(runDir, decisionRecorder) {
+  const contractPath = resolve(runDir, ARTIFACT_REGISTRY.determinismContract.filename);
+  
+  const adaptiveEvents = [];
+  const retryEvents = [];
+  const timingAdjustments = [];
+  
+  if (decisionRecorder) {
+    // Extract adaptive stabilization events
+    const adaptiveStabilization = decisionRecorder.getByCategory('ADAPTIVE_STABILIZATION');
+    for (const decision of adaptiveStabilization) {
+      adaptiveEvents.push({
+        decision_id: decision.decision_id,
+        category: decision.category,
+        timestamp: decision.timestamp,
+        reason: decision.reason,
+        context: decision.context || null,
+        chosen_value: decision.chosen_value,
+        inputs: decision.inputs || {}
+      });
+    }
+    
+    // Extract retry events
+    const retries = decisionRecorder.getByCategory('RETRY');
+    for (const decision of retries) {
+      retryEvents.push({
+        decision_id: decision.decision_id,
+        category: decision.category,
+        timestamp: decision.timestamp,
+        reason: decision.reason,
+        context: decision.context || null,
+        chosen_value: decision.chosen_value,
+        inputs: decision.inputs || {}
+      });
+    }
+    
+    // Extract timing adjustments (timeout decisions)
+    const timeouts = decisionRecorder.getByCategory('TIMEOUT');
+    for (const decision of timeouts) {
+      timingAdjustments.push({
+        decision_id: decision.decision_id,
+        category: decision.category,
+        timestamp: decision.timestamp,
+        reason: decision.reason,
+        context: decision.context || null,
+        chosen_value: decision.chosen_value,
+        inputs: decision.inputs || {}
+      });
+    }
+  }
+  
+  const contract = {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    adaptiveEvents,
+    retryEvents,
+    timingAdjustments,
+    summary: {
+      adaptiveEventsCount: adaptiveEvents.length,
+      retryEventsCount: retryEvents.length,
+      timingAdjustmentsCount: timingAdjustments.length,
+      isDeterministic: adaptiveEvents.length === 0 && retryEvents.length === 0
+    }
+  };
+  
+  writeFileSync(contractPath, JSON.stringify(contract, null, 2), 'utf8');
+  
+  return contractPath;
+}
+

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

@@ -0,0 +1,139 @@
+/**
+ * PHASE 21.2 — Determinism Truth Lock: Strict Contract
+ * 
+ * DETERMINISM CONTRACT:
+ * 
+ * DETERMINISTIC means:
+ * - Same inputs (source code, URL, config)
+ * - Same environment (browser, OS, Node version)
+ * - Same config (budget, timeouts, flags)
+ * → identical normalized artifacts (findings, traces, evidence)
+ * 
+ * NON_DETERMINISTIC means:
+ * - Any adaptive behavior occurred (adaptive stabilization, retries, dynamic timeouts)
+ * - Any timing variance that affects results
+ * - Any environment-dependent behavior
+ * - Tracking adaptive decisions is NOT determinism
+ * 
+ * HARD RULE: If adaptiveEvents.length > 0 → verdict MUST be NON_DETERMINISTIC
+ */
+
+/**
+ * PHASE 21.2: Determinism verdict (binary)
+ * PHASE 25: Extended with expected/unexpected distinction
+ */
+export const DETERMINISM_VERDICT = {
+  DETERMINISTIC: 'DETERMINISTIC',
+  NON_DETERMINISTIC_EXPECTED: 'NON_DETERMINISTIC_EXPECTED',
+  NON_DETERMINISTIC_UNEXPECTED: 'NON_DETERMINISTIC_UNEXPECTED',
+  NON_DETERMINISTIC: 'NON_DETERMINISTIC' // Backward compatibility
+};
+
+/**
+ * PHASE 21.2: Determinism reason codes (stable)
+ * PHASE 25: Extended with new reason codes
+ */
+export const DETERMINISM_REASON = {
+  ADAPTIVE_STABILIZATION_USED: 'ADAPTIVE_STABILIZATION_USED',
+  RETRY_TRIGGERED: 'RETRY_TRIGGERED',
+  TIMING_VARIANCE: 'TIMING_VARIANCE',
+  TRUNCATION_OCCURRED: 'TRUNCATION_OCCURRED',
+  ENVIRONMENT_VARIANCE: 'ENVIRONMENT_VARIANCE',
+  NO_ADAPTIVE_EVENTS: 'NO_ADAPTIVE_EVENTS',
+  RUN_FINGERPRINT_MISMATCH: 'RUN_FINGERPRINT_MISMATCH',
+  ARTIFACT_DIFF_DETECTED: 'ARTIFACT_DIFF_DETECTED',
+  VERIFIER_ERRORS_DETECTED: 'VERIFIER_ERRORS_DETECTED',
+  EXPECTED_ADAPTIVE_BEHAVIOR: 'EXPECTED_ADAPTIVE_BEHAVIOR',
+  UNEXPECTED_DIFF_WITHOUT_ADAPTIVE: 'UNEXPECTED_DIFF_WITHOUT_ADAPTIVE'
+};
+
+/**
+ * PHASE 21.2: Adaptive event categories that break determinism
+ */
+export const ADAPTIVE_EVENT_CATEGORIES = [
+  'ADAPTIVE_STABILIZATION',
+  'RETRY',
+  'TRUNCATION'
+];
+
+/**
+ * PHASE 21.2: Check if a decision category breaks determinism
+ * 
+ * @param {string} category - Decision category
+ * @returns {boolean} True if this category breaks determinism
+ */
+export function isAdaptiveEventCategory(category) {
+  return ADAPTIVE_EVENT_CATEGORIES.includes(category);
+}
+
+/**
+ * PHASE 21.2: Compute determinism verdict from DecisionRecorder
+ * 
+ * HARD RULE: If any adaptive event occurred → NON_DETERMINISTIC
+ * 
+ * @param {Object} decisionRecorder - Decision recorder instance
+ * @returns {Object} { verdict, reasons, adaptiveEvents }
+ */
+export function computeDeterminismVerdict(decisionRecorder) {
+  if (!decisionRecorder) {
+    return {
+      verdict: DETERMINISM_VERDICT.NON_DETERMINISTIC,
+      reasons: [DETERMINISM_REASON.ENVIRONMENT_VARIANCE],
+      adaptiveEvents: [],
+      message: 'DecisionRecorder not available - cannot verify determinism'
+    };
+  }
+  
+  const adaptiveEvents = [];
+  const reasons = [];
+  
+  // Check for adaptive stabilization
+  const adaptiveStabilization = decisionRecorder.getByCategory('ADAPTIVE_STABILIZATION');
+  const adaptiveExtensions = adaptiveStabilization.filter(d => 
+    d.decision_id === 'ADAPTIVE_STABILIZATION_extended'
+  );
+  
+  if (adaptiveExtensions.length > 0) {
+    adaptiveEvents.push(...adaptiveExtensions);
+    reasons.push(DETERMINISM_REASON.ADAPTIVE_STABILIZATION_USED);
+  }
+  
+  // Check for retries
+  const retries = decisionRecorder.getByCategory('RETRY');
+  if (retries.length > 0) {
+    adaptiveEvents.push(...retries);
+    reasons.push(DETERMINISM_REASON.RETRY_TRIGGERED);
+  }
+  
+  // Check for truncations
+  const truncations = decisionRecorder.getByCategory('TRUNCATION');
+  if (truncations.length > 0) {
+    adaptiveEvents.push(...truncations);
+    reasons.push(DETERMINISM_REASON.TRUNCATION_OCCURRED);
+  }
+  
+  // HARD RULE: If any adaptive events → NON_DETERMINISTIC
+  if (adaptiveEvents.length > 0) {
+    return {
+      verdict: DETERMINISM_VERDICT.NON_DETERMINISTIC,
+      reasons,
+      adaptiveEvents: adaptiveEvents.map(e => ({
+        decision_id: e.decision_id,
+        category: e.category,
+        timestamp: e.timestamp,
+        reason: e.reason,
+        context: e.context || null
+      })),
+      message: `Non-deterministic: ${adaptiveEvents.length} adaptive event(s) detected`
+    };
+  }
+  
+  // No adaptive events → DETERMINISTIC
+  return {
+    verdict: DETERMINISM_VERDICT.DETERMINISTIC,
+    reasons: [DETERMINISM_REASON.NO_ADAPTIVE_EVENTS],
+    adaptiveEvents: [],
+    message: 'Deterministic: No adaptive events detected'
+  };
+}
+