Spec #136: Finished belongs to the Series — owner-owned poll gate, Lifecycle bucket dropped (#163)

Closes #136.

Spec #136 end to end: `finished` becomes a fact about the Series, written only by the owner, and the reader-facing Lifecycle bucket is gone.

## What landed

- **#157** — `series.finished_at bigint NOT NULL DEFAULT 0` plus the migration whose statement order is load-bearing (seed from the buckets, then flip them); both Lane queries lose the `HAVING COUNT(*) FILTER (WHERE b.status <> 'finished')` clause and gate on `finished_at = 0` instead, with the due-query/eligible-count force asymmetry kept deliberate and commented; `StatusFinished`, its API special-case 400, the web tab and the templates' Finished bucket deleted.
- **#158** — owner Finish control on the Series detail page: confirm-gated finish, instant un-finish, admin accent (never ember, nothing is destroyed), `Store.SetSeriesFinished`, the two routes behind the owner gate, and the state displayed on the list row without offering the control there.
- **#160** — reader side: derived `finished` bool on the flat Bookmark (`s.finished_at > 0`), rendered as a text-only label in both userscripts and on the web card; read-only inbound by omission from `Upsert`'s explicit `series` column list, same mechanism that already protects `cover`.
- **#161** — glossary and the stale Reader-count divergence note catch up.
- **#159** — `finished` joins the admin filter vocabulary (predicate `finished_at > 0`, label `Finished`, own aggregate count, figure last in the stats block as informational); the four clock-driven hygiene predicates (stale, never-checked, no-cover, no-chapter) exclude finished Series while unpollable, orphan and sighting-raised deliberately do not.

## Verification

`go vet ./...` and `go test ./...` green on the merged branch (Docker-backed, throwaway `postgres:17-alpine` per package). Each ticket also passed a two-axis review (spec + standards) on its own branch before merge.

Reviewed-on: #163
Co-authored-by: Sulthan Zaki <sultankiki05@gmail.com>
Co-committed-by: Sulthan Zaki <sultankiki05@gmail.com>

backend/internal/store/admin_test.go

@@ -128,6 +128,85 @@ func TestAdminSeriesFilters(t *testing.T) {
 	}
 }
 
+// A finished Series is the owner's deliberate state, not a problem a Poll
+// will fix: the four clock-driven hygiene predicates exclude it (their
+// stamps stop advancing at the last Poll, so without the guard a retired row
+// is reported forever), the three outcome-driven ones still include it, and
+// the finished filter returns exactly the retired rows.
+func TestAdminFinishedSeriesFilters(t *testing.T) {
+	s := newTestStore(t)
+	// Each fin-* row is shaped to trip exactly one predicate if its guard
+	// fails: checked-but-old for stale, a zero stamp for never-checked, a
+	// stamp with no chapter for no-chapter, an empty cover for no-cover, and
+	// the unguarded three shaped to trip their own. A healthy, unfinished
+	// neighbour keeps the exclusion checks honest: a filter that regressed to
+	// matching nothing would pass a bare "no finished rows" assertion.
+	seedAdminSeries(t, s, seriesSeed{key: "asura:fin-stale", url: "u", cover: "c", checkedAt: 2000, latestNum: new(4.0), bookmarks: 1})
+	seedAdminSeries(t, s, seriesSeed{key: "asura:fin-neverchecked", url: "u", cover: "c", checkedAt: 0, latestNum: new(4.0), bookmarks: 1})
+	seedAdminSeries(t, s, seriesSeed{key: "asura:fin-nochapter", url: "u", cover: "c", checkedAt: 9000, bookmarks: 1})
+	seedAdminSeries(t, s, seriesSeed{key: "asura:fin-nocover", url: "u", checkedAt: 9000, latestNum: new(4.0), bookmarks: 1})
+	seedAdminSeries(t, s, seriesSeed{key: "asura:fin-nourl", url: "", cover: "c", checkedAt: 9000, latestNum: new(4.0), bookmarks: 1})
+	seedAdminSeries(t, s, seriesSeed{key: "asura:fin-orphan", url: "u", cover: "c", checkedAt: 9000, latestNum: new(4.0), bookmarks: 0})
+	seedAdminSeries(t, s, seriesSeed{key: "asura:fin-report", url: "u", cover: "c", checkedAt: 9000, latestNum: new(4.0), bookmarks: 1, raisedBy: true})
+	seedAdminSeries(t, s, seriesSeed{key: "asura:healthy", url: "u", cover: "c", checkedAt: 9000, latestNum: new(4.0), bookmarks: 1})
+	finished := []string{
+		"asura:fin-stale", "asura:fin-neverchecked", "asura:fin-nochapter",
+		"asura:fin-nocover", "asura:fin-nourl", "asura:fin-orphan", "asura:fin-report",
+	}
+	for _, key := range finished {
+		site, id, _ := strings.Cut(key, ":")
+		if err := s.SetSeriesFinished(site, id, 1000); err != nil {
+			t.Fatalf("finish %s: %v", key, err)
+		}
+	}
+
+	cases := []struct {
+		name string
+		f    SeriesFilter
+		want []string
+	}{
+		{"stale excludes finished", SeriesFilter{Name: SeriesFilterStale, Cutoff: 5000}, nil},
+		{"never checked excludes finished", SeriesFilter{Name: SeriesFilterNeverChecked}, nil},
+		{"no chapter excludes finished", SeriesFilter{Name: SeriesFilterNoChapter}, nil},
+		{"no cover excludes finished", SeriesFilter{Name: SeriesFilterNoCover}, nil},
+		{"no url includes finished", SeriesFilter{Name: SeriesFilterNoURL}, []string{"asura:fin-nourl"}},
+		{"no readers includes finished", SeriesFilter{Name: SeriesFilterNoReaders}, []string{"asura:fin-orphan"}},
+		{"reader report includes finished", SeriesFilter{Name: SeriesFilterReaderReport}, []string{"asura:fin-report"}},
+		{"finished returns the retired rows", SeriesFilter{Name: SeriesFilterFinished}, finished},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := pageKeys(t, s, tc.f)
+			want := map[string]bool{}
+			for _, k := range tc.want {
+				want[k] = true
+			}
+			if len(got) != len(want) {
+				t.Fatalf("%+v returned %v, want exactly %v", tc.f, got, want)
+			}
+			for k := range want {
+				if !got[k] {
+					t.Fatalf("%+v dropped %q (got %v)", tc.f, k, got)
+				}
+			}
+		})
+	}
+
+	// The aggregate's finished total counts every retired row — the same
+	// predicate the Overview's finished figure is summed from.
+	shapes, err := s.SeriesShapes(SeriesFilter{Name: SeriesFilterFinished})
+	if err != nil {
+		t.Fatalf("SeriesShapes(finished): %v", err)
+	}
+	sum := 0
+	for _, sh := range shapes {
+		sum += sh.Total
+	}
+	if sum != len(finished) {
+		t.Fatalf("finished aggregate = %d, want %d", sum, len(finished))
+	}
+}
+
 // "Never read a chapter" and "never checked" are disjoint by construction:
 // the first requires a non-zero check stamp, the second a zero one. Over a
 // mix that should satisfy both, no row may be counted twice.
