@veraxhq/verax 0.2.1 → 0.3.0

package/src/verax/core/guardrails/policy.defaults.js

@@ -0,0 +1,210 @@
+/**
+ * PHASE 21.4 — Guardrails Policy Defaults
+ * 
+ * Default guardrails policy extracted from hardcoded rules.
+ * All rules are mandatory and cannot be disabled.
+ */
+
+/**
+ * PHASE 17: Guardrails Rule Codes
+ */
+export const GUARDRAILS_RULE = {
+  NET_SUCCESS_NO_UI: 'GUARD_NET_SUCCESS_NO_UI',
+  ANALYTICS_ONLY: 'GUARD_ANALYTICS_ONLY',
+  SHALLOW_ROUTING: 'GUARD_SHALLOW_ROUTING',
+  UI_FEEDBACK_PRESENT: 'GUARD_UI_FEEDBACK_PRESENT',
+  INTERACTION_BLOCKED: 'GUARD_INTERACTION_BLOCKED',
+  VALIDATION_PRESENT: 'GUARD_VALIDATION_PRESENT',
+  CONTRADICT_EVIDENCE: 'GUARD_CONTRADICT_EVIDENCE',
+  VIEW_SWITCH_MINOR_CHANGE: 'GUARD_VIEW_SWITCH_MINOR_CHANGE',
+  VIEW_SWITCH_ANALYTICS_ONLY: 'GUARD_VIEW_SWITCH_ANALYTICS_ONLY',
+  VIEW_SWITCH_AMBIGUOUS: 'GUARD_VIEW_SWITCH_AMBIGUOUS',
+};
+
+/**
+ * Default guardrails policy
+ * 
+ * This policy matches the current hardcoded behavior exactly.
+ */
+export const DEFAULT_GUARDRAILS_POLICY = {
+  version: '21.4.0',
+  source: 'default',
+  rules: [
+    {
+      id: GUARDRAILS_RULE.NET_SUCCESS_NO_UI,
+      category: 'network',
+      trigger: 'Network request succeeded but no UI change observed',
+      action: 'BLOCK',
+      confidenceDelta: -0.3,
+      appliesTo: ['silent_failure', 'network'],
+      mandatory: true,
+      evaluation: {
+        type: 'network_success_no_ui',
+        conditions: {
+          networkSuccess: true,
+          noUiChange: true,
+          noErrors: true,
+          isSilentFailure: true,
+          isConfirmed: true
+        }
+      }
+    },
+    {
+      id: GUARDRAILS_RULE.ANALYTICS_ONLY,
+      category: 'network',
+      trigger: 'Only analytics/beacon requests detected',
+      action: 'BLOCK',
+      confidenceDelta: -0.5,
+      appliesTo: ['network', 'silent_failure'],
+      mandatory: true,
+      evaluation: {
+        type: 'analytics_only',
+        conditions: {
+          isAnalyticsOnly: true,
+          isNetworkFinding: true,
+          isConfirmed: true,
+          singleRequest: true
+        }
+      }
+    },
+    {
+      id: GUARDRAILS_RULE.SHALLOW_ROUTING,
+      category: 'navigation',
+      trigger: 'Hash-only or shallow routing detected',
+      action: 'BLOCK',
+      confidenceDelta: -0.2,
+      appliesTo: ['navigation', 'route'],
+      mandatory: true,
+      evaluation: {
+        type: 'shallow_routing',
+        conditions: {
+          isHashOnly: true,
+          isShallowRouting: true,
+          isNavigationFinding: true,
+          isConfirmed: true
+        }
+      }
+    },
+    {
+      id: GUARDRAILS_RULE.UI_FEEDBACK_PRESENT,
+      category: 'ui-feedback',
+      trigger: 'UI feedback is present, contradicting silent failure claim',
+      action: 'BLOCK',
+      confidenceDelta: -0.4,
+      appliesTo: ['silent_failure', 'feedback_missing'],
+      mandatory: true,
+      evaluation: {
+        type: 'ui_feedback_present',
+        conditions: {
+          hasFeedback: true,
+          isSilentFailure: true,
+          isConfirmed: true
+        }
+      }
+    },
+    {
+      id: GUARDRAILS_RULE.INTERACTION_BLOCKED,
+      category: 'state',
+      trigger: 'Interaction was disabled/blocked',
+      action: 'INFO',
+      confidenceDelta: -0.5,
+      appliesTo: ['silent_failure'],
+      mandatory: true,
+      evaluation: {
+        type: 'interaction_blocked',
+        conditions: {
+          isDisabled: true,
+          isSilentFailure: true,
+          isConfirmed: true
+        }
+      }
+    },
+    {
+      id: GUARDRAILS_RULE.VALIDATION_PRESENT,
+      category: 'validation',
+      trigger: 'Validation feedback is present, contradicting validation failure claim',
+      action: 'BLOCK',
+      confidenceDelta: -0.3,
+      appliesTo: ['validation', 'form'],
+      mandatory: true,
+      evaluation: {
+        type: 'validation_present',
+        conditions: {
+          hasValidationFeedback: true,
+          isValidationFailure: true,
+          isConfirmed: true
+        }
+      }
+    },
+    {
+      id: GUARDRAILS_RULE.CONTRADICT_EVIDENCE,
+      category: 'state',
+      trigger: 'Evidence package is incomplete',
+      action: 'BLOCK',
+      confidenceDelta: -0.2,
+      appliesTo: ['*'], // Applies to all findings
+      mandatory: true,
+      evaluation: {
+        type: 'contradict_evidence',
+        conditions: {
+          isConfirmed: true,
+          evidenceIncomplete: true
+        }
+      }
+    },
+    {
+      id: GUARDRAILS_RULE.VIEW_SWITCH_MINOR_CHANGE,
+      category: 'view-switch',
+      trigger: 'URL unchanged and change is minor (e.g. button text only)',
+      action: 'BLOCK',
+      confidenceDelta: -0.4,
+      appliesTo: ['view_switch', 'state_action'],
+      mandatory: true,
+      evaluation: {
+        type: 'view_switch_minor_change',
+        conditions: {
+          isViewSwitch: true,
+          urlUnchanged: true,
+          isMinorChange: true,
+          isConfirmed: true
+        }
+      }
+    },
+    {
+      id: GUARDRAILS_RULE.VIEW_SWITCH_ANALYTICS_ONLY,
+      category: 'view-switch',
+      trigger: 'Only analytics fired, no UI change',
+      action: 'BLOCK',
+      confidenceDelta: -0.5,
+      appliesTo: ['view_switch', 'state_action'],
+      mandatory: true,
+      evaluation: {
+        type: 'view_switch_analytics_only',
+        conditions: {
+          isViewSwitch: true,
+          analyticsOnly: true,
+          isConfirmed: true
+        }
+      }
+    },
+    {
+      id: GUARDRAILS_RULE.VIEW_SWITCH_AMBIGUOUS,
+      category: 'view-switch',
+      trigger: 'State change promise exists but UI outcome ambiguous (one signal only)',
+      action: 'DOWNGRADE',
+      confidenceDelta: -0.3,
+      appliesTo: ['view_switch', 'state_action'],
+      mandatory: true,
+      evaluation: {
+        type: 'view_switch_ambiguous',
+        conditions: {
+          isViewSwitch: true,
+          hasPromise: true,
+          ambiguousOutcome: true,
+          isConfirmed: true
+        }
+      }
+    }
+  ]
+};
+

