//! Advanced query DTOs for constraints checking and specialized lenses.

use serde::{Deserialize, Serialize};
use utoipa::ToSchema;

use super::enums::{ObjectValueDto, SourceClassDto};

// ============================================================================
// Constraints API DTOs (Agent Pre-Flight Checks)
// ============================================================================

/// Query parameters for the constraints endpoint.
///
/// Returns categorized constraints (must_use, forbidden, prefer) for a subject.
#[derive(Debug, Clone, Serialize, Deserialize, ToSchema, utoipa::IntoParams)]
pub struct ConstraintsQueryParams {
    /// Subject entity to check constraints for (required)
    pub subject: String,
}

/// A constraint assertion in a specific category.
#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
pub struct ConstraintEntryDto {
    /// The constraint category (extracted from predicate, e.g., "http_client" from "must_use:http_client")
    pub category: String,

    /// The constrained value (from assertion object)
    pub value: ObjectValueDto,

    /// Confidence in this constraint (0.0 to 1.0)
    #[schema(minimum = 0.0, maximum = 1.0)]
    pub confidence: f32,

    /// Hash of the underlying assertion (hex-encoded)
    pub assertion_hash: String,

    /// When this constraint was asserted (Unix timestamp)
    pub timestamp: u64,

    /// Source class of the constraint
    pub source_class: SourceClassDto,
}

/// Response from the constraints endpoint.
///
/// Returns assertions categorized by constraint type for agent pre-flight checks.
#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
pub struct ConstraintsResponse {
    /// The subject that was queried
    pub subject: String,

    /// Required constraints (predicate: `must_use:*`). Non-negotiable.
    pub must_use: Vec<ConstraintEntryDto>,

    /// Forbidden constraints (predicate: `forbidden:*`). Explicitly banned.
    pub forbidden: Vec<ConstraintEntryDto>,

    /// Preferred constraints (predicate: `prefer:*`). Recommendations.
    pub prefer: Vec<ConstraintEntryDto>,

    /// Total assertions considered (including non-constraint predicates)
    pub candidates_count: usize,

    /// Conflict score across all constraints (0.0 = consistent, 1.0 = conflicting)
    #[schema(minimum = 0.0, maximum = 1.0)]
    pub conflict_score: f32,

    /// Unix timestamp when this was computed
    pub computed_at: u64,
}
