@veraxhq/verax 0.2.1 → 0.3.0

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

@@ -0,0 +1,434 @@
+/**
+ * PHASE 21.6 — GA Readiness Contract
+ * 
+ * Hard gate that determines if VERAX is Enterprise-GA ready.
+ * No human judgment, only code decides.
+ */
+
+import { evaluateAllCapabilityGates, buildGateContext } from '../capabilities/gates.js';
+import { CAPABILITY_MATURITY } from '../capabilities/gates.js';
+import { verifyRun } from '../artifacts/verifier.js';
+import { checkSecurityStatus } from '../security/security.enforcer.js';
+import { readFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
+import { isBaselineFrozen, enforceBaseline } from '../baseline/baseline.enforcer.js';
+
+/**
+ * GA Blocker Codes
+ */
+export const GA_BLOCKER_CODE = {
+  NO_RUNS_FOUND: 'GA_NO_RUNS_FOUND',
+  CAPABILITY_GATES_FAILED: 'GA_CAPABILITY_GATES_FAILED',
+  FRAMEWORK_WAVES_UNSTABLE: 'GA_FRAMEWORK_WAVES_UNSTABLE',
+  EVIDENCE_LAW_VIOLATION: 'GA_EVIDENCE_LAW_VIOLATION',
+  DETERMINISM_NOT_ACCEPTED: 'GA_DETERMINISM_NOT_ACCEPTED',
+  BLOCKING_FAILURES: 'GA_BLOCKING_FAILURES',
+  DEGRADED_FAILURES: 'GA_DEGRADED_FAILURES',
+  INTERNAL_FAILURES: 'GA_INTERNAL_FAILURES',
+  CONTRACT_FAILURES: 'GA_CONTRACT_FAILURES',
+  POLICY_INVALID: 'GA_POLICY_INVALID',
+  ARTIFACT_VERIFIER_FAILED: 'GA_ARTIFACT_VERIFIER_FAILED',
+  SECURITY_NOT_CHECKED: 'GA_SECURITY_NOT_CHECKED',
+  SECURITY_BLOCKED: 'GA_SECURITY_BLOCKED',
+  PERFORMANCE_BLOCKED: 'GA_PERFORMANCE_BLOCKED',
+  BASELINE_DRIFT: 'GA_BASELINE_DRIFT'
+};
+
+/**
+ * GA Warning Codes
+ */
+export const GA_WARNING_CODE = {
+  WARNINGS_IN_LEDGER: 'GA_WARNINGS_IN_LEDGER',
+  NON_DETERMINISTIC_ACCEPTED: 'GA_NON_DETERMINISTIC_ACCEPTED',
+  SECURITY_NOT_CHECKED: 'GA_SECURITY_NOT_CHECKED'
+};
+
+/**
+ * @typedef {Object} GA_BLOCKER
+ * @property {string} code - Blocker code
+ * @property {string} message - Human-readable message
+ * @property {Object} context - Additional context
+ */
+
+/**
+ * @typedef {Object} GA_WARNING
+ * @property {string} code - Warning code
+ * @property {string} message - Human-readable message
+ * @property {Object} context - Additional context
+ */
+
+/**
+ * @typedef {Object} GAReadinessResult
+ * @property {boolean} pass - Whether GA-ready
+ * @property {GA_BLOCKER[]} blockers - List of blockers
+ * @property {GA_WARNING[]} warnings - List of warnings
+ * @property {Object} summary - Summary of evaluation
+ * @property {Object} inputs - Inputs used for evaluation
+ */
+
+/**
+ * Check if determinism acceptance policy exists and is valid
+ * 
+ * @param {string} projectDir - Project directory
+ * @returns {Object|null} Acceptance policy or null
+ */
+function loadDeterminismAcceptancePolicy(projectDir) {
+  const policyPath = resolve(projectDir, 'determinism.acceptance.json');
+  if (!existsSync(policyPath)) {
+    return null;
+  }
+  
+  try {
+    const content = readFileSync(policyPath, 'utf-8');
+    const policy = JSON.parse(content);
+    
+    // Validate policy structure
+    if (!policy.allowedAdaptiveEvents || !Array.isArray(policy.allowedAdaptiveEvents)) {
+      return null;
+    }
+    
+    if (!policy.justification || typeof policy.justification !== 'string') {
+      return null;
+    }
+    
+    return policy;
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Check if determinism verdict is accepted
+ * 
+ * @param {string} determinismVerdict - Determinism verdict (DETERMINISTIC | NON_DETERMINISTIC)
+ * @param {Object|null} acceptancePolicy - Determinism acceptance policy
+ * @returns {boolean} Whether verdict is accepted
+ */
+function isDeterminismAccepted(determinismVerdict, acceptancePolicy) {
+  if (determinismVerdict === 'DETERMINISTIC') {
+    return true;
+  }
+  
+  if (determinismVerdict === 'NON_DETERMINISTIC' && acceptancePolicy) {
+    return true;
+  }
+  
+  return false;
+}
+
+/**
+ * Check if all framework waves are STABLE
+ * 
+ * @param {Object} gateResult - Capability gates result
+ * @returns {Object} { allStable: boolean, unstable: string[] }
+ */
+function checkFrameworkWavesStable(gateResult) {
+  const unstable = [];
+  
+  // Check all capabilities marked as STABLE actually pass gates
+  for (const [capabilityId, result] of Object.entries(gateResult.perCapability || {})) {
+    // This is a simplified check - in reality, we'd need to check the registry
+    // to see which capabilities are marked as STABLE
+    // For now, we check if any capability fails gates
+    if (!result.pass) {
+      unstable.push(capabilityId);
+    }
+  }
+  
+  return {
+    allStable: unstable.length === 0,
+    unstable
+  };
+}
+
+/**
+ * Evaluate GA Readiness
+ * 
+ * @param {Object} context - Evaluation context
+ * @param {string} context.projectDir - Project directory
+ * @param {string} [context.runId] - Run ID (for artifact verification)
+ * @param {string} [context.determinismVerdict] - Determinism verdict
+ * @param {boolean} [context.evidenceLawViolated] - Whether Evidence Law was violated
+ * @param {Object} [context.failureLedger] - Failure ledger summary
+ * @returns {Promise<GAReadinessResult>} GA readiness result
+ */
+export async function evaluateGAReadiness(context) {
+  const {
+    projectDir,
+    runId = null,
+    determinismVerdict = null,
+    evidenceLawViolated = false,
+    failureLedger = null
+  } = context;
+  
+  const blockers = [];
+  const warnings = [];
+  const inputs = {
+    gates: null,
+    determinism: determinismVerdict || 'UNKNOWN',
+    evidenceLaw: evidenceLawViolated ? 'VIOLATED' : 'ENFORCED',
+    failureLedger: failureLedger || { total: 0, bySeverity: {} },
+    artifactVerifier: null
+  };
+  
+  // 1. Phase 19: Capability Gates - 100% PASS required
+  let gateResult = null;
+  try {
+    const gateContext = await buildGateContext({ projectRoot: projectDir });
+    gateResult = evaluateAllCapabilityGates(gateContext);
+    inputs.gates = gateResult.pass ? 'PASS' : 'FAIL';
+    
+    if (!gateResult.pass) {
+      blockers.push({
+        code: GA_BLOCKER_CODE.CAPABILITY_GATES_FAILED,
+        message: `Capability gates failed: ${gateResult.summary.fail} of ${gateResult.summary.total} capabilities failed`,
+        context: {
+          total: gateResult.summary.total,
+          pass: gateResult.summary.pass,
+          fail: gateResult.summary.fail,
+          failures: gateResult.summary.allFailures
+        }
+      });
+    }
+  } catch (error) {
+    blockers.push({
+      code: GA_BLOCKER_CODE.CAPABILITY_GATES_FAILED,
+      message: `Failed to evaluate capability gates: ${error.message}`,
+      context: { error: error.message }
+    });
+  }
+  
+  // 2. Phase 20: Framework Waves - ALL STABLE required
+  if (gateResult) {
+    const wavesCheck = checkFrameworkWavesStable(gateResult);
+    inputs.frameworkWaves = wavesCheck.allStable ? 'ALL_STABLE' : 'UNSTABLE';
+    
+    if (!wavesCheck.allStable) {
+      blockers.push({
+        code: GA_BLOCKER_CODE.FRAMEWORK_WAVES_UNSTABLE,
+        message: `Framework waves not stable: ${wavesCheck.unstable.length} capabilities unstable`,
+        context: {
+          unstable: wavesCheck.unstable
+        }
+      });
+    }
+  }
+  
+  // 3. Evidence Law - No violations allowed
+  if (evidenceLawViolated) {
+    blockers.push({
+      code: GA_BLOCKER_CODE.EVIDENCE_LAW_VIOLATION,
+      message: 'Evidence Law violated: CONFIRMED findings with incomplete evidence',
+      context: {}
+    });
+  }
+  
+  // 4. Determinism - Either DETERMINISTIC or explicitly accepted
+  const acceptancePolicy = loadDeterminismAcceptancePolicy(projectDir);
+  if (determinismVerdict) {
+    if (!isDeterminismAccepted(determinismVerdict, acceptancePolicy)) {
+      blockers.push({
+        code: GA_BLOCKER_CODE.DETERMINISM_NOT_ACCEPTED,
+        message: `NON_DETERMINISTIC execution without acceptance policy`,
+        context: {
+          verdict: determinismVerdict,
+          hasPolicy: !!acceptancePolicy
+        }
+      });
+    } else if (determinismVerdict === 'NON_DETERMINISTIC' && acceptancePolicy) {
+      warnings.push({
+        code: GA_WARNING_CODE.NON_DETERMINISTIC_ACCEPTED,
+        message: `NON_DETERMINISTIC execution accepted via policy: ${acceptancePolicy.justification}`,
+        context: {
+          allowedEvents: acceptancePolicy.allowedAdaptiveEvents
+        }
+      });
+    }
+  }
+  
+  // 5. Failure Ledger - BLOCKING = 0, DEGRADED = 0 required
+  if (failureLedger) {
+    const blockingCount = failureLedger.bySeverity?.BLOCKING || 0;
+    const degradedCount = failureLedger.bySeverity?.DEGRADED || 0;
+    const warningCount = failureLedger.bySeverity?.WARNING || 0;
+    
+    if (blockingCount > 0) {
+      blockers.push({
+        code: GA_BLOCKER_CODE.BLOCKING_FAILURES,
+        message: `${blockingCount} BLOCKING failure(s) in failure ledger`,
+        context: {
+          count: blockingCount
+        }
+      });
+    }
+    
+    if (degradedCount > 0) {
+      blockers.push({
+        code: GA_BLOCKER_CODE.DEGRADED_FAILURES,
+        message: `${degradedCount} DEGRADED failure(s) in failure ledger`,
+        context: {
+          count: degradedCount
+        }
+      });
+    }
+    
+    // Check for INTERNAL or CONTRACT failures
+    const internalCount = failureLedger.byCategory?.INTERNAL || 0;
+    const contractCount = failureLedger.byCategory?.CONTRACT || 0;
+    
+    if (internalCount > 0) {
+      blockers.push({
+        code: GA_BLOCKER_CODE.INTERNAL_FAILURES,
+        message: `${internalCount} INTERNAL failure(s) in failure ledger`,
+        context: {
+          count: internalCount
+        }
+      });
+    }
+    
+    if (contractCount > 0) {
+      blockers.push({
+        code: GA_BLOCKER_CODE.CONTRACT_FAILURES,
+        message: `${contractCount} CONTRACT failure(s) in failure ledger`,
+        context: {
+          count: contractCount
+        }
+      });
+    }
+    
+    if (warningCount > 0) {
+      warnings.push({
+        code: GA_WARNING_CODE.WARNINGS_IN_LEDGER,
+        message: `${warningCount} WARNING failure(s) in failure ledger`,
+        context: {
+          count: warningCount
+        }
+      });
+    }
+  }
+  
+  // 6. Policies - All must be valid and loaded
+  try {
+    const { loadGuardrailsPolicy } = await import('../guardrails/policy.loader.js');
+    const { loadConfidencePolicy } = await import('../confidence/confidence.loader.js');
+    
+    try {
+      loadGuardrailsPolicy();
+    } catch (error) {
+      blockers.push({
+        code: GA_BLOCKER_CODE.POLICY_INVALID,
+        message: `Guardrails policy invalid: ${error.message}`,
+        context: { error: error.message }
+      });
+    }
+    
+    try {
+      loadConfidencePolicy();
+    } catch (error) {
+      blockers.push({
+        code: GA_BLOCKER_CODE.POLICY_INVALID,
+        message: `Confidence policy invalid: ${error.message}`,
+        context: { error: error.message }
+      });
+    }
+  } catch (error) {
+    blockers.push({
+      code: GA_BLOCKER_CODE.POLICY_INVALID,
+      message: `Failed to load policies: ${error.message}`,
+      context: { error: error.message }
+    });
+  }
+  
+  // 7. Artifact Verifier - Must pass with no blocking errors
+  if (runId) {
+    try {
+      const runDir = resolve(projectDir, '.verax', 'runs', runId);
+      const verification = verifyRun(runDir);
+      inputs.artifactVerifier = verification.ok ? 'PASS' : 'FAIL';
+      
+      if (!verification.ok) {
+        blockers.push({
+          code: GA_BLOCKER_CODE.ARTIFACT_VERIFIER_FAILED,
+          message: `Artifact verifier failed: ${verification.errors.length} error(s)`,
+          context: {
+            errors: verification.errors,
+            warnings: verification.warnings
+          }
+        });
+      }
+    } catch (error) {
+      blockers.push({
+        code: GA_BLOCKER_CODE.ARTIFACT_VERIFIER_FAILED,
+        message: `Failed to verify artifacts: ${error.message}`,
+        context: { error: error.message }
+      });
+    }
+  }
+  
+  // 8. Security Baseline (PHASE 21.8) - SECURITY-OK required
+  try {
+    const securityCheck = checkSecurityStatus(projectDir);
+    inputs.security = securityCheck.ok ? 'OK' : 'BLOCKED';
+    
+    if (!securityCheck.exists) {
+      blockers.push({
+        code: GA_BLOCKER_CODE.SECURITY_NOT_CHECKED,
+        message: 'Security reports not found. Run "verax security:check" first.',
+        context: {}
+      });
+    } else if (!securityCheck.ok) {
+      blockers.push({
+        code: GA_BLOCKER_CODE.SECURITY_BLOCKED,
+        message: `SECURITY-BLOCKED: ${securityCheck.blockers.join('; ')}`,
+        context: { blockers: securityCheck.blockers }
+      });
+    }
+  } catch (error) {
+    blockers.push({
+      code: GA_BLOCKER_CODE.SECURITY_NOT_CHECKED,
+      message: `Security check failed: ${error.message}`,
+      context: { error: error.message }
+    });
+  }
+  
+  // 9. Performance Budget (PHASE 21.9) - BLOCKING perf violations block GA
+  if (runId) {
+    try {
+      const { checkPerformanceStatus } = await import('../perf/perf.enforcer.js');
+      const perfCheck = checkPerformanceStatus(projectDir, runId);
+      inputs.performance = perfCheck.ok ? 'OK' : 'BLOCKED';
+      
+      if (!perfCheck.exists) {
+        // Performance report missing is not a blocker (may be from old runs)
+        inputs.performance = 'MISSING';
+      } else if (!perfCheck.ok) {
+        blockers.push({
+          code: GA_BLOCKER_CODE.PERFORMANCE_BLOCKED,
+          message: `PERFORMANCE-BLOCKED: ${perfCheck.blockers.join('; ')}`,
+          context: { blockers: perfCheck.blockers, verdict: perfCheck.verdict }
+        });
+      }
+    } catch (error) {
+      // Performance check failure is not a blocker (may be from old runs)
+      inputs.performance = 'ERROR';
+    }
+  }
+  
+  const pass = blockers.length === 0;
+  
+  const summary = {
+    pass,
+    blockersCount: blockers.length,
+    warningsCount: warnings.length,
+    checkedAt: new Date().toISOString()
+  };
+  
+  return {
+    pass,
+    blockers,
+    warnings,
+    summary,
+    inputs
+  };
+}
+

package/src/verax/core/ga/ga.enforcer.js

@@ -0,0 +1,86 @@
+/**
+ * PHASE 21.6 — GA Enforcer
+ * 
+ * Hard enforcement that blocks shipping without GA-READY status.
+ * This is not advisory. This is hard enforcement.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
+import { createInternalFailure } from '../failures/failure.factory.js';
+import { FAILURE_CODE } from '../failures/failure.types.js';
+
+/**
+ * Check if GA status exists and is READY
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run ID
+ * @returns {Object} { exists: boolean, ready: boolean, status: Object|null }
+ */
+export function checkGAStatus(projectDir, runId) {
+  const statusPath = resolve(projectDir, '.verax', 'runs', runId, 'ga.status.json');
+  
+  if (!existsSync(statusPath)) {
+    return {
+      exists: false,
+      ready: false,
+      status: null
+    };
+  }
+  
+  try {
+    const content = readFileSync(statusPath, 'utf-8');
+    const status = JSON.parse(content);
+    
+    return {
+      exists: true,
+      ready: status.gaReady === true,
+      status
+    };
+  } catch (error) {
+    return {
+      exists: false,
+      ready: false,
+      status: null,
+      error: error.message
+    };
+  }
+}
+
+/**
+ * Enforce GA readiness before release operations
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run ID
+ * @param {string} operation - Operation name (publish, release, tag)
+ * @throws {Error} If GA not ready
+ */
+export function enforceGAReadiness(projectDir, runId, operation) {
+  const check = checkGAStatus(projectDir, runId);
+  
+  if (!check.exists) {
+    const failure = createInternalFailure(
+      FAILURE_CODE.INTERNAL_UNEXPECTED_ERROR,
+      `Cannot ${operation}: GA status not found. Run 'verax ga' first.`,
+      'ga.enforcer',
+      { operation, runId },
+      null
+    );
+    throw failure;
+  }
+  
+  if (!check.ready) {
+    const blockers = check.status?.blockers || [];
+    const blockerMessages = blockers.map(b => b.message).join('; ');
+    
+    const failure = createInternalFailure(
+      FAILURE_CODE.INTERNAL_UNEXPECTED_ERROR,
+      `Cannot ${operation}: GA-BLOCKED. Blockers: ${blockerMessages}`,
+      'ga.enforcer',
+      { operation, runId, blockers },
+      null
+    );
+    throw failure;
+  }
+}
+

package/src/verax/core/guardrails/guardrails-report-writer.js

@@ -0,0 +1,109 @@
+/**
+ * PHASE 23 — Guardrails Report Writer
+ * 
+ * Writes guardrails.report.json artifact per run.
+ */
+
+import { writeFileSync } from 'fs';
+import { resolve } from 'path';
+import { ARTIFACT_REGISTRY } from '../artifacts/registry.js';
+
+/**
+ * Write guardrails report to disk.
+ * 
+ * @param {string} runDir - Absolute run directory path
+ * @param {Array} findings - Array of findings with guardrails data
+ * @param {Object} truthDecisions - Map of findingIdentity -> truthDecision
+ * @returns {string} Path to written report
+ */
+export function writeGuardrailsReport(runDir, findings, truthDecisions = {}) {
+  const reportPath = resolve(runDir, ARTIFACT_REGISTRY.guardrailsReport.filename);
+  
+  // Build per-finding entries (deterministic ordering by findingIdentity)
+  const perFinding = {};
+  const summary = {
+    totalFindings: findings.length,
+    byFinalDecision: {
+      CONFIRMED: 0,
+      SUSPECTED: 0,
+      INFORMATIONAL: 0,
+      IGNORED: 0
+    },
+    topRules: {},
+    contradictionCount: 0,
+    reconciliationCount: 0
+  };
+  
+  for (const finding of findings) {
+    const findingIdentity = finding.findingId || finding.id || `finding-${findings.indexOf(finding)}`;
+    const guardrails = finding.guardrails || {};
+    const truthDecision = truthDecisions[findingIdentity] || null;
+    
+    const appliedRules = guardrails.appliedRules || [];
+    const contradictions = guardrails.contradictions || [];
+    const finalDecision = truthDecision?.finalStatus || guardrails.finalDecision || finding.severity || 'SUSPECTED';
+    
+    // Track top rules
+    for (const rule of appliedRules) {
+      const ruleCode = rule.code || rule.ruleId || 'unknown';
+      summary.topRules[ruleCode] = (summary.topRules[ruleCode] || 0) + 1;
+    }
+    
+    // Track contradictions
+    if (contradictions.length > 0) {
+      summary.contradictionCount += contradictions.length;
+    }
+    
+    // Track reconciliation
+    if (truthDecision && truthDecision.reconciliationReasons.length > 0) {
+      summary.reconciliationCount++;
+    }
+    
+    // Track by final decision
+    if (summary.byFinalDecision[finalDecision] !== undefined) {
+      summary.byFinalDecision[finalDecision]++;
+    }
+    
+    // Build per-finding entry
+    perFinding[findingIdentity] = {
+      appliedRules: appliedRules.map(r => ({
+        code: r.code || r.ruleId,
+        severity: r.severity,
+        category: r.category
+      })),
+      contradictions: contradictions.map(c => ({
+        code: c.code,
+        message: c.message
+      })),
+      finalDecision,
+      confidenceDelta: truthDecision?.confidenceDelta || guardrails.confidenceDelta || 0,
+      confidenceBefore: truthDecision?.confidenceBefore || finding.confidence || 0,
+      confidenceAfter: truthDecision?.confidenceAfter || finding.confidence || 0,
+      reconciliationReasons: truthDecision?.reconciliationReasons || [],
+      contradictionsResolved: truthDecision?.contradictionsResolved || []
+    };
+  }
+  
+  // Sort top rules by count (descending)
+  const topRulesSorted = Object.entries(summary.topRules)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 10)
+    .map(([code, count]) => ({ code, count }));
+  
+  // Build report
+  const report = {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    summary: {
+      ...summary,
+      topRules: topRulesSorted
+    },
+    perFinding
+  };
+  
+  // Write to disk
+  writeFileSync(reportPath, JSON.stringify(report, null, 2), 'utf8');
+  
+  return reportPath;
+}
+