fix(metadata): guard audnex enrichment writes against concurrent edits (#2926)

[vavallee]

Summary

Three paths made an Audnex call and then wrote the whole book row from the snapshot taken before it, so an edit saved during the call (unmonitor, new cover, narrator fix) was silently undone. They now use the same updated_at guard #2794 added for hydration. Rebind had the same shape around its provider fetch and is fixed too.

Closes #2926.

Implementation notes

Path	Before	After	When the guard loses
abs/importer.go enrichAudiobookFromASIN (background)	full Update	UpdateHydratedMetadata(book, snapshot.UpdatedAtRaw)	enrichment dropped, row reloaded so the rest of the import (series, editions, owned state, rollback snapshot) works from the edit; DEBUG log (the next ABS import enriches again)
hardcoverlistsyncer enrichAudiobook (background)	full Update	UpdateHydratedMetadata	enrichment dropped and row reloaded; INFO log, because list sync skips tracked books later and never retries it. On the create path the reloaded row is what the queued search sees; the widen path queued its copy before enriching
api/books.go EnrichAudiobook (manual)	full Update	UpdateHydratedMetadata, or UpdateIfUnchanged when the ASIN map rewrote the book's identity	retries once from a fresh read (ownership and audiobook/ASIN checks re-run); Audnex answers are cached in the aggregator, so the retry normally costs no second request. A second loss returns 409 "This book changed while it was being enriched. Try again."
api/books.go Rebind (manual)	full Update after GetBookFromProvider	UpdateIfUnchanged	409 "This book changed while it was being rebound. Try again." No retry, since the provider fetch is not cached. Both new 409s carry reason: "changed"; RebindModal previously turned any 409 without force_required into the duplicate message ("This metadata record conflicts with an existing book"), so it now branches on reason and shows bookRebind.changed (en.json only). The duplicate foreign ID 409 is unchanged.

• BookRepo.UpdateIfUnchanged is the guarded sibling of Update: the same full-row write with AND CAST(updated_at AS TEXT)=?, comparing stored text like UpdateHydratedMetadata so legacy timestamp shapes still match. On a lost guard it writes nothing and doesn't reload b. Update is now a thin wrapper over the shared helper. Its SQL and behaviour are unchanged.
• The manual enrich path only writes the whole row when the ASIN map actually changed the identity (tryMapAudiobookMetadataByASIN now returns whether it did). Otherwise only the enrichment columns are written.
• Same caveat as fix(metadata): preserve concurrent edits during hydration (#2758) #2794: a writer that does not bump updated_at is invisible to the guard (fix(db): SetFilePath fallback changes status without bumping updated_at #2793).

Follow-ups (not in this PR)

Other fetch-then-full-Update paths found by grepping every BookRepo.Update call site. Each one needs its own decision about what a lost guard means, so I left them out:

• abs/import_upserts.go mergeUpstreamBook (line ~573). It snapshots after applyBookFields, then runs the upstream lookup (lookupUpstreamBook, ISBN/search) and the merge. It is also reached from matchHardcoverSeries (import_hardcover_series.go:158) after SearchSeries/GetSeriesCatalog. The merge records conflicts and identifiers, so a lost guard needs a decision about those.
• api/authors.go runCatalogueSync, the seenTitles dedup branch (lines ~2529/2557/2568). Rows come from ListByAuthorIncludingExcluded at the start of the sync and are written after cover enrichment, edition fetches and earlier iterations' hydration, so the window is the whole catalogue loop.
• Not books: scheduler.refreshMetadata does meta.GetAuthor then a full authors.Update, which is the same bug on the authors table.

Checked and not affected (no network between the read and the write): BookHandler.Update, the bulk setters, applyGenresToBooks, add book core, queue removal, ABS conflict choice, adoptDirectInsertMatch, upsertManualBook, ABS and Calibre applyBookFields, both rollbacks, refreshBookStatus, and the list syncer's widen Update.

Checklist

• Commits signed off with git commit -s
• Tests added or updated
• Enrich button checked: it shows the server's error text for any failure, so its 409 already reads sensibly; a vitest now pins that
• Doc-update gate cleared (docs/User-Guide-Wiki.md paragraph next to the fix(metadata): preserve concurrent edits during hydration (#2758) #2794 hydration note)
• Added a changelog fragment under changelog.d/ (2926-audnex-concurrent-edits.md)

Test plan

Fail before (each test run against origin/main code, with only the new tests applied):

Test	On main
abs TestEnrichAudiobookFromASINPreservesConcurrentEdit	FAIL: monitored=true narrator="Audnex Narrator" image="https://audnex.test/cover.jpg"
hardcoverlistsyncer TestSync_EnrichmentPreservesConcurrentBookEdit	FAIL: same overwrite
api TestEnrichAudiobook_RetriesAfterConcurrentEdit	FAIL: monitored=true image="https://audnex.test/cover.jpg"
api TestEnrichAudiobook_MappedRetriesAfterConcurrentEdit	FAIL: concurrent unmonitor overwritten
api TestEnrichAudiobook_ConflictWhenEditsKeepLanding	FAIL: 200 instead of 409
api TestRebind_ConflictWhenBookChangesDuringFetch	FAIL: 200 instead of 409

The fake Audnex (AudnexBookClient stub, or the list syncer's enricher interface) commits a user edit through BookRepo.Update while it handles the request. Controls (...PersistsWithoutConcurrentEdit, TestEnrichAudiobook_PersistsAudnexFields) confirm the guarded write still lands when nothing races it. TestBookRepoUpdateIfUnchanged covers the new repo method on a legacy CURRENT_TIMESTAMP shaped row.

• gofmt -l internal/ cmd/ (clean)
• go vet ./...
• golangci-lint run ./... v2.11.4 (0 issues)
• go test -race on ./internal/db/, ./internal/abs/, ./internal/hardcoverlistsyncer/ (ok), and ./internal/api/ -run 'TestEnrichAudiobook|TestRebind|TestBook' (ok). The whole api package under -race hit a 45m timeout on this machine with no failures or races before it; left to CI's sharded race job.
• go test -count=1 ./cmd/... ./internal/... (all ok)
• After rebasing onto 2eeba271 (main had touched internal/db/books.go): go build ./..., and go test on db, abs, hardcoverlistsyncer, importer and the api enrich/rebind/book tests (all ok)
• cd web && npm run lint (0 errors; 7 warnings, all in untouched files) && npm run typecheck && npm run build
• npx vitest run src/components/RebindModal.test.tsx src/pages/BookDetailPage.test.tsx (127 passed, including the new changed-book rebind case and the enrich 409 case)
• After the UI commit: gofmt, go vet and go test on internal/api and internal/hardcoverlistsyncer, golangci-lint on both (0 issues)

🤖 Generated with Claude Code

https://claude.ai/code/session_016fJcCVbNnKsmj2MAAMwWj9

[github-actions]

Reviewed the guard mechanics end-to-end. No blocking defects.

Correctness

• UpdateHydratedMetadata guard miss → ReloadHydratedBook reloads b in-place (consistent with #2794). Both background callers (enrichAudiobookFromASIN, enrichAudiobook) correctly use b after the call. internal/abs/importer.go:49 comment is accurate.
• UpdateIfUnchanged intentionally does not reload b on miss. Both callers (Rebind, EnrichAudiobook) return immediately on !updated without touching b again, so there's no stale-pointer hazard. Worth a note in the godoc for future callers, but not a bug now.
• The retry loop in EnrichAudiobook (internal/api/books.go:218) is a for attempt := 0; ; attempt++ with all exits as explicit returns. Max two iterations, correct. Slightly unusual idiom but not wrong.
• Ownership re-checked on the fresh read at internal/api/books.go:266 — correct.
• The tryMapAudiobookMetadataByASIN → UpdateIfUnchanged vs UpdateHydratedMetadata branch is correct: the bool return distinguishes "identity rewritten" (needs full-row write) from "enrichment only" (partial-column write).

Security

No new surface. The 409 reason: "changed" field is safe to expose. The tenancy check on the reloaded book (auth.CheckOwnership) mirrors the pattern used throughout internal/api/.

Tests

Controls (PersistsWithoutConcurrentEdit) plus regression cases for each path. TestBookRepoUpdateIfUnchanged covers the legacy timestamp shape. TestEnrichAudiobook_ConflictWhenEditsKeepLanding verifies the second miss is a 409, not a 200.

Nit

internal/db/books.go:670 godoc for UpdateIfUnchanged could say explicitly that b is not reloaded on a missed guard, to match the equivalent note UpdateHydratedMetadata implies through ReloadHydratedBook. Low stakes given the tests, but a future caller scanning the signature will miss that distinction.

— 🤖 Bindery triage bot (automated). Reply to correct me; a human will see it.