package/src/verax/core/guardrails/policy.loader.js

@@ -0,0 +1,83 @@
+/**
+ * PHASE 21.4 — Guardrails Policy Loader
+ * 
+ * Loads guardrails policies from files or uses defaults.
+ * Validates policies and ensures all rules are mandatory.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
+import { validateGuardrailsPolicy } from './policy.schema.js';
+import { DEFAULT_GUARDRAILS_POLICY } from './policy.defaults.js';
+
+/**
+ * Load guardrails policy
+ * 
+ * @param {string|null} policyPath - Path to custom policy file (optional)
+ * @param {string} projectDir - Project directory
+ * @returns {Object} Guardrails policy
+ * @throws {Error} If policy is invalid
+ */
+export function loadGuardrailsPolicy(policyPath = null, projectDir = null) {
+  // If no custom policy path, use defaults
+  if (!policyPath) {
+    return DEFAULT_GUARDRAILS_POLICY;
+  }
+  
+  // Resolve policy path
+  const resolvedPath = projectDir ? resolve(projectDir, policyPath) : resolve(policyPath);
+  
+  // Check if file exists
+  if (!existsSync(resolvedPath)) {
+    throw new Error(`Guardrails policy file not found: ${resolvedPath}`);
+  }
+  
+  // Read and parse policy
+  let policy;
+  try {
+    const policyContent = readFileSync(resolvedPath, 'utf-8');
+    policy = JSON.parse(policyContent);
+  } catch (error) {
+    throw new Error(`Failed to load guardrails policy: ${error.message}`);
+  }
+  
+  // Validate policy
+  try {
+    validateGuardrailsPolicy(policy);
+  } catch (error) {
+    throw new Error(`Invalid guardrails policy: ${error.message}`);
+  }
+  
+  // Mark as custom
+  policy.source = 'custom';
+  
+  // HARD LOCK: Ensure all rules are mandatory
+  for (const rule of policy.rules) {
+    if (rule.mandatory !== true) {
+      throw new Error(`Guardrails rule ${rule.id} cannot be disabled (mandatory must be true)`);
+    }
+  }
+  
+  return policy;
+}
+
+/**
+ * Get policy report metadata
+ * 
+ * @param {Object} policy - Guardrails policy
+ * @returns {Object} Policy report metadata
+ */
+export function getPolicyReport(policy) {
+  return {
+    version: policy.version,
+    source: policy.source,
+    ruleCount: policy.rules.length,
+    rules: policy.rules.map(rule => ({
+      id: rule.id,
+      category: rule.category,
+      action: rule.action,
+      mandatory: rule.mandatory
+    }))
+  };
+}
+

