Sightings: a Reader report defers a Poll of a solitary Series (#103) (#108)

Closes #103.

A userscript PUT already carries the Latest Chapter the Reader's own browser read off the Series page. It may now stand in for a Poll, under one restriction and one ceiling:

- **Solitary Series only** — a Series two Readers share is Polled on schedule however recently it was sighted, so one Reader's mistake can never reach another's list.
- **One rest of standing**, and a **six-rest ceiling** (`sightingCeilingRests`, counted in the Site's own Rest): however many Sightings arrive, an unpolled Series is Polled.

Both live in the due query's HAVING clause (`Store.DueForLatestCheck`) — the same place the schedule has always been decided, so no timer and no second code path can disagree with it. No new query per scheduler round.

Judgement costs no extra request. `Poller.checkOne` already compares what the Site publishes against what is stored: a lower number contradicts the Sighting (Reader and both numbers logged), the same number confirms it, a higher number is the Site publishing and clears the attribution instead. Three contradictions stop that Reader deferring — their reports still write the Latest Chapter — and twenty consecutive confirmations forgive them, as does the owner's clear-marks control from #102.

One client change was required: both userscripts skipped the PUT when the number had not moved, so the case the whole mechanism exists for — visiting a Series with nothing new — never reached the backend. `reportLatestChapter` sends it, skipping only the local write and the re-render. A numberless PUT (favourite toggle, progress from a chapter page) is no Sighting and defers nothing.

Schema: migration `0011_series_sightings.sql` adds `series.latest_sighted_at` and `series.latest_raised_by`. Trust model, thresholds, and rejected alternatives with their citations: `docs/adr/0011-sighting-deferral-trust-model.md`.

Reviewed on both axes (spec against #103, standards against the repo's rules); the blocker — attribution surviving a Poll that overtook the report — is fixed and has a test that fails without the fix.

Verification: `go test ./...` green (needs Docker), `node --test userscript/test/*.test.js` 66 pass.
Reviewed-on: #108
Co-authored-by: Sulthan Zaki <sultankiki05@gmail.com>
Co-committed-by: Sulthan Zaki <sultankiki05@gmail.com>

backend/internal/latest/poller.go

@@ -250,7 +250,8 @@ func (p *Poller) runLanePass(ctx context.Context, name string, paced bool) time.
 		return defaultGap
 	}
 
-	due, err := p.Store.DueForLatestCheck(name, now.Add(-s.Rest).UnixMilli())
+	due, err := p.Store.DueForLatestCheck(name, now.Add(-s.Rest).UnixMilli(),
+		now.Add(-sightingCeilingRests*s.Rest).UnixMilli())
 	if err != nil {
 		log.Printf("latest poll %s: due query: %v", name, err)
 		st.Gap = defaultGap
@@ -461,6 +462,11 @@ func (p *Poller) checkOne(ctx context.Context, sr store.Series) error {
 		return nil
 	}
 
+	// The Poll is the oracle for whatever Sighting last raised this Series
+	// (issue #103), and the judgement is free: the comparison below already
+	// exists, and no extra request is made to reach it.
+	p.judgeSighting(sr, facts.Latest.Num)
+
 	// Equality, not >, mirroring the userscript (L427): a site that retracts a
 	// chapter should correct the stored number downward. The comparison is
 	// against the due-query snapshot; a concurrent write in between only costs
@@ -481,6 +487,43 @@ func (p *Poller) checkOne(ctx context.Context, sr store.Series) error {
 	return nil
 }
 
+// judgeSighting settles the Sighting the Series' stored Latest Chapter is owed
+// to, if any, against what the Site actually publishes. The asymmetry is the
+// whole of the detection rule and is what keeps it free of false alarms: a Poll
+// finding a *lower* number than stored means the Reader who raised it reported
+// a chapter that does not exist, while a Poll finding a higher one is only the
+// Site publishing since and means nothing about the report. Equality confirms
+// the report, which is how an honest Reader earns back a mark.
+//
+// A Series with no attribution — the stored value is a Poll's own, or a
+// previous Poll already judged the report — is nobody's to answer for.
+func (p *Poller) judgeSighting(sr store.Series, found float64) {
+	if sr.LatestRaisedBy == nil || sr.LatestChapterNum == nil {
+		return
+	}
+	stored := *sr.LatestChapterNum
+	if found > stored {
+		// The report is neither confirmed nor contradicted, but it is answered:
+		// the value about to be stored is the Poll's own, so leaving the
+		// attribution would credit this Reader with the next Poll's agreement
+		// and blame them if the Site later retracts.
+		if err := p.Store.ClearSightingAttribution(sr.Site, sr.SeriesID, *sr.LatestRaisedBy); err != nil {
+			log.Printf("latest poll %q: clear sighting attribution: %v", sr.Key(), err)
+		}
+		return
+	}
+	if found < stored {
+		// Logged with both numbers and the Reader, because that is what tells a
+		// broken Site adapter (which marks every Reader of that Site at once)
+		// from one Reader deliberately lying.
+		log.Printf("latest poll %q: sighting contradicted: reader %d raised it to %v, site publishes %v",
+			sr.Key(), *sr.LatestRaisedBy, stored, found)
+	}
+	if err := p.Store.RecordSightingOutcome(sr.Site, sr.SeriesID, *sr.LatestRaisedBy, found == stored); err != nil {
+		log.Printf("latest poll %q: record sighting outcome: %v", sr.Key(), err)
+	}
+}
+
 // healCover runs prefetchCover in the background. Cover bytes come from a
 // different host — often a CDN — and heal once in a Series's life, so they
 // must not consume a Lane's gap: a large import with many blanks would