mangaBookmark/docs/adr/0011-sighting-deferral-trust-model.md

ADR-0011: Sightings — a Reader report defers a Poll where being wrong hurts only them

Date: 2026-08-16 Status: accepted

Decision

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

• Solitary Series only. A Sighting defers the Poll of a Series exactly one Bookmark points at. A Series two Readers share is Polled on schedule no matter how recently it was sighted.
• One rest of standing. A Sighting postpones Polls for one Rest (defaultRest, an hour), not forever: a Series nobody visits again returns to the normal schedule by itself.
• Six-hour ceiling. sightingCeiling = 6 * defaultRest. However many Sightings arrive, a Series unpolled for six hours is Polled.

Both live in the due query's HAVING clause (store.DueForLatestCheck), beside the Rest cutoff — the same place the schedule has always been decided, so no timer and no second code path can disagree with it.

Attribution and judgement:

• Store.RecordSighting runs before the Upsert that stores the reported value, because the raise test needs the row as it stands. A report that raises the stored Latest Chapter names its Reader in series.latest_raised_by.
• The Poll is the oracle. Poller.checkOne already compares what the Site publishes against what is stored, so judgement costs no extra request: a lower number contradicts the Sighting (sighting_disagreements + 1, both numbers and the Reader logged), the same number confirms it (sighting_agreements + 1), a higher number is the Site publishing and means nothing either way.
• At SightingDisagreementLimit (3) that Reader's Sightings stop deferring anything. They still write the Latest Chapter — the penalty removes a privilege, it does not silence anyone.
• SightingAgreementsToClear (20) consecutive confirmations forgive the disagreements. A disagreement resets the run to zero.
• The owner clears marks from the administration page (issue #102, shipped first precisely so a false mark has a remedy the day the mechanism lands).

Why

Most of the backend's work was redundant. The userscript reads the Latest Chapter on every Series page visit and PUTs it; minutes later the Poll Lane fetches the same page for the same number. Deferring on a report converts a visit into a Poll saved, which is Lane capacity handed back to Series nobody is reading.

The restriction is the whole safety argument, and it is about blast radius, not about trust arithmetic:

• On a solitary Series, a wrong report can only mislead the Reader who made it. There is nobody else's ember to falsify.
• On a shared Series it could mislead someone else, so a report never postpones anything there.

The ceiling bounds the damage in time: a false value dies within six hours whatever happens, because the Poll that finds it is guaranteed. That is also what makes lying pointless — the six-hour audit is certain, not sampled, so a determined attacker buys at most three ceilings' worth of a wrong number on their own Series and then loses deferral entirely.

The cost of recovery is deliberate. An agreement is only recorded when a later Poll confirms a Sighting, so twenty agreements are twenty Polls of Series that Reader bookmarks — hours to days of real time, not twenty page views. Waiting is therefore not a strategy, and credit cannot be banked in advance.

Tradeoffs and rejections

• Trusting a Sighting on a shared Series rejected: it is the only case where one Reader's mistake reaches another Reader's list, and no amount of reputation makes that recoverable within the six-hour window.
• Cross-Reader agreement, voting, weighting, consensus scoring rejected: a single-source report cannot have its confidence evaluated by comparison, and with the typical two Readers a disagreement identifies nothing. The Poll is the only oracle in the system, so it is the only judge.
• A randomised audit (Poll a fraction of deferred Series) rejected in favour of the fixed ceiling: a sampled audit makes the attacker's expected cost a probability, while a ceiling makes it a certainty, and a certainty is what makes the solitary-Series rule defensible in one sentence.
• Blocking a marked Reader's writes rejected: the Latest Chapter they report is still the best available value, and their Sightings must keep being judged or they could never earn the privilege back.
• Per-Series flagging rejected in favour of per-Reader marks: a Series is not the thing that can be wrong. Naming the Reader and logging both numbers is also what distinguishes a broken Site adapter (every Reader of that Site contradicted at once) from one bad actor.
• Timers or a background reputation job rejected: deferral is decided from live facts every round — Bookmark count, sighting timestamp, the Reader's marks — so a Series that gains a second Bookmark stops deferring at once, with nothing to invalidate.

Constraints preserved

• A Sighting is not Progress: it may move the Latest Chapter and nothing else. updated_at never moves, so a report cannot reorder the list (ADR-0004).
• The Latest Chapter is a Series-level fact (ADR-0003): a Sighting writes the shared row, so every Reader of a shared Series sees it immediately — deferral is the only thing the solitary rule withholds.
• Ember means new chapter only (docs/design-system.md): a marked Reader renders no differently in their own list, and nothing about the trust model reaches the Series list's colour.
• The Poll remains authoritative. Where a Sighting and a Poll disagree, the Poll's value is what gets stored.