elicitation 0.10.0

//! Core traits for elicitation.

use crate::{ElicitClient, ElicitCommunicator, ElicitResult};
use rmcp::service::{Peer, RoleClient};
use std::sync::Arc;

/// Builder for one-off style overrides.
///
/// Enables ergonomic syntax: `Config::with_style(ConfigStyle::Curt).elicit(&peer).await?`
pub struct ElicitBuilder<T: Elicitation> {
    style: T::Style,
}

impl<T: Elicitation + 'static> ElicitBuilder<T> {
    /// Create a new builder with the given style.
    fn new(style: T::Style) -> Self {
        Self { style }
    }

    /// Elicit the value with the pre-set style.
    ///
    /// This is a convenience method that creates an ElicitClient, sets the style,
    /// and elicits the value in one call.
    ///
    /// # Arguments
    ///
    /// * `peer` - The RMCP peer to use for interaction
    ///
    /// # Returns
    ///
    /// Returns the elicited value with the style applied.
    pub async fn elicit(self, peer: Arc<Peer<RoleClient>>) -> ElicitResult<T> {
        let client = ElicitClient::new(peer).with_style::<T, T::Style>(self.style);
        T::elicit(&client).await
    }
}

/// Shared metadata for prompts across all elicitation patterns.
///
/// This trait provides optional prompt text to guide user interaction.
/// Types can override this to provide custom prompts, or accept the
/// default (None).
pub trait Prompt {
    /// Optional prompt to guide user interaction.
    ///
    /// Returns `None` by default. Implement this to provide a custom prompt
    /// for a type.
    fn prompt() -> Option<&'static str> {
        None
    }
}

