feat(author): surface duplicate-title candidates for human review (#1970)

[gchahcg]

Summary

Duplicate titles for one author ("The Martian" / "Martian", "Dune" / "Dune
(Unabridged)") were invisible. This adds a read-only candidate report per
author, plus a review modal whose only action is the existing exclude route.
Closes #1970.

Implementation notes

• internal/duplicates is a new package that nothing else may import — a
  source-scan test (TestIngestionPackagesNeverImportThis) pins the boundary.
  The aggressive fold (case, punctuation, diacritics; & → "and") is
  deliberately separate from the dedup key, which must stay conservative.

• Four rules, each reported per group and per member:

  Rule	Match
  alnum-equal	identical after the aggressive fold
  article-strip	identical after dropping a leading article (The/A/An, der/die/das, le/la, …)
  edition-suffix	identical after dropping a trailing edition marker (Unabridged, Audiobook, …)
  substring	one folded title contained in the other (min-length + residual guards)

• Groups are linked transitively (A≈B, B≈C → one group); output is
  deterministic (groups by key, members by id).

• GET /author/{id}/duplicate-candidates returns only groups with ≥2
  non-excluded members; it writes nothing.

Where it's mounted / how it's wired

• Route: GET /author/{id}/duplicate-candidates (cmd/bindery/main.go).
• Handler: internal/api/authors_duplicate_candidates.go (one file per
  feature, matching the repo convention).
• UI: "Review duplicates…" in the author page's More menu →
  DuplicateCandidatesModal (fetches on open, per-row Exclude calls
  PUT /book/{id}/exclude, re-fetches; excluded members struck through).
• Docs: docs/API.md endpoint + response shape; docs/User-Guide-Wiki.md
  review-flow paragraph.

Why minimal / scope decisions

• Detection is aggressive, action is human: nothing is merged, deleted, or
  rewritten automatically. The endpoint is read-only by design.
• Substring rule has guards (min key length 6, min residual 6, marker-only
  residual suppressed) so "Works of X" vs "Complete Works of X" does not
  light up; accepted false-positive classes are pinned in tests.
• Pairwise scan is O(n²) and the substring pass is capped at 2000 books per
  author (a 1000-book author scans in well under 2 s).
• The UI entry point is a menu item, not a page-load fetch: the report is
  opt-in, so it is computed on demand.

Suggested review order

1. internal/duplicates/duplicates.go — fold, keys, rules, Scan.
2. internal/duplicates/duplicates_test.go — rule matrix + pinned FPs.
3. internal/duplicates/imports_test.go — the import-boundary pin.
4. internal/api/authors_duplicate_candidates.go + tests — handler contract.
5. web/src/components/DuplicateCandidatesModal.tsx + test — review flow.
6. docs/API.md, docs/User-Guide-Wiki.md.

Checklist

• Tests added or updated
• Doc-update gate cleared (see commits skill — docs/, README.md, godoc, Helm values)
• Wiki pages updated if user-facing behaviour changed

Test plan

• go test ./cmd/... ./internal/...
• cd web && npm run build
• make check (build, vet, golangci-lint, govulncheck, test, test-race, web ci/typecheck/lint/build/test)
• go test ./internal/duplicates/ (L1 rule matrix)
• go test ./internal/api/ -run TestDuplicateCandidates (handler: groups, 404, empty, exclusion suppression, read-only, tenancy, 1000-book scale)
• cd web && npx vitest run src/components/DuplicateCandidatesModal.test.tsx (5 tests)
• cd web && npx vitest run (full web suite, 1007 tests)

Follow-ups (not in this PR)

• Cross-author duplicate detection (same book under two author rows).
• A "keep this one, exclude the rest" bulk action in the modal.

[codecov]

Codecov Report

❌ Patch coverage is 90.99099% with 20 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
internal/duplicates/duplicates.go	93.51%	6 Missing and 6 partials ⚠️
internal/api/authors_duplicate_candidates.go	78.37%	5 Missing and 3 partials ⚠️

📢 Thoughts on this report? Let us know!

[vavallee]

This is the shape I asked for on #1970: read only, `loadOwnedAuthor` on the route so it's tenancy scoped, the aggressive fold kept in its own package with a source scan test holding the boundary, and each group saying which rule fired. It builds and its tests pass once the docs conflict is resolved.

One thing blocks it, and it's about the only action the modal offers being Exclude.

The substring rule groups separate books of a series. I ran a batch of real titles through `duplicates.Scan`:

Grouped	Rule	Actually
Foundation, Foundation and Empire, Second Foundation	substring	three different Asimov novels
Mistborn, Mistborn: The Final Empire	substring	same book, correct
The Hobbit, The Hobbit (Unabridged)	edition-suffix	correct
The Martian, Martian	article-strip	correct
Dune, Dune Messiah, Children of Dune	not grouped	correct, but only because "dune" is under the length floor

So the guard is length based, and a long first book title that doubles as the series name (Foundation, Outlander, Discworld style) trips it. Someone trusting the report excludes Foundation and Empire.

The cleanest fix I can see: suppress a substring match when both books are linked to the same series at different positions, since two different positions in one series are by definition different works. That keeps Mistborn (usually one series position) and drops Foundation. If series links aren't available at that point, dropping substring from the default rule set and keeping the other three is also fine.

Two small things alongside:

• It conflicts with main in `docs/User-Guide-Wiki.md` only.
• It needs a changelog fragment under `changelog.d/` (`### Added`, no dashes in the text).

[gchahcg]

Fixed — thanks for running real titles through it.

Added duplicates.SeriesSlot and a sameSeriesDifferentPosition guard: Scan now takes each book's series memberships and drops a substring-only match between two books that are known, different positions in the same series. DuplicateCandidates loads them via h.series.ListBookSeriesMembershipsByAuthor (nil-guarded for tests/deployments without a series repo, which falls back to today's behaviour).

Verified against your table:

• Foundation / Foundation and Empire / Second Foundation (positions 1/2/3, same series) → no longer grouped
• Mistborn / Mistborn: The Final Empire (both position 1) → still grouped, unaffected
• The Hobbit / Hobbit (Unabridged), The Martian / Martian → unaffected (different rules)

Added unit tests in duplicates_test.go for both cases plus an end-to-end handler test wiring real series_books rows. Also rebased onto main (post-#2673) and fixed the docs/User-Guide-Wiki.md conflict, and added the changelog.d fragment.

[vavallee]

Thanks for turning the series fix around so fast, the guard works exactly as described. I pushed two commits on top:

• Subtitle matches now need a separator. The series guard only helps when series links exist, and plenty of authors don't have them. With no series data, Asimov's "Foundation" still pulled nine titles into one group (Prelude to Foundation, Foundation and Chaos, The Foundation Trilogy...), and "The Science of Discworld" grouped with its sequels, as did "Carrie" with "Carrie Soto Is Back". Now the shorter title has to be a whole part of the longer one as it's punctuated (colon, bracket, spaced dash). Mistborn, The Gunslinger, Hogfather (Discworld, release: v0.6.1 #20) and friends still group, and your series guard still earns its keep on "Mistborn" vs "Mistborn: The Well of Ascension". Across about 215 real Asimov, King and Pratchett titles the report went from 16 groups (roughly half wrong) to 10 (nine clearly right).
• Accents fold now. "Les Misérables" and "Les Miserables" weren't grouping, even though the UI text says diacritics are ignored.
• The handler series test gets a position 2 sequel, since the Foundation fixture passed with the guard deleted once the separator rule landed.
• Docs and the UI rule text now describe the new rule, and the changelog fragment dropped its dashes and credits you.

Rest looks good to me.