ahri_tre_app/

browser_study_discovery.rs

//! Browser-safe Study discovery and search workflow projection.

use crate::browser_resource_discovery::{
    BrowserResourceDiscoveryCapability, BrowserResourceDiscoveryError,
    BrowserResourceDiscoverySource,
};

use ahri_tre_protocol::{
    ProtocolError, ProtocolVersion, PublicUuid,
    domain::DomainSummary,
    refs::{StudyRef, TagRef, TagScope, TagSummary, VersionRef},
    search::PredicateSet,
    study::{
        BrowserContentSummaryPolicy, BrowserSearchOrdering, BrowserStudyAccessCondition,
        BrowserStudyAccessRequestReference, BrowserStudyDiscoveryEmptyState,
        BrowserStudyDiscoveryRecord, BrowserStudyDiscoveryResponse, BrowserStudyFacts,
        BrowserStudyMatchEvidence, BrowserStudyMatchedField, BrowserStudySearchEmptyState,
        BrowserStudySearchInput, BrowserStudySearchRecord, BrowserStudySearchResponse,
        MAX_BROWSER_STUDY_MATCH_EVIDENCE, StudyPredicate, StudySearchCursorAnchor, StudyTextField,
    },
};
use std::fmt;
use thiserror::Error;
use uuid::Uuid;

pub const BROWSER_STUDY_DISCOVERY_AUTHORITY: &str = "tre_browser.study_discovery";