/// Main elicitation trait - entry point for value elicitation.
///
/// This trait defines how to elicit a value of a given type from the user
/// via MCP (Model Context Protocol). All types that can be elicited implement
/// this trait.
///
/// # Associated Types
///
/// * `Style` - The style enum for this type. Each type has its own style
///   enum that controls how prompts are presented. The style enum itself
///   implements `Elicitation`, allowing automatic style selection.
///
/// # Example
///
/// ```rust,ignore
/// use elicitation::{Elicitation, ElicitClient, ElicitResult};
/// # async fn example(client: &ElicitClient) -> ElicitResult<()> {
/// // Elicit an i32 from the user
/// let value: i32 = i32::elicit(communicator).await?;
/// # Ok(())
/// # }
/// ```
pub trait Elicitation: Sized + Prompt + 'static {
    /// The style enum for this type.
    ///
    /// Controls how prompts are presented. For types with multiple styles,
    /// this enum has variants for each style. For types with no custom styles,
    /// this enum has only a `Default` variant.
    ///
    /// The style enum itself implements `Elicitation` (using the Select pattern),
    /// enabling automatic style selection when no style is pre-set.
    type Style: Elicitation
        + crate::style::ElicitationStyle
        + Default
        + Clone
        + Send
        + Sync
        + 'static;

    /// Elicit a value of this type from the user via style-aware client.
    ///
    /// # Arguments
    ///
    /// * `client` - The style-aware client wrapper to use for interaction
    ///
    /// # Returns
    ///
    /// Returns `Ok(Self)` if elicitation succeeds, or `Err(ElicitError)` if:
    /// - The user provides invalid input
    /// - The MCP tool call fails
    /// - The user cancels the operation
    ///
    /// # Errors
    ///
    /// See [`ElicitError`](crate::ElicitError) for details on error conditions.
    fn elicit<C: ElicitCommunicator>(
        communicator: &C,
    ) -> impl std::future::Future<Output = ElicitResult<Self>> + Send;

    /// Server-side elicitation via MCP peer.
    ///
    /// This method enables server-side elicitation through rmcp's `Peer<RoleServer>`.
    /// It has a default implementation that creates an `ElicitServer` wrapper and
    /// delegates to the `elicit()` method.
    ///
    /// This is used by the `#[elicit_tools]` macro for automatic tool generation.
    ///
    /// # Arguments
    ///
    /// * `peer` - rmcp server peer for MCP communication
    ///
    /// # Returns
    ///
    /// The elicited value or an `ElicitError`.
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// // Direct usage in tool
    /// #[tool]
    /// async fn my_tool(peer: Peer<RoleServer>) -> Result<Config, ErrorData> {
    ///     let config = Config::elicit_checked(peer).await?;
    ///     Ok(config)
    /// }
    ///
    /// // Or with #[elicit_tools] macro
    /// #[elicit_tools(Config)]
    /// #[tool_router]
    /// impl MyServer { }
    /// ```
    fn elicit_checked(
        peer: crate::rmcp::service::Peer<crate::rmcp::service::RoleServer>,
    ) -> impl std::future::Future<Output = ElicitResult<Self>> + Send {
        async move {
            use crate::ElicitServer;
            let server = ElicitServer::new(peer);
            Self::elicit(&server).await
        }
    }

    /// Create a builder for one-off style override.
    ///
    /// This enables ergonomic syntax for eliciting a value with a specific style
    /// without manually creating a styled client.
    ///
    /// # Arguments
    ///
    /// * `style` - The style to use for this elicitation
    ///
    /// # Returns
    ///
    /// Returns an `ElicitBuilder` that can be used to elicit the value.
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// use elicitation::Elicitation;
    /// # async fn example(peer: &botticelli::Peer<botticelli_core::RoleClient>) {
    /// // One-off style override - concise syntax
    /// let config = Config::with_style(ConfigStyle::Curt)
    ///     .elicit(&peer)
    ///     .await?;
    /// # }
    /// ```
    fn with_style(style: Self::Style) -> ElicitBuilder<Self> {
        ElicitBuilder::new(style)
    }

    /// Elicit a value with proof it inhabits type Self.
    ///
    /// After successful elicitation, returns both the value and a proof
    /// that the value inhabits type `Self`. This proof can be carried
    /// forward to downstream functions requiring guarantees.
    ///
    /// # Returns
    ///
    /// Returns `Ok((value, proof))` where `proof` is `Established<Is<Self>>`.
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// use elicitation::{Elicitation, contracts::{Established, Is}};
    /// # async fn example<C: ElicitCommunicator>(communicator: &C) -> ElicitResult<()> {
    /// // Elicit with proof
    /// let (email, proof): (String, Established<Is<String>>) =
    ///     String::elicit_proven(communicator).await?;
    ///
    /// // Use proof in downstream function
    /// send_email(email, proof).await?;
    /// # Ok(())
    /// # }
    /// ```
    fn elicit_proven<C: ElicitCommunicator>(
        communicator: &C,
    ) -> impl std::future::Future<
        Output = ElicitResult<(
            Self,
            crate::contracts::Established<crate::contracts::Is<Self>>,
        )>,
    > + Send {
        async move {
            let value = Self::elicit(communicator).await?;
            Ok((value, crate::contracts::Established::assert()))
        }
    }

    /// Generate a Kani symbolic execution proof harness for this type.
    ///
    /// Returns a [`proc_macro2::TokenStream`] containing a complete `#[kani::proof]`
    /// harness that verifies this type's invariants using symbolic execution.
    ///
    /// The returned token stream can be written to a `.rs` file and compiled with
    /// `cargo kani` to verify the invariants. No Kani installation is required to
    /// call this method or generate the proof code.
    ///
    /// For composite types (derived via `#[derive(Elicit)]`), returns the aggregated
    /// proofs of all constituent field types.
    ///
    /// Returns a [`proc_macro2::TokenStream`] containing a complete `#[kani::proof]`
    /// harness verifying this type's invariants with symbolic inputs.
    ///
    /// There is no default — every `impl Elicitation` must provide this method
    /// explicitly. Types with no Kani proof must return `TokenStream::new()` to
    /// opt out consciously. This is enforced so that missing proofs are caught
    /// at compile time when the `proofs` feature is active.
    ///
    /// Available with the `proofs` feature.
    fn kani_proof() -> proc_macro2::TokenStream;

    /// Returns a [`proc_macro2::TokenStream`] containing a Verus-verified function
    /// with `requires`/`ensures` specifications for this type's invariants.
    ///
    /// There is no default — every `impl Elicitation` must provide this method
    /// explicitly. Types with no Verus proof must return `TokenStream::new()` to
    /// opt out consciously.
    ///
    /// Available with the `proofs` feature.
    fn verus_proof() -> proc_macro2::TokenStream;

    /// Returns a [`proc_macro2::TokenStream`] containing Creusot contract functions
    /// with `#[requires]`/`#[ensures]`/`#[trusted]` attributes for this type's invariants.
    ///
    /// There is no default — every `impl Elicitation` must provide this method
    /// explicitly. Types with no Creusot proof must return `TokenStream::new()` to
    /// opt out consciously.
    ///
    /// Available with the `proofs` feature.
    fn creusot_proof() -> proc_macro2::TokenStream;

    /// Returns a [`proc_macro2::TokenStream`] containing Prusti contract functions
    /// with `#[requires]`/`#[ensures]` attributes for this type's invariants.
    ///
    /// Defaults to an empty token stream. Prusti does not support Rust edition 2024,
    /// so this is optional until upstream support is restored.
    ///
    /// Available with the `proofs` feature.
    fn prusti_proof() -> proc_macro2::TokenStream {
        proc_macro2::TokenStream::new()
    }
}

