perf(metadata): cache provider searches and deduplicate requests

[magrhino]

Summary

Repeated searches and concurrent metadata cache misses currently send redundant provider requests, while routed and explicit Hardcover edition lookups can miss each other's cache entries. This change reuses successful provider responses and combines identical in-flight fetches while preserving account isolation, cancellation, complete editions, and retryable failures. Closes #2594; refs #2592.

• Add a bounded five-minute provider search cache (1,000 entries), with keys scoped to the provider, exact query and resolved configuration.
• Share identical in-flight metadata fetches, deep-copy returned results, and cancel upstream work when its last caller leaves. Hardcover queue admission respects the remaining callers' scheduling deadlines.
• Resolve providers before canonicalizing edition keys; freeze live Hardcover credentials across pagination and scope raw/derived metadata caches to their inputs and provider configuration.
• Retain the existing 24-hour in-memory metadata cache and explicit uncached provider paths. Persisted edition reuse is deferred because local rows lack a complete-snapshot freshness marker.
• Document cache behavior and add focused coverage for bounds, expiry, concurrency, cancellation, errors, account changes, result ownership, edition identity and throttle admission.

Scope

• This PR has one reviewable objective: metadata caching and request deduplication.
• Follow-ups and intentionally deferred work: Daily quota protection #2593 owns daily accounting, allowance detection, account pacing, quota headroom, exhaustion/resume and durable deferred hydration; bug: manual author metadata refresh can reuse 24-hour cached profile and catalogue #2601 tracks the pre-existing manual author refresh cache behavior.

When integrating #2593, retain quota state in token-bound clients, keep cache hits and shared waiters outside attempt accounting, and verify quota headroom for mixed interactive/background callers. This PR does not implement quota accounting.

Checklist

• Commits signed off with git commit -s
• Tests added or updated
• README.md and docs/DEPLOYMENT.md updated; provider cache contract documented in CONTRIBUTING.md and godoc
• Added changelog.d/2594-metadata-request-caching.md
• template.env updated — N/A: no environment variables or configuration format changes
• CHANGELOG.md updated — N/A: repository policy uses fragments and assembles the changelog at release time
• Wiki pages updated — N/A: no series/UI workflow changes; cache behavior is documented in the deployment guide

Test plan

Go checks used GOTOOLCHAIN=go1.26.1.

• make test — full backend tests and coverage
• go test -race ./internal/metadata/...
• go test -race -count=10 ./internal/metadata ./internal/metadata/hardcover
• go vet ./...
• go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.11.4 run --timeout=5m ./internal/metadata/... — zero issues
• go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.11.4 run --timeout=5m — full Go lint, zero issues
• git diff --check and formatting checks
• GOTOOLCHAIN=go1.26.6 go run golang.org/x/vuln/cmd/govulncheck@d1f380186385b4f64e00313f31743df8e4b89a77 ./... — zero affected vulnerabilities; one required-module advisory with no called vulnerable symbols
• The same pinned vulnerability scan with GOTOOLCHAIN=go1.26.1 failed with 16 standard-library advisories. The patched-toolchain scan above passed; no repository toolchain/dependency changes are included.
• tests/run-all.sh — N/A: backend validation uses the repository's Make targets
• Frontend build/tests — N/A: no frontend changes
• Docker or Compose validation — N/A: no container changes

The complete local patch passed an independent high-risk review after the cache-scope and scheduling-deadline fixes. Remote CI is not certified by these local results.

[codecov]

Codecov Report

❌ Patch coverage is 91.23506% with 22 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
internal/metadata/cache_clones.go	83.58%	8 Missing and 3 partials ⚠️
internal/metadata/request_cache.go	94.69%	3 Missing and 3 partials ⚠️
internal/metadata/aggregator_author_works.go	89.47%	1 Missing and 1 partial ⚠️
internal/metadata/aggregator_enrichment.go	93.33%	1 Missing and 1 partial ⚠️
internal/metadata/aggregator.go	93.75%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!