Feature request: Allow tolerance-backed title rescue instead of exact reported-size only

[mrpops2ko]

Summary

I'd like to propose a small extension to the existing cross-seed title-rescue system:

Allow title-rescue candidates whose reported total size is within qui's existing 5% tolerance, rather than requiring the Torznab/qBittorrent reported sizes to be byte-for-byte identical.

This is deliberately narrow.

qui already has nearly all infrastructure required:

• existing 5% search-size tolerance
• Rescue title mismatches
• exact-size title rescue
• maximum 3 title-rescue attempts per search
• source-bound search decision provenance
• exact usable-file pairing for title-rescue candidates
• paused/full-recheck verification
• protection when Skip recheck is enabled

I am not proposing another tolerance setting, another matcher, another rescue queue, or weaker final verification.

The missing behaviour appears to be specifically that title rescue cannot currently use normal tolerance-backed reported-size evidence.

---

Current behaviour

Current search classification distinguishes only:

no exact size evidence
exact reported size

For title rescue, this effectively means:

title mismatch
    +
Rescue title mismatches enabled
    +
source reported size == candidate reported size
    +
remaining metadata compatible
    ↓
title rescue

If total reported size differs at all, title rescue cannot activate.

This includes a one-byte difference.

There are current unit tests explicitly pinning this behaviour:

CandidateSize--
→ title rescue rejected

and for generic exact-size fallback:

"within tolerance is not exact"
→ fallback rejected

So this is distinct from qui's existing 5% size tolerance.

---

Why this can miss valid cross-seeds

Reported torrent total size is not necessarily the same thing as reusable payload identity.

Example:

Source torrent

Movie.mkv      72,000,000,000
Movie.nfo              20,000

Total          72,000,020,000

Another tracker may package:

Candidate torrent

Renamed.Movie.mkv  72,000,000,000
Movie.nfo                  20,000
poster.jpg                 550,000

Total              72,000,570,000

Important media payload is byte-identical:

72,000,000,000
=
72,000,000,000

but reported torrent totals differ by 550 KB.

Both totals are vastly inside qui's existing 5% tolerance, yet a title mismatch cannot currently enter title rescue because reported totals are not exactly equal.

That means qui can reject candidate before downloading .torrent metadata, even though its existing downstream title-rescue validation could determine that usable files pair exactly.

---

Existing downstream validation is already strong enough

This request does not require weakening final validation.

Current title rescue already requires:

one exact-size partner for every usable file

That is much stronger evidence than Torznab-reported total size.

So proposed flow would be:

Indexer result
      ↓
normal strict matching
      ↓
title mismatch
      ↓
Rescue title mismatches enabled?
      ↓
reported size inside existing 5%?
      ↓
remaining title-rescue metadata rules compatible?
      ↓
existing bounded rescue attempt
      ↓
download candidate torrent
      ↓
existing exact usable-file pairing
      ↓
all usable files have exact-size partners?
       /                         \
     no                           yes
      ↓                            ↓
   reject                  add paused/stopped
                                  ↓
                            mandatory recheck
                                  ↓
                         seed only if verified

The 5% comparison would therefore only decide:

Is this candidate plausible enough to inspect?

It would not decide:

Is this a valid cross-seed?

Existing file validation and recheck remain final authority.

---

Proposed change

Conceptually, title-rescue admission could change from:

mismatchReason == titleMismatchReason &&
exactReportedSize

to something like:

mismatchReason == titleMismatchReason &&
reportedSizeWithinExistingTolerance

while retaining every existing title-rescue safety check afterwards.

Exact-size candidates should still rank ahead of tolerance-only candidates.

For example:

1. normal strict match
2. exact-size fallback
3. exact-size title rescue
4. tolerance-backed title rescue

No new user-configurable percentage appears necessary initially.

Use existing:

defaultSizeMismatchTolerancePercent = 5.0

---

Important: retain existing title-rescue safeguards

Tolerance-backed title rescue should reuse current protections unchanged.

Existing 3-attempt limit

qui already limits title-rescue attempts:

maxTitleRescueAttemptsPerSearch = 3

That should remain.

This is important because downloading .torrent files from private trackers may count as snatches or consume tokens.

The feature should not download every result inside 5%.

---

Existing source-bound provenance

Current title rescue is tied to original source torrent via search-decision provenance.

That should remain unchanged.

A tolerance-backed decision should only apply to exact source torrent which produced search.

