//! # Prime-Radiant: Universal Coherence Engine
//!
//! The Prime-Radiant crate implements a **universal coherence engine** using sheaf
//! Laplacian mathematics to provide structural consistency guarantees across domains.
//!
//! ## Vision
//!
//! > "Most systems try to get smarter by making better guesses. Prime-Radiant takes a
//! > different route: systems that stay stable under uncertainty by proving when the
//! > world still fits together and when it does not."
//!
//! **This is not prediction.** It is a continuously updated field of coherence that
//! shows where action is safe and where action must stop.
//!
//! ## The Universal Coherence Object
//!
//! The power of this approach lies in a **single underlying coherence object**. Once
//! the math is fixed, everything else becomes interpretation:
//!
//! | Domain | Nodes Are | Edges Are | Residual Becomes | Gate Becomes |
//! |--------|-----------|-----------|------------------|--------------|
//! | **AI Agents** | Facts, hypotheses, beliefs | Citations, logical implication | Contradiction energy | Hallucination refusal |
//! | **Finance** | Trades, positions, signals | Market dependencies, arbitrage | Regime mismatch | Trading throttle |
//! | **Medical** | Vitals, diagnoses, treatments | Physiological causality | Clinical disagreement | Escalation trigger |
//! | **Robotics** | Sensor readings, goals, plans | Physics, kinematics | Motion impossibility | Safety stop |
//! | **Security** | Identities, permissions, actions | Policy rules, trust chains | Authorization violation | Access denial |
//! | **Science** | Hypotheses, observations, models | Experimental evidence | Theory inconsistency | Pruning signal |
//!
//! ## Architecture Overview
//!
//! ```text
//! +-----------------------------------------------------------------------------+
//! |                           APPLICATION LAYER                                  |
//! |  LLM Guards | Fraud Detection | Compliance Proofs | Robotics Safety         |
//! +-----------------------------------------------------------------------------+
//!                                     |
//! +-----------------------------------------------------------------------------+
//! |                           COHERENCE GATE                                     |
//! |  Lane 0 (Reflex) | Lane 1 (Retrieval) | Lane 2 (Heavy) | Lane 3 (Human)     |
//! +-----------------------------------------------------------------------------+
//!                                     |
//! +-----------------------------------------------------------------------------+
//! |                           COHERENCE COMPUTATION                              |
//! |  Residual Calculator | Energy Aggregator | Spectral Analyzer | Fingerprints |
//! +-----------------------------------------------------------------------------+
//!                                     |
//! +-----------------------------------------------------------------------------+
//! |                           GOVERNANCE LAYER                                   |
//! |  Policy Bundles | Witness Records | Lineage Records | Threshold Tuning      |
//! +-----------------------------------------------------------------------------+
//!                                     |
//! +-----------------------------------------------------------------------------+
//! |                           KNOWLEDGE SUBSTRATE                                |
//! |  Sheaf Graph | Node States | Edge Constraints | Restriction Maps           |
//! +-----------------------------------------------------------------------------+
//!                                     |
//! +-----------------------------------------------------------------------------+
//! |                           STORAGE LAYER                                      |
//! |  PostgreSQL (Authority) | ruvector (Graph/Vector) | Event Log (Audit)       |
//! +-----------------------------------------------------------------------------+
//! ```
//!
//! ## Key Mathematical Concepts
//!
//! | Concept | Mathematical Definition | System Interpretation |
//! |---------|------------------------|----------------------|
//! | **Node** | Vertex v with state x_v | Entity with fixed-dimensional state vector |
//! | **Edge** | (u, v) connection | Constraint between entities |
//! | **Restriction Map** | rho: F(U) -> F(V) | How one state constrains another |
//! | **Residual** | r_e = rho_u(x_u) - rho_v(x_v) | **Contradiction energy** at edge |
//! | **Energy** | E(S) = sum(w_e * ||r_e||^2) | Global incoherence measure |
//! | **Gate** | E < threshold | **Refusal mechanism with witness** |
//!
//! ## Compute Ladder
//!
//! Most updates remain in a **low-latency reflex lane**, while **sustained or growing**
//! incoherence triggers escalation:
//!
//! - **Lane 0 (Reflex)**: Local residual updates, simple aggregates (<1ms)
//! - **Lane 1 (Retrieval)**: Evidence fetching, lightweight reasoning (~10ms)
//! - **Lane 2 (Heavy)**: Multi-step planning, spectral analysis (~100ms)
//! - **Lane 3 (Human)**: Human escalation for sustained incoherence
//!
//! ## Feature Flags
//!
//! | Feature | Default | Description |
//! |---------|---------|-------------|
//! | `tiles` | Yes | cognitum-gate-kernel 256-tile fabric |
//! | `sona` | Yes | Self-optimizing threshold tuning |
//! | `learned-rho` | No | GNN-learned restriction maps |
//! | `hyperbolic` | No | Hierarchy-aware Poincare energy |
//! | `mincut` | No | Subpolynomial graph partitioning |
//! | `neural-gate` | Yes | Nervous-system CoherenceGatedSystem |
//! | `attention` | No | Attention-weighted residuals (MoE, PDE) |
//! | `distributed` | No | Raft-based multi-node coherence |
//! | `postgres` | No | PostgreSQL governance storage |
//!
//! ## Example
//!
//! ```rust,ignore
//! use prime_radiant::{
//!     substrate::{SheafGraph, SheafNode, SheafEdge, RestrictionMap},
//!     coherence::{CoherenceEngine, CoherenceEnergy},
//!     execution::{CoherenceGate, ComputeLane, GateDecision},
//!     governance::{PolicyBundle, WitnessRecord},
//! };
//!
//! // Create a sheaf graph
//! let mut graph = SheafGraph::new();
//!
//! // Add nodes with state vectors
//! let node1 = SheafNode::new(vec![1.0, 0.0, 0.0]);
//! let node2 = SheafNode::new(vec![0.9, 0.1, 0.0]);
//! graph.add_node(node1);
//! graph.add_node(node2);
//!
//! // Add edge with restriction maps
//! let rho = RestrictionMap::identity(3);
//! let edge = SheafEdge::new(node1.id, node2.id, rho.clone(), rho, 1.0);
//! graph.add_edge(edge)?;
//!
//! // Compute coherence energy
//! let mut engine = CoherenceEngine::new();
//! let energy = engine.compute_energy(&graph);
//!
//! // Gate an action
//! let gate = CoherenceGate::new(policy);
//! let decision = gate.evaluate(&action, &energy);
//!
//! match decision.lane {
//!     ComputeLane::Reflex => println!("Action allowed in reflex lane"),
//!     ComputeLane::Human => println!("Escalating to human review"),
//!     _ => println!("Additional processing required"),
//! }
//! ```
//!
//! ## References
//!
//! 1. Hansen, J., & Ghrist, R. (2019). "Toward a spectral theory of cellular sheaves."
//! 2. ADR-014: Coherence Engine Architecture
//! 3. Robinson, M. (2014). "Topological Signal Processing."

