diff --git a/docs/living-network-stage-c-proposal.md b/docs/living-network-stage-c-proposal.md new file mode 100644 index 0000000..602bff3 --- /dev/null +++ b/docs/living-network-stage-c-proposal.md @@ -0,0 +1,55 @@ +# Living Network Stage C: spotting what's new (proposal for approval) + +4 November 2026. Stage C is **report only**: it labels what's new and books nothing, changes no channel and promotes nothing on its own. It's the evidence later stages use: channel suggestions (Stage D), and What's On's "new episodes" rule. Even then, What's On only ever shows booked programmes. + +## What the box's data shows today + +Read-only, from the library catalogue copy (imported 1 November, 132,545 items) and the box's pools at 18:10 today. + +- **Newly released:** 443 distinct works (252 series, 191 films) premiered between 5 September and 4 November 2026. + - **Mix:** drama 139, comedy 115, documentary 79, thriller 77. + - **Examples:** Blue Planet III (premiered 31 October), Dragon Ball Super: Beerus (10 October), Band of Brothers: Legacy, a new Resident Evil, and several new anime series. + - **Duplicates:** works are counted once, by their TMDB, TVDB or IMDb id, so a second copy of the same work isn't counted twice. +- **New to the library:** the catalogue is read oldest first by date added, so the newest additions are at its end. The last 2% holds 2,651 series and films. + - **No dates yet:** the catalogue has no "date added" of its own. Only an import after today can say exactly when something arrived. +- **New episodes of shows already on a channel:** comparing each pool with its previous read finds one new QI episode. + - **Why the matching needs care:** American Dad! showed 399 "new" files, but that was its pool switching to another copy of the same episodes. Stage C must match new episodes by season and episode, not by file. +- **The catalogue is 3 days stale:** it was last imported on 1 November, and the import is still started by hand. Stage C needs a regular, light refresh. + +## The four labels + +Each label carries the evidence behind it, so it can be explained. + +| Label | Means | Evidence | +|---|---|---| +| New to the library | First seen by Orbit's catalogue in the last 14 days | The date of the refresh that found it. Everything already in the 1 November import is the baseline, so isn't new | +| Newly released | Premiered in the last 60 days, and not in the future | The premiere date in its metadata | +| New episodes | A show already on a channel has episodes it didn't have at the previous pool read | Season and episode numbers that weren't there before, never just a new file of an old episode | +| Not yet shown on Orbit | In a channel's pool, but never booked anywhere since Stage C began | An append-only record of every work ever booked, starting the day Stage C is installed | + +Each work is identified by its provider ids, with the title and year as a fallback. That's the same identity the premiere and story grouping use. + +## What Stage C would build (one release, C1) + +1. **A light daily catalogue refresh.** + - Once a day, after the 12:00 What's On edition, while Orbit isn't playing, Orbit reads only the items added since its last position, in a few bounded pages. + - It uses the existing import code, which is read-only against Emby. It never re-reads the whole library. +2. **An arrivals record (`arrivals-0.json`)** for each new series or film: id, provider ids, type, title, year, premiere date, and the date first seen. + - It's capped and pruned after 90 days. + - The log shows counts only. +3. **The booked-works record (`booked-0.json`):** the ids of every work any plan books. It's added to at each top-up, so "not yet shown on Orbit" has evidence from day one. +4. **New-episode detection** at each pool read, by season and episode, recorded with the channel and the show. +5. **A report screen in Settings, "New arrivals":** the four lists, each item showing its labels and evidence. It's read-only, with no buttons that book or change anything. + +**Unchanged:** every booking, pool, channel list, cursor and the What's On screen. + +**Checks before install:** +- unit tests for each label's rule, including the copy switch that must not count as new episodes, and the baseline; +- booking fingerprints identical on all 30 channels; +- the refresh shown to read only the new pages; +- nothing written to the catalogue except the new rows. + +## After C1 + +- **Stage D:** suggests which channel each new work fits, with reasons, for your approval. For example, Blue Planet III for Terra, and new anime for Vortex's late block. +- **What's On:** its "new episodes" rule switches on, and still only for booked programmes.