@kromatv/sdk 0.1.40-canary.0

package/rust/kroma-domain/src/media.rs

@@ -0,0 +1,297 @@
+//! Media catalog types: kinds, stream descriptions, files, items and shows.
+//!
+//! The JSON shape here is a public contract web/TV clients depend on it, so
+//! field names and casing must not drift.
+
+use serde::{Deserialize, Serialize};
+
+use crate::metadata::{CastMember, Metadata};
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "lowercase")]
+pub enum Kind {
+    Movie,
+    Episode,
+    Video,
+}
+
+// (needle, label) cut/edition labels first, then source/quality.
+const EDITION_TABLE: &[(&str, &str)] = &[
+    ("director's cut", "Director's Cut"),
+    ("directors cut", "Director's Cut"),
+    ("director.cut", "Director's Cut"),
+    ("extended", "Extended"),
+    ("uncut", "Uncut"),
+    ("unrated", "Unrated"),
+    ("theatrical", "Theatrical"),
+    ("remastered", "Remastered"),
+    ("imax", "IMAX"),
+    ("remux", "Remux"),
+    ("2160p", "4K"),
+    ("4k", "4K"),
+    ("uhd", "4K"),
+    ("1080p", "1080p"),
+    ("720p", "720p"),
+    ("480p", "480p"),
+];
+
+/// The labels that name a distinct CUT of a title rather than a quality tier.
+/// Two files sharing a cut are the same content: one can replace the other.
+/// Two files differing in cut are different content and never replace one
+/// another, however their quality compares.
+pub const EDITION_CUTS: &[&str] = &[
+    "Director's Cut",
+    "Extended",
+    "Uncut",
+    "Unrated",
+    "Theatrical",
+    "Remastered",
+    "IMAX",
+];
+
+/// The edition label a file name carries, e.g. `Extended` or `4K`.
+pub fn detect_edition(file_name: &str) -> Option<String> {
+    let lower = file_name.to_ascii_lowercase();
+    EDITION_TABLE
+        .iter()
+        .find(|(needle, _)| lower.contains(needle))
+        .map(|(_, label)| label.to_string())
+}
+
+/// The cut an edition names, or `None` when it only names a quality tier
+/// (`4K`, `1080p`, `Remux`, ...) or nothing at all.
+pub fn edition_cut(edition: Option<&str>) -> Option<&'static str> {
+    let edition = edition?;
+    EDITION_CUTS
+        .iter()
+        .copied()
+        .find(|cut| cut.eq_ignore_ascii_case(edition))
+}
+
+/// Video stream description (best-effort; fields may be null when unknown).
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct VideoStream {
+    pub codec: String,
+    pub width: Option<u32>,
+    pub height: Option<u32>,
+    pub hdr: bool,
+    #[serde(rename = "bitDepth")]
+    pub bit_depth: Option<u32>,
+}
+
+/// One audio stream/track. An item can carry several (e.g. EN + FR, or a
+/// director's commentary); `index` is the audio-relative position (0-based
+/// among audio streams only), matching ffmpeg's `-map 0:a:<index>` selector
+/// used when remuxing a chosen track.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AudioStream {
+    #[serde(default)]
+    pub index: u32,
+    pub codec: String,
+    pub channels: Option<u32>,
+    pub language: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub title: Option<String>,
+    #[serde(default)]
+    pub default: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SubtitleTrack {
+    pub language: Option<String>,
+    pub codec: String,
+}
+
+/// Outcome of the EBU R128 loudness analysis of an audio track.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub enum AudioVerdict {
+    Ok,
+    HighDynamics,
+    QuietDialog,
+}
+
+/// EBU R128 loudness measurement of an item's default audio track, produced by
+/// the `pipeline.loudness` stage.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AudioAnalysis {
+    #[serde(rename = "lufsI")]
+    pub lufs_i: f64,
+    // Loudness range (LU); > ~15 is the classic "quiet dialogue, loud
+    // explosions" mix.
+    pub lra: f64,
+    #[serde(rename = "truePeak")]
+    pub true_peak: f64,
+    // Centre-channel loudness (LUFS), measured for 5.1+ tracks only.
+    #[serde(
+        rename = "dialogLufs",
+        default,
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub dialog_lufs: Option<f64>,
+    pub verdict: AudioVerdict,
+}
+
+/// One physical file backing a logical [`MediaItem`]. A single item can have
+/// several of these (Director's Cut + Theatrical, 1080p + 4K, …); they all share
+/// the same logical item id but each maps to a distinct file on disk.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MediaFile {
+    // `short_hash(abs_path)`, stable per physical file.
+    pub id: String,
+    #[serde(rename = "relPath")]
+    pub rel_path: Option<String>,
+    pub container: String,
+    #[serde(rename = "durationMs")]
+    pub duration_ms: Option<u64>,
+    pub video: Option<VideoStream>,
+    pub audio: Option<AudioStream>,
+    #[serde(rename = "audioTracks", default)]
+    pub audio_tracks: Vec<AudioStream>,
+    pub subtitles: Vec<SubtitleTrack>,
+    pub size: Option<u64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub edition: Option<String>,
+    // `false` until ffprobe has run (phase 2); the stream fields above are
+    // null until then.
+    pub probed: bool,
+    #[serde(skip)]
+    pub abs_path: Option<String>,
+}
+
+/// A single playable media item. `rel_path` is relative to the owning media
+/// directory; demo/seed items have `rel_path == None` and cannot be streamed.
+///
+/// An item can be backed by multiple physical [`MediaFile`]s; the top-level
+/// `video`/`audio`/`duration_ms`/`container`/`subtitles`/`abs_path` fields
+/// mirror the highest-resolution probed file, for clients that read
+/// `item.video.codec` directly.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MediaItem {
+    pub id: String,
+    pub title: String,
+    pub kind: Kind,
+    pub year: Option<u32>,
+    #[serde(rename = "durationMs")]
+    pub duration_ms: Option<u64>,
+    pub container: String,
+    pub video: Option<VideoStream>,
+    pub audio: Option<AudioStream>,
+    #[serde(rename = "audioTracks", default)]
+    pub audio_tracks: Vec<AudioStream>,
+    pub subtitles: Vec<SubtitleTrack>,
+    pub library: String,
+    #[serde(rename = "showId")]
+    pub show_id: Option<String>,
+    #[serde(rename = "showTitle")]
+    pub show_title: Option<String>,
+    pub season: Option<u32>,
+    pub episode: Option<u32>,
+    #[serde(rename = "episodeEnd")]
+    pub episode_end: Option<u32>,
+    #[serde(rename = "episodeTitle")]
+    pub episode_title: Option<String>,
+    #[serde(rename = "relPath")]
+    pub rel_path: Option<String>,
+    #[serde(rename = "addedAt")]
+    pub added_at: String,
+    // `None` until the background enrichment pass resolves it. Movies only;
+    // episodes inherit their show's metadata.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub metadata: Option<Metadata>,
+    // Mirrors the representative file's path so `/stream` keeps working.
+    #[serde(skip)]
+    pub abs_path: Option<String>,
+    #[serde(default)]
+    pub files: Vec<MediaFile>,
+    // Id of the representative file `/stream` serves and whose stream info
+    // populates the top-level fields above. `None` until a file exists.
+    #[serde(
+        rename = "defaultFileId",
+        default,
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub default_file_id: Option<String>,
+    // Episodes only. Empty until resolved from chapters or the
+    // audio-fingerprint job.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub markers: Vec<Marker>,
+    // `None` until the `pipeline.loudness` stage has measured it.
+    #[serde(
+        rename = "audioAnalysis",
+        default,
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub audio_analysis: Option<AudioAnalysis>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum MarkerKind {
+    Intro,
+    Credits,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Marker {
+    pub kind: MarkerKind,
+    #[serde(rename = "startMs")]
+    pub start_ms: u64,
+    #[serde(rename = "endMs")]
+    pub end_ms: u64,
+}
+
+/// A TV show aggregate (not a file). Built by grouping episodes during a scan.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Show {
+    pub id: String,
+    pub title: String,
+    pub year: Option<u32>,
+    pub library: String,
+    #[serde(rename = "seasonCount")]
+    pub season_count: u32,
+    #[serde(rename = "episodeCount")]
+    pub episode_count: u32,
+    // From a representative episode, for quality badges.
+    pub video: Option<VideoStream>,
+    #[serde(rename = "addedAt")]
+    pub added_at: String,
+    // `None` until the background enrichment pass resolves it.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub metadata: Option<Metadata>,
+    // Series-completion percent (0-100) when the request is authenticated;
+    // `None` for anonymous requests or shows with no progress.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub progress: Option<u8>,
+}
+
+/// Sorted by episode number.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Season {
+    pub number: u32,
+    pub episodes: Vec<MediaItem>,
+    // Empty until enriched, or when the provider returned none.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub cast: Vec<CastMember>,
+}
+
+/// `GET /api/shows/:id` payload: a show plus its seasons.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ShowDetail {
+    pub show: Show,
+    pub seasons: Vec<Season>,
+}
+
+/// One cover of the anonymous sign-in splash (`GET /api/splash`): enough to
+/// paint a backdrop and caption it, and deliberately nothing more.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SplashEntry {
+    /// `movie` or `show`.
+    pub kind: String,
+    pub title: String,
+    pub year: Option<u32>,
+    #[serde(rename = "backdropUrl")]
+    pub backdrop_url: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub rating: Option<f64>,
+}

