tawasuyu/brahman

1//! El trait `Engine` — contrato uniforme del orquestador.
2
3use crate::error::EngineError;
4use crate::event::TelemetryFrame;
5use crate::intent::{ExecHandle, Intent};
6use async_trait::async_trait;
7use sandokan_lifecycle::LifecycleState;
8use std::time::Duration;
9use ulid::Ulid;
10
11/// El orquestador. Tres implementaciones lo cumplen de forma intercambiable:
12///
13/// - `LocalEngine` — encarna in-process (`arje-incarnate` + `arje-brain-rules`).
14/// - `DaemonEngine` — delega a otro proceso vía Unix socket (postcard).
15/// - `RemoteEngine` — delega a otro host vía `brahman-ssh-multiplex`.
16///
17/// Un helper `Engine::auto()` (en `sandokan-local`) prueba si hay un
18/// daemon escuchando y elige `DaemonEngine`; si no, `LocalEngine`.
19///
20/// El contrato es poll-based (sin streams) para que las tres impls lo
21/// cumplan uniformemente sin complejidad de `Stream` sobre trait objects.
22#[async_trait]
23pub trait Engine: Send + Sync {
24    /// Encarna una intención. Devuelve un handle a la entidad corriendo.
25    async fn run(&self, intent: Intent) -> Result<ExecHandle, EngineError>;
26
27    /// Detiene una entidad con período de gracia (SIGTERM → espera →
28    /// SIGKILL). `grace == 0` = kill inmediato.
29    async fn stop(&self, card_id: Ulid, grace: Duration) -> Result<(), EngineError>;
30
31    /// Lista las entidades actualmente activas.
32    async fn list(&self) -> Result<Vec<ExecHandle>, EngineError>;
33
34    /// Estado actual de una entidad.
35    async fn status(&self, card_id: Ulid) -> Result<LifecycleState, EngineError>;
36
37    /// Telemetría puntual de una entidad.
38    async fn telemetry(&self, card_id: Ulid) -> Result<TelemetryFrame, EngineError>;
39}