metadata: provider-id ledger so orphaned StarTrack ratings resolve by type #372

Merged

mysticalsoap merged 2 commits from feat/startrack-ledger into trunk

2026-10-07 01:07:06 -04:00

mysticalsoap commented

2026-10-06 22:52:56 -04:00

Owner

Problem

#350: StarTrack keys ratings by Jellyfin item id, the id changes with the file path, and when a rating goes orphaned nothing in the pipeline remembers what it pointed at. #340's report leans on movie_poster_state.json, which only knows movies the poster sync processed, and only sees orphans that reach the tagging path. Live today: 9 of 190 ratings point at missing items, 8 of them below the 4-star threshold and so never reported.

Fix

First piece of #350, pipeline only:

Every run records each rated item's TMDB/IMDb/TVDB ids, name, year and type in state/startrack_ledger.json: refreshed while the item exists, kept once it vanishes (that record is what names the orphan), dropped once nobody rates the id any more (re-keyed or deleted).
Orphans are found up front from one chunked ids= lookup over all ratings (Jellyfin silently omits missing ids, confirmed live), so ratings below the threshold count too and tagging never hits a 404. The nightly ERROR GET /Items/4c443647… 404 on stderr goes away.
An orphan resolves through its ledger record by provider id in a per-type library index, fetched on first use and seeded with the movie listing the marker pass already has. Series and anime resolve the same way. A rating older than the ledger falls back to the poster state's TMDB id as before.
The dry run no longer sends the orphan notification (it did, so the test dry run below produced a duplicate ntfy push).
Maintenance.md names the ledger. Second commit adds media/metadata/state to the backup includes: the ledger is the only record of what an orphaned rating pointed at.

Verification

Inside the metadata container on the live Jellyfin (12.1.0):

--dry-run: 190 ratings, 67 qualify, 181 present, 9 gone, 8 named with OLD=NEW pairs via the poster state, 4c443647… still unknown (no record anywhere, as #350 says).
Ledger path exercised directly: a rated movie treated as an orphan resolves to itself from its ledger record; a Series record resolves through a lazily fetched Series index with Imdb/Tmdb/Tvdb keys; retention keeps a vanished id's record and drops an unrated one.
Real run: startrack_ledger.json written with 181 records (owned by apps), state file holds 9 orphans with 8 current ids, no tag changes, one notification.

The 8 pairs go to startrack_rekey.py by hand; that is still the hand step pieces 2 and 3 of #350 remove.

🤖 Generated with Claude Code

## Problem #350: StarTrack keys ratings by Jellyfin item id, the id changes with the file path, and when a rating goes orphaned nothing in the pipeline remembers what it pointed at. #340's report leans on `movie_poster_state.json`, which only knows movies the poster sync processed, and only sees orphans that reach the tagging path. Live today: 9 of 190 ratings point at missing items, 8 of them below the 4-star threshold and so never reported. ## Fix First piece of #350, pipeline only: - Every run records each rated item's TMDB/IMDb/TVDB ids, name, year and type in `state/startrack_ledger.json`: refreshed while the item exists, kept once it vanishes (that record is what names the orphan), dropped once nobody rates the id any more (re-keyed or deleted). - Orphans are found up front from one chunked `ids=` lookup over all ratings (Jellyfin silently omits missing ids, confirmed live), so ratings below the threshold count too and tagging never hits a 404. The nightly `ERROR GET /Items/4c443647… 404` on stderr goes away. - An orphan resolves through its ledger record by provider id in a per-type library index, fetched on first use and seeded with the movie listing the marker pass already has. Series and anime resolve the same way. A rating older than the ledger falls back to the poster state's TMDB id as before. - The dry run no longer sends the orphan notification (it did, so the test dry run below produced a duplicate ntfy push). - Maintenance.md names the ledger. Second commit adds `media/metadata/state` to the backup includes: the ledger is the only record of what an orphaned rating pointed at. ## Verification Inside the metadata container on the live Jellyfin (12.1.0): - `--dry-run`: 190 ratings, 67 qualify, 181 present, 9 gone, 8 named with `OLD=NEW` pairs via the poster state, `4c443647…` still unknown (no record anywhere, as #350 says). - Ledger path exercised directly: a rated movie treated as an orphan resolves to itself from its ledger record; a Series record resolves through a lazily fetched Series index with Imdb/Tmdb/Tvdb keys; retention keeps a vanished id's record and drops an unrated one. - Real run: `startrack_ledger.json` written with 181 records (owned by `apps`), state file holds 9 orphans with 8 current ids, no tag changes, one notification. The 8 pairs go to `startrack_rekey.py` by hand; that is still the hand step pieces 2 and 3 of #350 remove. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

mysticalsoap added 2 commits

2026-10-06 22:52:56 -04:00

metadata: keep a provider-id ledger of rated items so orphans resolve by type 644290aa44

StarTrack keys ratings by Jellyfin item id and the id changes with the
file path, so the nightly run now records every rated item's TMDB/IMDb/TVDB
ids, name, year and type in state/startrack_ledger.json (#350, first piece).
When an id vanishes the record names it and finds the current item by
provider id in a per-type library index, so series and anime resolve too;
ratings older than the ledger still fall back to movie_poster_sync's TMDB
record. Orphans are found up front from one `ids=` lookup over all ratings
rather than from a 404 on tagging, which covers ratings below the threshold
(eight of the nine live orphans) and ends the nightly 404 on stderr. The
dry run no longer sends the orphan notification.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

backup: include media/metadata/state for the StarTrack ledger

validate / validate (pull_request) Successful in 23s

Details

2d60387fbe

The ledger is the only record of what an orphaned rating pointed at; the
other state files there are regenerable but small.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

mysticalsoap merged commit e8eacb15c8 into trunk

2026-10-07 01:07:06 -04:00

mysticalsoap deleted branch feat/startrack-ledger

2026-10-07 01:07:07 -04:00

mysticalsoap referenced this pull request from a commit

2026-10-07 01:07:08 -04:00

Merge pull request 'metadata: provider-id ledger so orphaned StarTrack ratings resolve by type' (#372) from feat/startrack-ledger into trunk