Types

use async_trait::async_trait;
use serde_json::Value;

#[async_trait]
pub trait ProtocolModule: Send + Sync {
    /// Canonical protocol name. Static string for fast comparison.
    fn protocol_name(&self) -> &'static str;

    /// Semantic version of this implementation.
    fn version(&self) -> &'static str;

    /// All operations this module supports.
    fn operations(&self) -> Vec<&'static str>;

    /// Dispatch a single operation.
    async fn invoke(
        &self,
        operation: &str,
        payload: Value,
        ctx: &InvokeContext,
    ) -> Result<Response, ProtocolError>;
}

#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct InvokeContext {
    /// UUID v4. Threaded through the entire request flow.
    pub correlation_id: String,

    /// Organizational tenant scope for the call.
    pub tenant_id: String,

    /// Caller DID (did:oas:...).
    pub agent_did: String,

    /// Filled by IdentityMiddleware::enrich before handle_request.
    pub resolved_identity: Option<ResolvedAgentIdentity>,

    /// W3C Trace Context — traceparent + tracestate.
    pub trace_context: Option<TraceContext>,

    /// RFC3339 timestamp at the gateway ingress.
    pub timestamp: String,

    /// Free-form metadata map. Plugins read their config from here.
    pub metadata: HashMap<String, Value>,
}

impl InvokeContext {
    pub fn identity(&self) -> Option<&ResolvedAgentIdentity>;
    pub fn caller_entity_kind(&self) -> AgentEntityKind;
    pub fn caller_human_root(&self) -> Option<&str>;
    pub fn caller_lineage_verified(&self) -> bool;
    pub fn plugin_config(&self) -> Option<&Value>;
}

#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct Response {
    pub data: Value,
    pub metadata: Option<HashMap<String, Value>>,
}

#[derive(thiserror::Error, Debug)]
pub enum ProtocolError {
    #[error("unknown operation: {0}")]
    UnknownOperation(String),

    #[error("invalid payload: {0}")]
    InvalidPayload(String),

    #[error("capability missing: {0}")]
    MissingCapability(String),

    #[error("policy denied: {reason}")]
    PolicyDenied { reason: String },

    #[error("adapter error: {0}")]
    AdapterError(String),

    #[error("timeout")]
    Timeout,

    #[error("internal: {0}")]
    Internal(String),
}

#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct ResolvedAgentIdentity {
    pub did: String,
    pub entity_kind: AgentEntityKind,
    pub name: Option<String>,
    pub human_root_did: Option<String>,
    pub lineage_depth: u32,
    pub lineage_verified: bool,
    pub creator_did: Option<String>,
    pub conformance_level: ConformanceLevel,
    pub capabilities: Vec<AgentCapability>,
    pub service_endpoints: Vec<AgentServiceEndpoint>,
    pub revoked: bool,
    pub auth_method: String,
    pub extended: HashMap<String, Value>,
}

pub enum AgentEntityKind {
    HumanRoot,
    MultiHumanRoot,
    EntityNameRecord,
    Agent,
    AgentInstance,
    Tool,
    Skill,
    Workflow,
    Model,
    Dataset,
    Service,
    Unknown(String),
}

pub enum ConformanceLevel {
    L0, // minimal: DID exists, no lineage
    L1, // standard: lineage verified for non-roots
    L2, // enhanced: full extended sections, attestations, reputation
}

impl ResolvedAgentIdentity {
    pub fn is_human_root(&self) -> bool;
    pub fn is_autonomous_org(&self) -> bool;
    pub fn has_verified_lineage(&self) -> bool;
    pub fn effective_root_did(&self) -> &str;
    pub fn has_capability(&self, name: &str) -> bool;

    pub fn local_admin() -> Self;          // dev only
    pub fn unresolved(did: &str) -> Self;  // fallback when resolution fails
}

#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct AgentCapability {
    /// Hierarchical capability name. e.g. "map.macs.auth_negotiation"
    /// or "map.mind.*" for protocol-wildcard.
    pub name: String,

    /// Optional time-bound expiry.
    pub expires_at: Option<chrono::DateTime<chrono::Utc>>,

    /// Spending / rate ceiling specific to this capability.
    pub limits: Option<CapabilityLimits>,

    /// Caveats — additional constraints (jurisdiction, time-of-day, etc.).
    pub caveats: Vec<String>,
}

#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct AgentServiceEndpoint {
    pub kind: String,        // "did-auth" | "mcp" | "a2a" | ...
    pub url: String,
    pub protocols: Vec<String>,
}