Cross-seed: relax Year matching when content/files are identical

[backstab5983]

qui's built-in cross-seed matching appears to treat the parsed year as a hard requirement during candidate filtering/matching. Because of that, if a tracker uses a different "display year" in the torrent title than the actual release filename/year on disk, the match is skipped even when the payload is identical.

Example file on disk / current torrent content:

Society.of.the.Snow.2024.1080p.NF.WEB-DL.DUAL.DDP5.1.Atmos.H.264-FLUX.mkv

When searching for cross-seeds:

• On BLU, the torrent title is also ...2024... → qui finds the match.
• On ATH, the torrent title is ...2023... (even though the underlying files/names are identical) → qui does not match it.

I have *arrs integration working yet qui won't pick this up, I also suppose it's caused by the fact that the original filename release year is wrong (should be 2023), so when qui searches it tries to match a movie from 2024.

IIRC cross-seed can somehow handle these cases 😅 - is it possible for qui to support this?

[github-actions[bot]]

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Add an opt-in relaxation so a cross-seed candidate that differs only by release year can still match when the reported size proves identical content.

Current behavior:
Release comparison rejects a candidate with a year mismatch whenever both sides parse a year and the years differ. The exact-size fallback cannot rescue the pairing either: its identity check requires the two years to be equal, and year is not one of the difference categories replay is allowed to spend (season, episode, group, source, collection, codec, hdr, bit-depth, cut, edition, language, version, disc, platform, architecture, checksum, variant). So a tracker that lists a movie under a different display year than the year in the local release name never matches, even when the payload is identical. The yearless retry only drops the year from the indexer query; it does not relax the match gate, so the widened query returns the listing and the gate then rejects it. The season pack flow already has an opt-in that zeroes year, month and day on both sides before comparison (seasonPackSkipYearCompare), but the torrent search path has no equivalent.

Desired behavior:
An opt-in cross-seed setting, off by default, lets a year difference be spent as a relaxed difference in the exact-size fallback, in the same shape as rescueTitleMismatches. Every other identity gate stays strict: title, artist, resolution, group/site, checksum, TV structure and variant tags. Date-based (0day) releases that carry month and day keep the strict date rule. An admitted year relaxation is recorded on the search decision and forces a hash check before the added torrent seeds.

Key interfaces:

• CrossSeedSettings: one new opt-in boolean beside RescueTitleMismatches, persisted in the SQLite and Postgres schemas and exposed through the cross-seed settings API and the cross-seed settings UI.
• validateArtistAndDates(): keeps returning the year rejection for strict comparison; strict stays the default outcome.
• validateExactSizeSearchIdentity(): today requires year equality outright; must allow a year difference only when the setting is on and every other identity attribute is proven.
• exactSizeRelaxedDifferenceForReason(): must map the year rejection to a relaxable difference so replay can spend it once.
• searchRelaxationRequiresVerification(): a year relaxation must require verification, because equal reported size alone does not prove which release the candidate holds.

Acceptance criteria:

• With the setting off, a candidate whose parsed year differs is rejected with the year mismatch reason, unchanged from today.
• With the setting on, a movie candidate that differs only by year and reports the exact source size matches, and the recorded search decision names the year relaxation.
• With the setting on, a candidate that differs by year plus title, resolution, or group is still rejected.
• With the setting on, a date-based release whose month or day differs is still rejected.
• A candidate admitted through the year relaxation is hash checked before it seeds, and an apply that would skip the recheck is refused.
• The setting round-trips through the settings API and through both the SQLite and Postgres stores.

Out of scope:

• Strict behavior when the setting is off. No existing match or rejection may change.
• The season pack year toggle and the season pack matching path.
• Search query construction, including the existing yearless retry.

Why a human: This loosens a core identity gate that guards against seeding the wrong release, so whether qui takes that trade at all, and whether it lands as a global setting or something narrower, is a maintainer call.

[illutr0n]

Another data point: I hit this on a large share of manual movie searches. It is almost always exactly one year apart, and comes from trackers naming by TMDB year vs the release using the IMDb year (festival premiere vs wide release, or a late-December release). Same encode, same group, byte-identical size, e.g.:

local:     Example.Film.2020.UHD.BluRay.1080p.DDP.5.0.DoVi.HDR10.x265-Kyo
candidate: Example Film (2021) 1080p UHD BluRay x265 DV HDR DDP 5.0 DUAL-Kyo
→ rejected: year mismatch (exact-size fallback can't spend it)

I'm running a local patch along the lines of the triage brief, but narrower and without the setting, in case the shape is useful:

• exact-size fallback only (strict matching still rejects any year difference)
• years exactly one apart only (two or more stays a mismatch)
• non-TV only (a year in a TV name often tells a reboot from the original; TestClassifySearchCandidateExactSizeDateIdentity keeps passing unchanged)
• not date-based releases (month/day present stays strict)
• year mismatch added to searchRelaxationRequiresVerification, so an admission that spent the year is hash-checked before seeding

Implementation: adjacentReleaseYears() gates a year case in exactSizeRelaxedDifferenceForReason / withRelaxedDifferenceNeutralized / observedReleaseDifferences, and validateExactSizeSearchIdentity passes the adjacent year through to replay instead of rejecting it in validateTitleArtistAndDates. All ./internal/... and ./pkg/... test results are unchanged against v1.32.0. A different size, a different group, or a different resolution with the year one off is still rejected.

±1 alone might be enough to make this safe without an opt-in, given the size equality and the forced recheck.