feat(indexing): query-driven search — resolve t=tvsearch on demand (#58, DR-011)

[ChrisonSimtian]

Implements DR-011. Search previously served only what a crawler had already written, and the crawl list is three hardcoded seed shows — so Sonarr searching for anything else got an empty feed, indistinguishable from "not in the Mediathek". Now an uncrawled term resolves against the broadcasters on demand, which is what lets Krautwatch work with zero *arr configuration.

The wait is bounded; the crawl is not

Per your steer. A search waits RequestDeadline (default 8s, configurable) then answers with whatever landed — but the crawl keeps running to completion in the background, so the next call gets the full set. Abandoning a half-finished crawl would discard ARD round-trips already paid for and leave the cache permanently partial.

The consequence is the subtle bit: the crawl must not observe the request's CancellationToken. It's queued and drained by a hosted service under the host lifetime. Threading the request token through would cancel every crawl the instant the response was written — presenting as "resolution mysteriously never works".

There's a test for exactly that, and I mutation-checked it: reintroducing the bug fails that one test and nothing else, so the guarantee is genuinely enforced rather than incidentally true.

Negative caching matters more than positive

ResolvedQuery records normalised query, timestamp, result count, providers tried. Sonarr re-issues the same failing query every RSS-Sync cycle, so without a "we looked and found nothing" marker, each cycle triggers a fresh multi-hop ARD crawl. Hits trusted 6h, misses 45m.

Configuration

Indexing:OnDemandResolution:Enabled                   # true — kill switch
Indexing:OnDemandResolution:RequestDeadline           # 00:00:08
Indexing:OnDemandResolution:CrawlTimeout              # 00:02:00
Indexing:OnDemandResolution:PositiveTtl               # 06:00:00
Indexing:OnDemandResolution:NegativeTtl               # 00:45:00
Indexing:OnDemandResolution:MaxConcurrentResolutions  # 2 — politeness cap

Other decisions

RSS (no query) is never resolved — RSS-Sync polls constantly with no target, so resolving there means crawling on a timer for nothing specific. It keeps serving the standing crawl list per DR-011.

A miss returns 200 with an empty feed, never an error. Sonarr treats indexer errors as an availability problem and disables an indexer that keeps failing, so "no results yet" must stay distinguishable from "broken".

Concurrent identical queries coalesce to one crawl. Per-process only — several API replicas would each crawl once, not worth distributed locking.

The API host now registers the broadcaster crawlers, which until now only the agents had. That makes it run an IO-driven Action — the same narrow DR-009 deviation already recorded for TestArrConnection, because a synchronous request cannot wait on the durable bus.

Indexing gets its own crawl-and-upsert rather than calling Crawling's handler: the slice-isolation architecture test forbids the cross-slice call, and that small duplication is the intended cost of slice isolation, not an accident to refactor away.

Three bugs caught while writing this

None would have failed a build, so worth naming:

1. Captive dependency — the singleton resolver was capturing a scoped repository (and its DbContext) for the process lifetime. Now takes IServiceScopeFactory.
2. Data race — the provider list was being built inside concurrent Task.WhenAll lambdas, i.e. concurrent List.Add. Now captured before the fan-out.
3. Name collision — Domain has its own Channel entity (a broadcaster channel), ambiguous with System.Threading.Channels.Channel.

Verified end to end against live ARD, from an empty database

Step	Result
Cold search q=Panorama (never seeded)	8.56s, 0 items — deadline bounding the wait
Background crawl afterwards	16 episodes persisted; panorama|16|ard,kika,zdf
Warm search, same term	16 items in 98ms from Postgres
Nonexistent show, first call	recorded zzznotarealshow|0
Nonexistent show, repeat	28ms, no re-crawl — Sonarr-retry protection
RSS (no query)	ResolvedQueries unchanged at 2 rows
t=caps	still served

That second row is the one the whole design turns on: the crawl outliving the request that triggered it.

Tests: App 85 / Arch 11 / Infra 102 green, 0 warnings.

Known trade-off

A first interactive search for an uncrawled show may return few or no results and take ~8s. That's the trade DR-011 accepts consciously — and it self-heals, since the same search moments later is instant and complete. Tunable via RequestDeadline if you'd rather wait longer for a complete first answer.

Not in this PR

Adding resolved shows to the standing crawl list, so RSS picks up their future episodes automatically. Tempting, but it grows the list without bound and needs its own retention policy — deliberately left out rather than smuggled in.

Plan: docs/plans/2026-07-28 - query-driven-search.md

🤖 Generated with Claude Code