converge_core/

engine.rs

// Copyright 2024-2025 Aprio One AB, Sweden
// Author: Kenneth Pernyer, kenneth@aprio.one
// SPDX-License-Identifier: LicenseRef-Proprietary
// All rights reserved. This source code is proprietary and confidential.
// Unauthorized copying, modification, or distribution is strictly prohibited.

//! Converge execution engine.
//!
//! The engine owns convergence:
//! - Registers agents and builds dependency index
//! - Runs the convergence loop
//! - Merges effects serially
//! - Detects fixed point

use std::collections::{HashMap, HashSet};
use std::sync::Arc;
use strum::IntoEnumIterator;
use tracing::{debug, info, info_span};

use crate::agent::{Agent, AgentId};
use crate::context::{Context, ContextKey, Fact};
use crate::effect::AgentEffect;
use crate::error::ConvergeError;
use crate::invariant::{Invariant, InvariantError, InvariantId, InvariantRegistry};

/// Callback trait for streaming fact emissions during convergence.
///
/// Implement this trait to receive real-time notifications as the engine
/// executes. Useful for:
/// - Streaming output to CLI/UI
/// - Progress monitoring
/// - Real-time fact logging
///
/// # Thread Safety
///
/// Callbacks must be `Send + Sync` as they may be called from the engine's
/// execution context. Keep implementations lightweight to avoid blocking
/// the convergence loop.
pub trait StreamingCallback: Send + Sync {
    /// Called at the start of each convergence cycle.
    fn on_cycle_start(&self, cycle: u32);

    /// Called when a fact is added to the context during merge.
    fn on_fact(&self, cycle: u32, fact: &Fact);

    /// Called at the end of each convergence cycle.
    fn on_cycle_end(&self, cycle: u32, facts_added: usize);
}

/// Budget limits for execution.
///
/// Guarantees termination even with misbehaving agents.
#[derive(Debug, Clone)]
pub struct Budget {
    /// Maximum execution cycles before forced termination.
    pub max_cycles: u32,
    /// Maximum facts allowed in context.
    pub max_facts: u32,
}

impl Default for Budget {
    fn default() -> Self {
        Self {
            max_cycles: 100,
            max_facts: 10_000,
        }
    }
}

/// Result of a converged execution.
#[derive(Debug)]
pub struct ConvergeResult {
    /// Final context state.
    pub context: Context,
    /// Number of cycles executed.
    pub cycles: u32,
    /// Whether convergence was reached (vs budget exhaustion).
    pub converged: bool,
}

/// The Converge execution engine.
///
/// Owns agent registration, dependency indexing, and the convergence loop.
pub struct Engine {
    /// Registered agents in order of registration.
    agents: Vec<Box<dyn Agent>>,
    /// Dependency index: `ContextKey` → `AgentId`s interested in that key.
    index: HashMap<ContextKey, Vec<AgentId>>,
    /// Agents with no dependencies (run on every cycle).
    always_eligible: Vec<AgentId>,
    /// Next agent ID to assign.
    next_id: u32,
    /// Execution budget.
    budget: Budget,
    /// Runtime invariants (Gherkin compiled to predicates).
    invariants: InvariantRegistry,
    /// Optional streaming callback for real-time fact emission.
    streaming_callback: Option<Arc<dyn StreamingCallback>>,
}

impl Default for Engine {
    fn default() -> Self {
        Self::new()
    }
}

impl Engine {
    /// Creates a new engine with default budget.
    #[must_use]
    pub fn new() -> Self {
        Self {
            agents: Vec::new(),
            index: HashMap::new(),
            always_eligible: Vec::new(),
            next_id: 0,
            budget: Budget::default(),
            invariants: InvariantRegistry::new(),
            streaming_callback: None,
        }
    }

    /// Creates a new engine with custom budget.
    #[must_use]
    pub fn with_budget(budget: Budget) -> Self {
        Self {
            budget,
            ..Self::new()
        }
    }

    /// Sets the execution budget.
    pub fn set_budget(&mut self, budget: Budget) {
        self.budget = budget;
    }

