//! Self-describing capability metadata for service-shaped Lyquids.

//!

//! A Lyquid that wants to be discoverable as a service exposes a

//! `get_capabilities() -> LyquidResult<String>` ABI method returning a JSON-encoded

//! array of [`ServiceDescriptor`]. Other Lyquids and off-chain clients read this to

//! learn what capabilities the service offers, what input/output shapes to use, what

//! risk tier it operates at, and what it typically costs.

//!

//! ## Forward compatibility

//!

//! `ServiceDescriptor` is a versioned data shape, not an on-chain ABI commitment.

//! Optional fields use `#[serde(default)]` so older readers stay compatible. The

//! `capability` string carries the contract — `"amazon.gift.research.v1"` and

//! `"amazon.gift.research.v2"` are distinct capabilities.

//!

//! ## Why not commit schema hashes on chain?

//!

//! `input_schema` / `output_schema` are stored as full JSON Schema documents (not

//! hashes) because the immediate consumer is an LLM coordinator that needs to *read*

//! them. We deliberately skip on-chain hash commitment until a verifier exists — adding

//! a `*_schema_hash` field today would be dead weight.

use lyquor_primitives::LyquidID;

use serde::{Deserialize, Serialize};

use serde_json::Value;

use crate::core::RiskTier;

/// One capability advertised by a Lyquid.

#[derive(Clone, Debug, Serialize, Deserialize)]

pub struct ServiceDescriptor {

    /// The LyquidID of the service exposing this capability. Self-describing so a

    /// coordinator can cache `(capability, lyquid_id)` pairs without needing a side

    /// channel to learn which Lyquid produced the descriptor.

    pub lyquid_id: LyquidID,

    /// Human-readable capability identifier (e.g. `"amazon.gift.research.v1"`).

    /// Version-suffixed by convention so distinct revisions of the same logical

    /// capability are distinguishable.

    pub capability: String,

    /// Semver string for the implementation. Lets a coordinator pick (or reject) a

    /// service based on bug fixes / behavior changes within the same capability id.

    pub version: String,

    /// Full JSON Schema describing the dispatch input the service accepts.

    pub input_schema: Value,

    /// Full JSON Schema describing the receipt output the service produces.

    pub output_schema: Value,

    /// Highest risk tier this capability operates at. Coordinators use this to drive

    /// approval policy before dispatching.

    pub max_risk: RiskTier,

    /// Optional cost estimate. Coordinators that budget across a plan need this to

    /// reject obvious blowups before dispatching.

    #[serde(default)]

    pub cost_hint: Option<CostHint>,

    /// Replay/retry semantics.

    pub idempotency: IdempotencyClass,

    /// `true` if a coordinator may call this capability without explicit per-deploy

    /// authorization (e.g. read-only catalog queries). Default `false` — callers

    /// should be allowlisted by the service.

    #[serde(default)]

    pub allowed_by_default: bool,

}

/// Cost hint for coordinator budgeting. `unit` names the cost unit

/// (e.g. `"USDC"`); `typical_base_units` is a big-number string in that unit's smallest

/// denomination (so a 1 USDC fee shows up as `"1000000"`).

#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]

pub struct CostHint {

    pub unit: String,

    pub typical_base_units: String,

}

/// Replay/retry semantics of a capability. Lets a coordinator decide whether re-issuing

/// the same call is safe and whether it needs to track an idempotency key.

#[derive(Copy, Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]

pub enum IdempotencyClass {

    /// Safe to retry; identical inputs produce the same effect (e.g. a `correlation_id`-

    /// keyed call where the service dedupes internally).

    Idempotent,

    /// Retrying may produce duplicate effects unless the caller dedupes. Coordinators

    /// should retry only with care.

    AtLeastOnce,

    /// Caller must supply an `idempotency_key`; the service refuses duplicates within a

    /// retention window.

    ExactlyOnce,

}

