//! `contentKind` → `domain` — the routing table from METADATA_KEYS.md §1.
//!
//! `domain` answers **"which application is this record destined for?"**. It
//! is the coarsest facet in the registry and the key every client filters its
//! catalogue on:
//!
//! ```text
//! meta-watch   →  domain:film|tv
//! meta-listen  →  domain:music
//! meta-read    →  domain:literature
//! ```
//!
//! # Why it is stored and not derived on read
//!
//! `contentKind`'s vocabulary is deliberately open — a new feeder may mint a
//! kind and ship without a fleet-wide update. That only stays safe because the
//! domain travels *with* the record: a peer that has never heard of
//! `podcastEpisode` still routes it correctly, because it never has to
//! interpret the token. Deriving on read would silently drop every record
//! whose kind the reader predates.
//!
//! # ⚠ The binding is permanent and one-way
//!
//! Add kinds freely; **never re-map an existing kind to a different domain**.
//! Because the value is stored, two peers on different versions that disagree
//! about where `audiobook` belongs produce a split-brain that redeploying
//! cannot heal — the wrong domain is already written into records across the
//! mesh. If a kind genuinely has to move, mint a new kind.
//!
//! # Why `domain` and not one kind-key per medium
//!
//! `record_matches` is AND-across-keys / OR-within-key, and a non-matching key
//! fails the record outright. A per-medium split (`videoKind` / `audioKind` /
//! `documentKind`) would force meta-listen to express "music video **or**
//! audio track" as an OR across two *different* keys — which the query
//! language cannot represent at all. One domain key, OR-ed within itself,
//! always can.

/// The `contentKind` → `domain` table. A kind absent from this list has no
/// domain and is **not independently routable** — correct for sidecars
/// (subtitles, artwork) and for un-anchored hits, a producer bug for anything
/// else.
///
/// ⚠ `pack` is deliberately absent. A season pack and an album release are the
/// same structural thing, so the kind alone cannot tell `tv` from `music`; the
/// writer stamps `pack`'s domain from its own context (the same reason
/// `derive_file_type` cannot have a second `pack` arm).
const DOMAIN_BY_CONTENT_KIND: &[(&str, &str)] = &[
    // film / tv
    ("movie", "film"),
    ("series", "tv"),
    ("episode", "tv"),
    // music
    ("track", "music"),
    ("album", "music"),
    ("artist", "music"),
    ("musicVideo", "music"),
    ("djMix", "music"),
    ("liveSet", "music"),
    // spoken
    ("podcast", "spoken"),
    ("podcastEpisode", "spoken"),
    // literature — an audiobook's identity is the book (same author, same ISBN
    // family, same series as the ebook), so meta-read groups the two editions
    // on one page. The player does not decide the domain.
    ("book", "literature"),
    ("audiobook", "literature"),
    ("comic", "literature"),
    ("manga", "literature"),
    ("magazine", "literature"),
    // science
    ("paper", "science"),
];

/// Resolve the domain a `contentKind` belongs to.
///
/// Returns `None` for `pack` (not derivable from the kind — the writer supplies
/// it), for format/sidecar kinds that route nowhere, and for any kind this
/// build has never heard of. A caller that already knows the domain from its
/// own context must prefer that over this table.
pub fn domain_for_content_kind(content_kind: &str) -> Option<&'static str> {
    let k = content_kind.trim();
    DOMAIN_BY_CONTENT_KIND
        .iter()
        .find(|(kind, _)| kind.eq_ignore_ascii_case(k))
        .map(|(_, domain)| *domain)
}

/// The inverse: every `contentKind` that belongs to `domain`.
///
/// Used at the gateway-routing boundary. A gateway declares the *content kinds*
/// it serves (`served_content_kinds`), not domains, so a `domain:` filter is
/// matched by expanding it here rather than by adding a `served_domains` field
/// to the heartbeat — which would be a wire-protocol change requiring every
/// feeder manifest and every peer to move at once.
pub fn content_kinds_for_domain(domain: &str) -> Vec<&'static str> {
    let d = domain.trim();
    DOMAIN_BY_CONTENT_KIND
        .iter()
        .filter(|(_, dom)| dom.eq_ignore_ascii_case(d))
        .map(|(kind, _)| *kind)
        .collect()
}

/// Rewrite a query so a `domain:` filter can reach a plugin that has never
/// heard of the key.
///
/// Returns `None` when the query carries no `domain:` filter — the common
/// path, and cheaper than cloning.
///
/// # Why translate instead of teaching every plugin
///
/// `record_matches` fails a record outright when a filter key is missing from
/// its fields, and `domain` is missing from every record a not-yet-updated
/// feeder emits. Nine of the fifteen feeders pin the SDK by git tag, so they
/// cannot pick up a new key on our schedule. Translating `domain:literature`
/// into the `contentKind:` alternation it covers means the wire query a plugin
/// sees never mentions `domain` at all, and old plugins keep working unchanged
/// — while the dispatcher still enforces the real `domain:` filter afterwards,
/// against records it has just stamped.
///
/// An explicit `contentKind:` filter already in the query is left alone: it is
/// the narrower of the two, and the `domain` term is still enforced
/// post-stamp, so the AND semantics hold either way.
pub fn expand_domain_filter(query: &crate::query::GatewayQuery) -> Option<crate::query::GatewayQuery> {
    let domains = query.filters.get("domain")?;
    let mut out = query.clone();
    out.filters.remove("domain");
    if !out.filters.contains_key("contentKind") {
        let kinds: Vec<String> = domains
            .iter()
            .flat_map(|d| content_kinds_for_domain(d))
            .map(|k| k.to_string())
            .collect();
        // An unknown domain expands to nothing. Inserting an empty
        // alternation would drop every record at the plugin; leaving the
        // filter out lets the plugin answer and the post-stamp `domain:`
        // check do the (correct, empty) filtering.
        if !kinds.is_empty() {
            out.filters.insert("contentKind".to_string(), kinds);
        }
    }
    Some(out)
}

