maple_runtime/runtime_core/

runtime.rs

//! Main MAPLE Resonance Runtime implementation

use crate::allocator::AttentionAllocator;
use crate::config::RuntimeConfig;
use crate::fabrics::{CouplingFabric, PresenceFabric};
use crate::invariants::InvariantGuard;
use crate::runtime_core::{ContinuityProof, ProfileManager, ResonatorHandle, ResonatorRegistry};
use crate::scheduler::ResonanceScheduler;
use crate::telemetry::RuntimeTelemetry;
use crate::temporal::TemporalCoordinator;
use crate::types::*;
use std::sync::Arc;
use tokio::sync::RwLock;

/// The MAPLE Resonance Runtime - heart of the entire MAPLE ecosystem
///
/// This runtime powers:
/// - **Mapleverse**: Coordination of millions of pure AI agents
/// - **Finalverse**: Meaningful human-AI coexistence in experiential worlds
/// - **iBank**: Accountable autonomous financial operations
#[derive(Clone)]
pub struct MapleRuntime {
    inner: Arc<RuntimeInner>,
}

struct RuntimeInner {
    // ═══════════════════════════════════════════════════════════════════
    // RESONATOR MANAGEMENT
    // ═══════════════════════════════════════════════════════════════════
    resonator_registry: Arc<ResonatorRegistry>,
    profile_manager: Arc<ProfileManager>,

    // ═══════════════════════════════════════════════════════════════════
    // RESONANCE INFRASTRUCTURE
    // ═══════════════════════════════════════════════════════════════════
    presence_fabric: Arc<PresenceFabric>,
    coupling_fabric: Arc<CouplingFabric>,
    attention_allocator: Arc<AttentionAllocator>,

    // ═══════════════════════════════════════════════════════════════════
    // COGNITIVE PIPELINE (placeholders for now)
    // ═══════════════════════════════════════════════════════════════════
    // meaning_engine: Arc<MeaningFormationEngine>,
    // intent_engine: Arc<IntentStabilizationEngine>,
    // commitment_manager: Arc<CommitmentManager>,
    // consequence_tracker: Arc<ConsequenceTracker>,

    // ═══════════════════════════════════════════════════════════════════
    // SAFETY AND GOVERNANCE
    // ═══════════════════════════════════════════════════════════════════
    #[allow(dead_code)]
    invariant_guard: Arc<InvariantGuard>,
    // agency_protector: Arc<HumanAgencyProtector>,
    // safety_enforcer: Arc<SafetyBoundaryEnforcer>,

    // ═══════════════════════════════════════════════════════════════════
    // TEMPORAL AND SCHEDULING
    // ═══════════════════════════════════════════════════════════════════
    temporal_coordinator: Arc<TemporalCoordinator>,
    scheduler: Arc<ResonanceScheduler>,

    // ═══════════════════════════════════════════════════════════════════
    // OBSERVABILITY
    // ═══════════════════════════════════════════════════════════════════
    telemetry: Arc<RuntimeTelemetry>,

    // ═══════════════════════════════════════════════════════════════════
    // STATE
    // ═══════════════════════════════════════════════════════════════════
    shutdown: Arc<RwLock<bool>>,
}

impl MapleRuntime {
    /// Bootstrap the MAPLE Resonance Runtime
    ///
    /// This initializes all subsystems in the correct order to ensure
    /// architectural invariants are satisfied from the start.
    ///
    /// # Arguments
    ///
    /// * `config` - Runtime configuration
    ///
    /// # Returns
    ///
    /// * `Ok(MapleRuntime)` - Successfully bootstrapped runtime
    /// * `Err(BootstrapError)` - Bootstrap failed
    ///
    /// # Example
    ///
    /// ```no_run
    /// use maple_runtime::{MapleRuntime, config::RuntimeConfig};
    ///
    /// #[tokio::main]
    /// async fn main() {
    ///     let config = RuntimeConfig::default();
    ///     let runtime = MapleRuntime::bootstrap(config).await.unwrap();
    /// }
    /// ```
    pub async fn bootstrap(config: RuntimeConfig) -> Result<Self, BootstrapError> {
        tracing::info!("Bootstrapping MAPLE Resonance Runtime");

        // Phase 1: Initialize safety infrastructure FIRST
        tracing::debug!("Phase 1: Initializing safety infrastructure");
        let invariant_guard = Arc::new(InvariantGuard::new(&config.invariants));

        // Phase 2: Initialize temporal coordination
        tracing::debug!("Phase 2: Initializing temporal coordination");
        let temporal_coordinator = Arc::new(TemporalCoordinator::new(&config.temporal));

        // Phase 3: Initialize resonance infrastructure
        tracing::debug!("Phase 3: Initializing resonance infrastructure");
        let attention_allocator = Arc::new(AttentionAllocator::new(&config.attention));
        let presence_fabric = Arc::new(PresenceFabric::new(&config.presence));
        let coupling_fabric = Arc::new(CouplingFabric::new(
            &config.coupling,
            Arc::clone(&attention_allocator),
        ));

        // Phase 4: Initialize cognitive pipeline (placeholder)
        tracing::debug!("Phase 4: Cognitive pipeline (placeholder)");

        // Phase 5: Initialize Resonator management
        tracing::debug!("Phase 5: Initializing Resonator management");
        let profile_manager = Arc::new(ProfileManager::new(&config.profiles));
        let resonator_registry = Arc::new(ResonatorRegistry::new(&config.registry));

        // Phase 6: Initialize scheduler and telemetry
        tracing::debug!("Phase 6: Initializing scheduler and telemetry");
        let scheduler = Arc::new(ResonanceScheduler::new(&config.scheduling));
        let telemetry = Arc::new(RuntimeTelemetry::new(&config.telemetry));

        let inner = RuntimeInner {
            resonator_registry,
            profile_manager,
            presence_fabric,
            coupling_fabric,
            attention_allocator,
            invariant_guard,
            temporal_coordinator,
            scheduler,
            telemetry,
            shutdown: Arc::new(RwLock::new(false)),
        };

        tracing::info!("MAPLE Resonance Runtime bootstrapped successfully");

        Ok(Self {
            inner: Arc::new(inner),
        })
    }