#![deny(unsafe_code)]
#![warn(missing_docs)]
#![warn(clippy::all)]
#![warn(clippy::pedantic)]
#![allow(clippy::module_name_repetitions)]
#![allow(clippy::must_use_candidate)]
#![cfg_attr(docsrs, feature(doc_cfg))]

// ============================================================================
// MODULE DECLARATIONS
// ============================================================================

// -----------------------------------------------------------------------------
// Core Bounded Contexts
// -----------------------------------------------------------------------------

/// Signal ingestion - validates and normalizes incoming events
pub mod signal;

/// Knowledge substrate - sheaf graph with nodes, edges, and restriction maps
pub mod substrate;

/// Coherence computation - residuals, energy aggregation, spectral analysis
pub mod coherence;

/// Governance - policy bundles, witness records, lineage tracking
pub mod governance;

/// Action execution - coherence gate with compute ladder
pub mod execution;

/// Storage layer - PostgreSQL authority, ruvector graph/vector, event log
pub mod storage;

/// Security module - input validation, resource limits, path sanitization
pub mod security;

/// Cohomology computation - sheaf cohomology, obstruction detection, sheaf neural networks
pub mod cohomology;

// -----------------------------------------------------------------------------
// Ecosystem Integration Modules
// -----------------------------------------------------------------------------

/// Tile fabric - 256-tile WASM coherence fabric (cognitum-gate-kernel)
#[cfg(feature = "tiles")]
#[cfg_attr(docsrs, doc(cfg(feature = "tiles")))]
pub mod tiles;