    /// Sets a streaming callback for real-time fact emission.
    ///
    /// When set, the callback will be invoked:
    /// - At the start of each convergence cycle
    /// - When each fact is added to the context
    /// - At the end of each convergence cycle
    ///
    /// # Example
    ///
    /// ```ignore
    /// use std::sync::Arc;
    /// use converge_core::{Engine, StreamingCallback, Fact};
    ///
    /// struct MyCallback;
    /// impl StreamingCallback for MyCallback {
    ///     fn on_cycle_start(&self, cycle: u32) {
    ///         println!("[cycle:{}] started", cycle);
    ///     }
    ///     fn on_fact(&self, cycle: u32, fact: &Fact) {
    ///         println!("[cycle:{}] fact:{} | {}", cycle, fact.id, fact.content);
    ///     }
    ///     fn on_cycle_end(&self, cycle: u32, facts_added: usize) {
    ///         println!("[cycle:{}] ended with {} facts", cycle, facts_added);
    ///     }
    /// }
    ///
    /// let mut engine = Engine::new();
    /// engine.set_streaming(Arc::new(MyCallback));
    /// ```
    pub fn set_streaming(&mut self, callback: Arc<dyn StreamingCallback>) {
        self.streaming_callback = Some(callback);
    }

    /// Clears the streaming callback.
    pub fn clear_streaming(&mut self) {
        self.streaming_callback = None;
    }

    /// Registers an invariant (compiled Gherkin predicate).
    ///
    /// Invariants are checked at different points depending on their class:
    /// - Structural: after every merge
    /// - Semantic: at end of each cycle
    /// - Acceptance: when convergence is claimed
    pub fn register_invariant(&mut self, invariant: impl Invariant + 'static) -> InvariantId {
        let name = invariant.name().to_string();
        let class = invariant.class();
        let id = self.invariants.register(invariant);
        debug!(invariant = %name, ?class, ?id, "Registered invariant");
        id
    }

    /// Registers an agent and returns its ID.
    ///
    /// Agents are assigned monotonically increasing IDs.
    /// The dependency index is updated incrementally.
    pub fn register(&mut self, agent: impl Agent + 'static) -> AgentId {
        let id = AgentId(self.next_id);
        self.next_id += 1;

        let name = agent.name().to_string();
        let deps: Vec<ContextKey> = agent.dependencies().to_vec();

        // Update dependency index
        if deps.is_empty() {
            // No dependencies = always eligible for consideration
            self.always_eligible.push(id);
        } else {
            for &key in &deps {
                self.index.entry(key).or_default().push(id);
            }
        }

        self.agents.push(Box::new(agent));
        debug!(agent = %name, ?id, ?deps, "Registered agent");
        id
    }

    /// Returns the number of registered agents.
    #[must_use]
    pub fn agent_count(&self) -> usize {
        self.agents.len()
    }

