The Policy Gate: What Counts as Wanted

Sonarr's candidate set is not a shopping list. It is a collection of reports that still need to pass a policy gate. This chapter examines how Sonarr turns a parsed, mapped release into an explainable decision, how quality profiles distinguish “allowed” from “preferred” and “good enough,” and why rejection, delay, and later preference are different outcomes. The practical goal is to reason through a candidate without reducing the system to one opaque score.

That distinction matters because a release can be valid in several different senses. Its name may parse. Its episodes may map to a known series. Its quality may be recognized. Yet the release may still be outside the series policy, or an existing file may already meet the configured cutoff. Sonarr's decision engine exists to keep those judgments separate and to retain a reason when the answer is no.

A pass is not a preference

The decision engine receives a release report, parses its title, maps the result to a series and episodes, augments the remote episode with additional information, and calculates custom-format scores. Only then does it evaluate decision specifications. A specification is a focused rule that returns an accepted result or a rejection with a reason. The specifications are grouped by priority, and Sonarr stops at the first priority group that produces rejections.

This ordering gives the decision process a clear shape. Identity comes before policy because a release cannot be meaningfully judged for an episode Sonarr cannot identify. Policy checks then operate on a remote episode that has a series, an episode set, parsed quality, and other extracted facts. The result is not merely a Boolean hidden inside a downloader call. It is a DownloadDecision that retains the remote episode and any rejection information.

The distinction between an unknown identity and an unwanted candidate is especially important. If the parser cannot produce a series title, Sonarr does not pass the report into ordinary episode decision logic. If parsing produces a title but mapping finds no known series or no episodes, the decision records an unknown-series or unknown-episode outcome. If the series and episodes are known but a policy specification fails, the rejection means something different: the candidate was understood, but it did not satisfy the current rule.

That difference changes what a reader should do next. An unknown series may require a title or mapping correction. An unwanted quality may require a different release or a deliberate profile change. A temporary decision may be reconsidered later. Treating all three as “download failed” would erase the information Sonarr worked to preserve.

The engine also contains its own failure boundary. Each report is processed in a protected path. If parsing, mapping, or a specification throws an unexpected exception, Sonarr records a decision error for that report instead of allowing one broken report to abort the entire batch. Tests in the repository verify both the specification ordering and this per-report containment. The result is a system that can be conservative about one candidate without becoming blind to every other candidate in the same synchronization.