/// SONA tuning - self-optimizing threshold management
#[cfg(feature = "sona")]
#[cfg_attr(docsrs, doc(cfg(feature = "sona")))]
pub mod sona_tuning;

/// Neural gate - biologically-inspired gating (ruvector-nervous-system)
#[cfg(feature = "neural-gate")]
#[cfg_attr(docsrs, doc(cfg(feature = "neural-gate")))]
pub mod neural_gate;

/// Learned restriction maps - GNN-based rho learning (ruvector-gnn)
#[cfg(feature = "learned-rho")]
#[cfg_attr(docsrs, doc(cfg(feature = "learned-rho")))]
pub mod learned_rho;

/// Hyperbolic coherence - hierarchy-aware Poincare energy
#[cfg(feature = "hyperbolic")]
#[cfg_attr(docsrs, doc(cfg(feature = "hyperbolic")))]
pub mod hyperbolic;

/// MinCut isolation - subpolynomial incoherent region isolation
#[cfg(feature = "mincut")]
#[cfg_attr(docsrs, doc(cfg(feature = "mincut")))]
pub mod mincut;

/// Attention weighting - topology-gated, MoE, PDE diffusion
#[cfg(feature = "attention")]
#[cfg_attr(docsrs, doc(cfg(feature = "attention")))]
pub mod attention;

/// Distributed consensus - Raft-based multi-node coherence
#[cfg(feature = "distributed")]
#[cfg_attr(docsrs, doc(cfg(feature = "distributed")))]
pub mod distributed;

/// RuvLLM integration - coherence-to-confidence mapping and LLM gating
#[cfg(feature = "ruvllm")]
#[cfg_attr(docsrs, doc(cfg(feature = "ruvllm")))]
pub mod ruvllm_integration;

/// GPU acceleration - wgpu-based parallel coherence computation
#[cfg(feature = "gpu")]
#[cfg_attr(docsrs, doc(cfg(feature = "gpu")))]
pub mod gpu;

/// SIMD optimizations - explicit SIMD intrinsics for high-performance computation
#[cfg(feature = "simd")]
#[cfg_attr(docsrs, doc(cfg(feature = "simd")))]
pub mod simd;

// -----------------------------------------------------------------------------
// Shared Types and Errors
// -----------------------------------------------------------------------------

/// Domain events across all bounded contexts
pub mod events;

/// Error types for the coherence engine
pub mod error;

/// Shared types (IDs, timestamps, hashes)
pub mod types;

// ============================================================================
// PUBLIC API EXPORTS
// ============================================================================

// Re-export core types for convenience
pub use types::{
    ActorId,
    ApproverId,
    EdgeId,
    GraphId,
    Hash,
    LineageId,
    NamespaceId,
    // Identifiers
    NodeId,
    PolicyBundleId,
    ScopeId,
    // Primitives
    Timestamp,
    Version,
    WitnessId,
};

pub use error::{CoherenceError, ExecutionError, GovernanceError, StorageError, SubstrateError};

// Re-export security types
pub use security::{
    GraphLimits, InputValidator, PathValidator, ResourceLimits, SecurityConfig, StateValidator,
    ValidationError, ValidationResult,
};

pub use events::DomainEvent;

// Re-export substrate types
pub use substrate::{
    NodeMetadata, RestrictionMap, SheafEdge, SheafGraph, SheafNode, SheafSubgraph,
};

// Re-export coherence types
pub use coherence::{
    CoherenceConfig, CoherenceEnergy, CoherenceEngine, EnergyHistory, ResidualCache,
};

// Re-export cohomology types
pub use cohomology::{
    Activation,
    BettiNumbers,
    Chain,
    Coboundary,
    Cochain,
    // Cocycle and coboundary
    Cocycle,
    CocycleBuilder,
    CohomologyComputer,
    CohomologyConfig,
    // Cohomology groups
    CohomologyGroup,
    CohomologyPooling,
    DiffusionResult,
    HarmonicRepresentative,
    LaplacianConfig,
    LaplacianSpectrum,
    LocalSection,
    Obstruction,
    // Obstruction detection
    ObstructionDetector,
    ObstructionIndicator,
    ObstructionReport,
    ObstructionSeverity,
    PoolingMethod,
    // Sheaf types
    Sheaf,
    SheafBuilder,
    SheafConvolution,
    // Diffusion
    SheafDiffusion,
    SheafDiffusionConfig,
    // Laplacian
    SheafLaplacian,
    SheafNeuralConfig,
    // Neural network layers
    SheafNeuralLayer,
    SheafSection,
    // Simplex and simplicial complex
    Simplex,
    SimplexId,
    SimplicialComplex,
    Stalk,
};

