music_library/backlog/archive/tasks/ml-3 - Document-intentional-async-only-coupling-from-Records-to-Artists.md

id, title, status, assignee, created_date, updated_date, labels, dependencies, references, priority

id	title	status	assignee	created_date	updated_date	labels	dependencies	references	priority
ML-3	Document intentional async-only coupling from Records to Artists	To Do		2026-04-20 08:44	2026-04-20 08:44			https://github.com/cloud8421/music_library/issues/181	low

Description

GitHub: created 2026-04-16 · updated 2026-04-19 · closed 2026-04-19 · not planned

Summary

Records.create_record/1 calls Artists.refresh_artist_info_async/1 and Records.delete_record/1 calls Artists.prune_artist_info_async/1. Both are deliberately *_async (Oban enqueues) to avoid a runtime cycle with the embedding/genre regeneration path in Artists. The intent is not captured inline.

Evidence

• lib/music_library/records.ex:385 — Artists.refresh_artist_info_async/1 call
• lib/music_library/records.ex:415 — Artists.prune_artist_info_async/1 call

No comment explaining why the async form is required. A future refactor that decides to "just inline the synchronous version" would reintroduce runtime coupling.

Fix

Add a short inline comment above each call site explaining:

# async to avoid a runtime cycle:
# Records.create/delete -> Artists.refresh/prune (sync) -> Records (embedding regeneration)
Artists.refresh_artist_info_async(artist)

Acceptance Criteria

• #1 Inline comments added at records.ex:385 and :415
• #2 Comments explain the runtime-cycle motivation, not just "it's async"