Persist unmatched Letterboxd rows and retry them as the library grows (#25)

[Tailes14]

Closes #25.

A Letterboxd import can only rate films the server already has. Every other row is counted as "unmatched" and dropped, so importing a large history into a smaller library silently loses most of it, with no way back except re-uploading the export later and hoping the film has arrived.

This keeps those rows and replays them as the library grows.

Behavior

Opt-in, off by default: Dashboard → Plugins → StarTrack → "Keep Letterboxd ratings for films not yet in the library." With it off, nothing changes — no queue file is written and the import behaves exactly as before.

With it on, rows that match nothing are parked in a per-user queue. Later syncs replay them, and each row is removed once it applies. Retry is also triggered by "Sync now" and after a ZIP import, so a member who just added a film can pull its rating in without waiting.

Design notes

Storage. A JSON queue at data/InternalRating/letterboxd-pending.json, following the same shape as LetterboxdPushLedger (SemaphoreSlim + atomic tmp/move). It is the inverse of that ledger — the ledger records work already done so it can be skipped, this records work not done so it can be repeated — and unlike the ledger it shrinks, because every row that finally matches is removed. Capped at 10k rows per user.

I went with parsed rows rather than the "store the export ZIPs in an admin-configured directory" idea sketched in the issue: re-parsing whole exports every sync would also re-run watchlist/likes/diary as a side effect, and it needs a config surface (path validation, permissions, cleanup). The parsed queue holds only what actually failed. Happy to revisit if you'd prefer the other shape.

Dedupe key is (kind, normalized title, year), plus the watched date for diary rows only. Rewatches are genuinely separate entries and collapsing them on title+year would keep just one; ratings deliberately exclude the date so a re-export with a shifted timestamp updates in place instead of queueing a second copy. Re-importing an export merges rather than stacking, per the issue.

RSS is captured too, not just the CSVs. It matters more than the CSV paths: a CSV row can always be recovered by re-uploading the export, but an RSS entry is seen once, lastSyncedGuid moves past it, and it scrolls off the feed. Rating a film on Letterboxd the week before it lands in Jellyfin used to lose that rating permanently.

Cost control. Replaying needs the movie lookup, which is a full GetItemList plus a File.Exists per item — too expensive for a task that ticks every 10 minutes. GetLibraryFingerprint() gates it: movie count plus newest DateCreated from two indexed queries, compared against the previous tick. It is the local counterpart of the ETag the RSS poll already sends, used the same way, and here it is provably lossless rather than a heuristic — the only thing that can resolve a pending row is an item appearing, so an unmoved library means a retry cannot succeed. Steady state is one cheap query per tick.

The retry sits outside the RSS sync and is independent of its outcome, including the 304 path. The two wait on different things: the RSS poll on the member's Letterboxd feed, this on the Jellyfin library. Gating it on a feed change would drain a backlog only for members still actively posting to Letterboxd, which is the opposite of who needs it.

Known gap, documented at the method: an in-place metadata edit that fixes a title moves neither part of the fingerprint, so it is not picked up until the next add or remove. ItemSortBy has no DateLastSaved in 10.11, so catching it would mean materialising the library — the exact cost being avoided. Manual "Sync now" always forces a pass.

Testing

Verified on a live 10.11 server (ZimaOS, Docker) against a real Letterboxd export — deliberately a 19-movie library, which is the issue's scenario at its most extreme:

• 303 ratings rows → 6 matched, 297 unmatched → 297 queued, plus 155 watchlist, 242 likes, 296 diary. 990 rows total, matching the file exactly. All four capture sites fired, one write per CSV.
• Added two films from the queue, scanned, hit "Sync now" → both ratings applied and their rows removed.
• Confirmed with the setting off that no queue file is written.

That last round also caught the one bug in here: "Sync now" reported "Nothing new on Letterboxd right now" while ratings were visibly landing, because both status builders computed their total as imported + updated and never saw pendingResolved. An idle feed is the normal case for a retry, so that read as a failure exactly when the feature had done its job. Fixed in the final commit.

23 new unit tests cover the dedupe key from both sides (re-import must not stack; rewatches on different days must stay separate; two watches the same day must collapse), persistence, the cap, corrupt-file recovery, and the title-matching boundary every capture site branches on.

Commits

Six, each building independently so the history bisects: storage + config → capture and replay → wiring → admin toggle → tests → the status-message fix.

🤖 Generated with Claude Code