Thanks for this, and for the really clear writeup, it made the review easy. Since it's a draft and you asked for direction, here's where I'd push before taking it further.

• The biggest one for me is the ranking pool: it covers every aired, non-special episode Sonarr knows about, but it never checks hasFile (the filter is just season, valid airDateUtc, and <= now). Sonarr's EpisodeResource does expose hasFile, and Maintainerr is managing the media that's actually retained locally, so as written a user who only keeps an older subset can have every owned episode fall outside the newest N and get matched for deletion. I'd either rank over hasFile === true ("keep the latest N downloaded"), or rename and document it very explicitly as a catalog air-date rank so nobody reads it as "latest N on disk." Either is fine, but please make the call before this merges, since it changes which episodes get deleted.

• Could you drop the sw_ prefix? Right now it's sw_episodeRank, but sw_* is only used by the watch/library-style properties in the Plex, Tautulli, Jellyfin and Emby blocks. The Sonarr block has no sw_ properties, and the prefix reads as "watched/seen", which this isn't. Something like episodeAirRank or episodeRankByAirDate fits better, and since it's a new property there's no migration cost to renaming now.

• One of the new comments names a real show ("9000+ Jeopardy! episodes"). The repo convention is no real media titles in committed code, comments, tests or docs, so please swap it for a placeholder like "a long-running daily series." Worth a pass over the commit messages too.

• The e2e matrix entries don't really add coverage. That harness mocks the getter, so the two scenarios just hand 7 and 3 to the comparator, which is already covered generically for NUMBER props. The real coverage is your unit spec, and that's solid. I'd drop the matrix entries unless you specifically want them as named documentation cases.

• On redundancy: it's niche, but it isn't truly redundant. It covers a count-based window that the air-date rules can't express ("keep the last 5 episodes" isn't "keep the last 5 days" once a daily show skips a day or drops two at once). I'm happy to support it, just flagging the audience is small, which is why the naming and semantics matter for a permanent rule property.

• Excluding specials by default is the right call. I wouldn't add a flag for that in a first version.

The core implementation looks good. The fail-closed handling, the 0001-01-01 sentinel guard, and the run-scoped arrLookupCache memoization all look correct, and the spec is thorough. Mainly it's the hasFile decision, the rename, and the title-in-comment cleanup.

Thank you for the review - you make a good point about the Ranking Pool.

I will give it some thought and go over the logic again.

Other points can also be fixed in the next commit.

Also, have a look here: https://github.com/Maintainerr/Maintainerr/tree/development/.claude

(Since you use Claude)

Put some more work in to this today.

Major:

• Pool semantics: went with Option A from @enoch85's review, rank over hasFile === true only. The rule now means "keep the latest N downloaded" instead of "rank within Sonarr's catalog". Renamed sw_episodeRank to episodeFileRank to match. Felt this was closer to Maintainerr's goal of managing media on disk. Also removes the foot-gun where a partial library could have existing files deleted because none ranked in the catalog's newest N.

• Scope, Series Title (Sonarr.seriesTitle, TEXT). episodeFileRank deletes, and there was no first-class way to scope to one show. The only options were Sonarr tags or Plex collections, both out-of-band and invisible in the rule builder. Sonarr.seriesTitle EQUALS "<title>" is the discoverable scope predicate now. Pairs with episodeFileRank > N for "keep the latest N for this show".

• Scope, Series ID (Sonarr.seriesId, NUMBER). seriesTitle's strict-equals match is brittle: a user renaming the show in Sonarr, the title gaining a regional or year suffix (e.g. "(US)" or "(2019)") that wasn't there before, or trailing whitespace can silently zero the scope predicate and let the rank rule run library-wide. seriesId is the stable handle for production rank-and-delete rules. Both stay; recommendation in maintenance notes is seriesId for destructive rules.

Minor (review feedback):

• Dropped the sw_ prefix. The Sonarr block has no other sw_ props and the prefix reads as "watched/seen", which isn't what the rule does.

• Scrubbed the show-name reference in the getShowEpisodes comment (now "a long-running daily series"). Same scrub on the PR description.

• Dropped the two e2e matrix entries. That harness mocks the getter and the scenarios just handed 7 and 3 to the comparator, which is generic NUMBER-prop coverage. Real assertions live in sonarr-getter.service.spec.ts.

• Daily-series airtime crossing UTC midnight. The fallback was keying the rank map on the UTC day of Sonarr's airDateUtc and looking up by the UTC day of Plex's originallyAvailableAt. For a US primetime broadcast (e.g. 8pm Eastern) those land on different UTC days and the lookup misses. Switched the key to Sonarr's airDate string (broadcast-date in the show's local calendar) matched against originallyAvailableAt.toISOString().slice(0, 10). Regression spec covers the boundary.

• Opt-in bench spec (runs only with MAINTAINERR_BENCH=1) compares cached vs uncached rank-map at N=100/1000/9000. Doesn't run in CI. Will be removed in review candidate.

Other:

• Bug found while running dogfood: the Sonarr unmonitor API call can time out partway through, leaving the episode unmonitored but the file still on disk and the action reported as failed. Out of scope here; separate issue and PR.

Running end-to-end on my prod setup. Going to leave it for a bit.

Will then take another pass over the whole thing. Try and trim some of the code and see if I can find anything performance wise before submitting for review.

A note on scope before this goes further.

The original draft added one property (episodeFileRank). Since your review I've added two more, seriesTitle (TEXT) and seriesId (NUMBER), and I'd rather flag that explicitly than slip them past a review that covered one property.

Why they're here: episodeFileRank drives deletions, and there was no first-class way to scope it to a single show. The only options were Sonarr tags or Plex collections, both out-of-band and invisible in the rule builder, so an episodeFileRank > N rule effectively ran library-wide. seriesTitle EQUALS "..." gives a discoverable scope predicate; seriesId is the rename-proof version of the same thing, since a title gaining a "(US)" / "(2019)" suffix or trailing whitespace silently zeroes a strict-equals match and lets the rank rule run library-wide again. My recommendation for destructive rules is seriesId.

One caveat on seriesId: Maintainerr's UI doesn't surface Sonarr's internal series id anywhere, so a user has to read it off the Sonarr series URL / API. It's an advanced handle, not a discoverable one.

That's three permanent rule properties now instead of one, so I'd rather you make the call than assume. episodeFileRank does need some first-class way to scope to a single show, or the rule runs library-wide, so the two realistic options are:

• (a) keep seriesTitle and seriesId in this PR, or
• (b) split them into a separate PR so this one stays focused on the rank property.

Either works for me; let me know which you'd rather review.

Separately, I've removed the opt-in benchmark spec I mentioned earlier: it was dev-only scaffolding (gated behind MAINTAINERR_BENCH=1, skipped in CI) and didn't belong in the feature diff.

I’m reading and commenting on an iPhone, so I apologize if this has already been discussed and I missed it.

If this could also be applied to seasons, it would be one of the best features. A lot of people have been asking for a way to keep only the last X seasons.

I’m reading and commenting on an iPhone, so I apologize if this has already been discussed and I missed it.

If this could also be applied to seasons, it would be one of the best features. A lot of people have been asking for a way to keep only the last X seasons.

This could be expanded to manage seasons as well as episodes. Happy to fold that in.