    /// Runs the convergence loop until fixed point or budget exhaustion.
    ///
    /// # Algorithm
    ///
    /// ```text
    /// initialize context
    /// mark all keys as dirty (first cycle)
    ///
    /// repeat:
    ///   clear dirty flags
    ///   find eligible agents (dirty deps + accepts)
    ///   execute eligible agents (parallel read)
    ///   merge effects (serial, deterministic order)
    ///   track which keys changed
    /// until no keys changed OR budget exhausted
    /// ```
    ///
    /// # Errors
    ///
    /// Returns `ConvergeError::BudgetExhausted` if:
    /// - `max_cycles` is exceeded
    /// - `max_facts` is exceeded
    pub fn run(&mut self, mut context: Context) -> Result<ConvergeResult, ConvergeError> {
        let _span = info_span!("engine_run").entered();
        let mut cycles: u32 = 0;

        // First cycle: we treat all existing keys in the context as "dirty"
        // to ensure that dependency-indexed agents are triggered by initial data.
        let mut dirty_keys: Vec<ContextKey> = context.all_keys();

        loop {
            cycles += 1;
            let _cycle_span = info_span!("convergence_cycle", cycle = cycles).entered();
            info!(cycle = cycles, "Starting convergence cycle");

            // Emit cycle start callback
            if let Some(ref cb) = self.streaming_callback {
                cb.on_cycle_start(cycles);
            }

            // Budget check: cycles
            if cycles > self.budget.max_cycles {
                return Err(ConvergeError::BudgetExhausted {
                    kind: format!("max_cycles ({})", self.budget.max_cycles),
                });
            }

            // Find eligible agents
            let eligible = {
                let _span = info_span!("eligible_agents").entered();
                let e = self.find_eligible(&context, &dirty_keys);
                info!(count = e.len(), "Found eligible agents");
                e
            };

            if eligible.is_empty() {
                info!("No more eligible agents. Convergence reached.");
                // Emit cycle end callback (0 facts added)
                if let Some(ref cb) = self.streaming_callback {
                    cb.on_cycle_end(cycles, 0);
                }
                // No agents want to run — check acceptance invariants before declaring convergence
                if let Err(e) = self.invariants.check_acceptance(&context) {
                    self.emit_diagnostic(&mut context, &e);
                    return Err(ConvergeError::InvariantViolation {
                        name: e.invariant_name,
                        class: e.class,
                        reason: e.violation.reason,
                        context: Box::new(context),
                    });
                }

                return Ok(ConvergeResult {
                    context,
                    cycles,
                    converged: true,
                });
            }

            // Execute eligible agents and collect effects
            let effects = {
                let _span = info_span!("execute_agents", count = eligible.len()).entered();
                #[allow(deprecated)]
                let eff = self.execute_agents(&context, &eligible);
                info!(count = eff.len(), "Executed agents");
                eff
            };

            // Merge effects serially (deterministic order by AgentId)
            let (new_dirty_keys, facts_added) = {
                let _span = info_span!("merge_effects", count = effects.len()).entered();
                let (d, count) = self.merge_effects(&mut context, effects, cycles)?;
                info!(count = d.len(), "Merged effects");
                (d, count)
            };
            dirty_keys = new_dirty_keys;

            // Emit cycle end callback
            if let Some(ref cb) = self.streaming_callback {
                cb.on_cycle_end(cycles, facts_added);
            }

            // STRUCTURAL INVARIANTS: checked after every merge
            // Violation = immediate failure, no recovery
            if let Err(e) = self.invariants.check_structural(&context) {
                self.emit_diagnostic(&mut context, &e);
                return Err(ConvergeError::InvariantViolation {
                    name: e.invariant_name,
                    class: e.class,
                    reason: e.violation.reason,
                    context: Box::new(context),
                });
            }

            // Convergence check: no keys changed
            if dirty_keys.is_empty() {
                // Check acceptance invariants before declaring convergence
                if let Err(e) = self.invariants.check_acceptance(&context) {
                    self.emit_diagnostic(&mut context, &e);
                    return Err(ConvergeError::InvariantViolation {
                        name: e.invariant_name,
                        class: e.class,
                        reason: e.violation.reason,
                        context: Box::new(context),
                    });
                }

                return Ok(ConvergeResult {
                    context,
                    cycles,
                    converged: true,
                });
            }

            // SEMANTIC INVARIANTS: checked at end of each cycle
            // Violation = blocks convergence (could allow recovery in future)
            if let Err(e) = self.invariants.check_semantic(&context) {
                self.emit_diagnostic(&mut context, &e);
                return Err(ConvergeError::InvariantViolation {
                    name: e.invariant_name,
                    class: e.class,
                    reason: e.violation.reason,
                    context: Box::new(context),
                });
            }

            // Budget check: facts
            let fact_count = self.count_facts(&context);
            if fact_count > self.budget.max_facts {
                return Err(ConvergeError::BudgetExhausted {
                    kind: format!("max_facts ({} > {})", fact_count, self.budget.max_facts),
                });
            }
        }
    }

    /// Finds agents eligible to run based on dirty keys and `accepts()`.
    fn find_eligible(&self, context: &Context, dirty_keys: &[ContextKey]) -> Vec<AgentId> {
        let mut candidates: HashSet<AgentId> = HashSet::new();

        // Unique dirty keys to avoid redundant lookups
        let unique_dirty: HashSet<&ContextKey> = dirty_keys.iter().collect();

        // Agents whose dependencies intersect with dirty keys
        for key in unique_dirty {
            if let Some(ids) = self.index.get(key) {
                candidates.extend(ids);
            }
        }

        // Agents with no dependencies (always considered)
        candidates.extend(&self.always_eligible);

        // Filter by accepts()
        let mut eligible: Vec<AgentId> = candidates
            .into_iter()
            .filter(|&id| {
                let agent = &self.agents[id.0 as usize];
                agent.accepts(context)
            })
            .collect();

        // Sort for determinism
        eligible.sort();
        eligible
    }

