Skip to content

fix(engine): hold a sibling's pre-release skip - #793

Merged
av1155 merged 3 commits into
mainfrom
fix/unreleased-sibling-hold
Sep 18, 2026
Merged

av1155 merged 3 commits into
mainfrom
fix/unreleased-sibling-hold

Conversation

@av1155

@av1155 av1155 commented Sep 18, 2026

Copy link
Copy Markdown
Owner

Summary

The release gate writes its skip before group dedup, so in season, artist, and
author mode a record it blocks logs under the parent's synthetic id and reads as
the parent's own release state. not yet released was the half #770 left open:
the row re-armed the parent's retry on every cycle, and a released sibling drove
a fresh search each time, so the cooldown never applied.

Closes #782

Changes

  • A context-mode pre-release skip now waits until the end of the pass and is
    written only for a parent no other record cleared the gate for. This is the
    shape _QueuedSkips already uses for the download-queue gate.
  • Post-release grace rows are still written as they are reached. One proves its
    record was already released, which is what arms the parent's retry once the
    window elapses, and that wait is already bounded. Item-level rows are
    unchanged.
  • The held rows are keyed on their own set rather than the pass's group slot.
    The queue gate hands that slot back so a sibling can search in place of a
    downloading record, which would otherwise let a held row land again for a
    parent whose released record was reached.

The hold is per pass, so it is not absolute. A parent whose released record sits
on a page the cycle did not reach, while its blocked record sits on one it did,
still gets the row and one early retry; the dispatch that follows cancels it,
where before the retry came back every cycle. Wanted lists are read oldest
first, so a record dated ahead sorts behind every released one on the same page
and only the page order can split them. Forcing that split by hand produced one
extra search and no repeat, and none of the paged runs below produced a stale
row at all.

Testing

All checks pass.

Driven against a season holding one record released long ago and one dated five
minutes ahead, cooldown seven days, batch one, cycles a minute apart. Dispatches
across eight cycles, before and after:

instance clocks agree clocks disagree, before clocks disagree, after
Sonarr season-context 1 6 1
Lidarr artist-context 1 6 1

Every skewed configuration now matches the unskewed one. The count is a rate,
not a constant: the parent is dispatched on every cycle the difference lasts,
so the same five minutes produced four dispatches at a two minute cycle
interval, and a thirty minute difference produced eight out of eight.

On a shape closer to a real instance, 120 wanted records over three pages at
the default batch of ten and random page order, 40 cycles, the season was
searched 36 times before and once after.

The paths that had to keep working were driven the same way. A season only a
blocked record holds still logs the row and still takes its one retry the cycle
after that record's date passes. With the default grace, a record that leaves
the pre-release state enters post-release grace (Nh) and the parent takes its
retry one window later, which is where that prompt search already came from.

Six mutations, each caught: reverting the hold fails four of the new cases and
the rewritten peer case; never writing the held rows fails the two that cover a
parent nothing got past the gate for; deferring item-level rows fails the golden
search log; deferring grace rows as well fails four of the existing grace cases;
keying the held rows on the pass's group slot fails the downloading case; and
marking a parent before the gate rather than after fails the two that expect a
blocked parent to still log.

Which records can reach this state was read from upstream rather than assumed.
Lidarr AlbumRepository.cs and Readarr BookRepository.cs filter their wanted
lists on ReleaseDate <= currentTime, so any clock disagreement exposes one.
Sonarr and Whisparr v2 use AirDateUtc + Series.Runtime <= currentTime, so
there the disagreement has to exceed the episode runtime first. Radarr and
Whisparr v3 do return unreleased records but have no context mode.

Type of Change

  • Bug fix (fix:)
  • New feature (feat:)
  • Refactoring (refactor:)
  • Documentation (docs:)
  • CI/CD (ci:)
  • Chore (chore:)

Checklist

  • Issue exists and is linked above with Closes #N
  • Linked issue has exactly one type:* and one priority:* label
  • Linked issue has at most one phase:* label (or none when not roadmap work)
  • Branch name matches issue scope (feat/<slug>, fix/<slug>, etc.)
  • Tests added/updated for all changes
  • Type check passes (mypy src/)
  • Lint passes (ruff check .)
  • Format passes (ruff format --check .)
  • Documentation updated (if applicable)
  • No secrets or sensitive data committed
  • Scope check: This change helps search for missing or cutoff-unmet media in a controlled way

The release gate writes its skip before group dedup, so in season,
artist, and author mode a record it blocks logs under the parent's
synthetic id and reads as the parent's own release state. A
`not yet released` row then re-armed the parent's retry on every
cycle, and a released sibling drove a fresh search each time.

The apps with those modes keep unreleased records out of their
wanted lists, so such a record only appears while this host's clock
trails the *arr's. Measured on a season with one released record and
one five minutes ahead: six dispatches across eight cycles against a
seven-day cooldown, where an unskewed instance takes one.

Context-mode pre-release skips now wait until the end of the pass and
are written only for parents no sibling represented. Post-release
grace rows keep being written as they are reached; one proves its
record was already released, which is what arms the retry once the
window elapses.

Closes #782
Review follow-ups.

The held rows read their own set of parents a record cleared the gate
for, rather than the pass's group slot. The queue gate hands that slot
back so a sibling can search in place of a downloading record, which
would let a held row land again for a parent whose released record was
reached. Today the queue reason is filtered out of the retry lookup so
the outcome was the same either way; adding it back would not have
been.

The run-now case filled its batch on the released record before the
gate reached the blocked one, so it passed against the unfixed engine
too. The blocked record now comes first.

The grace bound's docstring, and the skip-reasons page, both described
the drop as happening when a sibling searched the parent. It happens
when one clears the gate, whatever a later gate does with it.
Second review follow-ups.

The skip-reasons page said a parent whose items were all blocked keeps
its row. The condition is no item past the check on that cycle, which
also covers a released item the cycle never reached.

The scheduling page said every item considered but not searched gets a
skipped row. Throttled reasons and the deferred rows are both
exceptions.

The run-now case cannot see whether the pre-release check still
applies, because in season mode either record dispatches the same
season search. Renamed to what it does pin, with a pointer to the case
that covers the rest.
@av1155
av1155 merged commit e12245b into main Sep 18, 2026
37 checks passed
@av1155
av1155 deleted the fix/unreleased-sibling-hold branch September 18, 2026 16:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

fix: a not yet released sibling re-searches its parent every cycle

1 participant