No global weakening of release matching is required.

---

Existing exact usable-file pairing

Current title rescue already checks that every usable source file has one exact-size partner.

That should remain mandatory.

For example:

Source:

Movie.mkv       72,000,000,000

Candidate:

Different.Name.mkv  72,000,000,000
poster.jpg                 550,000

Reported totals differ.

But usable payload pairing succeeds:

72,000,000,000
↔
72,000,000,000

Candidate can proceed to full recheck.

Whereas:

Source:
Movie.mkv       72,000,000,000

Candidate:
Movie.mkv       71,900,000,000

may be inside reported 5% tolerance, but exact usable-file pairing fails.

Result:

reject

So tolerance is only discovery evidence.

---

Existing mandatory recheck

Title-rescue candidates already require verification.

Tolerance-backed title rescue should continue to:

• require recheck
• remain paused/stopped during verification
• not seed until verification succeeds
• be unavailable when Skip recheck prevents required verification

No new verification mechanism is needed.

---

Existing precedent: WEB source relabel

Current code already demonstrates that tolerance-backed relaxation can be safe in a narrowly scoped search case.

The WEBRip ↔ WEB-DL source-relabel path can accept its specific metadata mismatch when reported sizes fall inside normal tolerance.

So conceptually qui already has both:

metadata mismatch
+
tolerance-backed reported size
+
stronger downstream validation

and:

title mismatch
+
exact reported size
+
stronger downstream validation

This request is essentially asking to combine those existing concepts for title rescue:

title mismatch
+
tolerance-backed reported size
+
existing exact file-pair validation
+
mandatory recheck

---

Why this may improve recall

I've been comparing qui with ccf-2012/seedcross.

For same source torrents and indexers, seedcross appears to identify substantially more possible cross-seeds.

I don't think qui should copy seedcross's permissive matching directly.

qui has much stronger validation.

But one architectural difference appears important:

seedcross

search candidate
      ↓
size sufficiently close
      ↓
candidate worth trying

versus roughly:

qui

search candidate
      ↓
release metadata mismatch
      ↓
unless exact-size rescue applies:
reject before torrent-level validation

The problem is not qui being too strict at verification.

The problem is potentially being too strict about which candidates are allowed to reach verification.

Tolerance-backed title rescue would improve discovery recall without weakening final safety.

---

Why exact reported-total equality is weaker than actual file evidence

Before candidate torrent is downloaded, qui has:

Torznab title
parsed release metadata
Torznab-reported total size

After candidate torrent is downloaded, qui has:

actual file list
actual per-file sizes
usable-file classification
torrent layout
piece metadata
recheck result

For deciding whether content can cross-seed, latter evidence is much stronger.

Example:

Reported totals:

Source       72,000,020,000
Candidate    72,000,570,000

not equal.

But actual usable files:

Source Movie.mkv       72,000,000,000
Candidate Movie.mkv    72,000,000,000

are exact.

Requiring equal reported totals before allowing existing exact per-file matcher to run seems unnecessarily restrictive.

---

Related prior work

PR #1592, fix(crossseed): relax discovery matching, previously explored broader separation between strict identity matching and more permissive discovery matching.

That PR was closed rather than merged.

Since then, qui has gained more targeted infrastructure including:

• exact-size fallback
• title rescue
• search-decision provenance
• bounded title-rescue attempts
• verification-required decisions
• stronger exact-size file pairing

Because these mechanisms now exist, I don't think broad discovery-matcher changes are necessary for this request.

A much smaller extension to existing title rescue may recover much of practical benefit.

---

Suggested acceptance tests

Exact-size title mismatch

SourceSize    = 10,000,000,000
CandidateSize = 10,000,000,000

Current behaviour remains unchanged.

Existing title rescue applies.

---

One-byte reported-size difference

SourceSize    = 10,000,000,000
CandidateSize =  9,999,999,999

Currently rejected from title rescue.

Proposed behaviour:

eligible for title-rescue investigation

Actual usable-file pairing must still pass before add.

---

Small sidecar difference

Source:
movie.mkv     10,000,000,000

Candidate:
movie.mkv     10,000,000,000
poster.jpg           500,000

Reported totals differ.

Proposed:

within 5%
→ inspect candidate
→ exact usable-file pairing succeeds
→ add paused
→ full recheck

---

Payload itself differs

Source:
movie.mkv     10,000,000,000

