feat(requestrouter): carry requested seasons to request routers

README.md

@@ -130,6 +130,37 @@ err = host.CallPluginJSON(ctx, runtimehost.CallPluginJSONRequest{
 
 The `auth_provider.v1` capability also exposes OAuth-flow RPCs (`InitAuthorize`, `ExchangeCode`, `RefreshSession`) for plugins that wrap external identity providers.
 
+## Request routers
+
+`request_router.v1` lets the host hand a media request to a download backend
+such as Sonarr, Radarr, or Seerr. The host owns the request lifecycle, policy,
+and quality governance; the plugin routes the request to a configured
+connection and reports its status.
+
+A series request may name seasons in `RequestDescriptor.seasons`. Season `0`
+is Specials, and an empty list means the whole series. A plugin that fulfils
+seasons individually declares it in its manifest:
+
+```json
+{
+  "type": "request_router.v1",
+  "id": "arr",
+  "request_router": { "supports_seasons": true }
+}
+```
+
+A declaring plugin must acquire only the requested seasons. When the series
+already exists upstream, it adds those seasons to what is already tracked and
+leaves the other seasons alone, so a request for season 4 never stops tracking
+seasons 1–3. Repeating a request must converge rather than add the series
+again. `CheckStatus` receives the same descriptor, so status can cover the
+requested seasons.
+
+Plugins without the flag, including every plugin built before it existed, keep
+today's whole-series behaviour. The host requests only the missing seasons of a
+series it already has from plugins that declare `supports_seasons`, because
+any other plugin would add the whole series again.
+
 ## Watch sync providers
 
 `watch_sync_provider.v1` lets external plugins participate in Silo's host-owned

docs/compatibility.md

@@ -68,6 +68,14 @@ Watch-sync rating fields (`WatchSyncEvent.rating` and
 ratings run from 1 to 10, so zero never carries a rating and no presence check
 is needed.
 
+`RequestDescriptor.seasons` is a repeated field, so it has no presence: an
+empty list means the whole series, and season `0` in a non-empty list means
+Specials. A plugin built before the field existed decodes it as an unknown
+field and fulfils the whole series. Because the plugin cannot say so on the
+wire, the host decides who may receive a season-only request from the
+manifest's `RequestRouterDescriptor.supports_seasons` flag instead. An absent
+descriptor means the flag is false.
+
 A season-scoped `GetImagesRequest` is a scope, not a guarantee. Plugins that
 can filter by season should do so, and plugins should populate
 `ImageRecord.season_number` whenever the season is known. Hosts must bucket and