    /// Shutdown gracefully, preserving all commitments
    ///
    /// This ensures that:
    /// 1. No new commitments are accepted
    /// 2. Active commitments are completed or recorded
    /// 3. All Resonator continuity is persisted
    /// 4. Coupling topology is saved
    pub async fn shutdown(&self) -> Result<(), ShutdownError> {
        tracing::info!("Shutting down MAPLE Resonance Runtime");

        let mut shutdown = self.inner.shutdown.write().await;
        if *shutdown {
            tracing::warn!("Runtime already shut down");
            return Ok(());
        }
        *shutdown = true;
        drop(shutdown);

        // Step 1: Stop accepting new commitments (placeholder)
        tracing::debug!("Step 1: Stopping new commitments");

        // Step 2: Wait for active commitments (placeholder)
        tracing::debug!("Step 2: Waiting for active commitments");

        // Step 3: Persist all Resonator continuity records
        tracing::debug!("Step 3: Persisting Resonator continuity");
        self.inner
            .resonator_registry
            .persist_all_continuity()
            .await
            .map_err(|e| ShutdownError::PersistenceError(e.to_string()))?;

        // Step 4: Persist coupling topology
        tracing::debug!("Step 4: Persisting coupling topology");
        self.inner
            .coupling_fabric
            .persist_topology()
            .await
            .map_err(|e| ShutdownError::PersistenceError(e.to_string()))?;

        // Step 5: Final telemetry flush
        tracing::debug!("Step 5: Flushing telemetry");
        self.inner.telemetry.flush().await;

        tracing::info!("MAPLE Resonance Runtime shutdown complete");
        Ok(())
    }

    /// Check if runtime is shutting down
    pub async fn is_shutting_down(&self) -> bool {
        *self.inner.shutdown.read().await
    }

    /// Register a new Resonator
    ///
    /// This creates a persistent identity that survives restarts,
    /// migrations, and network partitions.
    ///
    /// # Arguments
    ///
    /// * `spec` - Resonator specification
    ///
    /// # Returns
    ///
    /// * `Ok(ResonatorHandle)` - Handle to the registered Resonator
    /// * `Err(RegistrationError)` - Registration failed
    pub async fn register_resonator(
        &self,
        spec: ResonatorSpec,
    ) -> Result<ResonatorHandle, RegistrationError> {
        if self.is_shutting_down().await {
            return Err(RegistrationError::InvalidSpec(
                "Runtime is shutting down".to_string(),
            ));
        }

        // Validate against profile constraints
        self.inner
            .profile_manager
            .validate_spec(&spec)
            .map_err(|e| RegistrationError::ProfileValidation(e))?;

        // Check invariants
        // (placeholder for now)

        // Create persistent identity
        let identity = self
            .inner
            .resonator_registry
            .create_identity(&spec.identity)
            .await?;

        // Initialize presence
        self.inner
            .presence_fabric
            .initialize_presence(&identity, &spec.presence)
            .await
            .map_err(|e| RegistrationError::InvalidSpec(e.to_string()))?;

        // Allocate attention budget
        self.inner
            .attention_allocator
            .allocate_budget(&identity, &spec.attention)
            .await
            .map_err(|e| RegistrationError::InvalidSpec(e.to_string()))?;

        // Register in coupling topology
        self.inner
            .coupling_fabric
            .register(&identity)
            .await
            .map_err(|e| RegistrationError::InvalidSpec(e.to_string()))?;

        // Create Resonator handle
        let handle = ResonatorHandle::new(identity, self.clone());

        // Emit telemetry
        self.inner.telemetry.resonator_registered(&handle);

        tracing::info!("Registered Resonator: {}", identity);

        Ok(handle)
    }