package/rust/kroma-domain/src/metadata.rs

@@ -0,0 +1,389 @@
+//! Resolved provider metadata entities (TMDB), part of the wire contract shared
+//! with web/TV clients. The HTTP client that produces them lives in
+//! `crate::infra::metadata`.
+
+use serde::{Deserialize, Serialize};
+
+/// Provider metadata for one movie or show. Serialized to clients and
+/// round-tripped through the DB's `metadata` JSON column (hence `Deserialize`).
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Metadata {
+    // Always "tmdb"; a `&'static str` cannot be deserialized into.
+    #[serde(skip_deserializing, default = "default_provider")]
+    pub provider: &'static str,
+    #[serde(rename = "tmdbId")]
+    pub tmdb_id: u64,
+    #[serde(rename = "imdbId", skip_serializing_if = "Option::is_none")]
+    pub imdb_id: Option<String>,
+    pub title: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub tagline: Option<String>,
+    pub overview: Option<String>,
+    #[serde(rename = "releaseDate", skip_serializing_if = "Option::is_none")]
+    pub release_date: Option<String>,
+    pub genres: Vec<String>,
+    // Parallel to `genres`: both come from one TMDB list and align by index.
+    #[serde(
+        rename = "tmdbGenreIds",
+        default,
+        skip_serializing_if = "Vec::is_empty"
+    )]
+    pub tmdb_genre_ids: Vec<u32>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub rating: Option<f32>,
+    /// The provider's own spelling ("PG-13", "TV-MA", "12"), for the region the
+    /// enrichment language asked for.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub certification: Option<String>,
+    #[serde(rename = "posterUrl", skip_serializing_if = "Option::is_none")]
+    pub poster_url: Option<String>,
+    #[serde(rename = "backdropUrl", skip_serializing_if = "Option::is_none")]
+    pub backdrop_url: Option<String>,
+    #[serde(rename = "logoUrl", skip_serializing_if = "Option::is_none")]
+    pub logo_url: Option<String>,
+    // A local path, not a provider URL. TV shows only.
+    #[serde(rename = "themeUrl", default, skip_serializing_if = "Option::is_none")]
+    pub theme_url: Option<String>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub cast: Vec<CastMember>,
+    // Directors first, then writers; TV creators folded in.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub crew: Vec<CrewMember>,
+    // Internal: consumed by `build_doc` during enrichment, never persisted.
+    #[serde(default, skip_serializing)]
+    pub keywords: Vec<String>,
+    // Internal: looks up the theme song, then dropped.
+    #[serde(default, skip_serializing)]
+    pub tvdb_id: Option<u64>,
+    #[serde(rename = "tmdbUrl")]
+    pub tmdb_url: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CastMember {
+    pub name: String,
+    // None on every credit stored before the id was kept: those fold by name.
+    #[serde(rename = "tmdbId", default, skip_serializing_if = "Option::is_none")]
+    pub tmdb_id: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub character: Option<String>,
+    // A TMDB URL until `crate::image::localize` rewrites it to a local path.
+    #[serde(
+        rename = "profileUrl",
+        default,
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub profile_url: Option<String>,
+}
+
+/// The character each member of `core` plays according to `localized`, the same
+/// cast fetched in another language: matched by TMDB person id, then by name,
+/// never by position, since TMDB does not promise the two lists the same order.
+/// Index-aligned to `core`, so a reader can zip it; empty when nothing matched,
+/// so nothing is written and the reader keeps the core's own names.
+pub fn characters_aligned(core: &[CastMember], localized: &[CastMember]) -> Vec<Option<String>> {
+    let same = |member: &CastMember, other: &CastMember| match (member.tmdb_id, other.tmdb_id) {
+        (Some(a), Some(b)) => a == b,
+        _ => !member.name.is_empty() && other.name == member.name,
+    };
+    let aligned: Vec<Option<String>> = core
+        .iter()
+        .map(|member| {
+            localized
+                .iter()
+                .find(|other| same(member, other))
+                .and_then(|other| other.character.clone())
+        })
+        .collect();
+    if aligned.iter().all(Option::is_none) {
+        Vec::new()
+    } else {
+        aligned
+    }
+}
+
+/// `job` is the TMDB job title (`"Director"`, `"Writer"`, `"Creator"`, …).
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CrewMember {
+    pub name: String,
+    #[serde(rename = "tmdbId", default, skip_serializing_if = "Option::is_none")]
+    pub tmdb_id: Option<u64>,
+    pub job: String,
+    #[serde(
+        rename = "profileUrl",
+        default,
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub profile_url: Option<String>,
+}
+
+/// Not stored with a title's metadata: a person is not a library entity, so
+/// this is resolved on demand and cached in memory.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct PersonDetail {
+    #[serde(rename = "tmdbId")]
+    pub tmdb_id: u64,
+    pub name: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub biography: Option<String>,
+    // `YYYY-MM-DD`.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub birthday: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub deathday: Option<String>,
+    #[serde(rename = "placeOfBirth", skip_serializing_if = "Option::is_none")]
+    pub place_of_birth: Option<String>,
+    // TMDB's `known_for_department` (`"Acting"`, …), translated client-side.
+    #[serde(rename = "knownFor", skip_serializing_if = "Option::is_none")]
+    pub known_for: Option<String>,
+    #[serde(rename = "profileUrl", skip_serializing_if = "Option::is_none")]
+    pub profile_url: Option<String>,
+    #[serde(rename = "tmdbUrl")]
+    pub tmdb_url: String,
+}
+
+fn default_provider() -> &'static str {
+    "tmdb"
+}
+
+/// The text embedded for one title. Ordered most- to least-discriminating so a
+/// truncating tokenizer keeps the important parts.
+pub fn build_doc(title: &str, year: Option<u32>, meta: &Metadata) -> String {
+    let mut parts: Vec<String> = Vec::with_capacity(8);
+    parts.push(title.to_string());
+    if let Some(y) = year {
+        parts.push(y.to_string());
+    }
+    if !meta.genres.is_empty() {
+        let genres = meta.genres.join(" ");
+        parts.push(genres.clone()); // repeat: genres dominate similarity
+        parts.push(genres);
+    }
+    if !meta.keywords.is_empty() {
+        parts.push(meta.keywords.join(" "));
+    }
+    for c in meta.cast.iter().take(6) {
+        parts.push(c.name.clone());
+    }
+    if let Some(tagline) = &meta.tagline {
+        parts.push(tagline.clone());
+    }
+    if let Some(overview) = &meta.overview {
+        parts.push(overview.clone());
+    }
+    parts.join(". ")
+}
+
+/// One episode of a season, as the provider names it.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EpisodeInfo {
+    pub episode: u32,
+    pub name: Option<String>,
+    pub overview: Option<String>,
+    pub air_date: Option<String>,
+    pub still_url: Option<String>,
+}
+
+/// One TMDB title offered by the "fix the match" picker, with the confidence
+/// [`crate::matching`] gives it against what the filename parsed to.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct MatchCandidate {
+    pub tmdb_id: u64,
+    pub title: String,
+    pub original_title: Option<String>,
+    pub year: Option<u32>,
+    pub poster_url: Option<String>,
+    pub overview: Option<String>,
+    pub rating: Option<f32>,
+    // Confidence in `0.0..=1.0` that this is the title on disk.
+    pub score: f32,
+    pub current: bool,
+}
+
+/// `GET /api/rematch/{kind}/{id}/candidates`: what was matched against, and the
+/// ranked candidates to choose from.
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct MatchCandidates {
+    // The operator's query if they typed one, else the parsed filename title.
+    pub query: String,
+    // Parsed from the filename; what scoring compares against.
+    pub year: Option<u32>,
+    pub current_tmdb_id: Option<u64>,
+    // The current match was chosen by an operator, not resolved automatically.
+    pub pinned: bool,
+    pub results: Vec<MatchCandidate>,
+}
+
+#[cfg(test)]
+mod tests {
+    #[test]
+    fn a_character_follows_its_person_not_its_row() {
+        let member = |name: &str, id: Option<u64>, character: Option<&str>| super::CastMember {
+            name: name.into(),
+            tmdb_id: id,
+            character: character.map(String::from),
+            profile_url: None,
+        };
+        let core = vec![
+            member("Tom Hanks", Some(31), Some("Woody")),
+            member("Tim Allen", Some(12898), Some("Buzz")),
+            member("Joan Cusack", None, Some("Jessie")),
+        ];
+        let localized = vec![
+            member("Joan Cusack", None, Some("Jessie (voix)")),
+            member("Tim Allen", Some(12898), Some("Buzz (voix)")),
+            member("Tom Hanks", Some(31), Some("Woody (voix)")),
+            member("Someone New", Some(7), Some("Extra")),
+        ];
+
+        let aligned = super::characters_aligned(&core, &localized);
+
+        assert_eq!(
+            aligned,
+            vec![
+                Some("Woody (voix)".to_string()),
+                Some("Buzz (voix)".to_string()),
+                Some("Jessie (voix)".to_string()),
+            ]
+        );
+        assert!(
+            super::characters_aligned(&core, &[member("Nobody", Some(1), Some("X"))]).is_empty()
+        );
+    }
+
+    use super::*;
+
+    fn cast(name: &str) -> CastMember {
+        CastMember {
+            name: name.into(),
+            tmdb_id: None,
+            character: None,
+            profile_url: None,
+        }
+    }
+
+    fn metadata() -> Metadata {
+        Metadata {
+            provider: default_provider(),
+            tmdb_id: 603,
+            imdb_id: None,
+            title: Some("The Matrix".into()),
+            tagline: None,
+            overview: None,
+            release_date: None,
+            genres: Vec::new(),
+            tmdb_genre_ids: Vec::new(),
+            rating: None,
+            certification: None,
+            poster_url: None,
+            backdrop_url: None,
+            logo_url: None,
+            theme_url: None,
+            cast: Vec::new(),
+            crew: Vec::new(),
+            keywords: Vec::new(),
+            tvdb_id: None,
+            tmdb_url: "https://themoviedb.org/movie/603".into(),
+        }
+    }
+
+    #[test]
+    fn the_genre_ids_serialize_under_their_provider_qualified_wire_name() {
+        let meta = Metadata {
+            genres: vec!["Science Fiction".into()],
+            tmdb_genre_ids: vec![878],
+            ..metadata()
+        };
+
+        let json = serde_json::to_value(&meta).unwrap();
+
+        assert_eq!(json["tmdbGenreIds"], serde_json::json!([878]));
+        assert_eq!(json["genres"], serde_json::json!(["Science Fiction"]));
+    }
+
+    #[test]
+    fn a_title_with_no_genre_ids_omits_them_from_the_blob() {
+        let json = serde_json::to_value(metadata()).unwrap();
+
+        assert!(json.get("tmdbGenreIds").is_none());
+    }
+
+    #[test]
+    fn a_blob_stored_before_the_genre_ids_deserializes_without_them() {
+        let stored = r#"{"tmdbId":603,"title":"Dune","overview":null,
+            "genres":["Science Fiction"],"tmdbUrl":"https://themoviedb.org/movie/603"}"#;
+
+        let meta: Metadata = serde_json::from_str(stored).unwrap();
+
+        assert_eq!(meta.genres, vec!["Science Fiction".to_string()]);
+        assert!(meta.tmdb_genre_ids.is_empty());
+    }
+
+    #[test]
+    fn the_age_rating_survives_a_blob_round_trip_under_its_own_name() {
+        let meta = Metadata {
+            certification: Some("PG-13".into()),
+            ..metadata()
+        };
+
+        let json = serde_json::to_value(&meta).unwrap();
+
+        assert_eq!(json["certification"], serde_json::json!("PG-13"));
+        assert_eq!(
+            serde_json::from_value::<Metadata>(json)
+                .unwrap()
+                .certification,
+            Some("PG-13".to_string())
+        );
+    }
+
+    #[test]
+    fn a_blob_stored_before_the_age_rating_reads_as_having_none() {
+        let stored = r#"{"tmdbId":603,"title":"Dune","overview":null,"genres":[],
+            "tmdbUrl":"https://themoviedb.org/movie/603"}"#;
+
+        let meta: Metadata = serde_json::from_str(stored).unwrap();
+
+        assert!(meta.certification.is_none());
+    }
+
+    #[test]
+    fn the_embedded_doc_carries_every_discriminating_field_in_order() {
+        let meta = Metadata {
+            genres: vec!["Science Fiction".into(), "Action".into()],
+            keywords: vec!["dystopia".into(), "simulation".into()],
+            cast: vec![cast("Keanu Reeves"), cast("Carrie-Anne Moss")],
+            tagline: Some("Welcome to the Real World".into()),
+            overview: Some("A hacker learns the truth.".into()),
+            ..metadata()
+        };
+        assert_eq!(
+            build_doc("The Matrix", Some(1999), &meta),
+            "The Matrix. 1999. \
+             Science Fiction Action. Science Fiction Action. \
+             dystopia simulation. \
+             Keanu Reeves. Carrie-Anne Moss. \
+             Welcome to the Real World. \
+             A hacker learns the truth."
+        );
+    }
+
+    #[test]
+    fn the_embedded_doc_keeps_only_the_first_six_cast_members() {
+        let meta = Metadata {
+            cast: (1..=8).map(|n| cast(&format!("Actor {n}"))).collect(),
+            ..metadata()
+        };
+        let doc = build_doc("Ensemble", None, &meta);
+        assert!(doc.contains("Actor 6"), "{doc}");
+        assert!(!doc.contains("Actor 7"), "{doc}");
+    }
+
+    #[test]
+    fn an_empty_metadata_embeds_as_the_title_alone() {
+        assert_eq!(build_doc("Untitled", None, &metadata()), "Untitled");
+    }
+}