/// Trait for generating values of a type.
///
/// Generators encapsulate strategies for creating values without requiring
/// async elicitation. This is useful for:
/// - Test data generation with configurable strategies
/// - Mock value creation for testing
/// - Deterministic value generation (seeded randomness, offsets, etc.)
/// - Agent-driven test fixture creation
///
/// # Design Philosophy
///
/// Generators are **orthogonal to elicitation**. They:
/// - Are synchronous (no async/await)
/// - Don't require MCP client access
/// - Can be configured once and used many times
/// - Encapsulate "how to create this value" as data
///
/// Elicitation implementations can leverage generators when appropriate,
/// but generators exist independently and can be used without elicitation.
///
/// # Example
///
/// ```rust,ignore
/// // Elicit the generation strategy once
/// let mode = InstantGenerationMode::elicit(communicator).await?;
/// let generator = InstantGenerator::new(mode);
///
/// // Generate many values with the same strategy
/// let t1 = generator.generate();
/// let t2 = generator.generate();
/// let t3 = generator.generate();
/// ```
pub trait Generator {
    /// The type this generator produces.
    type Target;

    /// Generate a value of the target type.
    ///
    /// This is synchronous - all configuration must happen before calling generate().
    fn generate(&self) -> Self::Target;
}

/// Static introspection into a type's elicitation structure.
///
/// This trait provides compile-time metadata about HOW a type will be elicited,
/// enabling observability, debugging, and agent guidance without runtime state tracking.
///
/// # Observability Use Cases
///
/// - **Metrics**: Instrument elicitation with Prometheus counters/histograms
/// - **Tracing**: Add structured metadata to OpenTelemetry spans
/// - **Debugging**: Visualize the elicitation structure before execution
/// - **Agent Guidance**: Query type structure to plan elicitation strategy
///
/// # Design Philosophy
///
/// Unlike runtime validators or state machines, `ElicitIntrospect` is **stateless**:
/// - No stack traces or history tracking
/// - No memory overhead (just static metadata)
/// - O(1) memory usage regardless of nesting depth
/// - Pure functions with no side effects
///
/// This makes it ideal for developers to call in traces/metrics without
/// worrying about memory bloat or performance impact.
///
/// # Example: Basic Introspection
///
/// ```rust,ignore
/// use elicitation::{ElicitIntrospect, ElicitationPattern};
///
/// // Query structure before elicitation
/// let meta = Config::metadata();
/// println!("About to elicit: {}", meta.type_name);
///
/// match meta.pattern() {
///     ElicitationPattern::Survey => {
///         if let PatternDetails::Survey { fields } = meta.details {
///             println!("Requires {} fields", fields.len());
///         }
///     }
///     _ => {}
/// }
/// ```
///
/// # Example: Prometheus Metrics
///
/// ```rust,ignore
/// use prometheus::{Counter, Histogram};
///
/// async fn elicit_with_metrics<T: ElicitIntrospect>(
///     communicator: &impl ElicitCommunicator
/// ) -> ElicitResult<T> {
///     let meta = T::metadata();
///
///     // Increment counter for this type
///     ELICITATION_COUNTER
///         .with_label_values(&[meta.type_name, meta.pattern().as_str()])
///         .inc();
///
///     // Time the elicitation
///     let timer = ELICITATION_DURATION
///         .with_label_values(&[meta.type_name])
///         .start_timer();
///
///     let result = T::elicit(communicator).await;
///     timer.observe_duration();
///
///     result
/// }
/// ```
///
/// # Example: OpenTelemetry Tracing
///
/// ```rust,ignore
/// #[tracing::instrument(skip(communicator), fields(
///     type_name = %T::metadata().type_name,
///     pattern = ?T::pattern(),
///     field_count = tracing::field::Empty,
/// ))]
/// async fn elicit_with_tracing<T: ElicitIntrospect>(
///     communicator: &impl ElicitCommunicator
/// ) -> ElicitResult<T> {
///     let meta = T::metadata();
///
///     // Add structured fields based on pattern
///     if let PatternDetails::Survey { fields } = meta.details {
///         tracing::Span::current().record("field_count", fields.len());
///     }
///
///     T::elicit(communicator).await
/// }
/// ```
pub trait ElicitIntrospect: Elicitation {
    /// What elicitation pattern does this type use?
    ///
    /// This is a lightweight query that returns the pattern without
    /// allocating or examining detailed metadata.
    fn pattern() -> ElicitationPattern;