    /// Resume a Resonator from continuity record
    ///
    /// This restores a Resonator's identity, memory, and pending commitments
    /// after a restart or migration.
    pub async fn resume_resonator(
        &self,
        continuity_proof: ContinuityProof,
    ) -> Result<ResonatorHandle, ResumeError> {
        if self.is_shutting_down().await {
            return Err(ResumeError::StateRestorationFailed(
                "Runtime is shutting down".to_string(),
            ));
        }

        // Verify continuity proof
        let record = self
            .inner
            .resonator_registry
            .verify_continuity(&continuity_proof)
            .await?;

        // Restore identity
        let identity = record.identity;

        // Restore presence state
        self.inner
            .presence_fabric
            .restore_presence(&identity, &record.presence_state)
            .await
            .map_err(|e| ResumeError::StateRestorationFailed(e.to_string()))?;

        // Restore attention budget
        self.inner
            .attention_allocator
            .restore_budget(&identity, &record.attention_state)
            .await
            .map_err(|e| ResumeError::StateRestorationFailed(e.to_string()))?;

        // Restore coupling topology
        self.inner
            .coupling_fabric
            .restore_couplings(&identity, &record.couplings)
            .await
            .map_err(|e| ResumeError::StateRestorationFailed(e.to_string()))?;

        // Reconcile pending commitments (placeholder)

        let handle = ResonatorHandle::new(identity, self.clone());

        self.inner.telemetry.resonator_resumed(&handle);

        tracing::info!("Resumed Resonator: {}", identity);

        Ok(handle)
    }

    // ═══════════════════════════════════════════════════════════════════
    // ACCESSORS FOR SUBSYSTEMS
    // ═══════════════════════════════════════════════════════════════════

    pub fn presence_fabric(&self) -> &Arc<PresenceFabric> {
        &self.inner.presence_fabric
    }

    pub fn coupling_fabric(&self) -> &Arc<CouplingFabric> {
        &self.inner.coupling_fabric
    }

    pub fn attention_allocator(&self) -> &Arc<AttentionAllocator> {
        &self.inner.attention_allocator
    }

    pub fn temporal_coordinator(&self) -> &Arc<TemporalCoordinator> {
        &self.inner.temporal_coordinator
    }

    pub fn scheduler(&self) -> &Arc<ResonanceScheduler> {
        &self.inner.scheduler
    }

    pub fn telemetry(&self) -> &Arc<RuntimeTelemetry> {
        &self.inner.telemetry
    }
}

/// Specification for creating a new Resonator
#[derive(Debug, Clone)]
pub struct ResonatorSpec {
    /// Identity specification
    pub identity: ResonatorIdentitySpec,

    /// Profile determines constraints and behaviors
    pub profile: ResonatorProfile,

    /// Initial capabilities (placeholder)
    pub capabilities: Vec<CapabilitySpec>,

    /// Presence configuration
    pub presence: PresenceConfig,

    /// Attention budget
    pub attention: AttentionBudgetSpec,

    /// Initial memory (for continuity across restarts)
    pub initial_memory: Option<MemorySnapshot>,

    /// Coupling affinity (preferred coupling patterns)
    pub coupling_affinity: CouplingAffinitySpec,
}

impl Default for ResonatorSpec {
    fn default() -> Self {
        Self {
            identity: ResonatorIdentitySpec::default(),
            profile: ResonatorProfile::default(),
            capabilities: Vec::new(),
            presence: PresenceConfig::default(),
            attention: AttentionBudgetSpec::default(),
            initial_memory: None,
            coupling_affinity: CouplingAffinitySpec::default(),
        }
    }
}

/// Identity specification for a Resonator
#[derive(Debug, Clone)]
pub struct ResonatorIdentitySpec {
    /// Display name (optional)
    pub name: Option<String>,

    /// Additional metadata
    pub metadata: std::collections::HashMap<String, String>,
}

impl Default for ResonatorIdentitySpec {
    fn default() -> Self {
        Self {
            name: None,
            metadata: std::collections::HashMap::new(),
        }
    }
}

/// Capability specification (placeholder)
#[derive(Debug, Clone)]
pub struct CapabilitySpec {
    pub name: String,
    pub version: String,
}

/// Memory snapshot (placeholder)
#[derive(Debug, Clone)]
pub struct MemorySnapshot {
    pub data: Vec<u8>,
}