parliament 0.1.0

//! # Parliament Traits
//!
//! This module defines the abstract interfaces (traits) that form the boundaries
//! of the Parliament's core logic. These are the "Ports" in a Hexagonal
//! Architecture, allowing the core domain to remain agnostic of the specific
//! infrastructure used for communication and persistence.

use crate::{
    error::Result,
    model::{Echo, FlightPlan, HuntId, Vigil, Writ},
};
use async_trait::async_trait;
use bytes::Bytes;

/// An interface for a persistent, ordered event log.
///
/// This trait represents the capability to record immutable facts (`Echo` events)
/// into the system's source of truth. An adapter for Fluvio, Kafka, or a
/// database would implement this trait.
#[async_trait]
pub trait EventStream: Send + Sync {
    /// Records an Echo into the immutable log.
    ///
    /// This operation must be idempotent and guarantee at-least-once delivery.
    /// The implementation is responsible for serialization and partitioning.
    async fn record_echo(&self, echo: &Echo) -> Result<()>;
}

/// A trait describing the capability to dispatch formal commands (`Writs`)
/// into the communication fabric of the Parliament.
///
/// This trait represents the capability to send messages, not a specific
/// topology like a "bus". An adapter for a NATS supercluster or another
/// message mesh would implement this trait.
#[async_trait]
pub trait WritDispatcher: Send + Sync {
    /// Issues a Writ for immediate action.
    ///
    /// This is a fire-and-forget operation, optimized for low latency.
    /// Delivery is not guaranteed, but the operation is expected to be fast.
    async fn issue_writ(&self, writ: &Writ) -> Result<()>;

    /// Issues a Writ and awaits a direct response.
    ///
    /// This is used for request-reply patterns where a direct, immediate
    /// answer is required. The returned `Bytes` object contains the raw
    /// response payload.
    async fn request_writ(&self, writ: &Writ) -> Result<Bytes>;
}

/// A trait for a long-running, stateful process. A Hunt is the core
/// unit of value creation in the Parliament.
///
/// Implementors of this trait represent a specific business process, managing
/// their own state (`Vigil`) and interacting with the rest of the system
/// via the `WritDispatcher` and `EventStream`.
#[async_trait]
pub trait Hunt: Send + Sync {
    /// The unique, strongly-typed identifier for this Hunt.
    fn id(&self) -> &HuntId;

    /// The current state of the Hunt's Vigil.
    fn vigil(&self) -> &Vigil;

    /// Initiate the Hunt based on a Sighting and an approved FlightPlan.
    /// This method is responsible for transitioning the state to `Stalking`.
    async fn begin(&mut self, flight_plan: FlightPlan) -> Result<()>;

    /// Conclude the Hunt by making an Offering.
    /// This method is responsible for transitioning the state to `Offering`
    /// and eventually `Folklore`.
    async fn conclude(&mut self) -> Result<()>;
}