    /// Get the complete structural metadata for this type.
    ///
    /// Returns static metadata describing:
    /// - Type name
    /// - Description/prompt (if any)
    /// - Pattern-specific details (fields, options, etc.)
    ///
    /// This is a pure function with no side effects or state tracking.
    fn metadata() -> TypeMetadata;
}

/// The elicitation pattern used by a type.
///
/// Each pattern represents a different interaction model:
/// - **Survey**: Sequential field-by-field elicitation (structs)
/// - **Select**: Choose from finite options, then elicit variant fields (enums)
/// - **Affirm**: Yes/no confirmation (booleans)
/// - **Primitive**: Direct value elicitation (strings, numbers, etc.)
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum ElicitationPattern {
    /// Struct with sequential field elicitation.
    ///
    /// Example: `struct Config { timeout: u32, retries: u8 }`
    Survey,

    /// Enum with variant selection followed by field elicitation.
    ///
    /// Example: `enum Mode { Fast, Safe { level: u8 } }`
    Select,

    /// Boolean yes/no confirmation.
    ///
    /// Example: `bool`
    Affirm,

    /// Primitive type with direct value elicitation.
    ///
    /// Example: `String`, `i32`, `f64`
    Primitive,
}

impl ElicitationPattern {
    /// Get string representation for metrics/logging.
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::Survey => "survey",
            Self::Select => "select",
            Self::Affirm => "affirm",
            Self::Primitive => "primitive",
        }
    }
}

/// Complete metadata describing a type's elicitation structure.
///
/// This is static metadata returned by `ElicitIntrospect::metadata()`.
/// It describes the structure without tracking runtime state.
#[derive(Debug, Clone)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct TypeMetadata {
    /// Type name (e.g., "Config", "Mode", "String").
    pub type_name: &'static str,

    /// Optional description or prompt text.
    ///
    /// This comes from the type's `Prompt` implementation.
    pub description: Option<&'static str>,

    /// Pattern-specific structural details.
    pub details: PatternDetails,
}

impl TypeMetadata {
    /// Get the elicitation pattern.
    pub fn pattern(&self) -> ElicitationPattern {
        match self.details {
            PatternDetails::Survey { .. } => ElicitationPattern::Survey,
            PatternDetails::Select { .. } => ElicitationPattern::Select,
            PatternDetails::Affirm => ElicitationPattern::Affirm,
            PatternDetails::Primitive => ElicitationPattern::Primitive,
        }
    }
}

/// Metadata for one variant of a Select-pattern enum.
///
/// Unit variants have `fields: vec![]`. Tuple and struct variants carry
/// `FieldInfo` for each associated field, enabling graph traversal and
/// complete structural introspection.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct VariantMetadata {
    /// Variant label shown to the agent (e.g., `"Fast"`, `"Production"`).
    pub label: String,
    /// Field edges for this variant. Empty for unit variants.
    pub fields: Vec<crate::FieldInfo>,
}

/// Pattern-specific structural details.
///
/// Each variant corresponds to an `ElicitationPattern` and provides
/// the relevant metadata for that pattern.
///
/// Uses owned data to support both static and dynamic implementations.
#[derive(Debug, Clone)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum PatternDetails {
    /// Survey pattern (structs).
    Survey {
        /// Field metadata from the `Survey` trait.
        fields: Vec<crate::FieldInfo>,
    },

    /// Select pattern (enums).
    ///
    /// Each [`VariantMetadata`] carries the variant label and any associated
    /// field types, enabling full structural traversal of enums with data variants.
    Select {
        /// Variant metadata including per-variant field types.
        variants: Vec<VariantMetadata>,
    },

    /// Affirm pattern (booleans).
    Affirm,

    /// Primitive pattern (direct value).
    Primitive,
}

impl PatternDetails {
    /// For Select patterns: the variant labels in order.
    ///
    /// Convenience method for callers that only need labels (e.g. rendering
    /// option lists) without traversing variant field structure.
    pub fn variant_labels(&self) -> Vec<&str> {
        match self {
            Self::Select { variants } => variants.iter().map(|v| v.label.as_str()).collect(),
            _ => vec![],
        }
    }
}