@veraxhq/verax 0.2.1 → 0.3.0

package/src/verax/core/confidence-engine.js.backup

@@ -0,0 +1,471 @@
+/**
+ * PHASE 15 — Unified Confidence System
+ * 
+ * Central confidence engine that computes:
+ * - confidenceScore (0..1)
+ * - confidenceLevel (HIGH/MEDIUM/LOW/UNPROVEN)
+ * - confidenceReasons (list of stable reason codes)
+ * 
+ * Based on five pillars:
+ * A) Promise strength (AST-based promise, strong vs weak inference)
+ * B) Observation strength (URL change, DOM change, UI feedback confirmed, console errors, network outcomes)
+ * C) Correlation quality (timing alignment, matched request/route, trace linkage)
+ * D) Guardrails & contradictions (analytics filtered, shallow routing, network success + no UI change, etc.)
+ * E) Evidence completeness (before/after screenshots, traces, signals, snippets)
+ */
+
+import { computeConfidence as computeConfidenceLegacy } from '../detect/confidence-engine.js';
+
+/**
+ * PHASE 15: Confidence Levels
+ */
+export const CONFIDENCE_LEVEL = {
+  HIGH: 'HIGH',
+  MEDIUM: 'MEDIUM',
+  LOW: 'LOW',
+  UNPROVEN: 'UNPROVEN',
+};
+
+/**
+ * PHASE 15: Stable Reason Codes
+ */
+export const CONFIDENCE_REASON = {
+  // Promise Strength (A)
+  PROMISE_AST_BASED: 'PROMISE_AST_BASED',
+  PROMISE_PROVEN: 'PROMISE_PROVEN',
+  PROMISE_OBSERVED: 'PROMISE_OBSERVED',
+  PROMISE_WEAK: 'PROMISE_WEAK',
+  PROMISE_UNKNOWN: 'PROMISE_UNKNOWN',
+  
+  // Observation Strength (B)
+  OBS_URL_CHANGED: 'OBS_URL_CHANGED',
+  OBS_DOM_CHANGED: 'OBS_DOM_CHANGED',
+  OBS_UI_FEEDBACK_CONFIRMED: 'OBS_UI_FEEDBACK_CONFIRMED',
+  OBS_CONSOLE_ERRORS: 'OBS_CONSOLE_ERRORS',
+  OBS_NETWORK_FAILURE: 'OBS_NETWORK_FAILURE',
+  OBS_NETWORK_SUCCESS: 'OBS_NETWORK_SUCCESS',
+  OBS_NO_SIGNALS: 'OBS_NO_SIGNALS',
+  
+  // Correlation Quality (C)
+  CORR_TIMING_ALIGNED: 'CORR_TIMING_ALIGNED',
+  CORR_ROUTE_MATCHED: 'CORR_ROUTE_MATCHED',
+  CORR_REQUEST_MATCHED: 'CORR_REQUEST_MATCHED',
+  CORR_TRACE_LINKED: 'CORR_TRACE_LINKED',
+  CORR_WEAK_CORRELATION: 'CORR_WEAK_CORRELATION',
+  
+  // Guardrails & Contradictions (D)
+  GUARD_ANALYTICS_FILTERED: 'GUARD_ANALYTICS_FILTERED',
+  GUARD_SHALLOW_ROUTING: 'GUARD_SHALLOW_ROUTING',
+  GUARD_NETWORK_SUCCESS_NO_UI: 'GUARD_NETWORK_SUCCESS_NO_UI',
+  GUARD_UI_FEEDBACK_PRESENT: 'GUARD_UI_FEEDBACK_PRESENT',
+  GUARD_CONTRADICTION_DETECTED: 'GUARD_CONTRADICTION_DETECTED',
+  
+  // Evidence Completeness (E)
+  EVIDENCE_SCREENSHOTS: 'EVIDENCE_SCREENSHOTS',
+  EVIDENCE_TRACES: 'EVIDENCE_TRACES',
+  EVIDENCE_SIGNALS: 'EVIDENCE_SIGNALS',
+  EVIDENCE_SNIPPETS: 'EVIDENCE_SNIPPETS',
+  EVIDENCE_INCOMPLETE: 'EVIDENCE_INCOMPLETE',
+  
+  // Sensor Presence
+  SENSOR_NETWORK_PRESENT: 'SENSOR_NETWORK_PRESENT',
+  SENSOR_CONSOLE_PRESENT: 'SENSOR_CONSOLE_PRESENT',
+  SENSOR_UI_PRESENT: 'SENSOR_UI_PRESENT',
+  SENSOR_UI_FEEDBACK_PRESENT: 'SENSOR_UI_FEEDBACK_PRESENT',
+  SENSOR_MISSING: 'SENSOR_MISSING',
+};
+
+/**
+ * PHASE 15: Compute unified confidence
+ * 
+ * @param {Object} params - Confidence computation parameters
+ * @param {string} params.findingType - Type of finding
+ * @param {Object} params.expectation - Promise/expectation
+ * @param {Object} params.sensors - Sensor data
+ * @param {Object} params.comparisons - Comparison data
+ * @param {Object} params.evidence - Evidence data (optional)
+ * @returns {Object} { score, level, reasons[] }
+ */
+export function computeUnifiedConfidence({ findingType, expectation, sensors = {}, comparisons = {}, evidence = {} }) {
+  const reasons = [];
+  
+  // === PILLAR A: Promise Strength ===
+  const promiseStrength = assessPromiseStrength(expectation, reasons);
+  
+  // === PILLAR B: Observation Strength ===
+  const observationStrength = assessObservationStrength(sensors, comparisons, reasons);
+  
+  // === PILLAR C: Correlation Quality ===
+  const correlationQuality = assessCorrelationQuality(expectation, sensors, comparisons, evidence, reasons);
+  
+  // === PILLAR D: Guardrails & Contradictions ===
+  const guardrails = assessGuardrails(sensors, comparisons, findingType, reasons);
+  
+  // === PILLAR E: Evidence Completeness ===
+  const evidenceCompleteness = assessEvidenceCompleteness(evidence, sensors, reasons);
+  
+  // === COMPUTE BASE SCORE ===
+  // Weighted combination of pillars
+  const baseScore = (
+    promiseStrength * 0.25 +      // 25% weight
+    observationStrength * 0.30 +  // 30% weight
+    correlationQuality * 0.20 +   // 20% weight
+    guardrails * 0.15 +            // 15% weight
+    evidenceCompleteness * 0.10   // 10% weight
+  );
+  
+  // === APPLY CONTRADICTIONS ===
+  const contradictionPenalty = guardrails < 0.5 ? 0.3 : 0;
+  const finalScore = Math.max(0, Math.min(1, baseScore - contradictionPenalty));
+  
+  // === DETERMINE LEVEL ===
+  const level = determineConfidenceLevel(finalScore, promiseStrength, evidenceCompleteness);
+  
+  return {
+    score: finalScore,
+    level,
+    reasons: reasons.slice(0, 10), // Limit to top 10 reasons
+  };
+}
+
+/**
+ * Assess promise strength (Pillar A)
+ */
+function assessPromiseStrength(expectation, reasons) {
+  if (!expectation) {
+    reasons.push(CONFIDENCE_REASON.PROMISE_UNKNOWN);
+    return 0.0;
+  }
+  
+  // Check if AST-based
+  const isASTBased = expectation.source?.astSource || expectation.metadata?.astSource;
+  if (isASTBased) {
+    reasons.push(CONFIDENCE_REASON.PROMISE_AST_BASED);
+  }
+  
+  // Check expectation strength
+  const proof = expectation.proof || 'UNKNOWN';
+  if (proof === 'PROVEN_EXPECTATION' || proof === 'PROVEN') {
+    reasons.push(CONFIDENCE_REASON.PROMISE_PROVEN);
+    return 1.0;
+  }
+  
+  if (proof === 'OBSERVED' || expectation.confidence >= 0.8) {
+    reasons.push(CONFIDENCE_REASON.PROMISE_OBSERVED);
+    return 0.7;
+  }
+  
+  if (expectation.confidence >= 0.5) {
+    reasons.push(CONFIDENCE_REASON.PROMISE_WEAK);
+    return 0.5;
+  }
+  
+  reasons.push(CONFIDENCE_REASON.PROMISE_UNKNOWN);
+  return 0.2;
+}
+
+/**
+ * Assess observation strength (Pillar B)
+ */
+function assessObservationStrength(sensors, comparisons, reasons) {
+  let strength = 0.0;
+  let signals = 0;
+  
+  // URL change
+  const urlChanged = sensors.navigation?.urlChanged === true ||
+                     comparisons.urlChanged === true;
+  if (urlChanged) {
+    reasons.push(CONFIDENCE_REASON.OBS_URL_CHANGED);
+    strength += 0.3;
+    signals++;
+  }
+  
+  // DOM change
+  const domChanged = sensors.dom?.changed === true ||
+                     comparisons.domChanged === true;
+  if (domChanged) {
+    reasons.push(CONFIDENCE_REASON.OBS_DOM_CHANGED);
+    strength += 0.2;
+    signals++;
+  }
+  
+  // UI feedback confirmed
+  const uiFeedback = sensors.uiFeedback || {};
+  const uiFeedbackScore = uiFeedback.overallUiFeedbackScore || 0;
+  if (uiFeedbackScore > 0.5) {
+    reasons.push(CONFIDENCE_REASON.OBS_UI_FEEDBACK_CONFIRMED);
+    strength += 0.3;
+    signals++;
+  }
+  
+  // Console errors
+  const consoleErrors = sensors.console?.errors > 0 ||
+                        sensors.console?.errorCount > 0;
+  if (consoleErrors) {
+    reasons.push(CONFIDENCE_REASON.OBS_CONSOLE_ERRORS);
+    strength += 0.2;
+    signals++;
+  }
+  
+  // Network failure
+  const networkFailure = sensors.network?.failedRequests > 0 ||
+                          sensors.network?.topFailedUrls?.length > 0;
+  if (networkFailure) {
+    reasons.push(CONFIDENCE_REASON.OBS_NETWORK_FAILURE);
+    strength += 0.3;
+    signals++;
+  }
+  
+  // Network success
+  const networkSuccess = sensors.network?.successfulRequests > 0 &&
+                         !networkFailure;
+  if (networkSuccess) {
+    reasons.push(CONFIDENCE_REASON.OBS_NETWORK_SUCCESS);
+    strength += 0.1;
+    signals++;
+  }
+  
+  // No signals
+  if (signals === 0) {
+    reasons.push(CONFIDENCE_REASON.OBS_NO_SIGNALS);
+    return 0.0;
+  }
+  
+  return Math.min(1.0, strength);
+}
+
+/**
+ * Assess correlation quality (Pillar C)
+ */
+function assessCorrelationQuality(expectation, sensors, comparisons, evidence, reasons) {
+  let quality = 0.5; // Base correlation
+  
+  // Timing alignment (if trace timing is available)
+  if (evidence.timing || sensors.timing) {
+    reasons.push(CONFIDENCE_REASON.CORR_TIMING_ALIGNED);
+    quality += 0.2;
+  }
+  
+  // Route matched
+  if (evidence.correlation?.routeMatched === true ||
+      evidence.routeDefinition?.path) {
+    reasons.push(CONFIDENCE_REASON.CORR_ROUTE_MATCHED);
+    quality += 0.2;
+  }
+  
+  // Request matched
+  if (evidence.networkRequest?.matched === true ||
+      evidence.correlation?.requestMatched === true) {
+    reasons.push(CONFIDENCE_REASON.CORR_REQUEST_MATCHED);
+    quality += 0.2;
+  }
+  
+  // Trace linked
+  if (evidence.traceId || evidence.source?.file) {
+    reasons.push(CONFIDENCE_REASON.CORR_TRACE_LINKED);
+    quality += 0.1;
+  }
+  
+  // Weak correlation
+  if (quality < 0.6) {
+    reasons.push(CONFIDENCE_REASON.CORR_WEAK_CORRELATION);
+  }
+  
+  return Math.min(1.0, quality);
+}
+
+/**
+ * Assess guardrails & contradictions (Pillar D)
+ */
+function assessGuardrails(sensors, comparisons, findingType, reasons) {
+  let guardrailScore = 1.0; // Start at full score
+  
+  // Analytics filtered
+  const networkSensor = sensors.network || {};
+  const hasAnalytics = networkSensor.observedRequestUrls?.some(url =>
+    url && typeof url === 'string' && url.includes('/api/analytics')
+  );
+  if (hasAnalytics && !sensors.navigation?.urlChanged && !sensors.uiSignals?.diff?.changed) {
+    reasons.push(CONFIDENCE_REASON.GUARD_ANALYTICS_FILTERED);
+    guardrailScore -= 0.2;
+  }
+  
+  // Shallow routing
+  if (sensors.navigation?.shallowRouting === true && !sensors.navigation?.urlChanged) {
+    reasons.push(CONFIDENCE_REASON.GUARD_SHALLOW_ROUTING);
+    guardrailScore -= 0.3;
+  }
+  
+  // Network success but no UI change
+  const networkSuccess = networkSensor.successfulRequests > 0;
+  const noUIChange = !sensors.uiSignals?.diff?.changed &&
+                     !sensors.uiFeedback?.overallUiFeedbackScore;
+  if (networkSuccess && noUIChange && findingType?.includes('silent_failure')) {
+    reasons.push(CONFIDENCE_REASON.GUARD_NETWORK_SUCCESS_NO_UI);
+    guardrailScore -= 0.2;
+  }
+  
+  // UI feedback present (contradicts silent failure)
+  const uiFeedbackScore = sensors.uiFeedback?.overallUiFeedbackScore || 0;
+  if (uiFeedbackScore > 0.5 && findingType?.includes('silent_failure')) {
+    reasons.push(CONFIDENCE_REASON.GUARD_UI_FEEDBACK_PRESENT);
+    guardrailScore -= 0.4;
+  }
+  
+  // Contradiction detected
+  if (guardrailScore < 0.6) {
+    reasons.push(CONFIDENCE_REASON.GUARD_CONTRADICTION_DETECTED);
+  }
+  
+  return Math.max(0.0, guardrailScore);
+}
+
+/**
+ * Assess evidence completeness (Pillar E)
+ */
+function assessEvidenceCompleteness(evidence, sensors, reasons) {
+  let completeness = 0.0;
+  
+  // Screenshots
+  if (evidence.beforeAfter?.beforeScreenshot && evidence.beforeAfter?.afterScreenshot) {
+    reasons.push(CONFIDENCE_REASON.EVIDENCE_SCREENSHOTS);
+    completeness += 0.3;
+  }
+  
+  // Traces
+  if (evidence.traceId || sensors.traceId) {
+    reasons.push(CONFIDENCE_REASON.EVIDENCE_TRACES);
+    completeness += 0.2;
+  }
+  
+  // Signals
+  if (evidence.signals && Object.keys(evidence.signals).length > 0) {
+    reasons.push(CONFIDENCE_REASON.EVIDENCE_SIGNALS);
+    completeness += 0.2;
+  }
+  
+  // Snippets (AST source)
+  if (evidence.source?.astSource || evidence.navigationTrigger?.astSource) {
+    reasons.push(CONFIDENCE_REASON.EVIDENCE_SNIPPETS);
+    completeness += 0.3;
+  }
+  
+  // Incomplete
+  if (completeness < 0.5) {
+    reasons.push(CONFIDENCE_REASON.EVIDENCE_INCOMPLETE);
+  }
+  
+  return completeness;
+}
+
+/**
+ * Determine confidence level
+ */
+function determineConfidenceLevel(score, promiseStrength, evidenceCompleteness) {
+  // HIGH: score >= 0.8 AND promise is proven AND evidence is complete
+  if (score >= 0.8 && promiseStrength >= 0.9 && evidenceCompleteness >= 0.7) {
+    return CONFIDENCE_LEVEL.HIGH;
+  }
+  
+  // MEDIUM: score >= 0.6 OR (score >= 0.5 AND promise is observed)
+  if (score >= 0.6 || (score >= 0.5 && promiseStrength >= 0.7)) {
+    return CONFIDENCE_LEVEL.MEDIUM;
+  }
+  
+  // LOW: score >= 0.3
+  if (score >= 0.3) {
+    return CONFIDENCE_LEVEL.LOW;
+  }
+  
+  // UNPROVEN: score < 0.3
+  return CONFIDENCE_LEVEL.UNPROVEN;
+}
+
+/**
+ * PHASE 15: Compute confidence for finding (wrapper that integrates with legacy system)
+ * 
+ * @param {Object} params - Confidence computation parameters
+ * @returns {Object} { score, level, reasons[] }
+ */
+export function computeConfidenceForFinding(params) {
+  // Use legacy system for base computation
+  const legacyResult = computeConfidenceLegacy(params);
+  
+  // Normalize score from 0-100 to 0-1
+  const normalizedScore = (legacyResult.score || 0) / 100;
+  
+  // Extract reasons from legacy explain/factors
+  const reasons = extractReasonsFromLegacy(legacyResult, params);
+  
+  // Determine level
+  const level = determineConfidenceLevel(
+    normalizedScore,
+    assessPromiseStrength(params.expectation, []),
+    assessEvidenceCompleteness(params.evidence || {}, params.sensors || {}, [])
+  );
+  
+  return {
+    score: normalizedScore,
+    level,
+    reasons,
+  };
+}
+
+/**
+ * Extract stable reason codes from legacy confidence result
+ */
+function extractReasonsFromLegacy(legacyResult, params) {
+  const reasons = [];
+  
+  // Extract from explain array
+  if (legacyResult.explain && Array.isArray(legacyResult.explain)) {
+    for (const explanation of legacyResult.explain) {
+      if (typeof explanation === 'string') {
+        // Map explanation strings to reason codes
+        if (explanation.includes('AST') || explanation.includes('proven')) {
+          reasons.push(CONFIDENCE_REASON.PROMISE_PROVEN);
+        }
+        if (explanation.includes('network') && explanation.includes('failed')) {
+          reasons.push(CONFIDENCE_REASON.OBS_NETWORK_FAILURE);
+        }
+        if (explanation.includes('UI feedback')) {
+          reasons.push(CONFIDENCE_REASON.OBS_UI_FEEDBACK_CONFIRMED);
+        }
+        if (explanation.includes('contradiction')) {
+          reasons.push(CONFIDENCE_REASON.GUARD_CONTRADICTION_DETECTED);
+        }
+      }
+    }
+  }
+  
+  // Extract from factors
+  if (legacyResult.factors && Array.isArray(legacyResult.factors)) {
+    for (const factor of legacyResult.factors) {
+      if (factor.key === 'promise_strength' && factor.value === 'PROVEN') {
+        reasons.push(CONFIDENCE_REASON.PROMISE_PROVEN);
+      }
+      if (factor.key === 'ui_feedback_score' && parseFloat(factor.value) > 0.5) {
+        reasons.push(CONFIDENCE_REASON.OBS_UI_FEEDBACK_CONFIRMED);
+      }
+    }
+  }
+  
+  // Add sensor presence reasons
+  const sensors = params.sensors || {};
+  if (sensors.network && Object.keys(sensors.network).length > 0) {
+    reasons.push(CONFIDENCE_REASON.SENSOR_NETWORK_PRESENT);
+  }
+  if (sensors.console && Object.keys(sensors.console).length > 0) {
+    reasons.push(CONFIDENCE_REASON.SENSOR_CONSOLE_PRESENT);
+  }
+  if (sensors.uiSignals && Object.keys(sensors.uiSignals).length > 0) {
+    reasons.push(CONFIDENCE_REASON.SENSOR_UI_PRESENT);
+  }
+  if (sensors.uiFeedback && Object.keys(sensors.uiFeedback).length > 0) {
+    reasons.push(CONFIDENCE_REASON.SENSOR_UI_FEEDBACK_PRESENT);
+  }
+  
+  // Deduplicate
+  return [...new Set(reasons)];
+}
+