package/src/verax/core/guardrails/policy.schema.js

@@ -0,0 +1,110 @@
+/**
+ * PHASE 21.4 — Guardrails Policy Schema
+ * 
+ * Defines the structure for guardrails policies.
+ * All rules are mandatory and cannot be disabled.
+ */
+
+/**
+ * Guardrails Policy Schema
+ * 
+ * @typedef {Object} GuardrailsPolicy
+ * @property {string} version - Policy version
+ * @property {string} source - 'default' | 'custom'
+ * @property {Array<GuardrailsRule>} rules - Array of guardrails rules
+ */
+
+/**
+ * Guardrails Rule
+ * 
+ * @typedef {Object} GuardrailsRule
+ * @property {string} id - Stable rule identifier
+ * @property {string} category - Rule category (network, navigation, ui-feedback, validation, state)
+ * @property {string} trigger - Trigger condition description
+ * @property {string} action - Action type (BLOCK / DOWNGRADE / INFO)
+ * @property {number} confidenceDelta - Confidence adjustment (must be ≤ 0)
+ * @property {Array<string>} appliesTo - Capabilities list this rule applies to
+ * @property {boolean} mandatory - Always true (cannot be disabled)
+ * @property {Object} evaluation - Evaluation function parameters
+ */
+
+/**
+ * Validate guardrails policy
+ * 
+ * @param {Object} policy - Policy to validate
+ * @throws {Error} If policy is invalid
+ */
+export function validateGuardrailsPolicy(policy) {
+  if (!policy) {
+    throw new Error('Guardrails policy is required');
+  }
+  
+  if (!policy.version || typeof policy.version !== 'string') {
+    throw new Error('Guardrails policy must have a version string');
+  }
+  
+  if (!policy.rules || !Array.isArray(policy.rules)) {
+    throw new Error('Guardrails policy must have a rules array');
+  }
+  
+  for (const rule of policy.rules) {
+    validateGuardrailsRule(rule);
+  }
+}
+
+/**
+ * Validate a guardrails rule
+ * 
+ * @param {Object} rule - Rule to validate
+ * @throws {Error} If rule is invalid
+ */
+export function validateGuardrailsRule(rule) {
+  if (!rule.id || typeof rule.id !== 'string') {
+    throw new Error('Guardrails rule must have a stable id string');
+  }
+  
+  if (!rule.category || typeof rule.category !== 'string') {
+    throw new Error('Guardrails rule must have a category string');
+  }
+  
+  const validCategories = ['network', 'navigation', 'ui-feedback', 'validation', 'state'];
+  if (!validCategories.includes(rule.category)) {
+    throw new Error(`Guardrails rule category must be one of: ${validCategories.join(', ')}`);
+  }
+  
+  if (!rule.action || typeof rule.action !== 'string') {
+    throw new Error('Guardrails rule must have an action string');
+  }
+  
+  const validActions = ['BLOCK', 'DOWNGRADE', 'INFO'];
+  if (!validActions.includes(rule.action)) {
+    throw new Error(`Guardrails rule action must be one of: ${validActions.join(', ')}`);
+  }
+  
+  if (typeof rule.confidenceDelta !== 'number') {
+    throw new Error('Guardrails rule must have a confidenceDelta number');
+  }
+  
+  // HARD LOCK: Confidence delta must be ≤ 0 (can only decrease confidence)
+  if (rule.confidenceDelta > 0) {
+    throw new Error('Guardrails rule confidenceDelta must be ≤ 0 (cannot increase confidence)');
+  }
+  
+  if (!Array.isArray(rule.appliesTo)) {
+    throw new Error('Guardrails rule appliesTo must be an array');
+  }
+  
+  // HARD LOCK: All rules are mandatory
+  if (rule.mandatory !== true) {
+    throw new Error('Guardrails rule must have mandatory: true (cannot be disabled)');
+  }
+  
+  if (!rule.trigger || typeof rule.trigger !== 'string') {
+    throw new Error('Guardrails rule must have a trigger description');
+  }
+  
+  if (!rule.evaluation || typeof rule.evaluation !== 'object') {
+    throw new Error('Guardrails rule must have an evaluation object');
+  }
+}
+

