relay-knowledge 1.1.16

use serde::{Deserialize, Serialize};

use super::{DomainError, error::required_text};

/// Evidence media unit tracked by multimodal ingestion and retrieval.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum EvidenceModality {
    TextSpan,
    ImageAsset,
    OcrText,
    Caption,
    ImageEmbedding,
    Table,
    LayoutRegion,
}

impl EvidenceModality {
    /// Stable storage and API representation.
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::TextSpan => "text_span",
            Self::ImageAsset => "image_asset",
            Self::OcrText => "ocr_text",
            Self::Caption => "caption",
            Self::ImageEmbedding => "image_embedding",
            Self::Table => "table",
            Self::LayoutRegion => "layout_region",
        }
    }

    /// Returns whether this modality is derived from a parent evidence item.
    pub const fn requires_parent(self) -> bool {
        matches!(
            self,
            Self::OcrText | Self::Caption | Self::ImageEmbedding | Self::LayoutRegion
        )
    }
}

/// Page-space rectangle for table and layout evidence.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct LayoutRegion {
    pub page_number: u32,
    pub x: u32,
    pub y: u32,
    pub width: u32,
    pub height: u32,
}

impl LayoutRegion {
    /// Validates a one-based page coordinate and non-empty rectangle.
    pub fn new(
        page_number: u32,
        x: u32,
        y: u32,
        width: u32,
        height: u32,
    ) -> Result<Self, DomainError> {
        if page_number == 0 {
            return Err(DomainError::invalid(
                "layout_region",
                "page number must be one-based",
            ));
        }
        if width == 0 || height == 0 {
            return Err(DomainError::invalid(
                "layout_region",
                "width and height must be greater than zero",
            ));
        }

        Ok(Self {
            page_number,
            x,
            y,
            width,
            height,
        })
    }
}

/// Extraction outcome recorded when multimodal workers degrade or fail.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ExtractionStatus {
    Succeeded,
    Degraded,
    Failed,
}

impl ExtractionStatus {
    /// Stable storage and API representation.
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Succeeded => "succeeded",
            Self::Degraded => "degraded",
            Self::Failed => "failed",
        }
    }
}

/// Diagnostic emitted by an extractor without blocking other modalities.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ExtractionDiagnostic {
    pub status: ExtractionStatus,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub message: Option<String>,
}

impl ExtractionDiagnostic {
    /// Validates status and requires a useful message for degraded/failed work.
    pub fn new(status: ExtractionStatus, message: Option<String>) -> Result<Self, DomainError> {
        let message = message
            .map(|value| required_text("extraction_diagnostic", value))
            .transpose()?;
        if status != ExtractionStatus::Succeeded && message.is_none() {
            return Err(DomainError::invalid(
                "extraction_diagnostic",
                "degraded or failed extraction requires a diagnostic message",
            ));
        }

        Ok(Self { status, message })
    }
}

/// Metadata shared by text, image, OCR, caption, table, layout, and embedding evidence.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct EvidenceExtractionMetadata {
    pub modality: EvidenceModality,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub source_uri: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub source_hash: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub media_hash: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub extractor: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub extractor_version: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub observed_at: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub parent_evidence_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub layout_region: Option<LayoutRegion>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub embedding_model: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub embedding_dimension: Option<u16>,
    pub diagnostic: ExtractionDiagnostic,
}

impl EvidenceExtractionMetadata {
    /// Creates validated default text evidence metadata.
    pub fn text_span() -> Self {
        Self {
            modality: EvidenceModality::TextSpan,
            source_uri: None,
            source_hash: None,
            media_hash: None,
            extractor: None,
            extractor_version: None,
            observed_at: None,
            parent_evidence_id: None,
            layout_region: None,
            embedding_model: None,
            embedding_dimension: None,
            diagnostic: ExtractionDiagnostic {
                status: ExtractionStatus::Succeeded,
                message: None,
            },
        }
    }

    /// Validates extractor metadata and cross-field modality invariants.
    pub fn validate(mut self) -> Result<Self, DomainError> {
        self.source_uri = normalize_optional_text("source_uri", self.source_uri)?;
        self.source_hash = normalize_optional_text("source_hash", self.source_hash)?;
        self.media_hash = normalize_optional_text("media_hash", self.media_hash)?;
        self.extractor = normalize_optional_text("extractor", self.extractor)?;
        self.extractor_version =
            normalize_optional_text("extractor_version", self.extractor_version)?;
        self.observed_at = normalize_optional_text("observed_at", self.observed_at)?;
        self.parent_evidence_id =
            normalize_optional_text("parent_evidence_id", self.parent_evidence_id)?;
        self.embedding_model = normalize_optional_text("embedding_model", self.embedding_model)?;
        self.diagnostic =
            ExtractionDiagnostic::new(self.diagnostic.status, self.diagnostic.message)?;
        if let Some(region) = self.layout_region {
            self.layout_region = Some(LayoutRegion::new(
                region.page_number,
                region.x,
                region.y,
                region.width,
                region.height,
            )?);
        }

        if self.modality.requires_parent() && self.parent_evidence_id.is_none() {
            return Err(DomainError::invalid(
                "parent_evidence_id",
                "derived multimodal evidence must reference a parent evidence item",
            ));
        }
        if self.modality == EvidenceModality::ImageEmbedding
            && (self.embedding_model.is_none()
                || self.embedding_dimension.is_none()
                || self.embedding_dimension == Some(0))
        {
            return Err(DomainError::invalid(
                "embedding_model",
                "image embedding evidence requires model and positive dimension metadata",
            ));
        }
        if self.modality == EvidenceModality::LayoutRegion && self.layout_region.is_none() {
            return Err(DomainError::invalid(
                "layout_region",
                "layout region evidence requires coordinates",
            ));
        }
        if self.modality == EvidenceModality::ImageAsset
            && self.media_hash.is_none()
            && self.source_hash.is_none()
        {
            return Err(DomainError::invalid(
                "media_hash",
                "image evidence requires a media hash or source hash",
            ));
        }

        Ok(self)
    }
}

fn normalize_optional_text(
    field: &'static str,
    value: Option<String>,
) -> Result<Option<String>, DomainError> {
    value.map(|inner| required_text(field, inner)).transpose()
}

#[cfg(test)]
#[path = "mod_tests.rs"]
mod tests;