/// Encodes a slice of descriptors as a JSON array string, the format `get_capabilities()`

/// methods return. Wraps `serde_json` errors with a small context prefix.

pub fn capabilities_json(descriptors: &[ServiceDescriptor]) -> Result<String, String> {

    serde_json::to_string(descriptors).map_err(|e| 
format!0
("encode capabilities: {e}"))

}

impl ServiceDescriptor {

    /// Builder entry point. Required fields go up front; optionals (`cost`,

    /// `allowed_by_default`) are chainable setters with sensible defaults

    /// (`cost_hint = None`, `allowed_by_default = false`).

    ///

    /// Replaces 13-line struct literals in `get_capabilities()` ABI methods with:

    /// ```ignore

    /// ServiceDescriptor::build(

    ///     ctx.lyquid_id, CAPABILITY, "1.0.0",

    ///     my_input_schema(), my_output_schema(),

    ///     RiskTier::SensitiveMutation, IdempotencyClass::AtLeastOnce,

    /// ).cost("USDC", "100000").allowed_by_default(true).to_capabilities_json()

    /// ```

    pub fn build(

        lyquid_id: LyquidID, capability: impl Into<String>, version: impl Into<String>, input_schema: Value,

        output_schema: Value, max_risk: RiskTier, idempotency: IdempotencyClass,

    ) -> ServiceDescriptorBuilder {

        ServiceDescriptorBuilder {

            descriptor: ServiceDescriptor {

                lyquid_id,

                capability: capability.into(),

                version: version.into(),

                input_schema,

                output_schema,

                max_risk,

                cost_hint: None,

                idempotency,

                allowed_by_default: false,

            },

        }

    }

}

/// Owns a partially-constructed `ServiceDescriptor`. See [`ServiceDescriptor::build`].

pub struct ServiceDescriptorBuilder {

    descriptor: ServiceDescriptor,

}

impl ServiceDescriptorBuilder {

    /// Set the cost hint (currency unit + typical amount in that unit's smallest

    /// denomination as a decimal string).

    pub fn cost(mut self, unit: impl Into<String>, typical_base_units: impl Into<String>) -> Self {

        self.descriptor.cost_hint = Some(CostHint {

            unit: unit.into(),

            typical_base_units: typical_base_units.into(),

        });

        self

    }

    /// Override `allowed_by_default` (defaults to `false`).

    pub fn allowed_by_default(mut self, v: bool) -> Self {

        self.descriptor.allowed_by_default = v;

        self

    }

    /// Consume the builder and return the descriptor.

    pub fn finish(self) -> ServiceDescriptor {

        self.descriptor

    }

    /// Shortcut for `capabilities_json(&[self.finish()])` — the 1-descriptor case all

    /// current `get_capabilities()` ABI methods use.

    pub fn to_capabilities_json(self) -> Result<String, String> {

        capabilities_json(&[self.finish()])

    }

}

#[cfg(test)]

mod tests {

    use super::*;

    use serde_json::json;

    fn sample() -> ServiceDescriptor {

        ServiceDescriptor {

            lyquid_id: LyquidID([0xaa; 20]),

            capability: "amazon.gift.research.v1".into(),

            version: "1.0.0".into(),

            input_schema: json!({"type": "object", "required": ["recipient_description"]}),

            output_schema: json!({"type": "object", "required": ["recommendations"]}),

            max_risk: RiskTier::ReadOnly,

            cost_hint: Some(CostHint {

                unit: "USDC".into(),

                typical_base_units: "100000".into(),

            }),

            idempotency: IdempotencyClass::Idempotent,

            allowed_by_default: false,

        }

    }

    #[test]