@@ -394,3 +473,57 @@ func TestAdminSeriesCarriesForcePollAt(t *testing.T) {
 		t.Fatalf("row = %+v, want ForcePollAt 5000", page.Rows)
 	}
 }
+
+// SetSeriesFinished is the owner's finish stamp write: finishing writes the
+// given ms, un-finishing writes zero — the one undo, the same shape as the
+// correction stamp. Touching a missing series is not an error: the row may
+// have been orphaned, and the caller's read decides what exists.
+func TestSetSeriesFinishedStampsAndClears(t *testing.T) {
+	s := newTestStore(t)
+	seedAdminSeries(t, s, seriesSeed{key: "asura:x", url: "u", checkedAt: 9000, bookmarks: 1})
+
+	if err := s.SetSeriesFinished("asura", "x", 42); err != nil {
+		t.Fatalf("SetSeriesFinished: %v", err)
+	}
+	var got int64
+	if err := s.db.QueryRow(
+		`SELECT finished_at FROM series WHERE site = 'asura' AND series_id = 'x'`).Scan(&got); err != nil {
+		t.Fatalf("read finished_at: %v", err)
+	}
+	if got != 42 {
+		t.Fatalf("finished_at = %d, want 42", got)
+	}
+
+	if err := s.SetSeriesFinished("asura", "x", 0); err != nil {
+		t.Fatalf("SetSeriesFinished un-finish: %v", err)
+	}
+	if err := s.db.QueryRow(
+		`SELECT finished_at FROM series WHERE site = 'asura' AND series_id = 'x'`).Scan(&got); err != nil {
+		t.Fatalf("read finished_at after un-finish: %v", err)
+	}
+	if got != 0 {
+		t.Fatalf("finished_at = %d, want 0 (un-finish writes zero)", got)
+	}
+
+	if err := s.SetSeriesFinished("asura", "ghost", 42); err != nil {
+		t.Fatalf("SetSeriesFinished missing: %v", err)
+	}
+}
+
+// The admin projection carries the finish stamp so the web layer can render
+// the finished state without a second read.
+func TestAdminSeriesCarriesFinishedAt(t *testing.T) {
+	s := newTestStore(t)
+	seedAdminSeries(t, s, seriesSeed{key: "asura:x", url: "u", checkedAt: 1000, bookmarks: 1})
+	if err := s.SetSeriesFinished("asura", "x", 5000); err != nil {
+		t.Fatalf("SetSeriesFinished: %v", err)
+	}
+
+	page, err := s.SeriesPage(SeriesFilter{})
+	if err != nil {
+		t.Fatalf("SeriesPage: %v", err)
+	}
+	if len(page.Rows) != 1 || page.Rows[0].FinishedAt != 5000 {
+		t.Fatalf("row = %+v, want FinishedAt 5000", page.Rows)
+	}
+}