Add finished Series filter; clock-driven hygiene predicates exclude it (#159)

backend/internal/store/admin.go

@@ -7,11 +7,13 @@ import (
 	"strings"
 )
 
-// Series filter names (issue #140), ordered permanent-then-fixable — the
-// repairs nothing will ever undo first, the ones a Poll can make right after.
-// A name is the repair a row needs, not the SQL that finds it; the values are
-// the wire form the Series list URL carries (#142). "all" is the absent and
-// unknown case: every Series.
+// Series filter names (issue #140): the eight hygiene names are ordered
+// permanent-then-fixable — the repairs nothing will ever undo first, the
+// ones a Poll can make right after. SeriesFilterFinished is not part of
+// that ordering: a finished Series is a deliberate state, not a repair, so
+// it sits last, informational. A name is the repair a row needs, not the
+// SQL that finds it; the values are the wire form the Series list URL
+// carries (#142). "all" is the absent and unknown case: every Series.
 const (
 	SeriesFilterAll          = "all"
 	SeriesFilterNoURL        = "no_series_url"
@@ -21,6 +23,7 @@ const (
 	SeriesFilterStale        = "stale"
 	SeriesFilterNoCover      = "no_cover"
 	SeriesFilterReaderReport = "reader_report"
+	SeriesFilterFinished     = "finished"
 )
 
 // SeriesFilter is one named hygiene predicate over the whole library. Site
@@ -115,10 +118,19 @@ func (a AdminSeries) Key() string { return a.Site + ":" + a.SeriesID }
 // The WHERE set is: no URL (an empty URL only — the host-failing-the-fetch-
 // gate case is invisible to SQL, needs the Site registry in Go, and belongs to
 // a later repair), never-read-a-chapter and never-checked as disjoint halves
-// (non-zero versus zero check stamp), stale, no cover, and Reader-report.
+// (non-zero versus zero check stamp), stale, no cover, finished (the
+// retirement stamp, read directly), and Reader-report.
 // no_readers is the one HAVING predicate: it is the orphan test, an aggregate
 // over the LEFT JOIN, where a bare WHERE has no row to test.
 //
+// The clock-versus-outcome split decides which predicates exclude finished
+// Series (`s.finished_at = 0` in each of the four): the clock-driven one —
+// never-checked, stale, no-chapter, no-cover — keep ticking after the last
+// Poll, so they would report a retired row as a problem no Poll is coming to
+// fix; the three outcome-driven ones — no-URL, no-readers, Reader-report —
+// read stored facts that simply stop arriving, so a finished Series needing a
+// genuine repair still shows up under them.
+//
 // stale is the checked-but-old half of the stamp partition — because the
 // verdict line wants "not checked in twelve hours" as one figure, and a never
 // checked Series is already counted on its own "waiting"/never-checked
@@ -135,16 +147,18 @@ func adminFilter(f SeriesFilter) (where, having string, args []any, err error) {
 	case SeriesFilterNoURL:
 		clauses = append(clauses, `s.series_url = ''`)
 	case SeriesFilterNoChapter:
-		clauses = append(clauses, `s.latest_checked_at <> 0 AND s.latest_chapter_num IS NULL`)
+		clauses = append(clauses, `s.latest_checked_at <> 0 AND s.latest_chapter_num IS NULL AND s.finished_at = 0`)
 	case SeriesFilterNeverChecked:
-		clauses = append(clauses, `s.latest_checked_at = 0`)
+		clauses = append(clauses, `s.latest_checked_at = 0 AND s.finished_at = 0`)
 	case SeriesFilterStale:
-		clauses = append(clauses, `s.latest_checked_at > 0 AND s.latest_checked_at < $`+strconv.Itoa(len(args)+1))
+		clauses = append(clauses, `s.latest_checked_at > 0 AND s.latest_checked_at < $`+strconv.Itoa(len(args)+1)+` AND s.finished_at = 0`)
 		args = append(args, f.Cutoff)
 	case SeriesFilterNoCover:
-		clauses = append(clauses, `s.cover_address = ''`)
+		clauses = append(clauses, `s.cover_address = '' AND s.finished_at = 0`)
 	case SeriesFilterReaderReport:
 		clauses = append(clauses, `s.latest_raised_by IS NOT NULL`)
+	case SeriesFilterFinished:
+		clauses = append(clauses, `s.finished_at > 0`)
 	case SeriesFilterNoReaders:
 		having = `HAVING COUNT(b.reader_id) = 0`
 	default: