@veraxhq/verax 0.2.1 → 0.4.0

package/src/verax/core/artifacts/verifier.js

@@ -0,0 +1,990 @@
+/**
+ * PHASE 6 — Artifact Verifier (The Judge)
+ * 
+ * Authoritative verifier that evaluates the integrity and completeness of a VERAX run.
+ * 
+ * This module performs strict validation of:
+ * - Artifact existence and completeness
+ * - Contract version compliance
+ * - Evidence Law enforcement
+ * - Cross-artifact consistency
+ * 
+ * @module verifier
+ */
+
+import { existsSync, readFileSync, statSync } from 'fs';
+import { join, resolve } from 'path';
+import { ARTIFACT_REGISTRY, getArtifactVersions } from './registry.js';
+import { FINDING_STATUS } from '../contracts/types.js';
+import { isEvidenceSubstantive } from '../contracts/validators.js';
+import { validateEvidencePackage, validateEvidencePackageStrict } from '../evidence-builder.js';
+import { checkConfidenceInvariants, CONFIDENCE_RANGES } from '../confidence/confidence-invariants.js';
+
+/**
+ * Verifies a VERAX run directory against the artifact registry.
+ * 
+ * @param {string} runDir - Absolute path to the run directory (.verax/runs/<runId>)
+ * @param {Object} [registrySnapshot] - Optional snapshot of artifact versions (defaults to current registry)
+ * @returns {Object} Verdict object with ok, errors, warnings, and detailed findings
+ */
+export function verifyRun(runDir, registrySnapshot = null) {
+  const errors = [];
+  const warnings = [];
+  const missingArtifacts = [];
+  const invalidArtifacts = [];
+  const contractVersionMismatches = [];
+  
+  // Use provided snapshot or current registry
+  const expectedVersions = registrySnapshot || getArtifactVersions();
+  
+  // Track enforcement summary
+  const enforcementSummary = {
+    totalFindings: 0,
+    confirmedFindings: 0,
+    suspectedFindings: 0,
+    findingsWithoutEvidence: 0,
+    enforcementApplied: false
+  };
+  
+  // Check 1: All required artifacts exist
+  for (const [key, def] of Object.entries(ARTIFACT_REGISTRY)) {
+    const artifactPath = join(runDir, def.filename);
+    
+    if (def.type === 'file') {
+      if (!existsSync(artifactPath)) {
+        missingArtifacts.push({
+          key,
+          filename: def.filename,
+          path: artifactPath,
+          reason: 'File does not exist'
+        });
+        errors.push(`Missing required artifact: ${def.filename}`);
+        continue;
+      }
+      
+      // Check if it's a valid file (not a directory)
+      try {
+        const stats = statSync(artifactPath);
+        if (!stats.isFile()) {
+          invalidArtifacts.push({
+            key,
+            filename: def.filename,
+            path: artifactPath,
+            reason: 'Expected file but found directory or other type'
+          });
+          errors.push(`Invalid artifact type: ${def.filename} is not a file`);
+          continue;
+        }
+      } catch (statError) {
+        invalidArtifacts.push({
+          key,
+          filename: def.filename,
+          path: artifactPath,
+          reason: `Cannot stat file: ${statError.message}`
+        });
+        errors.push(`Cannot access artifact: ${def.filename}`);
+        continue;
+      }
+      
+      // For JSON files, validate structure and metadata
+      if (def.filename.endsWith('.json')) {
+        try {
+          const content = readFileSync(artifactPath, 'utf-8');
+  // @ts-expect-error - readFileSync with encoding returns string
+          const data = JSON.parse(content);
+          
+          // Check contractVersion
+          if (data.contractVersion === undefined || data.contractVersion === null) {
+            contractVersionMismatches.push({
+              key,
+              filename: def.filename,
+              expected: def.contractVersion,
+              found: data.contractVersion,
+              reason: 'Missing contractVersion field'
+            });
+            errors.push(`Artifact ${def.filename} missing contractVersion`);
+          } else if (data.contractVersion !== def.contractVersion) {
+            contractVersionMismatches.push({
+              key,
+              filename: def.filename,
+              expected: def.contractVersion,
+              found: data.contractVersion,
+              reason: `Contract version mismatch: expected ${def.contractVersion}, found ${data.contractVersion}`
+            });
+            errors.push(`Artifact ${def.filename} has contractVersion ${data.contractVersion}, expected ${def.contractVersion}`);
+          }
+          
+          // Check artifactVersions map (if present)
+          if (data.artifactVersions) {
+            const artifactVersions = data.artifactVersions;
+            for (const [regKey, regDef] of Object.entries(ARTIFACT_REGISTRY)) {
+              if (artifactVersions[regKey] !== undefined) {
+                if (artifactVersions[regKey] !== regDef.contractVersion) {
+                  warnings.push(
+                    `Artifact ${def.filename} has artifactVersions[${regKey}]=${artifactVersions[regKey]}, ` +
+                    `expected ${regDef.contractVersion}`
+                  );
+                }
+              }
+            }
+          }
+          
+          // Special validation for findings.json
+          if (key === 'findings') {
+            const findingsValidation = validateFindingsArtifact(data, runDir);
+            if (findingsValidation.errors.length > 0) {
+              errors.push(...findingsValidation.errors);
+              invalidArtifacts.push({
+                key,
+                filename: def.filename,
+                path: artifactPath,
+                reason: `Findings validation failed: ${findingsValidation.errors.join('; ')}`
+              });
+            }
+            if (findingsValidation.warnings.length > 0) {
+              warnings.push(...findingsValidation.warnings);
+            }
+            
+            // Update enforcement summary
+            if (data.enforcement) {
+              enforcementSummary.enforcementApplied = true;
+              enforcementSummary.droppedCount = data.enforcement.droppedCount || 0;
+              enforcementSummary.downgradedCount = data.enforcement.downgradedCount || 0;
+            }
+            
+            // PHASE 16: Count findings by status and validate evidencePackage
+            // PHASE 22: Validate evidence intent ledger for CONFIRMED findings
+            if (Array.isArray(data.findings)) {
+              enforcementSummary.totalFindings = data.findings.length;
+              
+              // PHASE 22: Read evidence intent ledger
+              const evidenceIntentPath = join(runDir, ARTIFACT_REGISTRY.evidenceIntent.filename);
+              let evidenceIntentLedger = null;
+              if (existsSync(evidenceIntentPath)) {
+                try {
+                  const intentContent = readFileSync(evidenceIntentPath, 'utf-8');
+  // @ts-expect-error - readFileSync with encoding returns string
+                  evidenceIntentLedger = JSON.parse(intentContent);
+                } catch (e) {
+                  // Will be caught by artifact validation
+                }
+              }
+              
+              for (let i = 0; i < data.findings.length; i++) {
+                const finding = data.findings[i];
+                const severity = finding.severity || finding.status;
+                if (severity === FINDING_STATUS.CONFIRMED || severity === 'CONFIRMED') {
+                  enforcementSummary.confirmedFindings++;
+                  
+                  // PHASE 16: Check evidencePackage completeness
+                  // PHASE 21.1: HARD LOCK - CONFIRMED without complete evidencePackage → INVALID (blocking error)
+                  if (finding.evidencePackage) {
+                    try {
+                      // PHASE 21.1: Strict validation - throws if incomplete
+                      validateEvidencePackageStrict(finding.evidencePackage, severity);
+                      // If we get here, evidencePackage is complete
+                      
+                      // PHASE 22: Validate evidence intent ledger for CONFIRMED findings
+                      if (evidenceIntentLedger) {
+                        const findingIdentity = finding.findingId || finding.id || `finding-${i}`;
+                        const intentEntry = evidenceIntentLedger.entries?.find(e => e.findingIdentity === findingIdentity);
+                        
+                        if (intentEntry) {
+                          // Check that all required fields have successful capture outcomes
+                          const failedFields = [];
+                          for (const [field, outcome] of Object.entries(intentEntry.captureOutcomes || {})) {
+                            if (outcome.required && !outcome.captured && outcome.failure) {
+                              failedFields.push(field);
+                            }
+                          }
+                          
+                          if (failedFields.length > 0) {
+                            // PHASE 22: CONFIRMED finding with capture failures in intent ledger → VERIFIED_WITH_ERRORS
+                            errors.push(
+                              `EVIDENCE_INTENT_MISMATCH: Finding ${findingIdentity} is CONFIRMED but evidence.intent.json shows capture failures: ${failedFields.join(', ')}`
+                            );
+                          }
+                        } else {
+                          // PHASE 22: CONFIRMED finding missing from evidence intent ledger → warning
+                          warnings.push(
+                            `EVIDENCE_INTENT_MISSING: Finding ${findingIdentity} is CONFIRMED but missing from evidence.intent.json`
+                          );
+                        }
+                      }
+                    } catch (error) {
+                      // PHASE 21.1: HARD FAILURE - blocking error, not warning
+                      enforcementSummary.findingsWithoutEvidence++;
+                      errors.push(
+                        `Evidence Law violation: Finding marked CONFIRMED but evidencePackage is incomplete. ` +
+                        `Missing fields: ${error.missingFields?.join(', ') || 'unknown'}. ` +
+                        `(finding type: ${finding.type || 'unknown'}, index: ${i})`
+                      );
+                    }
+                  } else if (!isEvidenceSubstantive(finding.evidence)) {
+                    // PHASE 21.1: CONFIRMED without evidencePackage and without substantive evidence → HARD FAILURE
+                    enforcementSummary.findingsWithoutEvidence++;
+                    errors.push(
+                      `Evidence Law violation: Finding marked CONFIRMED but lacks evidencePackage and has insufficient evidence. ` +
+                      `(finding type: ${finding.type || 'unknown'}, index: ${i})`
+                    );
+                  }
+                } else if (severity === FINDING_STATUS.SUSPECTED || severity === 'SUSPECTED') {
+                  enforcementSummary.suspectedFindings++;
+                }
+                
+                // PHASE 24: Check confidence invariants
+                const findingIdentity = finding.findingId || finding.id || `finding-${i}`;
+                const findingConfidence = finding.confidence !== undefined ? finding.confidence : 0;
+                const invariantCheck = checkConfidenceInvariants(findingConfidence, severity, {
+                  expectationProof: finding.expectation?.proof,
+                  verificationStatus: null, // Will be set after verification
+                  guardrailsOutcome: finding.guardrails
+                });
+                
+                if (invariantCheck.violated) {
+                  errors.push(
+                    `CONFIDENCE_INVARIANT_VIOLATION: Finding ${findingIdentity} (${severity}) has confidence ${findingConfidence} which violates invariants: ${invariantCheck.violations.map(v => v.code).join(', ')}`
+                  );
+                }
+                
+                // Specific invariant checks
+                if (severity === 'CONFIRMED' && findingConfidence < CONFIDENCE_RANGES.CONFIRMED.min) {
+                  errors.push(
+                    `CONFIDENCE_INVARIANT_VIOLATION: CONFIRMED finding ${findingIdentity} has confidence ${findingConfidence} < ${CONFIDENCE_RANGES.CONFIRMED.min}`
+                  );
+                }
+                
+                if (severity === 'SUSPECTED' && findingConfidence >= CONFIDENCE_RANGES.SUSPECTED.max + 0.01) {
+                  errors.push(
+                    `CONFIDENCE_INVARIANT_VIOLATION: SUSPECTED finding ${findingIdentity} has confidence ${findingConfidence} >= ${CONFIDENCE_RANGES.SUSPECTED.max + 0.01}`
+                  );
+                }
+              }
+            }
+          }
+          
+          // PHASE 22: Special validation for evidence.intent.json
+          if (key === 'evidenceIntent') {
+            const intentValidation = validateEvidenceIntentArtifact(data, runDir);
+            if (intentValidation.errors.length > 0) {
+              errors.push(...intentValidation.errors);
+              invalidArtifacts.push({
+                key,
+                filename: def.filename,
+                path: artifactPath,
+                reason: `Evidence intent validation failed: ${intentValidation.errors.join('; ')}`
+              });
+            }
+            if (intentValidation.warnings.length > 0) {
+              warnings.push(...intentValidation.warnings);
+            }
+          }
+          
+          // PHASE 23: Special validation for guardrails.report.json
+          if (key === 'guardrailsReport') {
+            const guardrailsValidation = validateGuardrailsReportArtifact(data, runDir);
+            if (guardrailsValidation.errors.length > 0) {
+              errors.push(...guardrailsValidation.errors);
+              invalidArtifacts.push({
+                key,
+                filename: def.filename,
+                path: artifactPath,
+                reason: `Guardrails report validation failed: ${guardrailsValidation.errors.join('; ')}`
+              });
+            }
+            if (guardrailsValidation.warnings.length > 0) {
+              warnings.push(...guardrailsValidation.warnings);
+            }
+          }
+          
+          // PHASE 24: Special validation for confidence.report.json
+          if (key === 'confidenceReport') {
+            const confidenceValidation = validateConfidenceReportArtifact(data, runDir);
+            if (confidenceValidation.errors.length > 0) {
+              errors.push(...confidenceValidation.errors);
+              invalidArtifacts.push({
+                key,
+                filename: def.filename,
+                path: artifactPath,
+                reason: `Confidence report validation failed: ${confidenceValidation.errors.join('; ')}`
+              });
+            }
+            if (confidenceValidation.warnings.length > 0) {
+              warnings.push(...confidenceValidation.warnings);
+            }
+          }
+          
+          // Special validation for run.status.json
+          if (key === 'runStatus') {
+            const statusValidation = validateRunStatusArtifact(data, expectedVersions);
+            if (statusValidation.errors.length > 0) {
+              errors.push(...statusValidation.errors);
+            }
+            if (statusValidation.warnings.length > 0) {
+              warnings.push(...statusValidation.warnings);
+            }
+          }
+          
+        } catch (parseError) {
+          invalidArtifacts.push({
+            key,
+            filename: def.filename,
+            path: artifactPath,
+            reason: `Invalid JSON: ${parseError.message}`
+          });
+          errors.push(`Artifact ${def.filename} contains invalid JSON: ${parseError.message}`);
+        }
+      }
+    } else if (def.type === 'directory') {
+      if (!existsSync(artifactPath)) {
+        missingArtifacts.push({
+          key,
+          filename: def.filename,
+          path: artifactPath,
+          reason: 'Directory does not exist'
+        });
+        // Directories are optional, so this is a warning, not an error
+        warnings.push(`Missing artifact directory: ${def.filename}`);
+      } else {
+        try {
+          const stats = statSync(artifactPath);
+          if (!stats.isDirectory()) {
+            invalidArtifacts.push({
+              key,
+              filename: def.filename,
+              path: artifactPath,
+              reason: 'Expected directory but found file or other type'
+            });
+            errors.push(`Invalid artifact type: ${def.filename} is not a directory`);
+          }
+        } catch (statError) {
+          warnings.push(`Cannot access artifact directory: ${def.filename} (${statError.message})`);
+        }
+      }
+    }
+  }
+  
+  // Check 2: Cross-artifact consistency
+  const consistencyChecks = checkCrossArtifactConsistency(runDir);
+  if (consistencyChecks.errors.length > 0) {
+    errors.push(...consistencyChecks.errors);
+  }
+  if (consistencyChecks.warnings.length > 0) {
+    warnings.push(...consistencyChecks.warnings);
+  }
+  
+  // Determine overall verdict
+  // PHASE 21.1: Evidence Law violation errors are blocking - do not allow VALID_WITH_WARNINGS
+  // PHASE 22: EVIDENCE_INTENT_MISMATCH errors mark run as VERIFIED_WITH_ERRORS
+  // PHASE 23: GUARDRAILS_REPORT_MISMATCH errors mark run as VERIFIED_WITH_ERRORS
+  // PHASE 24: CONFIDENCE_INVARIANT_VIOLATION and CONFIDENCE_REPORT_MISMATCH errors mark run as VERIFIED_WITH_ERRORS
+  const hasEvidenceLawViolations = errors.some(e => e.includes('Evidence Law violation'));
+  const hasEvidenceIntentMismatches = errors.some(e => e.includes('EVIDENCE_INTENT_MISMATCH'));
+  const hasGuardrailsReportMismatches = errors.some(e => e.includes('GUARDRAILS_REPORT_MISMATCH'));
+  const hasConfidenceInvariantViolations = errors.some(e => e.includes('CONFIDENCE_INVARIANT_VIOLATION'));
+  const hasConfidenceReportMismatches = errors.some(e => e.includes('CONFIDENCE_REPORT_MISMATCH'));
+  const ok = errors.length === 0;
+  
+  // PHASE 22/23/24: If evidence intent, guardrails report, confidence invariant violations, or confidence report mismatches found, mark as VERIFIED_WITH_ERRORS
+  const verdictStatus = ok ? 'VERIFIED' : 
+    (hasEvidenceIntentMismatches || hasGuardrailsReportMismatches || hasConfidenceInvariantViolations || hasConfidenceReportMismatches ? 'VERIFIED_WITH_ERRORS' : 'INVALID');
+  
+  return {
+    ok,
+    verdictStatus, // PHASE 22: Explicit verdict status
+    errors,
+    warnings,
+    missingArtifacts,
+    invalidArtifacts,
+    contractVersionMismatches,
+    enforcementSummary,
+    verifiedAt: new Date().toISOString(),
+    // PHASE 21.1: Track evidence law violations separately
+    evidenceLawViolations: hasEvidenceLawViolations ? errors.filter(e => e.includes('Evidence Law violation')) : [],
+    // PHASE 22: Track evidence intent mismatches separately
+    evidenceIntentMismatches: hasEvidenceIntentMismatches ? errors.filter(e => e.includes('EVIDENCE_INTENT_MISMATCH')) : [],
+    // PHASE 23: Track guardrails report mismatches separately
+    guardrailsReportMismatches: hasGuardrailsReportMismatches ? errors.filter(e => e.includes('GUARDRAILS_REPORT_MISMATCH')) : [],
+    // PHASE 24: Track confidence invariant violations separately
+    confidenceInvariantViolations: hasConfidenceInvariantViolations ? errors.filter(e => e.includes('CONFIDENCE_INVARIANT_VIOLATION')) : [],
+    // PHASE 24: Track confidence report mismatches separately
+    confidenceReportMismatches: hasConfidenceReportMismatches ? errors.filter(e => e.includes('CONFIDENCE_REPORT_MISMATCH')) : []
+  };
+}
+
+/**
+ * Validates the findings artifact for Evidence Law compliance.
+ * 
+ * @param {Object} findingsData - Parsed findings.json data
+ * @param {string} runDir - Run directory path
+ * @returns {Object} { errors: [], warnings: [] }
+ */
+function validateFindingsArtifact(findingsData, runDir) {
+  const errors = [];
+  const warnings = [];
+  
+  // Check required top-level keys
+  if (!findingsData.findings || !Array.isArray(findingsData.findings)) {
+    errors.push('findings.json missing or invalid findings array');
+  }
+  
+  // Check enforcement metadata exists
+  if (!findingsData.enforcement) {
+    warnings.push('findings.json missing enforcement metadata (Evidence Law may not have been applied)');
+  } else {
+    if (typeof findingsData.enforcement.droppedCount !== 'number') {
+      warnings.push('findings.json enforcement.droppedCount is not a number');
+    }
+    if (typeof findingsData.enforcement.downgradedCount !== 'number') {
+      warnings.push('findings.json enforcement.downgradedCount is not a number');
+    }
+  }
+  
+  // Validate each finding
+  if (Array.isArray(findingsData.findings)) {
+    for (let i = 0; i < findingsData.findings.length; i++) {
+      const finding = findingsData.findings[i];
+      
+      // PHASE 16: Check for CONFIRMED findings without complete evidencePackage
+      // PHASE 21.1: HARD LOCK - CONFIRMED without complete evidencePackage → INVALID (blocking error)
+      const severity = finding.severity || finding.status;
+      if (severity === FINDING_STATUS.CONFIRMED || severity === 'CONFIRMED') {
+        if (finding.evidencePackage) {
+          try {
+            // PHASE 21.1: Strict validation - throws if incomplete
+            validateEvidencePackageStrict(finding.evidencePackage, severity);
+            // If we get here, evidencePackage is complete
+          } catch (error) {
+            // PHASE 21.1: HARD FAILURE - blocking error with Evidence Law violation code
+            errors.push(
+              `Evidence Law violation: Finding at index ${i} is marked CONFIRMED but evidencePackage is incomplete. ` +
+              `Missing fields: ${error.missingFields?.join(', ') || 'unknown'}. ` +
+              `(type: ${finding.type || 'unknown'})`
+            );
+          }
+        } else if (!finding.evidence || !isEvidenceSubstantive(finding.evidence)) {
+          // PHASE 21.1: CONFIRMED without evidencePackage and without substantive evidence → HARD FAILURE
+          errors.push(
+            `Evidence Law violation: Finding at index ${i} is marked CONFIRMED but lacks evidencePackage and has insufficient evidence. ` +
+            `(type: ${finding.type || 'unknown'})`
+          );
+        }
+      }
+      
+      // Check required fields
+      if (!finding.type) {
+        errors.push(`Finding at index ${i} missing required field: type`);
+      }
+      if (!finding.what_happened) {
+        errors.push(`Finding at index ${i} missing required field: what_happened`);
+      }
+      if (!finding.what_was_expected) {
+        errors.push(`Finding at index ${i} missing required field: what_was_expected`);
+      }
+      if (!finding.what_was_observed) {
+        errors.push(`Finding at index ${i} missing required field: what_was_observed`);
+      }
+    }
+  }
+  
+  return { errors, warnings };
+}
+
+/**
+ * PHASE 22: Validates the evidence.intent.json artifact.
+ * 
+ * @param {Object} intentData - Parsed evidence.intent.json data
+ * @param {string} runDir - Run directory path
+ * @returns {Object} { errors: [], warnings: [] }
+ */
+function validateEvidenceIntentArtifact(intentData, runDir) {
+  const errors = [];
+  const warnings = [];
+  
+  // Check required top-level keys
+  if (typeof intentData.version !== 'number') {
+    errors.push('evidence.intent.json missing or invalid version field');
+  }
+  
+  if (!intentData.entries || !Array.isArray(intentData.entries)) {
+    errors.push('evidence.intent.json missing or invalid entries array');
+    return { errors, warnings };
+  }
+  
+  // Validate schema for each entry
+  for (let i = 0; i < intentData.entries.length; i++) {
+    const entry = intentData.entries[i];
+    
+    if (!entry.findingIdentity) {
+      errors.push(`evidence.intent.json entry at index ${i} missing findingIdentity`);
+    }
+    
+    if (!entry.requiredFields || !Array.isArray(entry.requiredFields)) {
+      errors.push(`evidence.intent.json entry at index ${i} missing or invalid requiredFields`);
+    }
+    
+    if (!entry.captureOutcomes || typeof entry.captureOutcomes !== 'object') {
+      errors.push(`evidence.intent.json entry at index ${i} missing or invalid captureOutcomes`);
+    }
+    
+    if (!Array.isArray(entry.missingFields)) {
+      errors.push(`evidence.intent.json entry at index ${i} missing or invalid missingFields`);
+    }
+    
+    // Check deterministic ordering (entries should be sorted by findingIdentity)
+    if (i > 0) {
+      const prevIdentity = intentData.entries[i - 1].findingIdentity;
+      const currIdentity = entry.findingIdentity;
+      if (prevIdentity && currIdentity && prevIdentity.localeCompare(currIdentity) > 0) {
+        warnings.push(
+          `evidence.intent.json entries not in deterministic order: entry ${i} (${currIdentity}) should come before entry ${i - 1} (${prevIdentity})`
+        );
+      }
+    }
+  }
+  
+  return { errors, warnings };
+}
+
+/**
+ * Validates the run.status.json artifact.
+ * 
+ * @param {Object} statusData - Parsed run.status.json data
+ * @param {Object} expectedVersions - Expected artifact versions map
+ * @returns {Object} { errors: [], warnings: [] }
+ */
+function validateRunStatusArtifact(statusData, expectedVersions) {
+  const errors = [];
+  const warnings = [];
+  
+  // Check required fields
+  if (!statusData.status) {
+    errors.push('run.status.json missing required field: status');
+  } else if (!['RUNNING', 'COMPLETE', 'FAILED'].includes(statusData.status)) {
+    warnings.push(`run.status.json has unexpected status: ${statusData.status}`);
+  }
+  
+  // Check artifactVersions matches registry
+  if (statusData.artifactVersions) {
+    for (const [key, expectedVersion] of Object.entries(expectedVersions)) {
+      if (statusData.artifactVersions[key] === undefined) {
+        warnings.push(`run.status.json artifactVersions missing key: ${key}`);
+      } else if (statusData.artifactVersions[key] !== expectedVersion) {
+        warnings.push(
+          `run.status.json artifactVersions[${key}]=${statusData.artifactVersions[key]}, ` +
+          `expected ${expectedVersion}`
+        );
+      }
+    }
+  } else {
+    warnings.push('run.status.json missing artifactVersions map');
+  }
+  
+  return { errors, warnings };
+}
+
+/**
+ * PHASE 23: Validates the guardrails.report.json artifact.
+ * 
+ * @param {Object} reportData - Parsed guardrails.report.json data
+ * @param {string} runDir - Run directory path
+ * @returns {Object} { errors: [], warnings: [] }
+ */
+function validateGuardrailsReportArtifact(reportData, runDir) {
+  const errors = [];
+  const warnings = [];
+  
+  // Check required top-level keys
+  if (typeof reportData.version !== 'number') {
+    errors.push('guardrails.report.json missing or invalid version field');
+  }
+  
+  if (!reportData.summary || typeof reportData.summary !== 'object') {
+    errors.push('guardrails.report.json missing or invalid summary object');
+  }
+  
+  if (!reportData.perFinding || typeof reportData.perFinding !== 'object') {
+    errors.push('guardrails.report.json missing or invalid perFinding object');
+    return { errors, warnings };
+  }
+  
+  // Validate summary structure
+  if (reportData.summary) {
+    if (typeof reportData.summary.totalFindings !== 'number') {
+      errors.push('guardrails.report.json summary missing or invalid totalFindings');
+    }
+    if (!reportData.summary.byFinalDecision || typeof reportData.summary.byFinalDecision !== 'object') {
+      errors.push('guardrails.report.json summary missing or invalid byFinalDecision');
+    }
+  }
+  
+  // Validate perFinding entries
+  const findingIdentities = Object.keys(reportData.perFinding).sort();
+  for (let i = 0; i < findingIdentities.length; i++) {
+    const findingIdentity = findingIdentities[i];
+    const entry = reportData.perFinding[findingIdentity];
+    
+    if (!entry.finalDecision) {
+      errors.push(`guardrails.report.json perFinding[${findingIdentity}] missing finalDecision`);
+    }
+    
+    if (!Array.isArray(entry.appliedRules)) {
+      errors.push(`guardrails.report.json perFinding[${findingIdentity}] missing or invalid appliedRules`);
+    }
+    
+    if (!Array.isArray(entry.contradictions)) {
+      errors.push(`guardrails.report.json perFinding[${findingIdentity}] missing or invalid contradictions`);
+    }
+    
+    if (typeof entry.confidenceDelta !== 'number') {
+      errors.push(`guardrails.report.json perFinding[${findingIdentity}] missing or invalid confidenceDelta`);
+    }
+    
+    if (!Array.isArray(entry.reconciliationReasons)) {
+      errors.push(`guardrails.report.json perFinding[${findingIdentity}] missing or invalid reconciliationReasons`);
+    }
+    
+    // Check deterministic ordering (entries should be sorted by findingIdentity)
+    if (i > 0) {
+      const prevIdentity = findingIdentities[i - 1];
+      if (prevIdentity.localeCompare(findingIdentity) > 0) {
+        warnings.push(
+          `guardrails.report.json perFinding entries not in deterministic order: ${findingIdentity} should come before ${prevIdentity}`
+        );
+      }
+    }
+  }
+  
+  // PHASE 23: Cross-validate with findings.json
+  const findingsPath = join(runDir, ARTIFACT_REGISTRY.findings.filename);
+  if (existsSync(findingsPath)) {
+    try {
+      const findingsContent = readFileSync(findingsPath, 'utf-8');
+  // @ts-expect-error - readFileSync with encoding returns string
+      const findingsData = JSON.parse(findingsContent);
+      
+      if (findingsData.findings && Array.isArray(findingsData.findings)) {
+        for (const finding of findingsData.findings) {
+          const findingIdentity = finding.findingId || finding.id || null;
+          if (findingIdentity && !reportData.perFinding[findingIdentity]) {
+            errors.push(
+              `GUARDRAILS_REPORT_MISMATCH: Finding ${findingIdentity} in findings.json missing from guardrails.report.json`
+            );
+          }
+        }
+      }
+    } catch (e) {
+      // findings.json validation errors are handled elsewhere
+      warnings.push(`Could not cross-validate guardrails.report.json with findings.json: ${e.message}`);
+    }
+  }
+  
+  return { errors, warnings };
+}
+
+/**
+ * PHASE 24: Validates the confidence.report.json artifact.
+ * 
+ * @param {Object} reportData - Parsed confidence.report.json data
+ * @param {string} runDir - Run directory path
+ * @returns {Object} { errors: [], warnings: [] }
+ */
+function validateConfidenceReportArtifact(reportData, runDir) {
+  const errors = [];
+  const warnings = [];
+  
+  // Check required top-level keys
+  if (typeof reportData.version !== 'number') {
+    errors.push('confidence.report.json missing or invalid version field');
+  }
+  
+  if (!reportData.summary || typeof reportData.summary !== 'object') {
+    errors.push('confidence.report.json missing or invalid summary object');
+  }
+  
+  if (!reportData.perFinding || typeof reportData.perFinding !== 'object') {
+    errors.push('confidence.report.json missing or invalid perFinding object');
+    return { errors, warnings };
+  }
+  
+  // Validate summary structure
+  if (reportData.summary) {
+    if (typeof reportData.summary.totalFindings !== 'number') {
+      errors.push('confidence.report.json summary missing or invalid totalFindings');
+    }
+    if (!reportData.summary.byConfidenceLevel || typeof reportData.summary.byConfidenceLevel !== 'object') {
+      errors.push('confidence.report.json summary missing or invalid byConfidenceLevel');
+    }
+    if (!reportData.summary.byTruthStatus || typeof reportData.summary.byTruthStatus !== 'object') {
+      errors.push('confidence.report.json summary missing or invalid byTruthStatus');
+    }
+  }
+  
+  // Validate perFinding entries
+  const findingIdentities = Object.keys(reportData.perFinding).sort();
+  for (let i = 0; i < findingIdentities.length; i++) {
+    const findingIdentity = findingIdentities[i];
+    const entry = reportData.perFinding[findingIdentity];
+    
+    if (typeof entry.confidenceBefore !== 'number') {
+      errors.push(`confidence.report.json perFinding[${findingIdentity}] missing or invalid confidenceBefore`);
+    }
+    
+    if (typeof entry.confidenceAfter !== 'number') {
+      errors.push(`confidence.report.json perFinding[${findingIdentity}] missing or invalid confidenceAfter`);
+    }
+    
+    if (!entry.truthStatus) {
+      errors.push(`confidence.report.json perFinding[${findingIdentity}] missing truthStatus`);
+    }
+    
+    if (!Array.isArray(entry.appliedInvariants)) {
+      errors.push(`confidence.report.json perFinding[${findingIdentity}] missing or invalid appliedInvariants`);
+    }
+    
+    if (!Array.isArray(entry.invariantViolations)) {
+      errors.push(`confidence.report.json perFinding[${findingIdentity}] missing or invalid invariantViolations`);
+    }
+    
+    if (!Array.isArray(entry.explanation)) {
+      errors.push(`confidence.report.json perFinding[${findingIdentity}] missing or invalid explanation`);
+    }
+    
+    // Check deterministic ordering
+    if (i > 0) {
+      const prevIdentity = findingIdentities[i - 1];
+      if (prevIdentity.localeCompare(findingIdentity) > 0) {
+        warnings.push(
+          `confidence.report.json perFinding entries not in deterministic order: ${findingIdentity} should come before ${prevIdentity}`
+        );
+      }
+    }
+  }
+  
+  // PHASE 24: Cross-validate with findings.json
+  const findingsPath = join(runDir, ARTIFACT_REGISTRY.findings.filename);
+  if (existsSync(findingsPath)) {
+    try {
+      const findingsContent = readFileSync(findingsPath, 'utf-8');
+  // @ts-expect-error - readFileSync with encoding returns string
+      const findingsData = JSON.parse(findingsContent);
+      
+      if (findingsData.findings && Array.isArray(findingsData.findings)) {
+        for (const finding of findingsData.findings) {
+          const findingIdentity = finding.findingId || finding.id || null;
+          if (findingIdentity && !reportData.perFinding[findingIdentity]) {
+            errors.push(
+              `CONFIDENCE_REPORT_MISMATCH: Finding ${findingIdentity} in findings.json missing from confidence.report.json`
+            );
+          }
+          
+          // Validate confidence consistency
+          if (findingIdentity && reportData.perFinding[findingIdentity]) {
+            const reportEntry = reportData.perFinding[findingIdentity];
+            const findingConfidence = finding.confidence !== undefined ? finding.confidence : 0;
+            const findingStatus = finding.severity || finding.status || 'SUSPECTED';
+            
+            if (Math.abs(reportEntry.confidenceAfter - findingConfidence) > 0.001) {
+              errors.push(
+                `CONFIDENCE_REPORT_MISMATCH: Finding ${findingIdentity} confidence mismatch: findings.json=${findingConfidence}, confidence.report.json=${reportEntry.confidenceAfter}`
+              );
+            }
+            
+            if (reportEntry.truthStatus !== findingStatus) {
+              errors.push(
+                `CONFIDENCE_REPORT_MISMATCH: Finding ${findingIdentity} status mismatch: findings.json=${findingStatus}, confidence.report.json=${reportEntry.truthStatus}`
+              );
+            }
+          }
+        }
+      }
+    } catch (e) {
+      warnings.push(`Could not cross-validate confidence.report.json with findings.json: ${e.message}`);
+    }
+  }
+  
+  return { errors, warnings };
+}
+
+/**
+ * Checks cross-artifact consistency (runId, timestamps, etc.).
+ * 
+ * @param {string} runDir - Run directory path
+ * @returns {Object} { errors: [], warnings: [] }
+ */
+function checkCrossArtifactConsistency(runDir) {
+  const errors = [];
+  const warnings = [];
+  
+  try {
+    // Read run.status.json for runId and timestamps
+    const statusPath = join(runDir, ARTIFACT_REGISTRY.runStatus.filename);
+    const timestamps = [];
+    let runId = null;
+    
+    if (existsSync(statusPath)) {
+      try {
+  // @ts-expect-error - readFileSync with encoding returns string
+        const statusData = JSON.parse(readFileSync(statusPath, 'utf-8'));
+        runId = statusData.runId;
+        
+        // Collect timestamps
+        if (statusData.startedAt) timestamps.push({ artifact: 'runStatus', time: statusData.startedAt });
+        if (statusData.completedAt) timestamps.push({ artifact: 'runStatus', time: statusData.completedAt });
+        
+        if (runId) {
+          // Check findings.json has matching runId (if it has one)
+          const findingsPath = join(runDir, ARTIFACT_REGISTRY.findings.filename);
+          if (existsSync(findingsPath)) {
+            try {
+  // @ts-expect-error - readFileSync with encoding returns string
+              const findingsData = JSON.parse(readFileSync(findingsPath, 'utf-8'));
+              // Findings don't always have runId, so this is optional
+              if (findingsData.runId && findingsData.runId !== runId) {
+                warnings.push(
+                  `runId mismatch: run.status.json has ${runId}, findings.json has ${findingsData.runId}`
+                );
+              }
+            } catch (e) {
+              // Already reported as invalid artifact
+            }
+          }
+          
+          // Check summary.json has matching runId (if it has one)
+          const summaryPath = join(runDir, ARTIFACT_REGISTRY.summary.filename);
+          if (existsSync(summaryPath)) {
+            try {
+  // @ts-expect-error - readFileSync with encoding returns string
+              const summaryData = JSON.parse(readFileSync(summaryPath, 'utf-8'));
+              if (summaryData.runId && summaryData.runId !== runId) {
+                warnings.push(
+                  `runId mismatch: run.status.json has ${runId}, summary.json has ${summaryData.runId}`
+                );
+              }
+            } catch (e) {
+              // Already reported as invalid artifact
+            }
+          }
+        }
+      } catch (e) {
+        // Already reported as invalid artifact
+      }
+    }
+    
+    // Check timestamp monotonicity (soft warning) - reuse findingsPath if already read
+    if (runId) {
+      // findingsPath was already read above, but we need to check for detectedAt
+      const findingsPathForTimestamp = join(runDir, ARTIFACT_REGISTRY.findings.filename);
+      if (existsSync(findingsPathForTimestamp)) {
+        try {
+  // @ts-expect-error - readFileSync with encoding returns string
+          const findingsDataForTimestamp = JSON.parse(readFileSync(findingsPathForTimestamp, 'utf-8'));
+          if (findingsDataForTimestamp.detectedAt) timestamps.push({ artifact: 'findings', time: findingsDataForTimestamp.detectedAt });
+        } catch (e) {
+          // Ignore
+        }
+      }
+    } else {
+      // If runId wasn't found, still try to read findings for timestamp
+      const findingsPathForTimestamp = join(runDir, ARTIFACT_REGISTRY.findings.filename);
+      if (existsSync(findingsPathForTimestamp)) {
+        try {
+  // @ts-expect-error - readFileSync with encoding returns string
+          const findingsDataForTimestamp = JSON.parse(readFileSync(findingsPathForTimestamp, 'utf-8'));
+          if (findingsDataForTimestamp.detectedAt) timestamps.push({ artifact: 'findings', time: findingsDataForTimestamp.detectedAt });
+        } catch (e) {
+          // Ignore
+        }
+      }
+    }
+    
+    // Sort timestamps and check monotonicity
+    if (timestamps.length > 1) {
+      // @ts-expect-error - Date arithmetic for sorting
+      timestamps.sort((a, b) => new Date(a.time) - new Date(b.time));
+      for (let i = 1; i < timestamps.length; i++) {
+        if (new Date(timestamps[i].time) < new Date(timestamps[i - 1].time)) {
+          warnings.push(
+            `Timestamp non-monotonic: ${timestamps[i].artifact} timestamp ${timestamps[i].time} ` +
+            `is before ${timestamps[i - 1].artifact} timestamp ${timestamps[i - 1].time}`
+          );
+        }
+      }
+    }
+  } catch (error) {
+    warnings.push(`Cross-artifact consistency check failed: ${error.message}`);
+  }
+  
+  return { errors, warnings };
+}
+
+/**
+ * Formats verification verdict for CLI output.
+ * 
+ * @param {Object} verdict - Verdict from verifyRun
+ * @param {boolean} verbose - Whether to include detailed output
+ * @returns {string} Formatted output string
+ */
+export function formatVerificationOutput(verdict, verbose = false) {
+  const lines = [];
+  
+  // PHASE 22: Use verdictStatus if available
+  const status = verdict.verdictStatus || (verdict.ok ? 'VERIFIED' : 'INVALID');
+  
+  if (status === 'VERIFIED' || status === 'VALID') {
+    if (verdict.warnings.length === 0) {
+      lines.push(`Run verification: ${status}`);
+    } else {
+      lines.push(`Run verification: ${status} WITH WARNINGS`);
+      if (verbose || verdict.warnings.length <= 3) {
+        lines.push('');
+        lines.push('Warnings:');
+        verdict.warnings.slice(0, verbose ? undefined : 3).forEach(w => {
+          lines.push(`  - ${w}`);
+        });
+        if (!verbose && verdict.warnings.length > 3) {
+          lines.push(`  ... and ${verdict.warnings.length - 3} more warnings`);
+        }
+      }
+    }
+  } else if (status === 'VERIFIED_WITH_ERRORS') {
+    lines.push('Run verification: VERIFIED_WITH_ERRORS');
+    lines.push('');
+    lines.push('Blocking errors:');
+    verdict.errors.slice(0, verbose ? undefined : 3).forEach(e => {
+      lines.push(`  - ${e}`);
+    });
+    if (!verbose && verdict.errors.length > 3) {
+      lines.push(`  ... and ${verdict.errors.length - 3} more errors`);
+    }
+  }
+  
+  if (verbose) {
+    lines.push('');
+    lines.push('Enforcement Summary:');
+    lines.push(`  Total findings: ${verdict.enforcementSummary.totalFindings}`);
+    lines.push(`  CONFIRMED: ${verdict.enforcementSummary.confirmedFindings}`);
+    lines.push(`  SUSPECTED: ${verdict.enforcementSummary.suspectedFindings}`);
+    lines.push(`  Findings without evidence: ${verdict.enforcementSummary.findingsWithoutEvidence}`);
+    lines.push(`  Enforcement applied: ${verdict.enforcementSummary.enforcementApplied ? 'Yes' : 'No'}`);
+    
+    if (verdict.missingArtifacts.length > 0) {
+      lines.push('');
+      lines.push('Missing artifacts:');
+      verdict.missingArtifacts.forEach(a => {
+        lines.push(`  - ${a.filename} (${a.reason})`);
+      });
+    }
+    
+    if (verdict.invalidArtifacts.length > 0) {
+      lines.push('');
+      lines.push('Invalid artifacts:');
+      verdict.invalidArtifacts.forEach(a => {
+        lines.push(`  - ${a.filename} (${a.reason})`);
+      });
+    }
+  }
+  
+  return lines.join('\n');
+}
+