aria-engine-core 0.0.1

Spec-faithful Aria state machine engine — optical–JEPA–graph dynamical system core with formally verified safety invariants
Documentation
//! Aria Engine — Spec-faithful state machine.
//!
//! Implements Init, Next, Spec per FORMAL_SPEC.md.
//! Checks Inv1–4 after every apply.
//! The scheduler is policy, not Spec.

use std::fmt::Debug;

use crate::action::Action;
use crate::condition::Condition;
use crate::config::AriaConfig;
use crate::error::AriaError;
use crate::graph::Graph;
use crate::invariants;
use crate::invariants::InvariantReport;
use crate::policy::{DiffPolicy, MatchPolicy};
use crate::scheduler::Scheduler;
use crate::state::State;
use crate::trace::Trace;

/// Optical backend trait — PRD §5.3
pub trait OpticalBackend: Debug + Send + Sync {
    /// Apply unitary step: ψ' = U_t(ψ)
    fn unitary_step(&self, t: u64, psi: &[num_complex::Complex64]) -> Vec<num_complex::Complex64>;
    /// Field energy: ‖ψ‖₂
    fn energy(&self, psi: &[num_complex::Complex64]) -> f64;
}

/// Predictor backend trait — PRD §5.3
pub trait Predictor: Debug + Send + Sync {
    /// Isometry I: H → Z
    fn embed(&self, psi: &[num_complex::Complex64]) -> Vec<f64>;
    /// Predictor P: Z × Condition → Z
    fn predict(&self, z: &[f64], a: Condition) -> Vec<f64>;
    /// Distance in latent space
    fn dist(&self, a: &[f64], b: &[f64]) -> f64;
}

/// Graph backend trait — PRD §5.3
pub trait GraphBackend: Debug + Send + Sync {
    /// Edit graph: G' = ED(G ⊕ z, policy, G*)
    fn edit(
        &self,
        g: &Graph,
        z: &[f64],
        policy: MatchPolicy,
        target: Option<&Graph>,
    ) -> Graph;
    /// GraphOK check
    fn ok(&self, g: &Graph) -> bool;
}

/// Diffuser backend trait — PRD §5.3
pub trait Diffuser: Debug + Send + Sync {
    /// Diffusion step: z' = Diff_G(z)
    fn diffuse(&self, g: &Graph, z: &[f64], policy: DiffPolicy) -> Vec<f64>;
}

/// Aria Engine — the Spec state machine with pluggable backends.
#[derive(Debug)]
pub struct Engine<O, P, G, D>
where
    O: OpticalBackend,
    P: Predictor,
    G: GraphBackend,
    D: Diffuser,
{
    config: AriaConfig,
    optical: O,
    predictor: P,
    graph_backend: G,
    diffuser: D,
}

