@veraxhq/verax 0.2.0 → 0.3.0

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 } from '../determinism-model.js';
+import { ARTIFACT_REGISTRY } from '../artifacts/registry.js';
+
+/**
+ * Write determinism contract artifact
+ * 
+ * @param {string} runDir - Absolute run directory path
+ * @param {DecisionRecorder} 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 {DecisionRecorder} 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'
+  };
+}
+

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

@@ -0,0 +1,364 @@
+/**
+ * PHASE 18 — Determinism Diff Builder
+ * 
+ * Generates structured diffs between normalized artifacts from different runs.
+ */
+
+import { computeFindingIdentity } from './finding-identity.js';
+
+/**
+ * PHASE 18: Diff reason codes
+ * PHASE 25: Extended with new reason codes
+ */
+export const DIFF_REASON = {
+  MISSING_ARTIFACT: 'DET_DIFF_MISSING_ARTIFACT',
+  SCHEMA_MISMATCH: 'DET_DIFF_SCHEMA_MISMATCH',
+  FINDING_ADDED: 'DET_DIFF_FINDING_ADDED',
+  FINDING_REMOVED: 'DET_DIFF_FINDING_REMOVED',
+  FINDING_STATUS_CHANGED: 'DET_DIFF_FINDING_STATUS_CHANGED',
+  FINDING_SEVERITY_CHANGED: 'DET_DIFF_FINDING_SEVERITY_CHANGED',
+  CONFIDENCE_CHANGED: 'DET_DIFF_CONFIDENCE_CHANGED',
+  CONFIDENCE_REASONS_CHANGED: 'DET_DIFF_CONFIDENCE_REASONS_CHANGED',
+  GUARDRAILS_CHANGED: 'DET_DIFF_GUARDRAILS_CHANGED',
+  EVIDENCE_COMPLETENESS_CHANGED: 'DET_DIFF_EVIDENCE_COMPLETENESS_CHANGED',
+  EVIDENCE_MISSING: 'DET_DIFF_EVIDENCE_MISSING',
+  OBSERVATION_COUNT_CHANGED: 'DET_DIFF_OBSERVATION_COUNT_CHANGED',
+  FIELD_VALUE_CHANGED: 'DET_DIFF_FIELD_VALUE_CHANGED',
+  RUN_FINGERPRINT_MISMATCH: 'DET_DIFF_RUN_FINGERPRINT_MISMATCH',
+};
+
+/**
+ * PHASE 18: Diff categories
+ */
+export const DIFF_CATEGORY = {
+  FINDINGS: 'FINDINGS',
+  EXPECTATIONS: 'EXPECTATIONS',
+  OBSERVATIONS: 'OBSERVATIONS',
+  EVIDENCE: 'EVIDENCE',
+  STATUS: 'STATUS',
+  ARTIFACTS: 'ARTIFACTS',
+};
+
+/**
+ * PHASE 18: Diff severity
+ */
+export const DIFF_SEVERITY = {
+  BLOCKER: 'BLOCKER',
+  WARN: 'WARN',
+  INFO: 'INFO',
+};
+
+/**
+ * PHASE 18: Diff artifacts
+ * 
+ * @param {Object} artifactA - First artifact (normalized)
+ * @param {Object} artifactB - Second artifact (normalized)
+ * @param {string} artifactName - Name of artifact
+ * @param {Map} findingIdentityMap - Map of finding identity to finding (for matching)
+ * @returns {Array} Array of diff objects
+ */
+export function diffArtifacts(artifactA, artifactB, artifactName, findingIdentityMap = null) {
+  const diffs = [];
+  
+  // Check if artifacts exist
+  if (!artifactA && artifactB) {
+    diffs.push({
+      category: DIFF_CATEGORY.ARTIFACTS,
+      severity: DIFF_SEVERITY.BLOCKER,
+      reasonCode: DIFF_REASON.MISSING_ARTIFACT,
+      message: `Artifact ${artifactName} missing in first run`,
+      artifact: artifactName,
+    });
+    return diffs;
+  }
+  
+  if (artifactA && !artifactB) {
+    diffs.push({
+      category: DIFF_CATEGORY.ARTIFACTS,
+      severity: DIFF_SEVERITY.BLOCKER,
+      reasonCode: DIFF_REASON.MISSING_ARTIFACT,
+      message: `Artifact ${artifactName} missing in second run`,
+      artifact: artifactName,
+    });
+    return diffs;
+  }
+  
+  if (!artifactA && !artifactB) {
+    return diffs; // Both missing, no diff
+  }
+  
+  // Artifact-specific diffing
+  if (artifactName === 'findings') {
+    diffs.push(...diffFindings(artifactA, artifactB, findingIdentityMap));
+  } else if (artifactName === 'runMeta') {
+    diffs.push(...diffRunMeta(artifactA, artifactB));
+  } else if (artifactName === 'determinismContract') {
+    diffs.push(...diffDeterminismContract(artifactA, artifactB));
+  } else if (artifactName === 'confidenceReport' || artifactName === 'guardrailsReport' || artifactName === 'evidenceIntent') {
+    diffs.push(...diffReportArtifact(artifactA, artifactB, artifactName));
+  } else {
+    // Generic diff for other artifacts
+    diffs.push(...diffGeneric(artifactA, artifactB, artifactName));
+  }
+  
+  return diffs;
+}
+
+/**
+ * Diff findings artifacts
+ */
+function diffFindings(artifactA, artifactB, findingIdentityMap) {
+  const diffs = [];
+  
+  const findingsA = artifactA.findings || [];
+  const findingsB = artifactB.findings || [];
+  
+  // Check counts
+  if (findingsA.length !== findingsB.length) {
+    diffs.push({
+      category: DIFF_CATEGORY.FINDINGS,
+      severity: DIFF_SEVERITY.BLOCKER,
+      reasonCode: DIFF_REASON.OBSERVATION_COUNT_CHANGED,
+      message: `Finding count changed: ${findingsA.length} → ${findingsB.length}`,
+      artifact: 'findings',
+      field: 'findings.length',
+      oldValue: findingsA.length,
+      newValue: findingsB.length,
+    });
+  }
+  
+  // Build identity maps if not provided
+  const mapA = new Map();
+  const mapB = new Map();
+  
+  for (const finding of findingsA) {
+    const identity = findingIdentityMap ? findingIdentityMap.get(finding) : computeFindingIdentitySimple(finding);
+    mapA.set(identity, finding);
+  }
+  
+  for (const finding of findingsB) {
+    const identity = findingIdentityMap ? findingIdentityMap.get(finding) : computeFindingIdentitySimple(finding);
+    mapB.set(identity, finding);
+  }
+  
+  // Find added findings
+  for (const [identity, finding] of mapB) {
+    if (!mapA.has(identity)) {
+      diffs.push({
+        category: DIFF_CATEGORY.FINDINGS,
+        severity: DIFF_SEVERITY.BLOCKER,
+        reasonCode: DIFF_REASON.FINDING_ADDED,
+        message: `Finding added: ${finding.type || 'unknown'}`,
+        artifact: 'findings',
+        findingIdentity: identity,
+        finding: finding,
+      });
+    }
+  }
+  
+  // Find removed findings
+  for (const [identity, finding] of mapA) {
+    if (!mapB.has(identity)) {
+      diffs.push({
+        category: DIFF_CATEGORY.FINDINGS,
+        severity: DIFF_SEVERITY.BLOCKER,
+        reasonCode: DIFF_REASON.FINDING_REMOVED,
+        message: `Finding removed: ${finding.type || 'unknown'}`,
+        artifact: 'findings',
+        findingIdentity: identity,
+        finding: finding,
+      });
+    }
+  }
+  
+  // Find changed findings
+  for (const [identity, findingA] of mapA) {
+    const findingB = mapB.get(identity);
+    if (findingB) {
+      diffs.push(...diffFinding(findingA, findingB, identity));
+    }
+  }
+  
+  return diffs;
+}
+
+/**
+ * Diff individual finding
+ */
+function diffFinding(findingA, findingB, identity) {
+  const diffs = [];
+  
+  // Check status/severity
+  const statusA = findingA.severity || findingA.status;
+  const statusB = findingB.severity || findingB.status;
+  if (statusA !== statusB) {
+    diffs.push({
+      category: DIFF_CATEGORY.FINDINGS,
+      severity: DIFF_SEVERITY.BLOCKER,
+      reasonCode: DIFF_REASON.FINDING_SEVERITY_CHANGED,
+      message: `Finding severity changed: ${statusA} → ${statusB}`,
+      artifact: 'findings',
+      findingIdentity: identity,
+      field: 'severity',
+      oldValue: statusA,
+      newValue: statusB,
+    });
+  }
+  
+  // Check confidence
+  const confA = findingA.confidence || 0;
+  const confB = findingB.confidence || 0;
+  if (Math.abs(confA - confB) > 0.001) {
+    diffs.push({
+      category: DIFF_CATEGORY.FINDINGS,
+      severity: DIFF_SEVERITY.WARN,
+      reasonCode: DIFF_REASON.CONFIDENCE_CHANGED,
+      message: `Finding confidence changed: ${confA.toFixed(3)} → ${confB.toFixed(3)}`,
+      artifact: 'findings',
+      findingIdentity: identity,
+      field: 'confidence',
+      oldValue: confA,
+      newValue: confB,
+    });
+  }
+  
+  // Check confidence reasons
+  const reasonsA = findingA.confidenceReasons || [];
+  const reasonsB = findingB.confidenceReasons || [];
+  if (JSON.stringify(reasonsA.sort()) !== JSON.stringify(reasonsB.sort())) {
+    diffs.push({
+      category: DIFF_CATEGORY.FINDINGS,
+      severity: DIFF_SEVERITY.WARN,
+      reasonCode: DIFF_REASON.CONFIDENCE_REASONS_CHANGED,
+      message: `Finding confidence reasons changed`,
+      artifact: 'findings',
+      findingIdentity: identity,
+      field: 'confidenceReasons',
+      oldValue: reasonsA,
+      newValue: reasonsB,
+    });
+  }
+  
+  // Check guardrails
+  const guardrailsA = findingA.guardrails;
+  const guardrailsB = findingB.guardrails;
+  if (guardrailsA || guardrailsB) {
+    if (!guardrailsA || !guardrailsB) {
+      diffs.push({
+        category: DIFF_CATEGORY.FINDINGS,
+        severity: DIFF_SEVERITY.WARN,
+        reasonCode: DIFF_REASON.GUARDRAILS_CHANGED,
+        message: `Finding guardrails presence changed`,
+        artifact: 'findings',
+        findingIdentity: identity,
+        field: 'guardrails',
+      });
+    } else if (guardrailsA.finalDecision !== guardrailsB.finalDecision) {
+      diffs.push({
+        category: DIFF_CATEGORY.FINDINGS,
+        severity: DIFF_SEVERITY.WARN,
+        reasonCode: DIFF_REASON.GUARDRAILS_CHANGED,
+        message: `Finding guardrails decision changed: ${guardrailsA.finalDecision} → ${guardrailsB.finalDecision}`,
+        artifact: 'findings',
+        findingIdentity: identity,
+        field: 'guardrails.finalDecision',
+        oldValue: guardrailsA.finalDecision,
+        newValue: guardrailsB.finalDecision,
+      });
+    }
+  }
+  
+  // Check evidence completeness
+  const evidenceA = findingA.evidenceCompleteness;
+  const evidenceB = findingB.evidenceCompleteness;
+  if (evidenceA || evidenceB) {
+    if (!evidenceA || !evidenceB) {
+      diffs.push({
+        category: DIFF_CATEGORY.EVIDENCE,
+        severity: DIFF_SEVERITY.BLOCKER,
+        reasonCode: DIFF_REASON.EVIDENCE_COMPLETENESS_CHANGED,
+        message: `Finding evidence completeness presence changed`,
+        artifact: 'findings',
+        findingIdentity: identity,
+        field: 'evidenceCompleteness',
+      });
+    } else if (evidenceA.isComplete !== evidenceB.isComplete) {
+      diffs.push({
+        category: DIFF_CATEGORY.EVIDENCE,
+        severity: DIFF_SEVERITY.BLOCKER,
+        reasonCode: DIFF_REASON.EVIDENCE_COMPLETENESS_CHANGED,
+        message: `Finding evidence completeness changed: ${evidenceA.isComplete} → ${evidenceB.isComplete}`,
+        artifact: 'findings',
+        findingIdentity: identity,
+        field: 'evidenceCompleteness.isComplete',
+        oldValue: evidenceA.isComplete,
+        newValue: evidenceB.isComplete,
+      });
+    }
+  }
+  
+  // Check evidencePackage presence
+  const evidencePackageA = findingA.evidencePackage;
+  const evidencePackageB = findingB.evidencePackage;
+  if (!evidencePackageA && evidencePackageB) {
+    diffs.push({
+      category: DIFF_CATEGORY.EVIDENCE,
+      severity: DIFF_SEVERITY.BLOCKER,
+      reasonCode: DIFF_REASON.EVIDENCE_MISSING,
+      message: `Finding evidence package missing in first run`,
+      artifact: 'findings',
+      findingIdentity: identity,
+      field: 'evidencePackage',
+    });
+  } else if (evidencePackageA && !evidencePackageB) {
+    diffs.push({
+      category: DIFF_CATEGORY.EVIDENCE,
+      severity: DIFF_SEVERITY.BLOCKER,
+      reasonCode: DIFF_REASON.EVIDENCE_MISSING,
+      message: `Finding evidence package missing in second run`,
+      artifact: 'findings',
+      findingIdentity: identity,
+      field: 'evidencePackage',
+    });
+  }
+  
+  return diffs;
+}
+
+/**
+ * Diff generic artifacts
+ */
+function diffGeneric(artifactA, artifactB, artifactName) {
+  const diffs = [];
+  
+  // Simple deep comparison
+  const jsonA = JSON.stringify(artifactA, null, 2);
+  const jsonB = JSON.stringify(artifactB, null, 2);
+  
+  if (jsonA !== jsonB) {
+    diffs.push({
+      category: DIFF_CATEGORY.ARTIFACTS,
+      severity: DIFF_SEVERITY.WARN,
+      reasonCode: DIFF_REASON.FIELD_VALUE_CHANGED,
+      message: `Artifact ${artifactName} content changed`,
+      artifact: artifactName,
+    });
+  }
+  
+  return diffs;
+}
+
+/**
+ * Simple finding identity computation (fallback)
+ */
+function computeFindingIdentitySimple(finding) {
+  const parts = [
+    finding.type || 'unknown',
+    finding.interaction?.type || '',
+    finding.interaction?.selector || '',
+    finding.expectation?.targetPath || '',
+    finding.expectation?.urlPath || '',
+  ];
+  return parts.join('|');
+}
+