/// Stamp `domain` on a field map that already carries a `contentKind`.
///
/// The convention from METADATA_KEYS.md §1: **whoever writes `contentKind`
/// writes `domain` in the same breath**. An existing `domain` is never
/// overwritten — a writer that knows better than the table (a `pack`, say) has
/// already set it.
pub fn stamp_domain(fields: &mut std::collections::BTreeMap<String, String>) {
    if fields.contains_key("domain") {
        return;
    }
    let Some(kind) = fields.get("contentKind").cloned() else {
        return;
    };
    if let Some(domain) = domain_for_content_kind(&kind) {
        fields.insert("domain".to_string(), domain.to_string());
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::collections::BTreeMap;

    #[test]
    fn kinds_map_to_their_domain() {
        assert_eq!(domain_for_content_kind("movie"), Some("film"));
        assert_eq!(domain_for_content_kind("episode"), Some("tv"));
        assert_eq!(domain_for_content_kind("track"), Some("music"));
        // The case that proves medium and domain are different axes.
        assert_eq!(domain_for_content_kind("musicVideo"), Some("music"));
        // The case that proves the player does not decide the domain.
        assert_eq!(domain_for_content_kind("audiobook"), Some("literature"));
    }

    #[test]
    fn pack_has_no_derivable_domain() {
        assert_eq!(domain_for_content_kind("pack"), None);
    }

    #[test]
    fn unknown_kind_is_none_not_a_guess() {
        assert_eq!(domain_for_content_kind("hologram"), None);
    }

    #[test]
    fn expansion_is_the_inverse() {
        let music = content_kinds_for_domain("music");
        assert!(music.contains(&"track"));
        assert!(music.contains(&"musicVideo"));
        assert!(!music.contains(&"audiobook"));
        for kind in content_kinds_for_domain("literature") {
            assert_eq!(domain_for_content_kind(kind), Some("literature"));
        }
    }

    fn q(filters: &[(&str, &[&str])]) -> crate::query::GatewayQuery {
        crate::query::GatewayQuery {
            raw_text: String::new(),
            free_text: String::new(),
            filters: filters
                .iter()
                .map(|(k, vs)| {
                    (
                        k.to_string(),
                        vs.iter().map(|v| v.to_string()).collect::<Vec<_>>(),
                    )
                })
                .collect(),
            ranges: Vec::new(),
            negations: Vec::new(),
        }
    }

    #[test]
    fn no_domain_filter_is_left_untouched() {
        assert!(expand_domain_filter(&q(&[("fileType", &["video"])])).is_none());
    }

    #[test]
    fn domain_becomes_the_content_kinds_it_covers() {
        let out = expand_domain_filter(&q(&[("domain", &["literature"])])).unwrap();
        // The plugin never sees `domain:` — that is the whole point.
        assert!(!out.filters.contains_key("domain"));
        let kinds = out.filters.get("contentKind").unwrap();
        assert!(kinds.contains(&"book".to_string()));
        assert!(kinds.contains(&"audiobook".to_string()));
        assert!(!kinds.contains(&"track".to_string()));
    }

    #[test]
    fn an_explicit_content_kind_filter_wins() {
        let out = expand_domain_filter(&q(&[
            ("domain", &["music"][..]),
            ("contentKind", &["track"][..]),
        ]))
        .unwrap();
        assert_eq!(
            out.filters.get("contentKind").map(Vec::as_slice),
            Some(&["track".to_string()][..])
        );
    }

    #[test]
    fn unknown_domain_adds_no_alternation() {
        // An empty alternation would drop every record at the plugin; the
        // post-stamp `domain:` check does the (correct, empty) filtering.
        let out = expand_domain_filter(&q(&[("domain", &["hologram"])])).unwrap();
        assert!(!out.filters.contains_key("contentKind"));
    }

    #[test]
    fn stamp_fills_in_and_never_overwrites() {
        let mut f: BTreeMap<String, String> = BTreeMap::new();
        f.insert("contentKind".into(), "episode".into());
        stamp_domain(&mut f);
        assert_eq!(f.get("domain").map(String::as_str), Some("tv"));

        // A pack writer that already knows its context keeps it.
        let mut p: BTreeMap<String, String> = BTreeMap::new();
        p.insert("contentKind".into(), "pack".into());
        p.insert("domain".into(), "music".into());
        stamp_domain(&mut p);
        assert_eq!(p.get("domain").map(String::as_str), Some("music"));

        // No contentKind → no domain invented.
        let mut n: BTreeMap<String, String> = BTreeMap::new();
        stamp_domain(&mut n);
        assert!(n.get("domain").is_none());
    }
}