impl<O, P, GB, D> Engine<O, P, GB, D>
where
    O: OpticalBackend,
    P: Predictor,
    GB: GraphBackend,
    D: Diffuser,
{
    /// Create a new engine with backends and config.
    pub fn new(config: AriaConfig, optical: O, predictor: P, graph_backend: GB, diffuser: D) -> Self {
        Engine {
            config,
            optical,
            predictor,
            graph_backend,
            diffuser,
        }
    }

    /// Init: create the initial state per FORMAL_SPEC §5.
    ///
    /// ψ = ψ₀, z = I(ψ₀), G = G₀, t = 0,
    /// prevRes = d(I(ψ₀), P(I(ψ₀), a(0)))
    pub fn init(&self, psi0: Vec<num_complex::Complex64>, g0: Graph, a0: Condition) -> State {
        let energy_0 = self.optical.energy(&psi0);
        let z0 = self.predictor.embed(&psi0);
        let p0 = self.predictor.predict(&z0, a0);
        let prev_res = self.predictor.dist(&z0, &p0);

        State {
            psi: psi0,
            z: z0,
            g: g0,
            t: 0,
            prev_res,
            energy_0,
        }
    }

    /// Apply a single named action to the state.
    ///
    /// Returns the new state on success, or an invariant violation.
    /// This is the Spec's Next relation turned into a deterministic function.
    pub fn apply(
        &self,
        mut state: State,
        action: Action,
        a: Condition,
    ) -> Result<State, AriaError> {
        match action {
            Action::OpticalStep => {
                // ψ' = U_t(ψ); UNCHANGED ⟨z, G, t⟩ — FORMAL_SPEC §6.1
                let prev_psi = state.psi.clone();
                state.psi = self.optical.unitary_step(state.t, &state.psi);

                // Update prevRes aux history
                let residual = self.compute_residual(&state, a);
                state.prev_res = residual;

                // Check invariants
                let report = invariants::check_all(&state, residual, self.config.eps, self.config.latent_dim);
                if self.config.strict && !report.all_ok() {
                    if let Some(v) = invariants::violation_from_report(
                        &report, action, state.energy(), state.energy_0,
                        residual, state.prev_res, self.config.eps,
                    ) {
                        state.psi = prev_psi; // rollback
                        return Err(AriaError::InvariantViolation(v));
                    }
                }
            }

            Action::Predict => {
                // z' = P(I(ψ), a_t); UNCHANGED ⟨ψ, G, t⟩ — FORMAL_SPEC §6.2
                let prev_z = state.z.clone();
                state.z = self.predictor.predict(&self.predictor.embed(&state.psi), a);

                let residual = self.compute_residual(&state, a);
                state.prev_res = residual;

                let report = invariants::check_all(&state, residual, self.config.eps, self.config.latent_dim);
                if self.config.strict && !report.all_ok() {
                    if let Some(v) = invariants::violation_from_report(
                        &report, action, state.energy(), state.energy_0,
                        residual, state.prev_res, self.config.eps,
                    ) {
                        state.z = prev_z;
                        return Err(AriaError::InvariantViolation(v));
                    }
                }
            }

            Action::Match => {
                // G' = ED(G ⊕ z, G*); UNCHANGED ⟨ψ, z, t⟩ — FORMAL_SPEC §6.3
                let prev_g = state.g.clone();
                let mut g_with_z = state.g.clone();
                g_with_z.add_node(
                    format!("z_{}", state.t),
                    state.z.clone(),
                    Some("latent".into()),
                );

                // Enforce max graph size
                if g_with_z.size() > self.config.max_graph_size {
                    return Err(AriaError::Schedule(format!(
                        "graph size {} exceeds max {}",
                        g_with_z.size(),
                        self.config.max_graph_size
                    )));
                }

                state.g = self.graph_backend.edit(
                    &g_with_z,
                    &state.z,
                    self.config.match_policy,
                    None,
                );

                let residual = self.compute_residual(&state, a);
                state.prev_res = residual;

                let report = invariants::check_all(&state, residual, self.config.eps, self.config.latent_dim);
                if self.config.strict && !report.all_ok() {
                    if let Some(v) = invariants::violation_from_report(
                        &report, action, state.energy(), state.energy_0,
                        residual, state.prev_res, self.config.eps,
                    ) {
                        state.g = prev_g;
                        return Err(AriaError::InvariantViolation(v));
                    }
                }
            }

            Action::Diffuse => {
                // z' = Diff_G(z); t' = t+1; UNCHANGED ⟨ψ, G⟩ — FORMAL_SPEC §6.4
                let prev_z = state.z.clone();
                let prev_t = state.t;
                state.z = self.diffuser.diffuse(&state.g, &state.z, self.config.diff_policy);
                state.t += 1;

                let residual = self.compute_residual(&state, a);
                state.prev_res = residual;

                let report = invariants::check_all(&state, residual, self.config.eps, self.config.latent_dim);
                if self.config.strict && !report.all_ok() {
                    if let Some(v) = invariants::violation_from_report(
                        &report, action, state.energy(), state.energy_0,
                        residual, state.prev_res, self.config.eps,
                    ) {
                        state.z = prev_z;
                        state.t = prev_t;
                        return Err(AriaError::InvariantViolation(v));
                    }
                }
            }

            Action::Stutter => {
                // UNCHANGED all vars — TLA stuttering
                // prevRes is also UNCHANGED (TLA encoding uses UNCHANGED vars including prevRes)
                // But we still check Inv1-4 (they hold vacuously since nothing changed)
                let residual = self.compute_residual(&state, a);
                // prevRes is NOT updated on Stutter in the TLA encoding:
                // Stutter == UNCHANGED vars (which includes prevRes)
                // So we leave prevRes as-is

                let report = invariants::check_all(&state, residual, self.config.eps, self.config.latent_dim);
                if self.config.strict && !report.all_ok() {
                    if let Some(v) = invariants::violation_from_report(
                        &report, action, state.energy(), state.energy_0,
                        residual, state.prev_res, self.config.eps,
                    ) {
                        return Err(AriaError::InvariantViolation(v));
                    }
                }
            }
        }

        Ok(state)
    }

    /// Step one full Φ-cycle: OpticalStep → Predict → Match → Diffuse (𝐂4).
    ///
    /// This is the preferred schedule. Each sub-step checks invariants.
    /// Returns the state after the full cycle, or the first invariant violation.
    pub fn step_phi(&self, state: State, a: Condition) -> Result<State, AriaError> {
        let s = state;
        let s = self.apply(s, Action::OpticalStep, a)?;
        let s = self.apply(s, Action::Predict, a)?;
        let s = self.apply(s, Action::Match, a)?;
        let s = self.apply(s, Action::Diffuse, a)?;
        Ok(s)
    }

    /// Run the engine for a number of steps with a scheduler.
    ///
    /// Returns the final state and a trace of all steps.
    pub fn run(
        &self,
        mut state: State,
        scheduler: &mut Scheduler,
        steps: u64,
        a: Condition,
    ) -> Result<(State, Trace), AriaError> {
        let mut trace = Trace::new(self.config.n_modes, self.config.latent_dim, self.config.eps);

        for _ in 0..steps {
            let action = scheduler.next_action_budgeted();
            let t_before = state.t;

            state = self.apply(state, action, a)?;

            let residual = self.compute_residual(&state, a);
            let energy = state.energy();
            trace.push(
                t_before,
                action,
                residual,
                energy,
                state.g.size(),
                &format!("{:?}", a).to_lowercase(),
            );
        }

        Ok((state, trace))
    }

    /// Check all invariants on the current state without applying an action.
    pub fn check(&self, state: &State, a: Condition) -> InvariantReport {
        let residual = self.compute_residual(state, a);
        invariants::check_all(state, residual, self.config.eps, self.config.latent_dim)
    }

    /// Compute JEPA residual: Res(ψ, z, t) = d(z, P(I(ψ), a_t))
    fn compute_residual(&self, state: &State, a: Condition) -> f64 {
        let embedded = self.predictor.embed(&state.psi);
        let predicted = self.predictor.predict(&embedded, a);
        self.predictor.dist(&state.z, &predicted)
    }

    /// Access config.
    pub fn config(&self) -> &AriaConfig {
        &self.config
    }
}