Spec #135: owner data-correction actions — Latest Chapter, series_url, Cover, orphan removal (#156)

Implements spec #135 (spec 2 of 4, derived from wayfinder map #114; decisions settled in #120/#121/#125/#131). Blocked-by #134 is merged, so this lands on `main`.

Four owner actions the dashboard can now perform, one ticket each:

- **#149** — Latest Chapter correction: one numeric input, overwritten by the next machine write.
- **#151** — Series URL repair: owner-typed, gated by the poller's own fetch gate.
- **#150 / #153 / #154** — Cover replacement: addresses derived from bytes (`#150`), a Forced Poll replaces the Cover while an ordinary pass still only fills a blank one (`#153`), and byte reclamation is one guarded helper, file first / covers row last (`#154`).
- **#155** — Orphan removal: one Series at a time, with the foreign key as the guard.

Plus **#152** — Latest Chapter provenance: one derived line naming the actor class, so an owner can tell a hand-edited number from a machine read.

- Migration `0015_latest_correction.sql` adds the correction/provenance columns; `0009` now derives cover addresses from bytes.
- ADR `0014-cover-addresses-from-bytes.md` records the address scheme.

Backend tests cover the store, poller, admin handlers, and web routes (`go test ./...`, needs Docker).

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

backend/internal/latest/acquire_test.go

