Skip to content

Canonical TV Metadata and Plex Episode Inventory

This capability is a read-only Media Manager slice. It answers explicit TV episode and Plex-library questions by comparing two independent truth sources. It does not discover acquisitions, invoke Lich, control a downloader, mutate files, or request a Plex scan.

Truth boundaries

TVmaze is the first canonical metadata provider. The bounded adapter uses only TVmaze search and show-episode endpoints. It normalizes series and episodes into CanonicalMediaIdentity, stores stable provider IDs, uses standard aired ordering, excludes unnumbered specials, and excludes episodes whose provider airtime is in the future. Same-title series remain ambiguous unless explicit country, premiere year, TVmaze ID, or Plex external identity resolves them. Ambiguous results render at most five stable operator choices and never select the provider's first search result.

Plex inspection discovers the TV section by section type. It resolves the show, loads external IDs from Plex metadata, enumerates numbered episode entries, and observes media-part paths. Title matching is a fallback; multiple title matches fail closed. Matching titles in another library are reported as wrong-library evidence.

The governed result carries an explicit comparison scope: latest_episode, latest_season, or whole_series. Latest-episode questions compare only the exact latest aired key. General missing/caught-up questions default to the latest aired season. Only explicit entire-series wording selects the full inventory. Whole-series governed results/evidence retain the total count and at most 25 recent keys; rendering uses only the five most recent. Serialized Plex inventory retains the total count and at most 100 recent episode observations. Each serialized episode retains at most five media-part paths, and unmatched-item detail is capped at 25; explicit count and truncation fields preserve abnormal-state visibility without unbounded transport payloads.

The comparison reports scoped missing aired keys, duplicate episode evidence, unmatched items, wrong-library state, Plex-ahead observations, and ambiguity. Plex entries later than canonical aired truth are never treated as proof that an episode has aired.

Identity

CanonicalMediaIdentity is the shared media-domain identity for both series and episodes. It includes media type, canonical provider and ID, title, year, country, aired-order season and episode numbers, episode title, air date, provider IDs, aliases, ordering scheme, and a stable canonical episode key. Later governed media capabilities should consume this identity rather than creating a parallel acquisition identity.

Evidence and readiness

Runtime responses include a bounded observational evidence packet in the normal Runtime Result and Kernel Record path. It contains the normalized target, provider identity, normalized provider-result digest, canonical series and latest episode keys, Plex section, relevant Plex episode keys, inventory digest, comparison scope and result, separate metadata/Plex observation times, and the overall observation time. A provider observation is fresh request evidence, not eternal cached truth. It is observational evidence, not an execution receipt.

Readiness is evaluated at request time. Metadata failures, Plex configuration or reachability failures, a missing TV section, unresolved identity, and ambiguity are reported separately. Rubick registers the capability only as a read-only wired provider; readiness metadata does not grant execution, approval, torrent-search, filesystem, or Plex-refresh authority.

Routing

The shared operational cognition router recognizes only explicit latest, latest-season, or whole-series library questions with a media target. Normal discussion of a series, quoted examples, negated instructions, and title-only conversation do not select the capability. Generic phrases such as “Am I up to date?” do not select it without an explicit target; conversational target carry forward is not implemented in this slice.

Known limitations

  • Only TVmaze standard aired ordering is implemented.
  • Specials and alternate DVD/streaming ordering are excluded.
  • Plex external IDs are available at show level; episode comparison therefore uses the canonical show identity plus aired season/episode numbers.
  • A same-title series absent from Plex remains ambiguous until the operator supplies country, year, or TVmaze ID in a subsequent explicit request.
  • The capability does not schedule checks or notify the operator of releases.