Candidate:
movie.mkv      9,900,000,000

Potentially still inside 5% reported-size tolerance.

But existing exact usable-file pairing fails.

Expected:

reject

---

Outside existing tolerance

reported difference > 5%

Expected:

no title rescue

---

Skip recheck enabled

Expected:

no tolerance-backed title rescue

Same safety behaviour as current title rescue.

---

Potential follow-up

If tolerance-backed title rescue proves safe in practice, it may later be worth evaluating whether selected exact-size fallback relaxations should also accept tolerance-backed size evidence.

Current tests explicitly reject even a one-byte/non-exact difference for generic exact-size fallback.

I would treat that as a separate follow-up rather than broadening this initial feature.

Starting with title rescue is narrower because it already has:

• explicit user opt-in
• 3-attempt cap
• exact usable-file pairing
• mandatory verification

which makes it a good place to evaluate whether exact reported-total equality is unnecessarily limiting recall.

---

Requested change in one sentence

Extend existing Rescue title mismatches behaviour so candidates inside qui's existing 5% reported-size tolerance can reach current exact usable-file validation and mandatory recheck, rather than requiring byte-for-byte equality of reported torrent total size.

[github-actions[bot]]

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Let Rescue title mismatches admit candidates whose reported size is inside the configured size-mismatch tolerance, not only candidates whose reported size is byte-equal.

Current behavior:
classifySearchCandidate reaches the title-rescue class only when the size evidence is exact: classifySearchSizeEvidence returns exact evidence only from positiveExactSize, which needs both reported sizes non-zero and equal. A title-mismatch candidate whose reported total differs by one byte is rejected before qui downloads the .torrent, so the stronger per-file pairing check never runs. The same classifier already carries a tolerance-backed branch: shouldAcceptWebSourceRelabel accepts its metadata mismatch on isSizeWithinTolerance evidence.

Desired behavior:
With RescueTitleMismatches enabled, a candidate rejected for a title mismatch enters title rescue when its reported size passes isSizeWithinTolerance against the source. Everything after admission is unchanged: exact per-file pairing for every usable source file, source-bound decision provenance, the maxTitleRescueAttemptsPerSearch cap, paused add with mandatory recheck, and the block when recheck is skipped. Exact-size evidence still outranks tolerance-only evidence, so exact candidates are attempted first and the attempt cap is not spent on weaker ones. A candidate outside tolerance, or with a zero or missing reported size on either side, is rejected as it is today. Tolerance decides only which candidates are worth inspecting; file pairing and recheck stay the authority on whether one is added and seeded.

Key interfaces:

• classifySearchCandidate(): the title-rescue branch requires exact size evidence today and must also accept tolerance-backed evidence
• searchSizeEvidence and classifySearchSizeEvidence(): carry only exact and none; a tolerance-backed level needs its own priority() rank below exact and its own matchReason()
• searchCandidateDecision: MatchReason and score must tell a tolerance-backed rescue apart from an exact-size one, so the decision trail stays readable
• defaultSizeMismatchTolerancePercent and maxTitleRescueAttemptsPerSearch: reused as they are; the request asks for no new setting

Acceptance criteria:

• A title mismatch with equal reported sizes still classifies as title rescue, with its current match reason.
• A title mismatch whose reported sizes differ by one byte, inside the configured tolerance, classifies as title rescue.
• A candidate that adds a small extra file and so reports a larger total, inside tolerance, reaches per-file pairing and is added paused for recheck when every usable source file has an exact-size partner.
• A tolerance-admitted candidate whose usable files have no exact-size partner is rejected before the add.
• Reported sizes outside the configured tolerance never produce a title rescue.
• A zero or missing reported size on either side never produces a title rescue.
• A tolerance-admitted title rescue is unavailable when recheck is skipped, matching current title-rescue behavior.
• Exact-size rescue candidates rank ahead of tolerance-only ones, and the per-search attempt cap still bounds how many candidate .torrent files one search downloads.

Out of scope:

• The generic exact-size fallback class, which keeps requiring equal reported sizes.
• Any new user-facing tolerance percentage; reuse the configured size-mismatch tolerance.
• The attempt cap, the provenance binding, the exact per-file pairing rule, and the recheck requirement.

Why a human: Admitting more candidates means downloading more .torrent files from private trackers, where a grab can cost a snatch or a token. How much discovery recall is worth that cost is a maintainer call.