package/src/verax/core/contracts/index.js

@@ -0,0 +1,29 @@
+/**
+ * VERAX Core Contracts - Main export
+ * 
+ * Single source of truth for:
+ * - Canonical type definitions (Finding, Evidence, Confidence, Observation, Signals)
+ * - All enums (CONFIDENCE_LEVEL, FINDING_STATUS, IMPACT, USER_RISK, OWNERSHIP, etc.)
+ * - Runtime validators that enforce contracts
+ * - Evidence Law enforcement (findings without evidence cannot be CONFIRMED)
+ */
+
+export {
+  CONFIDENCE_LEVEL,
+  FINDING_STATUS,
+  FINDING_TYPE,
+  IMPACT,
+  USER_RISK,
+  OWNERSHIP,
+  EVIDENCE_TYPE,
+  ALL_ENUMS
+} from './types.js';
+
+export {
+  validateFinding,
+  validateEvidence,
+  validateConfidence,
+  validateSignals,
+  isEvidenceSubstantive,
+  enforceContractsOnFindings
+} from './validators.js';

package/src/verax/core/contracts/types.js

@@ -0,0 +1,185 @@
+/**
+ * VERAX Core Contracts - Canonical Type Definitions
+ * 
+ * This module defines the single source of truth for all core VERAX types:
+ * Finding, Evidence, Observation, Confidence, and associated enums.
+ * 
+ * These definitions enforce strict runtime contracts and form the foundation
+ * for the Evidence Law: findings without sufficient evidence cannot be Confirmed.
+ */
+
+/**
+ * Confidence Levels - measure of certainty in a finding
+ */
+export const CONFIDENCE_LEVEL = {
+  HIGH: 'HIGH',
+  MEDIUM: 'MEDIUM',
+  LOW: 'LOW',
+  UNPROVEN: 'UNPROVEN'
+};
+
+/**
+ * Finding Status - the evaluation outcome
+ */
+export const FINDING_STATUS = {
+  CONFIRMED: 'CONFIRMED',      // Evidence law satisfied: sufficient evidence exists
+  SUSPECTED: 'SUSPECTED',      // Needs evidence: signal observed but evidence incomplete
+  INFORMATIONAL: 'INFORMATIONAL', // Observation recorded, no claim of failure
+  DROPPED: 'DROPPED'           // Violated contracts, removed from report
+};
+
+/**
+ * Finding Type - category of silent failure
+ */
+export const FINDING_TYPE = {
+  NAVIGATION_SILENT_FAILURE: 'navigation_silent_failure',
+  NETWORK_SILENT_FAILURE: 'network_silent_failure',
+  STATE_SILENT_FAILURE: 'state_silent_failure',
+  OBSERVED_BREAK: 'observed_break',
+  SILENT_FAILURE: 'silent_failure',
+  FLOW_SILENT_FAILURE: 'flow_silent_failure'
+};
+
+/**
+ * Impact Level - severity of the silence
+ */
+export const IMPACT = {
+  HIGH: 'HIGH',
+  MEDIUM: 'MEDIUM',
+  LOW: 'LOW'
+};
+
+/**
+ * User Risk - how the silence affects the user
+ */
+export const USER_RISK = {
+  BLOCKS: 'BLOCKS',       // User action is blocked from completion
+  CONFUSES: 'CONFUSES',   // User is confused about what happened
+  DEGRADES: 'DEGRADES'    // User experience is degraded
+};
+
+/**
+ * Ownership - which layer failed
+ */
+export const OWNERSHIP = {
+  FRONTEND: 'FRONTEND',
+  BACKEND: 'BACKEND',
+  INTEGRATION: 'INTEGRATION',
+  ACCESSIBILITY: 'ACCESSIBILITY',
+  PERFORMANCE: 'PERFORMANCE'
+};
+
+/**
+ * Evidence Type - what provides proof
+ */
+export const EVIDENCE_TYPE = {
+  NETWORK_ACTIVITY: 'network_activity',
+  DOM_CHANGE: 'dom_change',
+  STATE_CHANGE: 'state_change',
+  URL_CHANGE: 'url_change',
+  SCREENSHOT: 'screenshot',
+  CONSOLE_OUTPUT: 'console_output',
+  SENSOR_DATA: 'sensor_data'
+};
+
+/**
+ * Canonical Finding Interface
+ * 
+ * @typedef {Object} Finding
+ * @property {string} type - One of FINDING_TYPE
+ * @property {string} [status] - One of FINDING_STATUS (defaults to SUSPECTED if evidence insufficient)
+ * @property {Object} interaction - The user interaction that triggered analysis
+ * @property {Object} evidence - Proof of the gap (REQUIRED for CONFIRMED status)
+ * @property {Object} confidence - Certainty assessment
+ * @property {Object} signals - Impact classification (impact, userRisk, ownership, grouping)
+ * @property {string} what_happened - Factual description of what occurred
+ * @property {string} what_was_expected - Factual description of code promise
+ * @property {string} what_was_observed - Factual description of observed outcome
+ * @property {string} why_it_matters - Human explanation of the gap
+ * @property {string} [humanSummary] - Human-readable summary
+ * @property {string} [actionHint] - Recommended next step
+ * @property {Object} [promise] - Promise descriptor from source code
+ * @property {string} [id] - Optional unique identifier
+ * @property {string} [findingId] - Optional deterministic ID based on expectation
+ * @property {string} [expectationId] - Optional reference to matched expectation
+ */
+
+/**
+ * Canonical Evidence Interface
+ * 
+ * @typedef {Object} Evidence
+ * @property {string} [type] - One of EVIDENCE_TYPE
+ * @property {boolean} [hasDomChange] - Whether DOM structure changed
+ * @property {boolean} [hasUrlChange] - Whether URL changed
+ * @property {boolean} [hasNetworkActivity] - Whether network requests occurred
+ * @property {boolean} [hasStateChange] - Whether application state changed
+ * @property {string} [beforeUrl] - URL before interaction
+ * @property {string} [afterUrl] - URL after interaction
+ * @property {string} [before] - Before state (screenshot path or data)
+ * @property {string} [after] - After state (screenshot path or data)
+ * @property {Object} [beforeDom] - DOM structure before
+ * @property {Object} [afterDom] - DOM structure after
+ * @property {Array} [networkRequests] - Network activity captured
+ * @property {Array} [consoleLogs] - Console messages
+ * @property {Object} [sensors] - Sensor data (navigation, uiSignals, etc.)
+ * @property {string} [source] - Source file reference
+ * @property {string} [expectedTarget] - Expected target for navigation/network
+ * @property {boolean} [targetReached] - Whether expected target was reached
+ */
+
+/**
+ * Canonical Confidence Interface
+ * 
+ * @typedef {Object} Confidence
+ * @property {string} level - One of CONFIDENCE_LEVEL
+ * @property {number} score - 0-100 confidence percentage
+ * @property {Array} [factors] - List of confidence factors
+ * @property {string} [explanation] - Detailed explanation of confidence level
+ */
+
+/**
+ * Canonical Observation Interface
+ * 
+ * @typedef {Object} Observation
+ * @property {string} type - Type of observation
+ * @property {string} selector - Element selector
+ * @property {string} label - Human-readable label
+ * @property {Object} sensors - Sensor readings before and after
+ * @property {Array} [evidence] - Array of evidence items from observation
+ */
+
+/**
+ * Canonical Signals Interface
+ * 
+ * @typedef {Object} Signals
+ * @property {string} impact - One of IMPACT
+ * @property {string} userRisk - One of USER_RISK
+ * @property {string} ownership - One of OWNERSHIP
+ * @property {Object} grouping - Grouping metadata
+ * @property {string} [grouping.groupByRoute] - Route pattern
+ * @property {string} [grouping.groupByFailureType] - Type of failure
+ * @property {string} [grouping.groupByFeature] - Feature area
+ */
+
+/**
+ * Verify all enum exports are available
+ */
+export const ALL_ENUMS = {
+  CONFIDENCE_LEVEL,
+  FINDING_STATUS,
+  FINDING_TYPE,
+  IMPACT,
+  USER_RISK,
+  OWNERSHIP,
+  EVIDENCE_TYPE
+};
+
+export default {
+  CONFIDENCE_LEVEL,
+  FINDING_STATUS,
+  FINDING_TYPE,
+  IMPACT,
+  USER_RISK,
+  OWNERSHIP,
+  EVIDENCE_TYPE
+};