// Re-export governance types
pub use governance::{
    ApprovalSignature,
    ApproverId as GovApproverId,
    EntityRef,
    EscalationRule,
    // Top-level error
    GovernanceError as GovError,
    // Common types
    Hash as GovHash,
    LineageError,
    LineageId as GovLineageId,
    // Lineage types
    LineageRecord,
    LineageRepository,
    Operation,
    // Policy types
    PolicyBundle,
    PolicyBundleBuilder,
    PolicyBundleRef,
    PolicyBundleStatus,
    PolicyError,
    // Repository traits
    PolicyRepository,
    ThresholdConfig,
    Timestamp as GovTimestamp,
    Version as GovVersion,
    WitnessChainError,
    WitnessError,
    WitnessId as GovWitnessId,
    // Witness types (governance's own witness format)
    WitnessRecord as GovWitnessRecord,
    WitnessRepository,
};

// Re-export execution types (coherence gate and compute ladder)
pub use execution::{
    // Actions
    Action,
    ActionExecutor,
    ActionId,
    ActionImpact,
    ActionMetadata,
    ActionResult,
    // Gate and ladder
    CoherenceGate,
    ComputeLane,
    EnergySnapshot,
    EscalationReason,
    ExecutionContext,
    ExecutionResult,
    ExecutorConfig,
    ExecutorStats,
    GateDecision,
    LaneThresholds,
    PolicyBundleRef as ExecutionPolicyRef,
    // Scope
    ScopeId as ExecutionScopeId,
    WitnessId as ExecWitnessId,
    // Witness (execution's witness format - aliased to avoid conflict with types::WitnessId)
    WitnessRecord as ExecWitnessRecord,
};

// Conditional re-exports based on features

#[cfg(feature = "tiles")]
pub use tiles::{CoherenceFabric, FabricReport, ShardMap, TileAdapter};

#[cfg(feature = "sona")]
pub use sona_tuning::{
    SonaThresholdTuner, ThresholdAdjustment, ThresholdConfig as SonaThresholdConfig,
};

#[cfg(feature = "neural-gate")]
pub use neural_gate::{NeuralCoherenceGate, NeuralDecision, WitnessEncoding};

#[cfg(feature = "learned-rho")]
pub use learned_rho::{LearnedRestrictionMap, RestrictionMapConfig, TrainingBatch};

#[cfg(feature = "hyperbolic")]
pub use hyperbolic::{
    DepthComputer, HierarchyLevel, HyperbolicAdapter, HyperbolicCoherence,
    HyperbolicCoherenceConfig, HyperbolicEnergy, WeightedResidual,
};

#[cfg(feature = "mincut")]
pub use mincut::{
    IncoherenceIsolator, IsolationMetrics, IsolationRegion, IsolationResult, MinCutAdapter,
    MinCutConfig,
};

#[cfg(feature = "attention")]
pub use attention::{
    AttentionAdapter, AttentionCoherence, AttentionCoherenceConfig, AttentionEnergyAnalysis,
    DiffusionSmoothing, ExpertRouting, MoEResidualProcessor, SmoothedEnergy, TopologyGate,
    TopologyGateResult, WeightedEdgeResidual,
};

#[cfg(feature = "distributed")]
pub use distributed::{
    ClusterStatus, CoherenceStateMachine, CoherenceStatus, DistributedCoherence,
    DistributedCoherenceConfig, NodeRole, RaftAdapter,
};

#[cfg(feature = "ruvllm")]
pub use ruvllm_integration::{
    CoherenceConfidence, ConfidenceLevel, ConfidenceScore, EnergyContributor,
};

