//! Daemon → client events.

use crate::request::RequestId;

/// One event in the daemon's response stream for some request.
///
/// Streams are unordered across requests but ordered within a
/// single `RequestId`. Every terminal event sets some semantic
/// equivalent of "finished"; clients should not assume the stream
/// continues after a terminal event for a given request id.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub enum ServerEvent {
    /// The supervisor has admitted the request and queued it.
    /// `queue_position` is zero when work begins immediately.
    Accepted {
        request_id: RequestId,
        queue_position: u32,
    },
    /// One chunk of generated tokens. Terminal when `finished`.
    Tokens {
        request_id: RequestId,
        chunk: TokenChunk,
        finished: bool,
    },
    /// Response to a `DescribeFleet` request. Terminal for that
    /// request.
    FleetDescription(FleetSnapshot),
    /// Terminal error for a request.
    Error {
        request_id: RequestId,
        kind: ErrorKind,
        message: String,
    },
}

/// Generated tokens plus the rendered text. The text is what most
/// clients display; the IDs let token-counting clients (rate
/// limiters, billing surfaces) operate without re-tokenizing.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct TokenChunk {
    /// UTF-8 text the tokenizer produced for these IDs.
    pub text: String,
    /// Token IDs in this chunk, in generation order. Opaque to the
    /// client; the value space is the model's vocabulary.
    pub ids: Vec<u32>,
}

/// Snapshot of the fleet as the daemon sees it right now.
/// Deliberately minimal at A1; expanded as Thread D (audit) and
/// Thread G (operator UX) grow.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct FleetSnapshot {
    pub hostname: String,
    pub executors: Vec<ExecutorSummary>,
    pub loaded_models: Vec<LoadedModel>,
    pub active_requests: u32,
}

/// One executor's externally visible summary.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct ExecutorSummary {
    pub name: String,
    pub vendor: String,
    pub device_count: u32,
}

/// A model the daemon has resident.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct LoadedModel {
    pub name: String,
    pub revision: Option<String>,
    pub assigned_executor: String,
}

/// Closed enum of error kinds at the API layer. Vendor-specific
/// detail goes in the accompanying `message`. Adding a variant is
/// semver-minor; renaming or removing is semver-major.
#[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum ErrorKind {
    /// Request payload failed validation (shape, range, dtype).
    Invalid,
    /// Referenced model is not loaded and the daemon will not
    /// auto-load it for this request.
    ModelNotLoaded,
    /// Supervisor refused the request — out of capacity, over
    /// quota, or rate-limited.
    Rejected,
    /// Request was cancelled, either by the client or by the
    /// supervisor enforcing a deadline.
    Cancelled,
    /// Internal daemon error. `message` carries the detail.
    Internal,
}