    fn capabilities_json_roundtrip() {

        let descriptors = vec![sample()];

        let encoded = capabilities_json(&descriptors).expect("encode");

        let decoded: Vec<ServiceDescriptor> = serde_json::from_str(&encoded).expect("decode");

        assert_eq!(decoded.len(), 1);

        assert_eq!(decoded[0].capability, "amazon.gift.research.v1");

        assert_eq!(decoded[0].version, "1.0.0");

        assert_eq!(decoded[0].max_risk, RiskTier::ReadOnly);

        assert_eq!(decoded[0].idempotency, IdempotencyClass::Idempotent);

        assert_eq!(

            decoded[0].cost_hint.as_ref().unwrap(),

            &CostHint {

                unit: "USDC".into(),

                typical_base_units: "100000".into(),

            }

        );

        assert!(!decoded[0].allowed_by_default);

    }

    #[test]

    fn cost_hint_is_optional() {

        let mut d = sample();

        d.cost_hint = None;

        let encoded = capabilities_json(&[d]).expect("encode");

        let decoded: Vec<ServiceDescriptor> = serde_json::from_str(&encoded).expect("decode");

        assert!(decoded[0].cost_hint.is_none());

    }

    #[test]

    fn idempotency_variants_roundtrip() {

        for variant in [

            IdempotencyClass::Idempotent,

            IdempotencyClass::AtLeastOnce,

            IdempotencyClass::ExactlyOnce,

        ] {

            let encoded = serde_json::to_string(&variant).expect("encode");

            let decoded: IdempotencyClass = serde_json::from_str(&encoded).expect("decode");

            assert_eq!(decoded, variant);

        }

    }

    #[test]

    fn capabilities_json_empty_slice() {

        let encoded = capabilities_json(&[]).expect("encode");

        assert_eq!(encoded, "[]");

    }

    #[test]

    fn builder_produces_descriptor_with_defaults() {

        let d = ServiceDescriptor::build(

            LyquidID([0xbb; 20]),

            "demo.capability.v1",

            "0.1.0",

            json!({"type": "object"}),

            json!({"type": "object"}),

            RiskTier::SensitiveMutation,

            IdempotencyClass::AtLeastOnce,

        )

        .finish();

        assert_eq!(d.capability, "demo.capability.v1");

        assert_eq!(d.version, "0.1.0");

        assert_eq!(d.max_risk, RiskTier::SensitiveMutation);

        assert_eq!(d.idempotency, IdempotencyClass::AtLeastOnce);

        assert!(d.cost_hint.is_none(), "cost defaults to None");

        assert!(!d.allowed_by_default, "allowed_by_default defaults to false");

    }

    #[test]

    fn builder_setters_chain() {

        let json = ServiceDescriptor::build(

            LyquidID([0xcc; 20]),

            "demo.capability.v1",

            "0.1.0",

            json!({"type": "object"}),

            json!({"type": "object"}),

            RiskTier::ReadOnly,

            IdempotencyClass::Idempotent,

        )

        .cost("USDC", "100000")

        .allowed_by_default(true)

        .to_capabilities_json()

        .expect("encode");

        // Round-trip and verify cost + allowed flag landed.

        let decoded: Vec<ServiceDescriptor> = serde_json::from_str(&json).expect("decode");

        assert_eq!(decoded.len(), 1);

        let cost = decoded[0].cost_hint.as_ref().expect("cost set");

        assert_eq!(cost.unit, "USDC");

        assert_eq!(cost.typical_base_units, "100000");

        assert!(decoded[0].allowed_by_default);

    }

    #[test]

    fn allowed_by_default_default_false_when_missing() {

        // Construct a JSON value omitting `allowed_by_default` and `cost_hint`.

        let mut value = serde_json::to_value(sample()).unwrap();

        let obj = value.as_object_mut().unwrap();

        obj.remove("allowed_by_default");

        obj.remove("cost_hint");

        let s = serde_json::to_string(&value).unwrap();

        let decoded: ServiceDescriptor = serde_json::from_str(&s).expect("decode");

        assert!(!decoded.allowed_by_default, "missing field should default to false");

        assert!(decoded.cost_hint.is_none(), "missing cost_hint should default to None");

    }

}