#[cfg(feature = "gpu")]
pub use gpu::{
    BindingDesc,
    BindingType,
    BufferKey,
    BufferUsage,
    BufferUsageFlags,
    ComputeEnergyKernel,
    // Pipeline management
    ComputePipeline,
    // Kernel types
    ComputeResidualsKernel,
    DispatchBuilder,
    DispatchConfig,
    // Buffer management
    GpuBuffer,
    GpuBufferManager,
    GpuBufferPool,
    GpuCapabilities,
    GpuCoherenceEnergy,
    // GPU coherence engine
    GpuCoherenceEngine,
    GpuConfig,
    // Device management
    GpuDevice,
    GpuDeviceInfo,
    GpuDeviceOptions,
    // Dispatch and synchronization
    GpuDispatcher,
    // Errors
    GpuError,
    GpuResult,
    PipelineCache,
    SheafAttentionKernel,
    TokenRoutingKernel,
};

#[cfg(feature = "simd")]
pub use simd::{
    batch_lane_assignment_simd, batch_residuals_simd, best_simd_width, dot_product_simd,
    matmul_simd, matvec_simd, norm_squared_simd, scale_simd, subtract_simd,
    weighted_energy_sum_simd, SimdContext, SimdWidth,
};

// ============================================================================
// PRELUDE MODULE
// ============================================================================

/// Convenient imports for common use cases
pub mod prelude {
    pub use crate::{
        CoherenceEnergy,

        // Coherence
        CoherenceEngine,
        // Errors
        CoherenceError,
        // Execution
        CoherenceGate,
        CohomologyComputer,
        CohomologyGroup,
        ComputeLane,

        // Events
        DomainEvent,
        EdgeId,
        GateDecision,
        GovWitnessRecord as WitnessRecord, // Re-export governance witness as default

        GraphId,
        Hash,
        // Security
        InputValidator,
        // Core types
        NodeId,
        ObstructionDetector,
        // Governance
        PolicyBundle,
        RestrictionMap,

        ScopeId,
        SecurityConfig,

        SheafDiffusion,
        SheafEdge,
        // Substrate
        SheafGraph,
        // Cohomology
        SheafLaplacian,
        SheafNeuralLayer,

        SheafNode,
        ThresholdConfig,
        Timestamp,
        ValidationError,

        Version,
    };
}

// ============================================================================
// CRATE-LEVEL CONSTANTS
// ============================================================================

/// Crate version
pub const VERSION: &str = env!("CARGO_PKG_VERSION");

/// Default dimension for state vectors
pub const DEFAULT_STATE_DIM: usize = 64;

/// Default number of tiles in the fabric
pub const DEFAULT_TILE_COUNT: usize = 256;

/// Default persistence window for threshold detection (seconds)
pub const DEFAULT_PERSISTENCE_WINDOW_SECS: u64 = 300;

// ============================================================================
// PERFORMANCE TARGETS (ADR-014)
// ============================================================================

/// Performance targets from ADR-014
pub mod targets {
    /// Single residual calculation target: < 1us
    pub const RESIDUAL_CALC_US: u64 = 1;

    /// Full graph energy (10K nodes) target: < 10ms
    pub const FULL_ENERGY_MS: u64 = 10;

    /// Incremental update (1 node) target: < 100us
    pub const INCREMENTAL_UPDATE_US: u64 = 100;

    /// Gate evaluation target: < 500us
    pub const GATE_EVAL_US: u64 = 500;

    /// Witness persistence target: < 5ms
    pub const WITNESS_PERSIST_MS: u64 = 5;

    /// Tile tick (256 tiles parallel) target: < 1ms
    pub const TILE_TICK_MS: u64 = 1;

    /// SONA instant adaptation target: < 0.05ms (50us)
    pub const SONA_ADAPT_US: u64 = 50;

    /// MinCut update (amortized) target: n^o(1)
    pub const MINCUT_SUBPOLY: bool = true;

    /// HDC witness encoding target: < 10us
    pub const HDC_ENCODE_US: u64 = 10;

    /// Hyperbolic distance target: < 500ns
    pub const HYPERBOLIC_DIST_NS: u64 = 500;

    /// Attention-weighted energy target: < 5ms
    pub const ATTENTION_ENERGY_MS: u64 = 5;

    /// Distributed consensus target: < 50ms
    pub const CONSENSUS_MS: u64 = 50;
}