package/src/verax/core/guardrails/truth-reconciliation.js

@@ -0,0 +1,136 @@
+/**
+ * PHASE 23 — Guardrails Truth Reconciliation
+ * 
+ * Reconciles confidence with guardrails outcome to ensure consistency.
+ * Guardrails outcome is the authoritative "final claim boundary".
+ */
+
+import { CONFIDENCE_LEVEL } from '../confidence-engine.js';
+
+/**
+ * Reconciliation reason codes
+ */
+export const RECONCILIATION_REASON = {
+  GUARDRAILS_DOWNGRADE_CONFIRMED: 'RECON_GUARDRAILS_DOWNGRADE_CONFIRMED',
+  GUARDRAILS_DOWNGRADE_SUSPECTED: 'RECON_GUARDRAILS_DOWNGRADE_SUSPECTED',
+  GUARDRAILS_INFORMATIONAL: 'RECON_GUARDRAILS_INFORMATIONAL',
+  GUARDRAILS_IGNORED: 'RECON_GUARDRAILS_IGNORED',
+  CONFIDENCE_CAP_GUARDRAILS_DOWNGRADE: 'RECON_CONF_CAP_GUARDRAILS_DOWNGRADE',
+  CONFIDENCE_CAP_INFORMATIONAL: 'RECON_CONF_CAP_INFORMATIONAL',
+  CONFIDENCE_CAP_IGNORED: 'RECON_CONF_CAP_IGNORED',
+  NO_RECONCILIATION_NEEDED: 'RECON_NO_RECONCILIATION_NEEDED',
+};
+
+/**
+ * Finalize finding truth by reconciling confidence with guardrails outcome.
+ * 
+ * @param {Object} finding - Finding object (may have been modified by guardrails)
+ * @param {Object} guardrailsResult - Result from applyGuardrails
+ * @param {Object} context - Context { initialConfidence, initialConfidenceLevel }
+ * @returns {Object} { finalFinding, truthDecision }
+ */
+export function finalizeFindingTruth(finding, guardrailsResult, context = {}) {
+  const guardrails = guardrailsResult.guardrails || finding.guardrails || {};
+  const finalDecision = guardrails.finalDecision || guardrails.recommendedStatus || finding.severity || 'SUSPECTED';
+  
+  // Capture initial confidence before guardrails
+  const confidenceBefore = context.initialConfidence !== undefined 
+    ? context.initialConfidence 
+    : (finding.confidence || 0);
+  const confidenceLevelBefore = context.initialConfidenceLevel 
+    || finding.confidenceLevel 
+    || (confidenceBefore >= 0.8 ? 'HIGH' : confidenceBefore >= 0.5 ? 'MEDIUM' : confidenceBefore >= 0.2 ? 'LOW' : 'UNPROVEN');
+  
+  // Start with guardrails-adjusted confidence
+  let confidenceAfter = finding.confidence !== undefined ? finding.confidence : confidenceBefore;
+  let confidenceLevelAfter = finding.confidenceLevel || confidenceLevelBefore;
+  
+  const reconciliationReasons = [];
+  const contradictionsResolved = [];
+  
+  // Enforce truth boundaries based on final decision
+  if (finalDecision === 'CONFIRMED') {
+    // CONFIRMED must have guardrails finalDecision == CONFIRMED
+    if (guardrails.finalDecision !== 'CONFIRMED' && guardrails.recommendedStatus !== 'CONFIRMED') {
+      // This should not happen if guardrails are applied correctly, but enforce it
+      contradictionsResolved.push({
+        code: 'CONTRADICTION_CONFIRMED_WITHOUT_GUARDRAILS',
+        message: 'Finding marked CONFIRMED but guardrails did not approve CONFIRMED status'
+      });
+    }
+    // CONFIRMED can have any confidence level (no cap)
+  } else if (finalDecision === 'SUSPECTED') {
+    // SUSPECTED due to guardrails downgrade -> cap confidence at 0.69 (MEDIUM)
+    const wasDowngraded = guardrails.contradictions && guardrails.contradictions.length > 0;
+    const hasEvidenceIntentFailure = guardrails.appliedRules?.some(r => 
+      r.code?.includes('EVIDENCE') || r.message?.includes('evidence')
+    );
+    
+    if (wasDowngraded || hasEvidenceIntentFailure) {
+      if (confidenceAfter > 0.69) {
+        confidenceAfter = 0.69;
+        confidenceLevelAfter = 'MEDIUM';
+        reconciliationReasons.push(RECONCILIATION_REASON.CONFIDENCE_CAP_GUARDRAILS_DOWNGRADE);
+      }
+      reconciliationReasons.push(RECONCILIATION_REASON.GUARDRAILS_DOWNGRADE_SUSPECTED);
+    }
+  } else if (finalDecision === 'INFORMATIONAL') {
+    // INFORMATIONAL -> confidence must be LOW or UNPROVEN
+    if (confidenceAfter > 0.2) {
+      confidenceAfter = 0.2;
+      confidenceLevelAfter = 'LOW';
+      reconciliationReasons.push(RECONCILIATION_REASON.CONFIDENCE_CAP_INFORMATIONAL);
+    }
+    reconciliationReasons.push(RECONCILIATION_REASON.GUARDRAILS_INFORMATIONAL);
+  } else if (finalDecision === 'IGNORED') {
+    // IGNORED -> confidence must be UNPROVEN
+    confidenceAfter = 0;
+    confidenceLevelAfter = 'UNPROVEN';
+    reconciliationReasons.push(RECONCILIATION_REASON.CONFIDENCE_CAP_IGNORED);
+    reconciliationReasons.push(RECONCILIATION_REASON.GUARDRAILS_IGNORED);
+  }
+  
+  // If no reconciliation was needed, record it
+  if (reconciliationReasons.length === 0) {
+    reconciliationReasons.push(RECONCILIATION_REASON.NO_RECONCILIATION_NEEDED);
+  }
+  
+  // Build final finding with reconciled confidence
+  const finalFinding = {
+    ...finding,
+    severity: finalDecision,
+    status: finalDecision,
+    confidence: confidenceAfter,
+    confidenceLevel: confidenceLevelAfter,
+    guardrails: {
+      ...guardrails,
+      reconciliation: {
+        confidenceBefore,
+        confidenceAfter,
+        confidenceLevelBefore,
+        confidenceLevelAfter,
+        reconciliationReasons,
+        contradictionsResolved
+      }
+    }
+  };
+  
+  // Build truth decision
+  const truthDecision = {
+    finalStatus: finalDecision,
+    appliedGuardrails: guardrails.appliedRules?.map(r => r.code) || [],
+    confidenceBefore,
+    confidenceAfter,
+    confidenceLevelBefore,
+    confidenceLevelAfter,
+    reconciliationReasons,
+    contradictionsResolved,
+    confidenceDelta: confidenceAfter - confidenceBefore
+  };
+  
+  return {
+    finalFinding,
+    truthDecision
+  };
+}
+