Living Network Stage C proposal: spotting what's new (report only), with evidence from the box

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

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.