#[derive(Debug, Error, Clone, Copy, PartialEq, Eq)]
pub enum BrowserStudyDiscoveryError {
    #[error("selected datastore identity is invalid")]
    InvalidDatastoreIdentity,
    #[error("selected datastore is not available for browser discovery")]
    DatastoreUnavailable,
    #[error("browser study discovery authority is unavailable")]
    AuthorityUnavailable,
    #[error("study was not found in the selected datastore")]
    StudyNotFound,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct BrowserStudyDiscoverySource {
    pub datastore_id: PublicUuid,
    pub studies: Vec<BrowserStudyDiscoverySourceRecord>,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct BrowserStudyDiscoverySourceRecord {
    pub study: ahri_tre_pgmeta::PgStudyReadModel,
    pub domains: Vec<ahri_tre_pgmeta::PgDomainReadModel>,
    pub tags: Vec<ahri_tre_pgmeta::PgTagReadModel>,
    pub access_conditions: Vec<ahri_tre_pgmeta::PgDuoRestrictionReadModel>,
}

/// Resolved adapter capability used by the application-owned Study workflow.
pub trait BrowserStudyDiscoveryCapability: fmt::Debug + Send + Sync {
    fn discover_studies(
        &self,
        datastore_id: PublicUuid,
    ) -> Result<BrowserStudyDiscoverySource, BrowserStudyDiscoveryError>;
}

pub fn discover_browser_studies(
    capability: &dyn BrowserStudyDiscoveryCapability,
    datastore_id: PublicUuid,
) -> Result<BrowserStudyDiscoveryResponse, BrowserStudyDiscoveryError> {
    capability
        .discover_studies(datastore_id)
        .map(browser_study_discovery_response)
}

pub fn discover_browser_study(
    capability: &dyn BrowserStudyDiscoveryCapability,
    datastore_id: PublicUuid,
    study_id: PublicUuid,
) -> Result<BrowserStudyDiscoveryResponse, BrowserStudyDiscoveryError> {
    browser_study_get_response(capability.discover_studies(datastore_id)?, study_id)
}

#[allow(clippy::result_large_err)]
pub fn search_browser_studies(
    capability: &dyn BrowserResourceDiscoveryCapability,
    datastore_id: PublicUuid,
    request: &BrowserStudySearchInput,
    protocol_version: &ProtocolVersion,
) -> Result<BrowserStudySearchResponse, BrowserStudyWorkflowError> {
    validate_search_references(datastore_id, request, protocol_version)
        .map_err(BrowserStudyWorkflowError::InvalidRequest)?;
    let sources = capability.discover_catalogue_search_resources(datastore_id)?;
    browser_study_search_response(datastore_id, sources, request, protocol_version)
        .map_err(BrowserStudyWorkflowError::InvalidRequest)
}

#[allow(clippy::result_large_err)]
fn validate_search_references(
    datastore_id: PublicUuid,
    request: &BrowserStudySearchInput,
    protocol_version: &ProtocolVersion,
) -> Result<(), ProtocolError> {
    use crate::browser_catalogue_search::{validate_domain, validate_tag};
    if let Some(predicates) = &request.predicates {
        for predicate in predicates.predicates() {
            match predicate {
                ahri_tre_protocol::study::StudyPredicate::Domain { domain } => {
                    validate_domain(datastore_id, domain)?
                }
                ahri_tre_protocol::study::StudyPredicate::Tag(tag) => {
                    validate_tag(datastore_id, &tag.selector)?
                }
                _ => {}
            }
        }
    }
    if let Some(query) = &request.query {
        for domain in &query.facets.any_domains {
            validate_domain(datastore_id, domain)?;
        }
        for tag in &query.facets.any_tags {
            validate_tag(datastore_id, tag)?;
        }
    }
    if let Some(cursor) = request.decoded_cursor(datastore_id, protocol_version)? {
        cursor
            .study
            .validate_context(datastore_id, ahri_tre_protocol::refs::ObjectKind::Study)?;
    }
    Ok(())
}

#[derive(Debug, Error, Clone, PartialEq, Eq)]
pub enum BrowserStudyWorkflowError {
    #[error(transparent)]
    Discovery(#[from] BrowserResourceDiscoveryError),
    #[error("browser Study search request is invalid")]
    InvalidRequest(ProtocolError),
}

pub fn browser_study_discovery_response(
    source: BrowserStudyDiscoverySource,
) -> BrowserStudyDiscoveryResponse {
    let datastore_id = source.datastore_id;
    let studies = source
        .studies
        .into_iter()
        .map(|record| browser_study_discovery_record(datastore_id, record))
        .collect::<Vec<_>>();
    let empty_state = studies.is_empty().then(|| BrowserStudyDiscoveryEmptyState {
        code: "no_browser_visible_studies".to_string(),
        message: "No browser-visible studies are available in this datastore.".to_string(),
    });

    BrowserStudyDiscoveryResponse {
        authority: BROWSER_STUDY_DISCOVERY_AUTHORITY.to_string(),
        datastore_id,
        studies,
        empty_state,
        content_derived_summaries: BrowserContentSummaryPolicy {
            included: false,
            reason: "Content-derived summaries are excluded from broad Discovery metadata."
                .to_string(),
        },
    }
}

pub fn browser_study_get_response(
    source: BrowserStudyDiscoverySource,
    study_id: PublicUuid,
) -> Result<BrowserStudyDiscoveryResponse, BrowserStudyDiscoveryError> {
    let filtered = BrowserStudyDiscoverySource {
        datastore_id: source.datastore_id,
        studies: source
            .studies
            .into_iter()
            .filter(|record| PublicUuid::from_uuid(record.study.study_id.0) == study_id)
            .collect(),
    };

    if filtered.studies.is_empty() {
        Err(BrowserStudyDiscoveryError::StudyNotFound)
    } else {
        Ok(browser_study_discovery_response(filtered))
    }
}

#[allow(clippy::result_large_err)]
pub fn browser_study_search_response(
    datastore_id: PublicUuid,
    sources: Vec<BrowserResourceDiscoverySource>,
    request: &BrowserStudySearchInput,
    protocol_version: &ProtocolVersion,
) -> Result<BrowserStudySearchResponse, ProtocolError> {
    validate_search_references(datastore_id, request, protocol_version)?;
    let after = request.decoded_cursor(datastore_id, protocol_version)?;
    let mut studies = sources
        .into_iter()
        .filter_map(|source| study_candidate(source, request))
        .collect::<Vec<_>>();
    studies.sort_by_key(study_sort_key);
    if let Some(after) = after {
        studies.retain(|record| study_sort_key(record) > cursor_sort_key(&after));
    }

    let limit = usize::from(request.page.limit);
    let has_more = studies.len() > limit;
    let page = studies.into_iter().take(limit).collect::<Vec<_>>();
    let next_cursor = if has_more {
        match page.last() {
            Some(record) => Some(request.encode_cursor(
                datastore_id,
                protocol_version,
                study_cursor_anchor(datastore_id, record),
            )?),
            None => None,
        }
    } else {
        None
    };
    let returned_count = u16::try_from(page.len()).expect("page length fits u16");
    let empty_state = page.is_empty().then(|| BrowserStudySearchEmptyState {
        code: "no_matching_browser_visible_studies".to_string(),
        message: "No browser-visible studies match the active search filters.".to_string(),
    });

    Ok(BrowserStudySearchResponse {
        protocol_version: protocol_version.clone(),
        datastore_id,
        family: "studies".to_string(),
        predicates: request.predicates.clone(),
        query: request.query.clone(),
        studies: page
            .into_iter()
            .map(BrowserStudyCandidate::record)
            .collect(),
        returned_count,
        requested_limit: request.page.limit,
        ordering: BrowserSearchOrdering {
            id: "study_name_then_identity".to_string(),
            description: "Studies are ordered by canonical name, then stable identity.".to_string(),
        },
        has_more,
        next_cursor,
        empty_state,
    })
}

#[derive(Debug)]
struct BrowserStudyCandidate {
    source: BrowserResourceDiscoverySource,
    evidence: Vec<BrowserStudyMatchEvidence>,
    evidence_truncated: bool,
}

impl BrowserStudyCandidate {
    fn record(self) -> BrowserStudySearchRecord {
        let datastore_id = self.source.datastore_id;
        let record = BrowserStudyDiscoverySourceRecord {
            study: self.source.study,
            domains: self.source.domains,
            tags: self.source.study_tags,
            access_conditions: self.source.study_access_conditions,
        };
        BrowserStudySearchRecord {
            discovery: browser_study_discovery_record(datastore_id, record),
            match_evidence: self.evidence,
            match_evidence_truncated: self.evidence_truncated,
        }
    }
}

fn browser_study_discovery_record(
    datastore_id: PublicUuid,
    record: BrowserStudyDiscoverySourceRecord,
) -> BrowserStudyDiscoveryRecord {
    let study = StudyRef {
        datastore_id,
        kind: ahri_tre_protocol::refs::ObjectKind::Study,
        id: PublicUuid::from_uuid(record.study.study_id.0),
    };
    BrowserStudyDiscoveryRecord {
        facts: browser_study_facts(datastore_id, &record),
        domains: record
            .domains
            .into_iter()
            .map(|value| domain_summary(datastore_id, value))
            .collect(),
        access_request: BrowserStudyAccessRequestReference {
            datastore_id,
            study,
        },
    }
}

fn study_candidate(
    mut source: BrowserResourceDiscoverySource,
    request: &BrowserStudySearchInput,
) -> Option<BrowserStudyCandidate> {
    let datastore_id = source.datastore_id;
    if request.query.is_none() {
        return legacy_study_candidate(source, request);
    }
    let query = request.query.as_ref().expect("query branch checked");
    source
        .datasets
        .sort_by_key(|record| asset_evidence_sort_key(&record.asset));
    source
        .datafiles
        .sort_by_key(|record| asset_evidence_sort_key(&record.asset));

    let domain_matches = query.facets.any_domains.is_empty()
        || query.facets.any_domains.iter().any(|selector| {
            source
                .domains
                .iter()
                .any(|domain| domain_matches(domain, selector))
        });
    if !domain_matches {
        return None;
    }

    let tag_matches = query.facets.any_tags.is_empty()
        || source_tags(&source).any(|tag| {
            query
                .facets
                .any_tags
                .iter()
                .any(|selector| tag_matches_selector(tag, selector))
        });
    if !tag_matches {
        return None;
    }

    let mut evidence = Vec::new();
    let study_fields = study_matched_fields(&source, request);
    if !study_fields.is_empty() {
        evidence.push(BrowserStudyMatchEvidence::Study {
            study: StudyRef {
                datastore_id,
                kind: ahri_tre_protocol::refs::ObjectKind::Study,
                id: PublicUuid::from_uuid(source.study.study_id.0),
            },
            matched_fields: study_fields,
        });
    }
    for dataset in &source.datasets {
        for matched in
            asset_version_matches(&dataset.asset, &dataset.tags, &dataset.versions, request)
        {
            let version = &dataset.versions[matched.version_index];
            evidence.push(BrowserStudyMatchEvidence::Dataset {
                asset: ahri_tre_protocol::refs::AssetRef {
                    datastore_id,
                    kind: ahri_tre_protocol::refs::ObjectKind::Asset,
                    id: PublicUuid::from_uuid(dataset.asset.asset_id.0),
                },
                dataset: ahri_tre_protocol::refs::DatasetRef {
                    datastore_id,
                    kind: ahri_tre_protocol::refs::ObjectKind::Asset,
                    id: PublicUuid::from_uuid(dataset.asset.asset_id.0),
                },
                version: VersionRef {
                    datastore_id,
                    kind: ahri_tre_protocol::refs::ObjectKind::AssetVersion,
                    id: PublicUuid::from_uuid(version.version.version_id.0),
                },
                name: dataset.asset.name.clone(),
                matched_fields: matched.fields,
            });
        }
    }
    for datafile in &source.datafiles {
        for matched in
            asset_version_matches(&datafile.asset, &datafile.tags, &datafile.versions, request)
        {
            let version = &datafile.versions[matched.version_index];
            evidence.push(BrowserStudyMatchEvidence::Datafile {
                asset: ahri_tre_protocol::refs::AssetRef {
                    datastore_id,
                    kind: ahri_tre_protocol::refs::ObjectKind::Asset,
                    id: PublicUuid::from_uuid(datafile.asset.asset_id.0),
                },
                datafile: ahri_tre_protocol::refs::DataFileRef {
                    datastore_id,
                    kind: ahri_tre_protocol::refs::ObjectKind::Asset,
                    id: PublicUuid::from_uuid(datafile.asset.asset_id.0),
                },
                version: VersionRef {
                    datastore_id,
                    kind: ahri_tre_protocol::refs::ObjectKind::AssetVersion,
                    id: PublicUuid::from_uuid(version.version.version_id.0),
                },
                name: datafile.asset.name.clone(),
                matched_fields: matched.fields,
            });
        }
    }

    let text_matches = query.text.is_none()
        || evidence.iter().any(|item| {
            matched_fields(item).iter().any(|field| {
                *field != BrowserStudyMatchedField::Tag
                    && *field != BrowserStudyMatchedField::Domain
            })
        });
    if !text_matches {
        return None;
    }
    if evidence.is_empty() {
        evidence.push(BrowserStudyMatchEvidence::Study {
            study: StudyRef {
                datastore_id,
                kind: ahri_tre_protocol::refs::ObjectKind::Study,
                id: PublicUuid::from_uuid(source.study.study_id.0),
            },
            matched_fields: Vec::new(),
        });
    }
    let evidence_truncated = evidence.len() > MAX_BROWSER_STUDY_MATCH_EVIDENCE;
    evidence.truncate(MAX_BROWSER_STUDY_MATCH_EVIDENCE);
    Some(BrowserStudyCandidate {
        source,
        evidence,
        evidence_truncated,
    })
}

fn legacy_study_candidate(
    source: BrowserResourceDiscoverySource,
    request: &BrowserStudySearchInput,
) -> Option<BrowserStudyCandidate> {
    let datastore_id = source.datastore_id;
    let predicates = request
        .predicates
        .as_ref()
        .expect("validated browser search has predicates or a query");
    let evaluated = predicates
        .predicates()
        .iter()
        .map(|predicate| legacy_predicate_match(&source, predicate))
        .collect::<Vec<_>>();
    let matches = match predicates {
        PredicateSet::AllOf(_) => evaluated.iter().all(|(matches, _)| *matches),
        PredicateSet::AnyOf(_) => evaluated.iter().any(|(matches, _)| *matches),
    };
    if !matches {
        return None;
    }

    let mut matched_fields = evaluated
        .into_iter()
        .filter_map(|(matches, field)| matches.then_some(field))
        .collect::<Vec<_>>();
    matched_fields.sort_by_key(|field| format!("{field:?}"));
    matched_fields.dedup();
    Some(BrowserStudyCandidate {
        evidence: vec![BrowserStudyMatchEvidence::Study {
            study: StudyRef {
                datastore_id,
                kind: ahri_tre_protocol::refs::ObjectKind::Study,
                id: PublicUuid::from_uuid(source.study.study_id.0),
            },
            matched_fields,
        }],
        source,
        evidence_truncated: false,
    })
}

fn legacy_predicate_match(
    source: &BrowserResourceDiscoverySource,
    predicate: &StudyPredicate,
) -> (bool, BrowserStudyMatchedField) {
    match predicate {
        StudyPredicate::Text(text) => {
            let (candidate, field) = match text.field {
                StudyTextField::Name => (
                    Some(source.study.name.as_str()),
                    BrowserStudyMatchedField::Name,
                ),
                StudyTextField::Title => (
                    source.study.documentation.as_deref(),
                    BrowserStudyMatchedField::Documentation,
                ),
                StudyTextField::Description => (
                    source.study.description.as_deref(),
                    BrowserStudyMatchedField::Description,
                ),
            };
            (
                candidate.is_some_and(|candidate| {
                    ahri_tre_core::search_text_matches(
                        candidate,
                        match text.mode {
                            ahri_tre_protocol::search::TextMode::Exact => {
                                ahri_tre_core::SearchTextMode::Exact
                            }
                            ahri_tre_protocol::search::TextMode::Prefix => {
                                ahri_tre_core::SearchTextMode::Prefix
                            }
                            ahri_tre_protocol::search::TextMode::Contains => {
                                ahri_tre_core::SearchTextMode::Contains
                            }
                        },
                        &text.value,
                    )
                }),
                field,
            )
        }
        StudyPredicate::Domain { domain } => (
            source
                .domains
                .iter()
                .any(|candidate| domain_matches(candidate, domain)),
            BrowserStudyMatchedField::Domain,
        ),
        StudyPredicate::Tag(tag) => (
            source
                .study_tags
                .iter()
                .any(|candidate| tag_matches_selector(candidate, &tag.selector)),
            BrowserStudyMatchedField::Tag,
        ),
    }
}

fn study_matched_fields(
    source: &BrowserResourceDiscoverySource,
    request: &BrowserStudySearchInput,
) -> Vec<BrowserStudyMatchedField> {
    let query = request
        .query
        .as_ref()
        .expect("asset-aware query is present");
    let mut fields = Vec::new();
    if let Some(text) = query.text.as_ref() {
        push_text_match(
            &mut fields,
            BrowserStudyMatchedField::Name,
            &source.study.name,
            text,
        );
        push_optional_text_match(
            &mut fields,
            BrowserStudyMatchedField::ExternalId,
            source.study.external_id.as_deref(),
            text,
        );
        push_optional_text_match(
            &mut fields,
            BrowserStudyMatchedField::Description,
            source.study.description.as_deref(),
            text,
        );
        push_optional_text_match(
            &mut fields,
            BrowserStudyMatchedField::Documentation,
            source.study.documentation.as_deref(),
            text,
        );
    }
    if !query.facets.any_domains.is_empty()
        && source.domains.iter().any(|domain| {
            query
                .facets
                .any_domains
                .iter()
                .any(|selector| domain_matches(domain, selector))
        })
    {
        fields.push(BrowserStudyMatchedField::Domain);
    }
    if tags_match_selected(&source.study_tags, request) {
        fields.push(BrowserStudyMatchedField::Tag);
    }
    fields
}

struct AssetVersionMatch {
    version_index: usize,
    fields: Vec<BrowserStudyMatchedField>,
}

trait AssetVersionEvidenceSource {
    fn version(&self) -> &ahri_tre_pgmeta::PgAssetVersionReadModel;
    fn tags(&self) -> &[ahri_tre_pgmeta::PgTagReadModel];

    fn available_for_latest_selection(&self) -> bool {
        true
    }

    fn format(&self) -> Option<&str> {
        None
    }
}

impl AssetVersionEvidenceSource
    for crate::browser_resource_discovery::BrowserDatasetVersionDiscoverySourceRecord
{
    fn version(&self) -> &ahri_tre_pgmeta::PgAssetVersionReadModel {
        &self.version
    }

    fn tags(&self) -> &[ahri_tre_pgmeta::PgTagReadModel] {
        &self.tags
    }

    fn available_for_latest_selection(&self) -> bool {
        self.withdrawn_at.is_none()
    }
}

impl AssetVersionEvidenceSource
    for crate::browser_resource_discovery::BrowserDataFileVersionDiscoverySourceRecord
{
    fn version(&self) -> &ahri_tre_pgmeta::PgAssetVersionReadModel {
        &self.version
    }

    fn tags(&self) -> &[ahri_tre_pgmeta::PgTagReadModel] {
        &self.tags
    }

    fn format(&self) -> Option<&str> {
        Some(&self.datafile.format)
    }
}

fn asset_version_matches<V: AssetVersionEvidenceSource>(
    asset: &ahri_tre_pgmeta::PgAssetReadModel,
    asset_tags: &[ahri_tre_pgmeta::PgTagReadModel],
    versions: &[V],
    request: &BrowserStudySearchInput,
) -> Vec<AssetVersionMatch> {
    let query = request
        .query
        .as_ref()
        .expect("asset-aware query is present");
    let latest_index = versions
        .iter()
        .position(|source| {
            source.available_for_latest_selection() && source.version().is_latest.unwrap_or(false)
        })
        .or_else(|| {
            versions
                .iter()
                .rposition(AssetVersionEvidenceSource::available_for_latest_selection)
        });
    let mut asset_fields = Vec::new();
    if let Some(text) = query.text.as_ref() {
        push_text_match(
            &mut asset_fields,
            BrowserStudyMatchedField::Name,
            &asset.name,
            text,
        );
        push_optional_text_match(
            &mut asset_fields,
            BrowserStudyMatchedField::Description,
            asset.description.as_deref(),
            text,
        );
    }
    if tags_match_selected(asset_tags, request) {
        asset_fields.push(BrowserStudyMatchedField::Tag);
    }

    let mut matches = versions
        .iter()
        .enumerate()
        .filter_map(|(version_index, source)| {
            let version = source.version();
            let mut fields = Vec::new();
            if let Some(text) = query.text.as_ref() {
                push_optional_text_match(
                    &mut fields,
                    BrowserStudyMatchedField::VersionLabel,
                    version.version_label.as_deref(),
                    text,
                );
                push_optional_text_match(
                    &mut fields,
                    BrowserStudyMatchedField::VersionNote,
                    version.version_note.as_deref(),
                    text,
                );
                push_optional_text_match(
                    &mut fields,
                    BrowserStudyMatchedField::Doi,
                    version.doi.as_deref(),
                    text,
                );
                push_optional_text_match(
                    &mut fields,
                    BrowserStudyMatchedField::Format,
                    source.format(),
                    text,
                );
            }
            if tags_match_selected(source.tags(), request) {
                fields.push(BrowserStudyMatchedField::Tag);
            }
            (!fields.is_empty()).then_some(AssetVersionMatch {
                version_index,
                fields,
            })
        })
        .collect::<Vec<_>>();

    if !asset_fields.is_empty()
        && let Some(latest_index) = latest_index
    {
        if let Some(latest) = matches
            .iter_mut()
            .find(|matched| matched.version_index == latest_index)
        {
            for field in asset_fields {
                if !latest.fields.contains(&field) {
                    latest.fields.push(field);
                }
            }
        } else {
            matches.insert(
                0,
                AssetVersionMatch {
                    version_index: latest_index,
                    fields: asset_fields,
                },
            );
        }
    }
    matches
}

fn push_optional_text_match(
    fields: &mut Vec<BrowserStudyMatchedField>,
    field: BrowserStudyMatchedField,
    candidate: Option<&str>,
    text: &ahri_tre_protocol::study::BrowserStudyTextQuery,
) {
    if let Some(candidate) = candidate {
        push_text_match(fields, field, candidate, text);
    }
}

fn push_text_match(
    fields: &mut Vec<BrowserStudyMatchedField>,
    field: BrowserStudyMatchedField,
    candidate: &str,
    text: &ahri_tre_protocol::study::BrowserStudyTextQuery,
) {
    if text_matches(candidate, text) && !fields.contains(&field) {
        fields.push(field);
    }
}

fn text_matches(candidate: &str, text: &ahri_tre_protocol::study::BrowserStudyTextQuery) -> bool {
    ahri_tre_core::search_text_matches(
        candidate,
        match text.mode {
            ahri_tre_protocol::search::TextMode::Exact => ahri_tre_core::SearchTextMode::Exact,
            ahri_tre_protocol::search::TextMode::Prefix => ahri_tre_core::SearchTextMode::Prefix,
            ahri_tre_protocol::search::TextMode::Contains => {
                ahri_tre_core::SearchTextMode::Contains
            }
        },
        &text.value,
    )
}

fn tags_match_selected(
    tags: &[ahri_tre_pgmeta::PgTagReadModel],
    request: &BrowserStudySearchInput,
) -> bool {
    let query = request
        .query
        .as_ref()
        .expect("asset-aware query is present");
    !query.facets.any_tags.is_empty()
        && tags.iter().any(|tag| {
            query
                .facets
                .any_tags
                .iter()
                .any(|selector| tag_matches_selector(tag, selector))
        })
}

fn source_tags(
    source: &BrowserResourceDiscoverySource,
) -> impl Iterator<Item = &ahri_tre_pgmeta::PgTagReadModel> {
    source
        .study_tags
        .iter()
        .chain(source.datasets.iter().flat_map(|record| {
            record.tags.iter().chain(
                record
                    .versions
                    .iter()
                    .flat_map(|version| version.tags.iter()),
            )
        }))
        .chain(source.datafiles.iter().flat_map(|record| {
            record.tags.iter().chain(
                record
                    .versions
                    .iter()
                    .flat_map(|version| version.tags.iter()),
            )
        }))
}

fn tag_matches_selector(
    tag: &ahri_tre_pgmeta::PgTagReadModel,
    selector: &ahri_tre_protocol::refs::TagSelector,
) -> bool {
    match selector {
        ahri_tre_protocol::refs::TagSelector::Id { tag: expected } => {
            ahri_tre_protocol::refs::encode_scoped_integer_ref("tag", tag.tag_id) == expected.id
        }
        ahri_tre_protocol::refs::TagSelector::Label { scope, label } => {
            *scope == TagScope::Global && tag.name == label.as_str()
        }
    }
}

fn domain_matches(
    domain: &ahri_tre_pgmeta::PgDomainReadModel,
    selector: &ahri_tre_protocol::domain::DomainSelector,
) -> bool {
    match selector {
        ahri_tre_protocol::domain::DomainSelector::Id { domain: expected } => {
            ahri_tre_protocol::refs::encode_scoped_integer_ref("domain", domain.domain_id.0)
                == expected.id
        }
        ahri_tre_protocol::domain::DomainSelector::Name { name } => domain.name == name.as_str(),
    }
}

fn matched_fields(evidence: &BrowserStudyMatchEvidence) -> &[BrowserStudyMatchedField] {
    match evidence {
        BrowserStudyMatchEvidence::Study { matched_fields, .. }
        | BrowserStudyMatchEvidence::Dataset { matched_fields, .. }
        | BrowserStudyMatchEvidence::Datafile { matched_fields, .. } => matched_fields,
    }
}

fn asset_evidence_sort_key(record: &ahri_tre_pgmeta::PgAssetReadModel) -> (String, String, Uuid) {
    (
        record.name.to_ascii_lowercase(),
        record.name.clone(),
        record.asset_id.0,
    )
}

fn study_sort_key(record: &BrowserStudyCandidate) -> (String, String, Uuid) {
    (
        record.source.study.name.as_str().to_ascii_lowercase(),
        record.source.study.name.as_str().to_string(),
        record.source.study.study_id.0,
    )
}

fn cursor_sort_key(anchor: &StudySearchCursorAnchor) -> (String, String, Uuid) {
    (
        anchor.name.to_ascii_lowercase(),
        anchor.name.clone(),
        anchor.study.id.as_uuid(),
    )
}

fn study_cursor_anchor(
    datastore_id: PublicUuid,
    record: &BrowserStudyCandidate,
) -> StudySearchCursorAnchor {
    StudySearchCursorAnchor {
        study: StudyRef {
            datastore_id,
            kind: ahri_tre_protocol::refs::ObjectKind::Study,
            id: PublicUuid::from_uuid(record.source.study.study_id.0),
        },
        name: record.source.study.name.as_str().to_string(),
    }
}

pub fn browser_study_facts(
    datastore_id: PublicUuid,
    record: &BrowserStudyDiscoverySourceRecord,
) -> BrowserStudyFacts {
    BrowserStudyFacts {
        study: StudyRef {
            datastore_id,
            kind: ahri_tre_protocol::refs::ObjectKind::Study,
            id: PublicUuid::from_uuid(record.study.study_id.0),
        },
        name: record.study.name.clone(),
        external_id: record.study.external_id.clone(),
        description: record.study.description.clone(),
        documentation: record.study.documentation.clone(),
        tags: record
            .tags
            .iter()
            .cloned()
            .map(|tag| tag_summary(datastore_id, tag))
            .collect(),
        access_conditions: record
            .access_conditions
            .iter()
            .cloned()
            .map(access_condition)
            .collect(),
    }
}

fn domain_summary(
    datastore_id: PublicUuid,
    domain: ahri_tre_pgmeta::PgDomainReadModel,
) -> DomainSummary {
    DomainSummary {
        domain: crate::projections::domain_ref(datastore_id, domain.domain_id),
        name: domain.name,
        description: domain.description,
        uri: domain.uri,
    }
}

fn tag_summary(datastore_id: PublicUuid, tag: ahri_tre_pgmeta::PgTagReadModel) -> TagSummary {
    TagSummary {
        tag: TagRef {
            datastore_id,
            kind: ahri_tre_protocol::refs::ObjectKind::Tag,
            id: ahri_tre_protocol::refs::encode_scoped_integer_ref("tag", tag.tag_id),
        },
        scope: TagScope::Global,
        label: tag.name,
    }
}

fn access_condition(
    condition: ahri_tre_pgmeta::PgDuoRestrictionReadModel,
) -> BrowserStudyAccessCondition {
    BrowserStudyAccessCondition {
        duo_id: condition.duo_id,
        code: condition.duo_code,
        label: condition.label,
        qualifier_ontology_namespace: condition.qualifier_ontology_namespace,
        qualifier_ontology_id: condition.qualifier_ontology_id,
        qualifier_text: condition.qualifier_text,
        qualifier_date: condition.qualifier_date,
        qualifier_integer: condition.qualifier_integer,
    }
}

#[cfg(test)]
mod asset_aware_search_tests {
    use super::*;
    use crate::browser_resource_discovery::{
        BrowserDataFileDiscoverySourceRecord, BrowserDataFileMetadataSource,
        BrowserDataFileVersionDiscoverySourceRecord, BrowserDatasetDiscoverySourceRecord,
        BrowserDatasetVersionDiscoverySourceRecord, BrowserResourceDiscoverySource,
    };
    use ahri_tre_protocol::{
        pagination::PageRequest,
        study::{
            BrowserStudyFacetGroups, BrowserStudySearchInput, BrowserStudySearchQuery,
            BrowserStudyTextQuery,
        },
    };
    use ahri_tre_types::{AssetId, AssetType, DomainId, StudyId, VersionId};

    #[test]
    fn returned_study_domain_uses_the_analyst_reference_and_can_filter_again() {
        let datastore_id = PublicUuid::from_uuid(Uuid::from_u128(42));
        let domain = source(datastore_id).domains.remove(0);
        let returned = domain_summary(datastore_id, domain.clone()).domain;
        assert_eq!(
            returned,
            crate::projections::domain_ref(datastore_id, domain.domain_id)
        );
        assert_eq!(
            ahri_tre_protocol::refs::decode_scoped_integer_ref("domain", returned.id),
            Some(domain.domain_id.0)
        );
        assert!(domain_matches(
            &domain,
            &ahri_tre_protocol::domain::DomainSelector::Id { domain: returned }
        ));
    }

    #[test]
    fn aggregate_search_matches_study_dataset_and_datafile_once_with_nested_facets() {
        let datastore_id = PublicUuid::from_uuid(Uuid::from_u128(42));
        let mut request = BrowserStudySearchInput {
            session: None,
            predicates: None,
            query: Some(BrowserStudySearchQuery {
                text: Some(BrowserStudyTextQuery {
                    mode: ahri_tre_protocol::search::TextMode::Contains,
                    value: "sentinel".to_string(),
                }),
                facets: BrowserStudyFacetGroups {
                    any_tags: vec![
                        ahri_tre_protocol::refs::TagSelector::Label {
                            scope: TagScope::Global,
                            label: ahri_tre_protocol::PublicName::new("missing-tag").unwrap(),
                        },
                        ahri_tre_protocol::refs::TagSelector::Label {
                            scope: TagScope::Global,
                            label: ahri_tre_protocol::PublicName::new("curated").unwrap(),
                        },
                    ],
                    any_domains: vec![
                        ahri_tre_protocol::domain::DomainSelector::Name {
                            name: ahri_tre_protocol::PublicName::new("missing-domain").unwrap(),
                        },
                        ahri_tre_protocol::domain::DomainSelector::Name {
                            name: ahri_tre_protocol::PublicName::new("demography").unwrap(),
                        },
                    ],
                },
            }),
            page: PageRequest {
                cursor: None,
                limit: 10,
            },
        };
        request
            .validate(datastore_id, &ProtocolVersion::current())
            .unwrap();

        let response = browser_study_search_response(
            datastore_id,
            vec![source(datastore_id)],
            &request,
            &ProtocolVersion::current(),
        )
        .unwrap();

        assert_eq!(response.studies.len(), 1);
        assert_eq!(response.studies[0].match_evidence.len(), 3);
        assert!(matches!(
            response.studies[0].match_evidence[0],
            ahri_tre_protocol::study::BrowserStudyMatchEvidence::Study { .. }
        ));
        assert!(matches!(
            response.studies[0].match_evidence[1],
            ahri_tre_protocol::study::BrowserStudyMatchEvidence::Dataset { .. }
        ));
        assert!(matches!(
            response.studies[0].match_evidence[2],
            ahri_tre_protocol::study::BrowserStudyMatchEvidence::Datafile { .. }
        ));
    }

    #[test]
    fn aggregate_search_bounds_evidence_and_excludes_private_source_fields() {
        let datastore_id = PublicUuid::from_uuid(Uuid::from_u128(42));
        let mut source = source(datastore_id);
        let template = source.datasets[0].clone();
        for offset in 1_u128..7 {
            let mut dataset = template.clone();
            dataset.asset.asset_id = AssetId(Uuid::from_u128(200 + offset));
            dataset.asset.name = format!("Sentinel dataset {offset}");
            dataset.versions[0].version.asset_id = dataset.asset.asset_id;
            dataset.versions[0].version.version_id = VersionId(Uuid::from_u128(220 + offset));
            dataset.versions[0].dataset.dataset_id = dataset.versions[0].version.version_id;
            source.datasets.push(dataset);
        }
        let mut request = BrowserStudySearchInput {
            session: None,
            predicates: None,
            query: Some(BrowserStudySearchQuery {
                text: Some(BrowserStudyTextQuery {
                    mode: ahri_tre_protocol::search::TextMode::Contains,
                    value: "sentinel".to_string(),
                }),
                facets: BrowserStudyFacetGroups::default(),
            }),
            page: PageRequest {
                cursor: None,
                limit: 10,
            },
        };
        request
            .validate(datastore_id, &ProtocolVersion::current())
            .unwrap();

        let response = browser_study_search_response(
            datastore_id,
            vec![source],
            &request,
            &ProtocolVersion::current(),
        )
        .unwrap();
        let result = &response.studies[0];
        assert_eq!(
            result.match_evidence.len(),
            ahri_tre_protocol::study::MAX_BROWSER_STUDY_MATCH_EVIDENCE
        );
        assert!(result.match_evidence_truncated);
        let public_json = serde_json::to_string(&response).unwrap();
        assert!(!public_json.contains("never disclose me"));
        assert!(!public_json.contains("agent_instructions"));
    }

    #[test]
    fn aggregate_search_keeps_dataset_and_datafile_version_evidence_separate() {
        let datastore_id = PublicUuid::from_uuid(Uuid::from_u128(42));
        let mut source = source(datastore_id);
        source.study.name = "Cohort".to_string();
        source.study.description = None;
        source.datasets[0].asset.name = "Dataset".to_string();
        let mut historical = source.datasets[0].versions[0].clone();
        historical.version.version_id = VersionId(Uuid::from_u128(199));
        historical.version.version_label = Some("historical needle".to_string());
        historical.version.is_latest = Some(false);
        historical.dataset.dataset_id = historical.version.version_id;
        source.datasets[0].versions[0].version.version_label = Some("current".to_string());
        source.datasets[0].versions[0].version.doi = Some("needle dataset DOI".to_string());
        source.datasets[0].versions.insert(0, historical);
        source.datafiles[0].asset.name = "Datafile".to_string();
        source.datafiles[0].versions[0].version.version_label = Some("current".to_string());
        source.datafiles[0].versions[0].datafile.format = "needle/format".to_string();
        let mut historical = source.datafiles[0].versions[0].clone();
        historical.version.version_id = VersionId(Uuid::from_u128(299));
        historical.version.version_note = Some("historical needle note".to_string());
        historical.version.doi = None;
        historical.version.is_latest = Some(false);
        historical.datafile.datafile_id = historical.version.version_id;
        historical.datafile.format = "text/csv".to_string();
        source.datafiles[0].versions.insert(0, historical);
        let mut request = search_request("needle");
        request
            .validate(datastore_id, &ProtocolVersion::current())
            .unwrap();

        let response = browser_study_search_response(
            datastore_id,
            vec![source],
            &request,
            &ProtocolVersion::current(),
        )
        .unwrap();

        let evidence = &response.studies[0].match_evidence;
        assert_eq!(evidence.len(), 4);
        assert!(evidence.iter().any(|item| matches!(
            item,
            BrowserStudyMatchEvidence::Dataset { version, matched_fields, .. }
                if version.id == PublicUuid::from_uuid(Uuid::from_u128(199))
                    && matched_fields == &[BrowserStudyMatchedField::VersionLabel]
        )));
        assert!(evidence.iter().any(|item| matches!(
            item,
            BrowserStudyMatchEvidence::Dataset { version, matched_fields, .. }
                if version.id == PublicUuid::from_uuid(Uuid::from_u128(201))
                    && matched_fields == &[BrowserStudyMatchedField::Doi]
        )));
        assert!(evidence.iter().any(|item| matches!(
            item,
            BrowserStudyMatchEvidence::Datafile { version, matched_fields, .. }
                if version.id == PublicUuid::from_uuid(Uuid::from_u128(299))
                    && matched_fields == &[BrowserStudyMatchedField::VersionNote]
        )));
        assert!(evidence.iter().any(|item| matches!(
            item,
            BrowserStudyMatchEvidence::Datafile { version, matched_fields, .. }
                if version.id == PublicUuid::from_uuid(Uuid::from_u128(301))
                    && matched_fields == &[BrowserStudyMatchedField::Format]
        )));
    }

    #[test]
    fn aggregate_search_attributes_asset_evidence_to_latest_available_dataset_version() {
        let datastore_id = PublicUuid::from_uuid(Uuid::from_u128(42));
        let mut source = source(datastore_id);
        source.study.name = "Cohort".to_string();
        source.study.description = None;
        source.datafiles.clear();

        let mut available = source.datasets[0].versions[0].clone();
        available.version.version_id = VersionId(Uuid::from_u128(199));
        available.version.is_latest = Some(false);
        available.dataset.dataset_id = available.version.version_id;
        source.datasets[0].versions[0].withdrawn_at = Some(chrono::Utc::now());
        source.datasets[0].versions.insert(0, available);

        let request = search_request("sentinel dataset");
        let response = browser_study_search_response(
            datastore_id,
            vec![source],
            &request,
            &ProtocolVersion::current(),
        )
        .unwrap();

        assert!(matches!(
            response.studies[0].match_evidence.as_slice(),
            [BrowserStudyMatchEvidence::Dataset {
                version,
                matched_fields,
                ..
            }] if version.id == PublicUuid::from_uuid(Uuid::from_u128(199))
                && matched_fields == &[BrowserStudyMatchedField::Name]
        ));
    }

    #[test]
    fn predicate_search_keeps_existing_study_only_behavior() {
        let datastore_id = PublicUuid::from_uuid(Uuid::from_u128(42));
        let mut request: BrowserStudySearchInput = serde_json::from_value(serde_json::json!({
            "predicates": {
                "kind": "all_of",
                "predicates": [{
                    "kind": "text",
                    "field": "name",
                    "mode": "contains",
                    "value": "cohort"
                }]
            },
            "page": {"limit": 10}
        }))
        .unwrap();
        request
            .validate(datastore_id, &ProtocolVersion::current())
            .unwrap();

        let response = browser_study_search_response(
            datastore_id,
            vec![source(datastore_id)],
            &request,
            &ProtocolVersion::current(),
        )
        .unwrap();

        assert_eq!(response.returned_count, 1);
        assert_eq!(response.predicates, request.predicates);
        assert!(response.query.is_none());
    }

    fn search_request(value: &str) -> BrowserStudySearchInput {
        BrowserStudySearchInput {
            session: None,
            predicates: None,
            query: Some(BrowserStudySearchQuery {
                text: Some(BrowserStudyTextQuery {
                    mode: ahri_tre_protocol::search::TextMode::Contains,
                    value: value.to_string(),
                }),
                facets: BrowserStudyFacetGroups::default(),
            }),
            page: PageRequest {
                cursor: None,
                limit: 10,
            },
        }
    }

    fn source(datastore_id: PublicUuid) -> BrowserResourceDiscoverySource {
        let study_id = StudyId(Uuid::from_u128(100));
        let dataset_asset_id = AssetId(Uuid::from_u128(200));
        let dataset_version_id = VersionId(Uuid::from_u128(201));
        let datafile_asset_id = AssetId(Uuid::from_u128(300));
        let datafile_version_id = VersionId(Uuid::from_u128(301));
        BrowserResourceDiscoverySource {
            datastore_id,
            study: ahri_tre_pgmeta::PgStudyReadModel {
                study_id,
                name: "Sentinel cohort".to_string(),
                description: Some("A sentinel Study".to_string()),
                documentation: None,
                agent_instructions: Some("never disclose me".to_string()),
                external_id: None,
                study_type_id: None,
                date_created: None,
                created_by: None,
            },
            study_tags: vec![tag(1, "priority")],
            study_access_conditions: Vec::new(),
            domains: vec![ahri_tre_pgmeta::PgDomainReadModel {
                domain_id: DomainId(7),
                name: "demography".to_string(),
                uri: None,
                description: None,
            }],
            datasets: vec![BrowserDatasetDiscoverySourceRecord {
                asset: asset(
                    dataset_asset_id,
                    study_id,
                    "Sentinel dataset",
                    AssetType::Dataset,
                ),
                tags: vec![tag(2, "curated")],
                versions: vec![BrowserDatasetVersionDiscoverySourceRecord {
                    version: version(dataset_version_id, dataset_asset_id),
                    dataset: ahri_tre_pgmeta::PgDatasetReadModel {
                        dataset_id: dataset_version_id,
                    },
                    withdrawn_at: None,
                    tags: Vec::new(),
                    access_conditions: Vec::new(),
                }],
            }],
            datafiles: vec![BrowserDataFileDiscoverySourceRecord {
                asset: asset(datafile_asset_id, study_id, "sentinel.csv", AssetType::File),
                tags: Vec::new(),
                versions: vec![BrowserDataFileVersionDiscoverySourceRecord {
                    version: version(datafile_version_id, datafile_asset_id),
                    datafile: BrowserDataFileMetadataSource {
                        datafile_id: datafile_version_id,
                        format: "text/csv".to_string(),
                        size_bytes: None,
                        compressed: None,
                        encrypted: None,
                    },
                    tags: vec![tag(2, "curated")],
                    access_conditions: Vec::new(),
                }],
            }],
        }
    }

    fn asset(
        asset_id: AssetId,
        study_id: StudyId,
        name: &str,
        asset_type: AssetType,
    ) -> ahri_tre_pgmeta::PgAssetReadModel {
        ahri_tre_pgmeta::PgAssetReadModel {
            asset_id,
            study_id,
            name: name.to_string(),
            description: None,
            agent_instructions: Some("never disclose me".to_string()),
            asset_type,
            date_created: None,
            created_by: None,
        }
    }

    fn version(
        version_id: VersionId,
        asset_id: AssetId,
    ) -> ahri_tre_pgmeta::PgAssetVersionReadModel {
        ahri_tre_pgmeta::PgAssetVersionReadModel {
            version_id,
            asset_id,
            major: 1,
            minor: 0,
            patch: 0,
            version_label: Some("sentinel release".to_string()),
            version_note: None,
            is_latest: Some(true),
            doi: None,
            created_at: None,
            created_by: None,
        }
    }

    fn tag(tag_id: i64, name: &str) -> ahri_tre_pgmeta::PgTagReadModel {
        ahri_tre_pgmeta::PgTagReadModel {
            tag_id,
            name: name.to_string(),
        }
    }
}