Reduce Plex reload payloads for large show operations

[antwanchild]

What type of PR is this?

• Bug Fix (non-breaking change which fixes an issue)
• Feature/Tweak (non-breaking change which adds new functionality or enhances existing functionality)
• Breaking Change (fix or feature that would break any existing functionality for users)
• Documentation Update
• Chore (maintenance, dependency bumps, housekeeping - no functional change)
• Other

Description

This PR provides a targeted mitigation for Plex metadata reload failures on very large TV shows during library operations.

Before any item operation runs, Kometa reloads the show's /library/metadata/{ratingKey} resource. Plex may aggregate a substantial amount of show-level cast, crew, and media metadata for long-running shows. In #3519, Plex returns 404 Not Found for two especially large shows, causing Kometa to skip all operations for those shows, including show and season poster updates.

For TV-show library operations, the reload now asks Plex to exclude elements that the operations pipeline does not read:

Excluded element	Needed by library operations?	Expected impact
Media	No	Avoids serializing unused media details
Role	No	Avoids potentially large aggregated cast lists
Director, Writer, Producer	No	Avoids unused crew lists
Similar	No	Avoids unused related-title metadata
Style, Mood, Format	No	Avoids unused descriptive metadata

The metadata required by operations remains available:

Preserved data	Example consumers
GUIDs and external IDs	TMDb, TVDb, IMDb lookups
Labels and collections	Ignore rules and overlay-label handling
Fields and lock state	ignore_locked, lock, unlock, and reset operations
Genres, ratings, and dates	Mass metadata updates and mappers
Locations	Asset discovery and Sonarr/Radarr operations
Poster/background attributes	Show, season, and episode image operations

Scope and cache safety

Behavior	Before	After
TV-show operation reload	Full show-level element payload	Excludes unused heavy elements
Movie operation reload	Standard reload	Unchanged
Other Plex reload callers	Standard reload	Unchanged
Cache state after a limited reload	Not applicable	Retained as partial, allowing a later full reload
Forced limited reload of a previously full item	Not applicable	Downgrades the cache entry to partial

Keeping the limited response marked as partial is important when run_order places overlays or another metadata consumer after operations. Those later stages can still perform a normal full reload if they need an excluded element.

This is a client-side mitigation based on the failure pattern in #3519. Confirmation against one of the affected Plex libraries will establish whether reducing the response payload resolves the server-generated 404.

Validation

Check	Result
Full pytest suite	1,492 passed
Focused Plex/operations tests	215 passed
Black formatting check	Passed
isort	Passed
flake8	Passed
git diff --check	Passed

Regression tests cover the limited reload parameter, partial/full cache transitions, forced limited reloads, show-only operation behavior, and unchanged movie behavior.

Related Issues [optional]

• Related Issue Very large TV Shows error and fail operations #3519
• Fixes Very large TV Shows error and fail operations #3519

Have you updated the Documentation to reflect changes (if necessary)?

• Yes
• No
• Not Applicable

This changes internal Plex request behavior only; no user-facing configuration or workflow changes.

Have you updated the JSON Schema files (if necessary)?

• Yes
• No
• Not Applicable

No configuration attributes, accepted values, or schema structures changed.

Have you updated the CHANGELOG.md?

• Yes
• No

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

[badja-dev]

Mechanically sound - the exclude/cache-downgrade wiring checks out end to end, movie behavior is unchanged, CI is green, and the CHANGELOG/tests boxes are ticked

[badja-dev]

the entry states this change is "preventing poster operations from failing on very large shows" as a fact, but the PR description itself is explicit that this is an unconfirmed mitigation ("Confirmation against one of the affected Plex libraries will establish whether reducing the response payload resolves the server-generated 404"). @antwanchild - can you soften the wording (e.g. "aiming to prevent" / "mitigate") until it's actually confirmed against #3519's affected libraries? As written it overclaims a fix that hasn't been verified yet

[badja-dev]

test_uses_limited_metadata_reload and test_movie_uses_standard_metadata_reload both build their item via make_item(1, "Movie A") while the library is set to is_show = True/is_movie = False for the first test. Cosmetic only (assertions are correct), but the "Movie A" naming is confusing next to a show-reload assertion - worth a quick rename if you're touching the file again