@@ -123,10 +123,10 @@ func TestAcquireFillsChapterAndCoverFromOneFetch(t *testing.T) {
 	if got.LatestChapterNum == nil || *got.LatestChapterNum != 181 {
 		t.Fatalf("LatestChapterNum = %v, want 181", got.LatestChapterNum)
 	}
-	if want := testCoverBaseURL + "/covers/" + store.CoverAddress(acquireCoverURL); got.Cover != want {
+	if want := testCoverBaseURL + "/covers/" + store.CoverAddressForBytes([]byte("cover-bytes")); got.Cover != want {
 		t.Fatalf("Cover = %q, want the absolute address %q", got.Cover, want)
 	}
-	body, contentType, ok, err := s.CoverByAddress(store.CoverAddress(acquireCoverURL))
+	body, contentType, ok, err := s.CoverByAddress(store.CoverAddressForBytes([]byte("cover-bytes")))
 	if err != nil || !ok {
 		t.Fatalf("CoverByAddress = %v, %v", ok, err)
 	}
@@ -182,7 +182,7 @@ func TestAcquireSkipsAnExistingSeries(t *testing.T) {
 		t.Fatalf("cover fetches = %d, want 1", got)
 	}
 	got := readBookmark(t, s, acquireKey)
-	if want := testCoverBaseURL + "/covers/" + store.CoverAddress(acquireCoverURL); got.Cover != want {
+	if want := testCoverBaseURL + "/covers/" + store.CoverAddressForBytes([]byte("cover-bytes")); got.Cover != want {
 		t.Fatalf("Cover = %q, want the acquired one %q", got.Cover, want)
 	}
 }
@@ -343,10 +343,10 @@ func TestAcquireKaganeCoverThroughBrowser(t *testing.T) {
 		t.Fatalf("browser cover fetched URL %q, want %q", got, kaganeCoverSrc)
 	}
 	got := readBookmark(t, s, kaganeKey)
-	if want := testCoverBaseURL + "/covers/" + store.CoverAddress(kaganeCoverSrc); got.Cover != want {
+	if want := testCoverBaseURL + "/covers/" + store.CoverAddressForBytes([]byte("cover-bytes")); got.Cover != want {
 		t.Fatalf("Cover = %q, want the content-addressed URL %q", got.Cover, want)
 	}
-	body, contentType, ok, err := s.CoverByAddress(store.CoverAddress(kaganeCoverSrc))
+	body, contentType, ok, err := s.CoverByAddress(store.CoverAddressForBytes([]byte("cover-bytes")))
 	if err != nil || !ok {
 		t.Fatalf("CoverByAddress = %v, %v", ok, err)
 	}
@@ -381,7 +381,7 @@ func TestAcquireNovelfullCoverOverPlainTLS(t *testing.T) {
 		t.Fatalf("cover fetched from %q, want %q", got, novelfullCoverURL)
 	}
 	got := readBookmark(t, s, novelfullKey)
-	if want := testCoverBaseURL + "/covers/" + store.CoverAddress(novelfullCoverURL); got.Cover != want {
+	if want := testCoverBaseURL + "/covers/" + store.CoverAddressForBytes([]byte("cover-bytes")); got.Cover != want {
 		t.Fatalf("Cover = %q, want %q", got.Cover, want)
 	}
 }
@@ -451,7 +451,7 @@ func TestAcquireNovelfullCoverWithoutBrowser(t *testing.T) {
 		t.Fatalf("cover fetches = %d, want 1", got)
 	}
 	got := readBookmark(t, s, novelfullKey)
-	if want := testCoverBaseURL + "/covers/" + store.CoverAddress(novelfullCoverURL); got.Cover != want {
+	if want := testCoverBaseURL + "/covers/" + store.CoverAddressForBytes([]byte("cover-bytes")); got.Cover != want {
 		t.Fatalf("Cover = %q, want %q", got.Cover, want)
 	}
 }

backend/internal/latest/browser.go

@@ -124,7 +124,7 @@ func (f *BrowserFetcher) Get(ctx context.Context, seriesURL string) (string, int
 // request must be made from inside the page so it carries the clearance
 // cookie, and the API is the only place the list exists. Refusing any other
 // address is the per-Site half of the SSRF gate, kept deliberately behind
-// fetchableSeriesURL (see browserRead.Read).
+// FetchableSeriesURL (see browserRead.Read).
 func kaganeRead(seriesURL string, out *string) (chromedp.Action, bool) {
 	apiURL, ok := kaganeAPIURL(seriesURL)
 	if !ok {
@@ -326,7 +326,7 @@ func (f *BrowserFetcher) run(ctx context.Context, target string, read chromedp.A
 
 // kaganeAPIURL maps a stored series_url to the JSON endpoint carrying its
 // chapter list. Returning false for anything else is a second line of defence
-// behind fetchableSeriesURL: a headless browser is a strong SSRF primitive and
+// behind FetchableSeriesURL: a headless browser is a strong SSRF primitive and
 // series_url is client-supplied, so the host is pinned here too.
 func kaganeAPIURL(seriesURL string) (string, bool) {
 	u, err := url.Parse(seriesURL)

backend/internal/latest/cover.go

@@ -174,7 +174,7 @@ func (f *TLSCoverFetcher) Fetch(ctx context.Context, sourceURL string) ([]byte,
 	return body, contentType, nil
 }
 
-// This gate deliberately differs from fetchableSeriesURL: cover hosts are
+// This gate deliberately differs from FetchableSeriesURL: cover hosts are
 // site-independent CDNs, so a Site host allowlist would reject valid covers.
 func (f *TLSCoverFetcher) validateURL(ctx context.Context, u *url.URL) error {
 	if u == nil || u.Scheme != "https" || u.Host == "" || u.User != nil {

backend/internal/latest/poller.go

@@ -98,6 +98,23 @@ func (p *Poller) fillBlankCover(ctx context.Context, sr store.Series, cover stri
 	}()
 }
 
+// replaceCover is the Forced Poll's Cover path: the owner asked to accept the
+// page as it now stands, so where fillBlankCover leaves a non-blank Cover
+// alone (ADR-0007) this writes through whatever the page's Cover URL answers
+// with, whether one exists or not. The accepted consequence (issue #135):
+// refreshing the Cover and re-reading the chapters are one act — there is no
+// Cover-only refetch.
+func (p *Poller) replaceCover(ctx context.Context, sr store.Series, cover string) {
+	if cover == "" {
+		return
+	}
+	p.coverWG.Add(1)
+	go func() {
+		defer p.coverWG.Done()
+		p.storeCover(ctx, sr, cover)
+	}()
+}
+
 // prefetchCover heals Series that already carry a third-party source URL but
 // no stored address — the state left by client-supplied covers before
 // acquisition moved server-side. Every Site takes the same path; fetchCoverBytes
@@ -122,17 +139,42 @@ func (p *Poller) prefetchCover(ctx context.Context, sr store.Series) {
 	p.storeCover(ctx, sr, sr.Cover)
 }
 
-// storeCover fetches bytes for sourceURL and points the Series at them. Every
-// failure is logged against the Series and swallowed so the chapter poll
-// cannot see it.
+// storeCover fetches bytes for sourceURL and points the Series at them: a
+// fill-only write for an ordinary pass, a write-through for a forced one
+// (issue #135). Every failure is logged against the Series and swallowed so
+// the chapter poll cannot see it.
 func (p *Poller) storeCover(ctx context.Context, sr store.Series, sourceURL string) {
 	bytes, contentType, err := fetchCoverBytes(ctx, sourceURL, p.CoverFetch, p.CoverBytesFetch)
 	if err != nil {
 		log.Printf("latest poll %q: fetch cover %s: %v", sr.Key(), sourceURL, err)
 		return
 	}
-	if err := p.Store.SetSeriesCover(sr.Site, sr.SeriesID, sourceURL, bytes, contentType); err != nil {
+	if !sr.Forced {
+		if err := p.Store.SetSeriesCover(sr.Site, sr.SeriesID, sourceURL, bytes, contentType); err != nil {
+			log.Printf("latest poll %q: persist cover: %v", sr.Key(), err)
+		}
+		return
+	}
+	// The forced write replaces whether or not a Cover exists, and the row
+	// then tells the three outcomes apart: a blank filled, identical artwork
+	// re-served — an honest no-op — or a replacement whose previous address
+	// is stranded and reclaimed below. A failed reclaim is logged and the
+	// stranded bytes stay served until a later call reclaims them.
+	previous, current, err := p.Store.ReplaceSeriesCover(sr.Site, sr.SeriesID, sourceURL, bytes, contentType)
+	if err != nil {
 		log.Printf("latest poll %q: persist cover: %v", sr.Key(), err)
+		return
+	}
+	switch {
+	case previous == "":
+		log.Printf("latest poll %q: cover filled at %s", sr.Key(), current)
+	case previous == current:
+		log.Printf("latest poll %q: cover unchanged, the site re-serves the same bytes", sr.Key())
+	default:
+		if err := p.Store.ReclaimCover(previous); err != nil {
+			log.Printf("latest poll %q: reclaim cover %s: %v", sr.Key(), previous, err)
+		}
+		log.Printf("latest poll %q: cover replaced %s -> %s", sr.Key(), previous, current)
 	}
 }
 
@@ -621,7 +663,12 @@ func (p *Poller) checkOne(ctx context.Context, sr store.Series) (outcome readOut
 	p.healCover(ctx, sr)
 	// Cover fill is independent of the chapter signal: a page that lost its
 	// chapter list may keep its og:image, and a blank Series heals either way.
-	p.fillBlankCover(ctx, sr, facts.Cover)
+	// A forced pass writes the Cover through the replace path instead.
+	if sr.Forced {
+		p.replaceCover(ctx, sr, facts.Cover)
+	} else {
+		p.fillBlankCover(ctx, sr, facts.Cover)
+	}
 	if !facts.HasLatest {
 		// Most likely a challenge page or a layout change. Either way the row is
 		// already stamped, so this waits out a rest instead of hot-looping.
@@ -710,7 +757,7 @@ func (p *Poller) waitCovers() {
 	p.coverWG.Wait()
 }
 
-// fetchableSeriesURL reports whether site is a Site the registry knows and
+// FetchableSeriesURL reports whether site is a Site the registry knows and
 // seriesURL is safe to hand to a fetcher: an https URL whose host matches the
 // Site's pinned hostname exactly. series_url comes from client-supplied PUT
 // bodies, so this is a defence against the poller being used to probe
@@ -719,7 +766,11 @@ func (p *Poller) waitCovers() {
 // browser Site guards a control that executes JavaScript and carries cookies,
 // a parser Site guards a wasted request — but the rule is one rule, from the
 // registry.
-func fetchableSeriesURL(site, seriesURL string) bool {
+//
+// The owner's series URL repair (issue #151) is a second caller: the web
+// layer validates with this same gate before storing a repair, so there is
+// never a second copy of it.
+func FetchableSeriesURL(site, seriesURL string) bool {
 	s, known := sites[site]
 	if !known {
 		return false

backend/internal/latest/poller_test.go

@@ -6,8 +6,10 @@ import (
 	"database/sql"
 	"errors"
 	"fmt"
+	"io/fs"
 	"log"
 	"os"
+	"path/filepath"
 	"strings"
 	"sync"
 	"testing"
@@ -214,9 +216,9 @@ func TestRunOncePrefetchesPublicCover(t *testing.T) {
 	if got := covers.callCount(); got != 1 {
 		t.Fatalf("cover fetch calls = %d, want 1", got)
 	}
-	body, contentType, found, err := s.GetCover(coverURL)
+	body, contentType, found, err := s.CoverByAddress(store.CoverAddressForBytes([]byte("cover-bytes")))
 	if err != nil || !found {
-		t.Fatalf("GetCover: %v found=%v", err, found)
+		t.Fatalf("CoverByAddress: %v found=%v", err, found)
 	}
 	if string(body) != "cover-bytes" || contentType != "image/jpeg" {
 		t.Fatalf("stored cover = (%q, %q), want (cover-bytes, image/jpeg)", body, contentType)
@@ -588,8 +590,8 @@ func TestFetchableSeriesURL(t *testing.T) {
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			if got := fetchableSeriesURL(tt.site, tt.seriesURL); got != tt.want {
-				t.Errorf("fetchableSeriesURL(%q, %q) = %v, want %v",
+			if got := FetchableSeriesURL(tt.site, tt.seriesURL); got != tt.want {
+				t.Errorf("FetchableSeriesURL(%q, %q) = %v, want %v",
 					tt.site, tt.seriesURL, got, tt.want)
 			}
 		})
@@ -663,7 +665,7 @@ func TestNovelfullUsesTLSWhenNoBrowserFetcher(t *testing.T) {
 	if err != nil || !found {
 		t.Fatalf("Get: %v found=%v", err, found)
 	}
-	if want := testCoverBaseURL + "/covers/" + store.CoverAddress(novelfullCoverURL); got.Cover != want {
+	if want := testCoverBaseURL + "/covers/" + store.CoverAddressForBytes([]byte("cover-bytes")); got.Cover != want {
 		t.Fatalf("Cover = %q, want %q", got.Cover, want)
 	}
 	if got.LatestChapterNum == nil || *got.LatestChapterNum != 2334 {
@@ -811,7 +813,7 @@ func TestRunOncePrefetchesKaganeCover(t *testing.T) {
 	p.runOnce(context.Background())
 	p.waitCovers()
 
-	body, contentType, ok, err := s.CoverByAddress(store.CoverAddress(coverURL))
+	body, contentType, ok, err := s.CoverByAddress(store.CoverAddressForBytes([]byte("cover-bytes")))
 	if err != nil || !ok {
 		t.Fatalf("CoverByAddress: %v found=%v", err, ok)
 	}
@@ -821,7 +823,7 @@ func TestRunOncePrefetchesKaganeCover(t *testing.T) {
 	if got := covers.callCount(); got != 1 {
 		t.Fatalf("cover fetch calls = %d, want 1", got)
 	}
-	if got := readBookmark(t, s, key); got.Cover != testCoverBaseURL+"/covers/"+store.CoverAddress(coverURL) {
+	if got := readBookmark(t, s, key); got.Cover != testCoverBaseURL+"/covers/"+store.CoverAddressForBytes([]byte("cover-bytes")) {
 		t.Fatalf("wire Cover = %q, want content-addressed URL", got.Cover)
 	}
 }
@@ -914,7 +916,7 @@ func TestRunOnceRejectsInvalidKaganeCover(t *testing.T) {
 	p.runOnce(context.Background())
 	p.waitCovers()
 
-	if _, _, found, err := s.CoverByAddress(store.CoverAddress(coverURL)); err != nil || found {
+	if _, _, found, err := s.CoverByAddress(store.CoverAddressForBytes([]byte("not an image"))); err != nil || found {
 		t.Fatalf("invalid cover persisted = %v, err %v; want missing", found, err)
 	}
 }
@@ -940,7 +942,7 @@ func TestRunOnceWithoutCoverFetcherStillPollsKagane(t *testing.T) {
 	p.runOnce(context.Background())
 	p.waitCovers()
 
-	if _, _, found, err := s.CoverByAddress(store.CoverAddress(coverURL)); err != nil || found {
+	if _, _, found, err := s.CoverByAddress(store.CoverAddressForBytes([]byte("cover-bytes"))); err != nil || found {
 		t.Fatalf("cover after nil CoverFetch = found %v, err %v; want missing", found, err)
 	}
 }
@@ -1019,8 +1021,8 @@ func TestFetchableSeriesURLPinsNovelHosts(t *testing.T) {
 	}
 	for _, tc := range cases {
 		t.Run(tc.name, func(t *testing.T) {
-			if got := fetchableSeriesURL(tc.site, tc.url); got != tc.want {
-				t.Fatalf("fetchableSeriesURL(%q, %q) = %v, want %v", tc.site, tc.url, got, tc.want)
+			if got := FetchableSeriesURL(tc.site, tc.url); got != tc.want {
+				t.Fatalf("FetchableSeriesURL(%q, %q) = %v, want %v", tc.site, tc.url, got, tc.want)
 			}
 		})
 	}
@@ -1038,7 +1040,6 @@ func TestRunOnceFillsBlankCoverFromSeriesPage(t *testing.T) {
 		seriesURL string
 		kind      string
 		body      string
-		wantCover string
 		browser   bool
 	}{
 		{
@@ -1047,14 +1048,12 @@ func TestRunOnceFillsBlankCoverFromSeriesPage(t *testing.T) {
 			seriesID:  "chronicles-of-the-demon-faction-f886a8af",
 			seriesURL: "https://asurascans.com/comics/chronicles-of-the-demon-faction-f886a8af",
 			kind:      store.KindManga, body: asuraSeriesFixture + asuraCoverFixture,
-			wantCover: "https://cdn.asurascans.com/asura-images/covers/chronicles-of-the-demon-faction.d4dcb8.webp",
 		},
 		{
 			name: "lightnovelworld novel",
 			key:  "lightnovelworld:all-jobs-and-classes-i-just-wanted-one-skill-not-them-all", site: "lightnovelworld",
 			seriesID: "all-jobs-and-classes-i-just-wanted-one-skill-not-them-all", seriesURL: "https://lightnovelworld.net/novel/all-jobs-and-classes-i-just-wanted-one-skill-not-them-all/",
 			kind: store.KindNovel, body: lnwSeriesFixture + lnwCoverFixture,
-			wantCover: "https://i1.wp.com/lightnovelworld.net/wp-content/uploads/2025/10/all-jobs-and-classes-i-just-wanted-one-skill-not-them-all.jpg",
 		},
 		{
 			name: "kagane manga",
@@ -1062,7 +1061,6 @@ func TestRunOnceFillsBlankCoverFromSeriesPage(t *testing.T) {
 			seriesID:  "019fe11a-8670-7cf3-8343-0b02057d3787",
 			seriesURL: "https://kagane.to/series/019fe11a-8670-7cf3-8343-0b02057d3787",
 			kind:      store.KindManga, body: kaganeAPIFixtureWithCover, browser: true,
-			wantCover: "https://kagane.to/api/v2/image/019fe11a-84c3-7fc3-a84b-88787374b617/compressed",
 		},
 	}
 	for _, tc := range cases {
@@ -1086,7 +1084,7 @@ func TestRunOnceFillsBlankCoverFromSeriesPage(t *testing.T) {
 			p.waitCovers()
 
 			got := readBookmark(t, s, tc.key)
-			wantWire := testCoverBaseURL + "/covers/" + store.CoverAddress(tc.wantCover)
+			wantWire := testCoverBaseURL + "/covers/" + store.CoverAddressForBytes([]byte("cover-bytes"))
 			if got.Cover != wantWire {
 				t.Fatalf("Cover = %q, want %q", got.Cover, wantWire)
 			}
@@ -1143,7 +1141,7 @@ func TestRunOnceDoesNotReplaceExistingCover(t *testing.T) {
 		t.Fatalf("cover fetch calls = %d, want 0", got)
 	}
 	got := readBookmark(t, s, key)
-	if want := testCoverBaseURL + "/covers/" + store.CoverAddress(first); got.Cover != want {
+	if want := testCoverBaseURL + "/covers/" + store.CoverAddressForBytes([]byte("first")); got.Cover != want {
 		t.Fatalf("Cover = %q, want the first one %q", got.Cover, want)
 	}
 }
@@ -1190,7 +1188,7 @@ func TestRunOnceRetriesFailedBlankCoverOnNextPoll(t *testing.T) {
 		t.Fatalf("cover fetch calls after retry = %d, want 2", got)
 	}
 	got := readBookmark(t, s, key)
-	if want := testCoverBaseURL + "/covers/" + store.CoverAddress(coverURL); got.Cover != want {
+	if want := testCoverBaseURL + "/covers/" + store.CoverAddressForBytes([]byte("cover-bytes")); got.Cover != want {
 		t.Fatalf("Cover after retry = %q, want %q", got.Cover, want)
 	}
 }
@@ -2337,3 +2335,363 @@ func TestForcedSeriesWakesSleepingBrowser(t *testing.T) {
 		t.Fatalf("browser fetches with a forced series = %d, want 2 (the lane wakes)", got)
 	}
 }
+
+// A forced pass accepts the page as it now stands, so it writes the Cover
+// through the replace path; an ordinary pass still only fills a blank one
+// (issue #135).
+func TestRunOnceForcedPassReplacesExistingCover(t *testing.T) {
+	s, _ := newTestStore(t)
+	const (
+		key       = "asura:chronicles-of-the-demon-faction-f886a8af"
+		seriesID  = "chronicles-of-the-demon-faction-f886a8af"
+		seriesURL = "https://asurascans.com/comics/chronicles-of-the-demon-faction-f886a8af"
+		first     = "https://cdn.example/covers/first.jpg"
+	)
+	if _, err := s.Upsert(s.OwnerID(), store.Bookmark{
+		Key: key, Site: "asura", SeriesID: seriesID, SeriesURL: seriesURL, UpdatedAt: 1000,
+	}); err != nil {
+		t.Fatalf("seed: %v", err)
+	}
+	if err := s.SetSeriesCover("asura", seriesID, first, []byte("first"), "image/jpeg"); err != nil {
+		t.Fatalf("seed cover: %v", err)
+	}
+	at := time.UnixMilli(5_000_000)
+	public := &fakeBytesCoverFetcher{body: []byte("second"), contentType: "image/jpeg"}
+
+	t.Run("unforced pass leaves the cover alone", func(t *testing.T) {
+		p := &Poller{
+			Store: s, Fetch: &fakeFetcher{body: asuraSeriesFixture + asuraCoverFixture, status: 200},
+			CoverBytesFetch: public,
+			Now:             func() time.Time { return at },
+		}
+		p.runOnce(context.Background())
+		p.waitCovers()
+		if got := public.callCount(); got != 0 {
+			t.Fatalf("cover fetch calls = %d, want 0", got)
+		}
+		got := readBookmark(t, s, key)
+		if want := testCoverBaseURL + "/covers/" + store.CoverAddressForBytes([]byte("first")); got.Cover != want {
+			t.Fatalf("Cover = %q, want the first one %q", got.Cover, want)
+		}
+	})
+
+	t.Run("forced pass replaces the cover", func(t *testing.T) {
+		if err := s.ForceSeriesPoll("asura", seriesID, at.Add(time.Hour).UnixMilli()); err != nil {
+			t.Fatalf("ForceSeriesPoll: %v", err)
+		}
+		p := &Poller{
+			Store: s, Fetch: &fakeFetcher{body: asuraSeriesFixture + asuraCoverFixture, status: 200},
+			CoverBytesFetch: public,
+			Now:             func() time.Time { return at },
+		}
+		p.runOnce(context.Background())
+		p.waitCovers()
+		if got := public.callCount(); got != 1 {
+			t.Fatalf("cover fetch calls = %d, want 1", got)
+		}
+		got := readBookmark(t, s, key)
+		if want := testCoverBaseURL + "/covers/" + store.CoverAddressForBytes([]byte("second")); got.Cover != want {
+			t.Fatalf("Cover = %q, want the second one %q", got.Cover, want)
+		}
+		body, _, ok, err := s.CoverByAddress(store.CoverAddressForBytes([]byte("second")))
+		if err != nil || !ok {
+			t.Fatalf("CoverByAddress: %v found=%v", err, ok)
+		}
+		if string(body) != "second" {
+			t.Fatalf("stored cover = %q, want second", body)
+		}
+	})
+}
+
+// Identical artwork re-served is an honest no-op the caller can tell apart
+// from a replacement: the address comes from the bytes, so the row cannot
+// change in substance, and the replace call site reports the three outcomes
+// distinctly (issue #135).
+func TestRunOnceForcedPassIdenticalBytesLogsNoOp(t *testing.T) {
+	s, _ := newTestStore(t)
+	const (
+		key       = "asura:chronicles-of-the-demon-faction-f886a8af"
+		seriesID  = "chronicles-of-the-demon-faction-f886a8af"
+		seriesURL = "https://asurascans.com/comics/chronicles-of-the-demon-faction-f886a8af"
+		first     = "https://cdn.example/covers/first.jpg"
+	)
+	if _, err := s.Upsert(s.OwnerID(), store.Bookmark{
+		Key: key, Site: "asura", SeriesID: seriesID, SeriesURL: seriesURL, UpdatedAt: 1000,
+	}); err != nil {
+		t.Fatalf("seed: %v", err)
+	}
+	if err := s.SetSeriesCover("asura", seriesID, first, []byte("cover-bytes"), "image/jpeg"); err != nil {
+		t.Fatalf("seed cover: %v", err)
+	}
+	at := time.UnixMilli(5_000_000)
+	if err := s.ForceSeriesPoll("asura", seriesID, at.Add(time.Hour).UnixMilli()); err != nil {
+		t.Fatalf("ForceSeriesPoll: %v", err)
+	}
+	var logs strings.Builder
+	prev := log.Writer()
+	log.SetOutput(&logs)
+	t.Cleanup(func() { log.SetOutput(prev) })
+
+	p := &Poller{
+		Store: s, Fetch: &fakeFetcher{body: asuraSeriesFixture + asuraCoverFixture, status: 200},
+		CoverBytesFetch: &fakeBytesCoverFetcher{body: []byte("cover-bytes"), contentType: "image/jpeg"},
+		Now:             func() time.Time { return at },
+	}
+	p.runOnce(context.Background())
+	p.waitCovers()
+
+	got := readBookmark(t, s, key)
+	if want := testCoverBaseURL + "/covers/" + store.CoverAddressForBytes([]byte("cover-bytes")); got.Cover != want {
+		t.Fatalf("Cover = %q, want unchanged %q", got.Cover, want)
+	}
+	if body, _, ok, err := s.CoverByAddress(store.CoverAddressForBytes([]byte("cover-bytes"))); err != nil || !ok || string(body) != "cover-bytes" {
+		t.Fatalf("stored cover after no-op: found=%v err=%v", ok, err)
+	}
+	logged := logs.String()
+	if !strings.Contains(logged, "cover unchanged") {
+		t.Fatalf("no-op not reported as unchanged; log:\n%s", logged)
+	}
+	if strings.Contains(logged, "cover replaced") {
+		t.Fatalf("no-op reported as a replacement; log:\n%s", logged)
+	}
+}
+
+// A Series whose sharded Cover file was unlinked out from under it is
+// repaired by one forced pass: same bytes mean the same address and the file
+// re-linked (issue #135, story 32).
+func TestRunOnceForcedPassRelinksUnlinkedCoverFile(t *testing.T) {
+	coverDir := t.TempDir()
+	url := pgtest.URL(t)
+	s, err := store.Open(url, testOwner, coverDir, testCoverBaseURL)
+	if err != nil {
+		t.Fatalf("Open: %v", err)
+	}
+	t.Cleanup(func() { s.Close() })
+	const (
+		key       = "asura:chronicles-of-the-demon-faction-f886a8af"
+		seriesID  = "chronicles-of-the-demon-faction-f886a8af"
+		seriesURL = "https://asurascans.com/comics/chronicles-of-the-demon-faction-f886a8af"
+		first     = "https://cdn.example/covers/first.jpg"
+	)
+	if _, err := s.Upsert(s.OwnerID(), store.Bookmark{
+		Key: key, Site: "asura", SeriesID: seriesID, SeriesURL: seriesURL, UpdatedAt: 1000,
+	}); err != nil {
+		t.Fatalf("seed: %v", err)
+	}
+	if err := s.SetSeriesCover("asura", seriesID, first, []byte("cover-bytes"), "image/jpeg"); err != nil {
+		t.Fatalf("seed cover: %v", err)
+	}
+	address := store.CoverAddressForBytes([]byte("cover-bytes"))
+	coverPath := filepath.Join(coverDir, filepath.FromSlash(address[:2]+"/"+address[2:4]+"/"+address))
+	if err := os.Remove(coverPath); err != nil {
+		t.Fatalf("unlink cover file: %v", err)
+	}
+	if _, _, ok, err := s.CoverByAddress(address); err != nil || ok {
+		t.Fatalf("CoverByAddress after unlink = found %v err %v; want missing (file gone)", ok, err)
+	}
+
+	at := time.UnixMilli(5_000_000)
+	if err := s.ForceSeriesPoll("asura", seriesID, at.Add(time.Hour).UnixMilli()); err != nil {
+		t.Fatalf("ForceSeriesPoll: %v", err)
+	}
+	p := &Poller{
+		Store: s, Fetch: &fakeFetcher{body: asuraSeriesFixture + asuraCoverFixture, status: 200},
+		CoverBytesFetch: &fakeBytesCoverFetcher{body: []byte("cover-bytes"), contentType: "image/jpeg"},
+		Now:             func() time.Time { return at },
+	}
+	p.runOnce(context.Background())
+	p.waitCovers()
+
+	body, contentType, ok, err := s.CoverByAddress(address)
+	if err != nil || !ok {
+		t.Fatalf("CoverByAddress after forced pass: found=%v err=%v; want the file re-linked", ok, err)
+	}
+	if string(body) != "cover-bytes" || contentType != "image/jpeg" {
+		t.Fatalf("re-linked cover = (%q, %q), want (cover-bytes, image/jpeg)", body, contentType)
+	}
+}
+
+// A forced pass degrades exactly like an ordinary one when the cover sidecar
+// is unreachable: the fetch is skipped and logged, the chapter poll is
+// untouched, and the stored Cover is not moved (issue #135, story 6).
+func TestRunOnceForcedPassWithoutCoverFetcherStillPolls(t *testing.T) {
+	s, _ := newTestStore(t)
+	const (
+		key      = "kagane:019f84bc-9ba0-7ed9-86f5-8b905ec7c28b"
+		seriesID = "019f84bc-9ba0-7ed9-86f5-8b905ec7c28b"
+	)
+	if _, err := s.Upsert(s.OwnerID(), store.Bookmark{
+		Key: key, Site: "kagane", SeriesID: seriesID,
+		SeriesURL: "https://kagane.to/series/" + seriesID, UpdatedAt: 1000,
+	}); err != nil {
+		t.Fatalf("seed: %v", err)
+	}
+	if err := s.SetSeriesCover("kagane", seriesID, "https://kagane.to/api/v2/image/019f84bc-9ba0-7ed9-86f5-8b905ec7c28b/compressed", []byte("existing"), "image/webp"); err != nil {
+		t.Fatalf("seed cover: %v", err)
+	}
+	at := time.UnixMilli(5_000_000)
+	if err := s.ForceSeriesPoll("kagane", seriesID, at.Add(time.Hour).UnixMilli()); err != nil {
+		t.Fatalf("ForceSeriesPoll: %v", err)
+	}
+	var logs strings.Builder
+	prev := log.Writer()
+	log.SetOutput(&logs)
+	t.Cleanup(func() { log.SetOutput(prev) })
+
+	p := &Poller{
+		Store: s, BrowserFetch: &fakeFetcher{body: kaganeAPIFixtureWithCover, status: 200},
+		Now: func() time.Time { return at },
+	}
+	p.runOnce(context.Background())
+	p.waitCovers()
+
+	got := readBookmark(t, s, key)
+	if got.LatestChapterNum == nil || *got.LatestChapterNum != 41 {
+		t.Fatalf("LatestChapterNum = %v, want 41", got.LatestChapterNum)
+	}
+	if want := testCoverBaseURL + "/covers/" + store.CoverAddressForBytes([]byte("existing")); got.Cover != want {
+		t.Fatalf("Cover = %q, want the existing one %q untouched", got.Cover, want)
+	}
+	if checked := readLatestCheckedAt(t, s, key); checked != at.UnixMilli() {
+		t.Fatalf("latest_checked_at = %d, want %d", checked, at.UnixMilli())
+	}
+	if !strings.Contains(logs.String(), "fetch cover") {
+		t.Fatalf("missing skipped-cover log; log:\n%s", logs.String())
+	}
+}
+
+// A forced replacement strands the previous address, and the poller reclaims
+// it from the stranded branch: the old sharded file and covers row are both
+// gone once the pass lands while the new bytes read back (issue #154). The
+// identical-bytes no-op that follows reclaims nothing: previous == current
+// there, and a reclamation would delete the Cover the pass just wrote.
+func TestRunOnceForcedPassReclaimsSupersededCover(t *testing.T) {
+	coverDir := t.TempDir()
+	url := pgtest.URL(t)
+	s, err := store.Open(url, testOwner, coverDir, testCoverBaseURL)
+	if err != nil {
+		t.Fatalf("Open: %v", err)
+	}
+	t.Cleanup(func() { s.Close() })
+	const (
+		key       = "asura:chronicles-of-the-demon-faction-f886a8af"
+		seriesID  = "chronicles-of-the-demon-faction-f886a8af"
+		seriesURL = "https://asurascans.com/comics/chronicles-of-the-demon-faction-f886a8af"
+		first     = "https://cdn.example/covers/first.jpg"
+	)
+	if _, err := s.Upsert(s.OwnerID(), store.Bookmark{
+		Key: key, Site: "asura", SeriesID: seriesID, SeriesURL: seriesURL, UpdatedAt: 1000,
+	}); err != nil {
+		t.Fatalf("seed: %v", err)
+	}
+	if err := s.SetSeriesCover("asura", seriesID, first, []byte("first"), "image/jpeg"); err != nil {
+		t.Fatalf("seed cover: %v", err)
+	}
+	stale := store.CoverAddressForBytes([]byte("first"))
+	stalePath := filepath.Join(coverDir, filepath.FromSlash(stale[:2]+"/"+stale[2:4]+"/"+stale))
+
+	at := time.UnixMilli(5_000_000)
+	if err := s.ForceSeriesPoll("asura", seriesID, at.Add(time.Hour).UnixMilli()); err != nil {
+		t.Fatalf("ForceSeriesPoll: %v", err)
+	}
+	p := &Poller{
+		Store: s, Fetch: &fakeFetcher{body: asuraSeriesFixture + asuraCoverFixture, status: 200},
+		CoverBytesFetch: &fakeBytesCoverFetcher{body: []byte("second"), contentType: "image/jpeg"},
+		Now:             func() time.Time { return at },
+	}
+	p.runOnce(context.Background())
+	p.waitCovers()
+
+	// The stranded address is gone on disk and in SQL; the new one reads back.
+	if _, err := os.Stat(stalePath); !errors.Is(err, fs.ErrNotExist) {
+		t.Fatalf("stale sharded file after replacement = %v, want fs.ErrNotExist", err)
+	}
+	if _, _, ok, err := s.CoverByAddress(stale); err != nil || ok {
+		t.Fatalf("stale bytes after replacement = found %v err %v, want reclaimed", ok, err)
+	}
+	if body, _, ok, err := s.CoverByAddress(store.CoverAddressForBytes([]byte("second"))); err != nil || !ok || string(body) != "second" {
+		t.Fatalf("new bytes after replacement = found %v err %v, want served", ok, err)
+	}
+
+	// The identical-bytes pass is an honest no-op and reclaims nothing.
+	if err := s.ForceSeriesPoll("asura", seriesID, at.Add(2*time.Hour).UnixMilli()); err != nil {
+		t.Fatalf("ForceSeriesPoll: %v", err)
+	}
+	p.runOnce(context.Background())
+	p.waitCovers()
+	current := store.CoverAddressForBytes([]byte("second"))
+	currentPath := filepath.Join(coverDir, filepath.FromSlash(current[:2]+"/"+current[2:4]+"/"+current))
+	if _, err := os.Stat(currentPath); err != nil {
+		t.Fatalf("live sharded file after no-op pass = %v, want present", err)
+	}
+	if body, _, ok, err := s.CoverByAddress(current); err != nil || !ok || string(body) != "second" {
+		t.Fatalf("bytes after no-op pass = found %v err %v, want still served", ok, err)
+	}
+}
+
+// A reclamation that fails must not fail the Poll: the failure is logged
+// against the Series and the replacement still lands, so the stranded bytes
+// stay reachable for a retry and the owner's act succeeded (issue #154).
+func TestRunOnceForcedPassReclaimFailureDoesNotFailPoll(t *testing.T) {
+	coverDir := t.TempDir()
+	url := pgtest.URL(t)
+	s, err := store.Open(url, testOwner, coverDir, testCoverBaseURL)
+	if err != nil {
+		t.Fatalf("Open: %v", err)
+	}
+	t.Cleanup(func() { s.Close() })
+	const (
+		key       = "asura:chronicles-of-the-fallen-f886a8af"
+		seriesID  = "chronicles-of-the-fallen-f886a8af"
+		seriesURL = "https://asurascans.com/comics/chronicles-of-the-fallen-f886a8af"
+		first     = "https://cdn.example/covers/first.jpg"
+	)
+	if _, err := s.Upsert(s.OwnerID(), store.Bookmark{
+		Key: key, Site: "asura", SeriesID: seriesID, SeriesURL: seriesURL, UpdatedAt: 1000,
+	}); err != nil {
+		t.Fatalf("seed: %v", err)
+	}
+	if err := s.SetSeriesCover("asura", seriesID, first, []byte("first"), "image/jpeg"); err != nil {
+		t.Fatalf("seed cover: %v", err)
+	}
+	// Make the stranded file unremovable: a non-empty directory in its place.
+	stale := store.CoverAddressForBytes([]byte("first"))
+	stalePath := filepath.Join(coverDir, filepath.FromSlash(stale[:2]+"/"+stale[2:4]+"/"+stale))
+	if err := os.Remove(stalePath); err != nil {
+		t.Fatalf("clear file: %v", err)
+	}
+	if err := os.Mkdir(stalePath, 0o755); err != nil {
+		t.Fatalf("replace file with dir: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(stalePath, "blob"), []byte("x"), 0o644); err != nil {
+		t.Fatalf("fill dir: %v", err)
+	}
+
+	at := time.UnixMilli(5_000_000)
+	if err := s.ForceSeriesPoll("asura", seriesID, at.Add(time.Hour).UnixMilli()); err != nil {
+		t.Fatalf("ForceSeriesPoll: %v", err)
+	}
+	var logs strings.Builder
+	prev := log.Writer()
+	log.SetOutput(&logs)
+	t.Cleanup(func() { log.SetOutput(prev) })
+	p := &Poller{
+		Store: s, Fetch: &fakeFetcher{body: asuraSeriesFixture + asuraCoverFixture, status: 200},
+		CoverBytesFetch: &fakeBytesCoverFetcher{body: []byte("second"), contentType: "image/jpeg"},
+		Now:             func() time.Time { return at },
+	}
+	p.runOnce(context.Background())
+	p.waitCovers()
+
+	logged := logs.String()
+	if !strings.Contains(logged, "reclaim cover") {
+		t.Fatalf("failed reclamation not logged; log:\n%s", logged)
+	}
+	if !strings.Contains(logged, "cover replaced") {
+		t.Fatalf("replacement not reported after a failed reclaim; log:\n%s", logged)
+	}
+	got := readBookmark(t, s, key)
+	if want := testCoverBaseURL + "/covers/" + store.CoverAddressForBytes([]byte("second")); got.Cover != want {
+		t.Fatalf("Cover = %q, want the replacement %q", got.Cover, want)
+	}
+}

backend/internal/latest/read.go

@@ -41,7 +41,7 @@ var (
 // its own network position to whatever URL a token-holder writes, including
 // link-local/internal addresses or non-https schemes.
 func readSeriesPage(ctx context.Context, site, seriesURL string, browser, tls Fetcher) (seriesRead, error) {
-	if !fetchableSeriesURL(site, seriesURL) {
+	if !FetchableSeriesURL(site, seriesURL) {
 		return seriesRead{}, fmt.Errorf("%w: site=%q url=%q", errNotFetchable, site, seriesURL)
 	}
 	f := fetcherFor(site, browser, tls)

backend/internal/latest/sites.go

@@ -46,7 +46,7 @@ type site struct {
 type browserRead struct {
 	// Read builds the tab read for seriesURL, refusing (false) an address
 	// this Site will not open in a browser — the per-Site half of the SSRF
-	// gate, kept deliberately behind fetchableSeriesURL: a headless browser
+	// gate, kept deliberately behind FetchableSeriesURL: a headless browser
 	// executes JavaScript and carries cookies, and series_url is
 	// client-supplied.
 	Read func(seriesURL string, out *string) (chromedp.Action, bool)

backend/internal/latest/smoke_image_test.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"net/http"
 	"os"
+	"strings"
 	"testing"
 	"time"
 
@@ -108,10 +109,7 @@ func TestSmokeAcquireKaganeCover(t *testing.T) {
 	if ws == "" {
 		t.Skip("SMOKE_BROWSER_WS_URL unset")
 	}
-	const (
-		seriesID = "019fe11a-8670-7cf3-8343-0b02057d3787"
-		coverURL = "https://kagane.to/api/v2/image/019fe11a-84c3-7fc3-a84b-88787374b617/compressed"
-	)
+	const seriesID = "019fe11a-8670-7cf3-8343-0b02057d3787"
 	s, _ := newTestStore(t)
 	bf, err := NewBrowserFetcher(ws)
 	if err != nil {
@@ -140,12 +138,13 @@ func TestSmokeAcquireKaganeCover(t *testing.T) {
 	if err != nil || !found {
 		t.Fatalf("Get: %v found=%v", err, found)
 	}
-	if want := testCoverBaseURL + "/covers/" + store.CoverAddress(coverURL); got.Cover != want {
-		t.Fatalf("Cover = %q, want %q — the acquire path did not store the browser-fetched bytes", got.Cover, want)
+	addr, ok := strings.CutPrefix(got.Cover, testCoverBaseURL+"/covers/")
+	if !ok {
+		t.Fatalf("Cover = %q, want an address on %q — the acquire path did not store the browser-fetched bytes", got.Cover, testCoverBaseURL+"/covers/")
 	}
-	body, contentType, ok, err := s.CoverByAddress(store.CoverAddress(coverURL))
+	body, contentType, ok, err := s.CoverByAddress(addr)
 	if err != nil || !ok {
-		t.Fatalf("CoverByAddress: %v found=%v", err, ok)
+		t.Fatalf("CoverByAddress(%q): %v found=%v", addr, err, ok)
 	}
 	if len(body) < 1000 {
 		t.Fatalf("stored cover is %d bytes, want a real image", len(body))
@@ -153,5 +152,10 @@ func TestSmokeAcquireKaganeCover(t *testing.T) {
 	if contentType != "image/webp" {
 		t.Fatalf("content type = %q, want image/webp", contentType)
 	}
+	// The address the row carries is the bytes' own SHA-256: a re-art behind
+	// the same URL would be a different address, which is the whole point.
+	if want := testCoverBaseURL + "/covers/" + store.CoverAddressForBytes(body); got.Cover != want {
+		t.Fatalf("Cover = %q, want %q", got.Cover, want)
+	}
 	t.Logf("stored %d bytes of %s", len(body), contentType)
 }

backend/internal/latest/smoke_lnw_test.go

@@ -40,7 +40,7 @@ func TestSmokeLnwCommentBoundary(t *testing.T) {
 	if seriesURL == "" {
 		t.Skip("SMOKE_LNW_SERIES_URL unset")
 	}
-	if !fetchableSeriesURL("lightnovelworld", seriesURL) {
+	if !FetchableSeriesURL("lightnovelworld", seriesURL) {
 		t.Fatalf("%q is not a fetchable lightnovelworld series URL", seriesURL)
 	}