    /// Executes agents sequentially and collects their effects.
    ///
    /// # Deprecation Notice
    ///
    /// This method currently uses sequential execution. In converge-core v2.0.0,
    /// parallel execution was removed to eliminate the rayon dependency.
    /// Use `converge-runtime` with an `Executor` implementation for parallel execution.
    #[deprecated(
        since = "2.0.0",
        note = "Use converge-runtime with Executor trait for parallel execution"
    )]
    fn execute_agents(
        &self,
        context: &Context,
        eligible: &[AgentId],
    ) -> Vec<(AgentId, AgentEffect)> {
        eligible
            .iter()
            .map(|&id| {
                let agent = &self.agents[id.0 as usize];
                let effect = agent.execute(context);
                (id, effect)
            })
            .collect()
    }

    /// Merges effects into context in deterministic order.
    ///
    /// Returns a tuple of (dirty keys for next cycle, count of facts added).
    fn merge_effects(
        &self,
        context: &mut Context,
        mut effects: Vec<(AgentId, AgentEffect)>,
        cycle: u32,
    ) -> Result<(Vec<ContextKey>, usize), ConvergeError> {
        // Sort by AgentId for deterministic ordering (DECISIONS.md §1)
        effects.sort_by_key(|(id, _)| *id);

        context.clear_dirty();
        let mut facts_added = 0usize;

        for (id, effect) in effects {
            // 1. Process explicit facts
            for fact in effect.facts {
                // Emit streaming callback before adding (so we have the fact data)
                if let Some(ref cb) = self.streaming_callback {
                    cb.on_fact(cycle, &fact);
                }
                if let Err(e) = context.add_fact(fact) {
                    return match e {
                        ConvergeError::Conflict {
                            id, existing, new, ..
                        } => Err(ConvergeError::Conflict {
                            id,
                            existing,
                            new,
                            context: Box::new(context.clone()),
                        }),
                        _ => Err(e),
                    };
                }
                facts_added += 1;
            }

            // 2. Process proposals (Validation & Promotion)
            for proposal in effect.proposals {
                let _span =
                    info_span!("validate_proposal", agent = %id, proposal = %proposal.id).entered();
                match Fact::try_from(proposal) {
                    Ok(fact) => {
                        info!(agent = %id, fact = %fact.id, "Proposal promoted to fact");
                        // Emit streaming callback for promoted proposal
                        if let Some(ref cb) = self.streaming_callback {
                            cb.on_fact(cycle, &fact);
                        }
                        if let Err(e) = context.add_fact(fact) {
                            return match e {
                                ConvergeError::Conflict {
                                    id, existing, new, ..
                                } => Err(ConvergeError::Conflict {
                                    id,
                                    existing,
                                    new,
                                    context: Box::new(context.clone()),
                                }),
                                _ => Err(e),
                            };
                        }
                        facts_added += 1;
                    }
                    Err(e) => {
                        info!(agent = %id, reason = %e, "Proposal rejected");
                        // Future: emit diagnostic fact or signal
                    }
                }
            }
        }

        Ok((context.dirty_keys().to_vec(), facts_added))
    }

    /// Counts total facts in context.
    #[allow(clippy::unused_self)] // Keeps API consistent
    #[allow(clippy::cast_possible_truncation)] // Budget is u32, context won't exceed
    fn count_facts(&self, context: &Context) -> u32 {
        ContextKey::iter()
            .map(|key| context.get(key).len() as u32)
            .sum()
    }

    /// Emits a diagnostic fact to the context.
    fn emit_diagnostic(&self, context: &mut Context, err: &InvariantError) {
        let _ = self; // May use engine state in future (e.g., for diagnostic IDs)
        let fact = Fact {
            key: ContextKey::Diagnostic,
            id: format!("violation:{}:{}", err.invariant_name, context.version()),
            content: format!(
                "{:?} invariant '{}' violated: {}",
                err.class, err.invariant_name, err.violation.reason
            ),
        };
        let _ = context.add_fact(fact);
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::context::Fact;
    use tracing_test::traced_test;

    #[test]
    #[traced_test]
    fn engine_emits_tracing_logs() {
        let mut engine = Engine::new();
        engine.register(SeedAgent);
        let _ = engine.run(Context::new()).unwrap();

        assert!(logs_contain("Starting convergence cycle"));
        assert!(logs_contain("Found eligible agents"));
    }

    /// Agent that emits a seed fact once.
    struct SeedAgent;

    impl Agent for SeedAgent {
        fn name(&self) -> &'static str {
            "SeedAgent"
        }

        fn dependencies(&self) -> &[ContextKey] {
            &[] // No dependencies = runs first cycle
        }

        fn accepts(&self, ctx: &Context) -> bool {
            !ctx.has(ContextKey::Seeds)
        }

        fn execute(&self, _ctx: &Context) -> AgentEffect {
            AgentEffect::with_fact(Fact {
                key: ContextKey::Seeds,
                id: "seed-1".into(),
                content: "initial seed".into(),
            })
        }
    }

    /// Agent that reacts to seeds once.
    struct ReactOnceAgent;

    impl Agent for ReactOnceAgent {
        fn name(&self) -> &'static str {
            "ReactOnceAgent"
        }

        fn dependencies(&self) -> &[ContextKey] {
            &[ContextKey::Seeds]
        }

        fn accepts(&self, ctx: &Context) -> bool {
            ctx.has(ContextKey::Seeds) && !ctx.has(ContextKey::Hypotheses)
        }

        fn execute(&self, _ctx: &Context) -> AgentEffect {
            AgentEffect::with_fact(Fact {
                key: ContextKey::Hypotheses,
                id: "hyp-1".into(),
                content: "derived from seed".into(),
            })
        }
    }

    #[test]
    fn engine_converges_with_single_agent() {
        let mut engine = Engine::new();
        engine.register(SeedAgent);

        let result = engine.run(Context::new()).expect("should converge");

        assert!(result.converged);
        assert_eq!(result.cycles, 2); // Cycle 1: emit seed, Cycle 2: no eligible agents
        assert!(result.context.has(ContextKey::Seeds));
    }

    #[test]
    fn engine_converges_with_chain() {
        let mut engine = Engine::new();
        engine.register(SeedAgent);
        engine.register(ReactOnceAgent);

        let result = engine.run(Context::new()).expect("should converge");

        assert!(result.converged);
        assert!(result.context.has(ContextKey::Seeds));
        assert!(result.context.has(ContextKey::Hypotheses));
    }

    #[test]
    fn engine_converges_deterministically() {
        let run = || {
            let mut engine = Engine::new();
            engine.register(SeedAgent);
            engine.register(ReactOnceAgent);
            engine.run(Context::new()).expect("should converge")
        };

        let r1 = run();
        let r2 = run();

        assert_eq!(r1.cycles, r2.cycles);
        assert_eq!(
            r1.context.get(ContextKey::Seeds),
            r2.context.get(ContextKey::Seeds)
        );
        assert_eq!(
            r1.context.get(ContextKey::Hypotheses),
            r2.context.get(ContextKey::Hypotheses)
        );
    }

    #[test]
    fn engine_respects_cycle_budget() {
        use std::sync::atomic::{AtomicU32, Ordering};

        /// Agent that always wants to run (would loop forever).
        struct InfiniteAgent {
            counter: AtomicU32,
        }

        impl Agent for InfiniteAgent {
            fn name(&self) -> &'static str {
                "InfiniteAgent"
            }

            fn dependencies(&self) -> &[ContextKey] {
                &[]
            }

            fn accepts(&self, _ctx: &Context) -> bool {
                true // Always wants to run
            }

            fn execute(&self, _ctx: &Context) -> AgentEffect {
                let n = self.counter.fetch_add(1, Ordering::SeqCst);
                AgentEffect::with_fact(Fact {
                    key: ContextKey::Seeds,
                    id: format!("inf-{n}"),
                    content: "infinite".into(),
                })
            }
        }

        let mut engine = Engine::with_budget(Budget {
            max_cycles: 5,
            max_facts: 1000,
        });
        engine.register(InfiniteAgent {
            counter: AtomicU32::new(0),
        });

        let result = engine.run(Context::new());

        assert!(result.is_err());
        let err = result.unwrap_err();
        assert!(matches!(err, ConvergeError::BudgetExhausted { .. }));
    }

    #[test]
    fn engine_respects_fact_budget() {
        /// Agent that emits many facts.
        struct FloodAgent;

        impl Agent for FloodAgent {
            fn name(&self) -> &'static str {
                "FloodAgent"
            }

            fn dependencies(&self) -> &[ContextKey] {
                &[]
            }

            fn accepts(&self, _ctx: &Context) -> bool {
                true
            }

            fn execute(&self, ctx: &Context) -> AgentEffect {
                let n = ctx.get(ContextKey::Seeds).len();
                AgentEffect::with_facts(
                    (0..10)
                        .map(|i| Fact {
                            key: ContextKey::Seeds,
                            id: format!("flood-{n}-{i}"),
                            content: "flood".into(),
                        })
                        .collect(),
                )
            }
        }

        let mut engine = Engine::with_budget(Budget {
            max_cycles: 100,
            max_facts: 25,
        });
        engine.register(FloodAgent);

        let result = engine.run(Context::new());

        assert!(result.is_err());
        let err = result.unwrap_err();
        assert!(matches!(err, ConvergeError::BudgetExhausted { .. }));
    }

    #[test]
    fn dependency_index_filters_agents() {
        /// Agent that only cares about Strategies.
        struct StrategyAgent;

        impl Agent for StrategyAgent {
            fn name(&self) -> &'static str {
                "StrategyAgent"
            }

            fn dependencies(&self) -> &[ContextKey] {
                &[ContextKey::Strategies]
            }

            fn accepts(&self, _ctx: &Context) -> bool {
                true
            }

            fn execute(&self, _ctx: &Context) -> AgentEffect {
                AgentEffect::with_fact(Fact {
                    key: ContextKey::Constraints,
                    id: "constraint-1".into(),
                    content: "from strategy".into(),
                })
            }
        }

        let mut engine = Engine::new();
        engine.register(SeedAgent); // Emits to Seeds
        engine.register(StrategyAgent); // Only watches Strategies

        let result = engine.run(Context::new()).expect("should converge");

        // SeedAgent runs, but StrategyAgent never runs because
        // Seeds changed, not Strategies
        assert!(result.context.has(ContextKey::Seeds));
        assert!(!result.context.has(ContextKey::Constraints));
    }

    /// Agent used to probe dependency scheduling.
    struct AlwaysAgent;

    impl Agent for AlwaysAgent {
        fn name(&self) -> &'static str {
            "AlwaysAgent"
        }

        fn dependencies(&self) -> &[ContextKey] {
            &[]
        }

        fn accepts(&self, _ctx: &Context) -> bool {
            true
        }

        fn execute(&self, _ctx: &Context) -> AgentEffect {
            AgentEffect::empty()
        }
    }

    /// Agent that depends on Seeds regardless of their values.
    struct SeedWatcher;

    impl Agent for SeedWatcher {
        fn name(&self) -> &'static str {
            "SeedWatcher"
        }

        fn dependencies(&self) -> &[ContextKey] {
            &[ContextKey::Seeds]
        }

        fn accepts(&self, _ctx: &Context) -> bool {
            true
        }

        fn execute(&self, _ctx: &Context) -> AgentEffect {
            AgentEffect::empty()
        }
    }

    #[test]
    fn find_eligible_respects_dirty_keys() {
        let mut engine = Engine::new();
        let always_id = engine.register(AlwaysAgent);
        let watcher_id = engine.register(SeedWatcher);
        let ctx = Context::new();

        let eligible = engine.find_eligible(&ctx, &[]);
        assert_eq!(eligible, vec![always_id]);

        let eligible = engine.find_eligible(&ctx, &[ContextKey::Seeds]);
        assert_eq!(eligible, vec![always_id, watcher_id]);
    }

    /// Agent that depends on multiple keys, used to assert dedup.
    struct MultiDepAgent;

    impl Agent for MultiDepAgent {
        fn name(&self) -> &'static str {
            "MultiDepAgent"
        }

        fn dependencies(&self) -> &[ContextKey] {
            &[ContextKey::Seeds, ContextKey::Hypotheses]
        }

        fn accepts(&self, _ctx: &Context) -> bool {
            true
        }

        fn execute(&self, _ctx: &Context) -> AgentEffect {
            AgentEffect::empty()
        }
    }

    #[test]
    fn find_eligible_deduplicates_agents() {
        let mut engine = Engine::new();
        let multi_id = engine.register(MultiDepAgent);
        let ctx = Context::new();

        let eligible = engine.find_eligible(&ctx, &[ContextKey::Seeds, ContextKey::Hypotheses]);
        assert_eq!(eligible, vec![multi_id]);
    }

    /// Agent with static fact output used for merge ordering tests.
    struct NamedAgent {
        name: &'static str,
        fact_id: &'static str,
    }

    impl Agent for NamedAgent {
        fn name(&self) -> &str {
            self.name
        }

        fn dependencies(&self) -> &[ContextKey] {
            &[]
        }

        fn accepts(&self, _ctx: &Context) -> bool {
            true
        }

        fn execute(&self, _ctx: &Context) -> AgentEffect {
            AgentEffect::with_fact(Fact {
                key: ContextKey::Seeds,
                id: self.fact_id.into(),
                content: format!("emitted-by-{}", self.name),
            })
        }
    }

    #[test]
    fn merge_effects_respect_agent_ordering() {
        let mut engine = Engine::new();
        let id_a = engine.register(NamedAgent {
            name: "AgentA",
            fact_id: "a",
        });
        let id_b = engine.register(NamedAgent {
            name: "AgentB",
            fact_id: "b",
        });
        let mut context = Context::new();

        let effect_a = AgentEffect::with_fact(Fact {
            key: ContextKey::Seeds,
            id: "a".into(),
            content: "first".into(),
        });
        let effect_b = AgentEffect::with_fact(Fact {
            key: ContextKey::Seeds,
            id: "b".into(),
            content: "second".into(),
        });

        // Intentionally feed merge_effects in reverse order.
        let (dirty, facts_added) = engine
            .merge_effects(&mut context, vec![(id_b, effect_b), (id_a, effect_a)], 1)
            .expect("should not conflict");

        let seeds = context.get(ContextKey::Seeds);
        assert_eq!(seeds.len(), 2);
        assert_eq!(seeds[0].id, "a");
        assert_eq!(seeds[1].id, "b");
        assert_eq!(dirty, vec![ContextKey::Seeds, ContextKey::Seeds]);
        assert_eq!(facts_added, 2);
    }

    // ========================================================================
    // INVARIANT VIOLATION TESTS
    // ========================================================================

    use crate::invariant::{Invariant, InvariantClass, InvariantResult, Violation};

    /// Structural invariant that forbids facts with "forbidden" content.
    struct ForbidContent {
        forbidden: &'static str,
    }

    impl Invariant for ForbidContent {
        fn name(&self) -> &'static str {
            "forbid_content"
        }

        fn class(&self) -> InvariantClass {
            InvariantClass::Structural
        }

        fn check(&self, ctx: &Context) -> InvariantResult {
            for fact in ctx.get(ContextKey::Seeds) {
                if fact.content.contains(self.forbidden) {
                    return InvariantResult::Violated(Violation::with_facts(
                        format!("content contains '{}'", self.forbidden),
                        vec![fact.id.clone()],
                    ));
                }
            }
            InvariantResult::Ok
        }
    }

    /// Semantic invariant that requires balance between seeds and hypotheses.
    struct RequireBalance;

    impl Invariant for RequireBalance {
        fn name(&self) -> &'static str {
            "require_balance"
        }

        fn class(&self) -> InvariantClass {
            InvariantClass::Semantic
        }

        fn check(&self, ctx: &Context) -> InvariantResult {
            let seeds = ctx.get(ContextKey::Seeds).len();
            let hyps = ctx.get(ContextKey::Hypotheses).len();
            // Semantic rule: can't have seeds without hypotheses for more than one cycle
            if seeds > 0 && hyps == 0 {
                return InvariantResult::Violated(Violation::new(
                    "seeds exist but no hypotheses derived yet",
                ));
            }
            InvariantResult::Ok
        }
    }

    /// Acceptance invariant that requires at least two seeds.
    struct RequireMultipleSeeds;

    impl Invariant for RequireMultipleSeeds {
        fn name(&self) -> &'static str {
            "require_multiple_seeds"
        }

        fn class(&self) -> InvariantClass {
            InvariantClass::Acceptance
        }

        fn check(&self, ctx: &Context) -> InvariantResult {
            let seeds = ctx.get(ContextKey::Seeds).len();
            if seeds < 2 {
                return InvariantResult::Violated(Violation::new(format!(
                    "need at least 2 seeds, found {seeds}"
                )));
            }
            InvariantResult::Ok
        }
    }

    #[test]
    fn structural_invariant_fails_immediately() {
        let mut engine = Engine::new();
        engine.register(SeedAgent);
        engine.register_invariant(ForbidContent {
            forbidden: "initial", // SeedAgent emits "initial seed"
        });

        let result = engine.run(Context::new());

        assert!(result.is_err());
        let err = result.unwrap_err();
        match err {
            ConvergeError::InvariantViolation { name, class, .. } => {
                assert_eq!(name, "forbid_content");
                assert_eq!(class, InvariantClass::Structural);
            }
            _ => panic!("expected InvariantViolation, got {err:?}"),
        }
    }

    #[test]
    fn semantic_invariant_blocks_convergence() {
        // This test uses an agent that emits a seed but no agent to emit hypotheses.
        // The semantic invariant requires balance, so it should fail.
        let mut engine = Engine::new();
        engine.register(SeedAgent);
        engine.register_invariant(RequireBalance);

        let result = engine.run(Context::new());

        assert!(result.is_err());
        let err = result.unwrap_err();
        match err {
            ConvergeError::InvariantViolation { name, class, .. } => {
                assert_eq!(name, "require_balance");
                assert_eq!(class, InvariantClass::Semantic);
            }
            _ => panic!("expected InvariantViolation, got {err:?}"),
        }
    }

    #[test]
    fn acceptance_invariant_rejects_result() {
        // SeedAgent emits only one seed, but acceptance requires 2
        let mut engine = Engine::new();
        engine.register(SeedAgent);
        engine.register(ReactOnceAgent); // Add hypotheses to pass semantic
        engine.register_invariant(RequireMultipleSeeds);

        let result = engine.run(Context::new());

        assert!(result.is_err());
        let err = result.unwrap_err();
        match err {
            ConvergeError::InvariantViolation { name, class, .. } => {
                assert_eq!(name, "require_multiple_seeds");
                assert_eq!(class, InvariantClass::Acceptance);
            }
            _ => panic!("expected InvariantViolation, got {err:?}"),
        }
    }

    #[test]
    fn all_invariant_classes_pass_when_satisfied() {
        /// Agent that emits two seeds.
        struct TwoSeedAgent;

        impl Agent for TwoSeedAgent {
            fn name(&self) -> &'static str {
                "TwoSeedAgent"
            }

            fn dependencies(&self) -> &[ContextKey] {
                &[]
            }

            fn accepts(&self, ctx: &Context) -> bool {
                !ctx.has(ContextKey::Seeds)
            }

            fn execute(&self, _ctx: &Context) -> AgentEffect {
                AgentEffect::with_facts(vec![
                    Fact {
                        key: ContextKey::Seeds,
                        id: "seed-1".into(),
                        content: "good content".into(),
                    },
                    Fact {
                        key: ContextKey::Seeds,
                        id: "seed-2".into(),
                        content: "more good content".into(),
                    },
                ])
            }
        }

        /// Agent that derives hypothesis from seeds.
        struct DeriverAgent;

        impl Agent for DeriverAgent {
            fn name(&self) -> &'static str {
                "DeriverAgent"
            }

            fn dependencies(&self) -> &[ContextKey] {
                &[ContextKey::Seeds]
            }

            fn accepts(&self, ctx: &Context) -> bool {
                ctx.has(ContextKey::Seeds) && !ctx.has(ContextKey::Hypotheses)
            }

            fn execute(&self, _ctx: &Context) -> AgentEffect {
                AgentEffect::with_fact(Fact {
                    key: ContextKey::Hypotheses,
                    id: "hyp-1".into(),
                    content: "derived".into(),
                })
            }
        }

        /// Semantic invariant that is always satisfied.
        struct AlwaysSatisfied;

        impl Invariant for AlwaysSatisfied {
            fn name(&self) -> &'static str {
                "always_satisfied"
            }

            fn class(&self) -> InvariantClass {
                InvariantClass::Semantic
            }

            fn check(&self, _ctx: &Context) -> InvariantResult {
                InvariantResult::Ok
            }
        }

        let mut engine = Engine::new();
        engine.register(TwoSeedAgent);
        engine.register(DeriverAgent);

        // Register all three invariant classes
        engine.register_invariant(ForbidContent {
            forbidden: "forbidden", // Won't match
        });
        engine.register_invariant(AlwaysSatisfied); // Semantic that passes
        engine.register_invariant(RequireMultipleSeeds);

        let result = engine.run(Context::new());

        assert!(result.is_ok());
        let result = result.unwrap();
        assert!(result.converged);
        assert_eq!(result.context.get(ContextKey::Seeds).len(), 2);
        assert!(result.context.has(ContextKey::Hypotheses));
    }
}