Two perf gaps that would have failed Cin's review:
# Gap #1: alias lookup fired unconditionally
Pre-fix in this commit, `_resolve_expected_artist_aliases` ran at
the top of every `verify_audio_file` call regardless of whether
the direct artist match would have passed. For users whose library
is mostly same-script (95% of cases), every successful verification
was paying for a wasted DB query (and possibly a wasted MB API
call for un-enriched artists).
Restructured the helper to accept a callable provider instead of a
pre-resolved list. Provider invoked LAZILY only when direct
similarity falls below `ARTIST_MATCH_THRESHOLD`. Verifier passes a
memoising thunk that resolves once across the 3 comparison sites
within one verification.
`_alias_aware_artist_sim` now accepts `aliases` as either:
- iterable of strings (used eagerly — backward compat with tests
that already know the aliases)
- callable returning the iterable (resolved on first need within
a verification)
Happy path (direct match passes): zero DB queries, zero MB calls.
Cross-script case: one resolution shared across 3 sites — same as
the prior contract.
# Gap #2: existing-MBID artists never got alias backfill
Worker's `_process_item` artist branch had an `existing_id` short-
circuit (line 296) that updated MBID status but skipped alias
fetch. Result: every user with an already-enriched library had
MBIDs but NULL aliases on day-one of this PR. Live MB lookup at
verify-time covered them, but at the cost of N live calls for N
artists across the library.
Added one-time backfill: when existing-MBID is found AND
`artists.aliases` for that row is empty, fetch + persist aliases.
Subsequent re-scan cycles short-circuit on the populated column —
no repeated MB calls.
New helper `_artist_aliases_empty(artist_id)` does the cheap NULL
check via direct SQL. Best-effort: defensively returns True on
errors so backfill happens (a redundant MB call is cheaper than
missing the backfill entirely).
# Tests added (9)
`test_acoustid_verification_aliases.py` (+6):
- `TestLazyAliasResolution` (3): no lookup when direct match passes,
lookup fires only when direct fails, lookup memoised across the
3 sites within one verification.
- `TestAliasProviderCallable` (3): iterable passed directly,
callable resolves lazily, callable returning empty falls back to
direct sim.
`test_artist_alias_service.py` (+3):
- `test_existing_mbid_path_backfills_aliases_when_column_empty`
- `test_existing_mbid_path_skips_backfill_when_aliases_already_set`
- `test_existing_mbid_backfill_failure_does_not_break_match`
# Verification
- 79/79 matching tests pass (+9 from prior commit)
- 2537 full suite passes (+9, +79 PR-total)
- Ruff clean
- Backward compat: every prior-commit test still passes (the
iterable-shape API still works alongside the new callable shape)
Previous commit only populated `artists.aliases` for artists the MB
worker had enriched. But the AcoustID verifier (next commit) needs
aliases for ANY expected artist — including:
- Artists not yet in the user's library (first download)
- Artists in the library where MB enrichment hasn't run yet
- Artists where MB enrichment ran but found no MBID (NULL aliases)
This commit adds a multi-tier resolution helper that fills those
gaps without thrashing the MB API.
# Multi-tier resolution
`lookup_artist_aliases(artist_name) -> list[str]`:
1. **Library DB** (fast path): existing `get_artist_aliases` lookup
by name. No network. Most common path once the worker has
enriched everything.
2. **Cache** (existing `musicbrainz_cache` table, entity_type=
`artist_aliases`): a prior live lookup for this name. Empty
cache hit is respected (don't re-query when MB previously had
nothing).
3. **Live MB**: search artist by name → pick highest-confidence
match (combined name-similarity + MB relevance) → fetch aliases
for that MBID → cache the result.
Always returns a list (possibly empty), never raises. Empty result
on any tier means "no alternate spellings found, fall back to
direct match" — identical to the pre-fix behaviour.
# Threshold gate
Live lookup only trusts the MB search result when combined
similarity score >= 0.6. Below that, we'd be guessing at the wrong
artist — searching `John Smith` returns multiple John Smiths and
pulling aliases for one of them could mismatch. Cache the empty
result so we don't keep re-searching the same low-confidence name.
# Performance contract
Critical for the verifier path: 100 quarantine candidates with the
same expected artist must NOT trigger 100 MB API calls. Cache hit
on second + subsequent calls per unique artist name. Verified by
test pinning the call counts.
# Tests added (8)
- Tier 1 library DB hit — no MB API call fired
- Tier 3 live MB lookup → search → fetch → returns aliases
- Tier 2 cache hit on second call — no re-query
- Empty input → empty return + no API call
- Network failure on search → empty + cached so we don't retry
- No search results → empty + cached
- Low-confidence match (sim < 0.6) skipped — defends against
picking the wrong artist
- Library row exists but aliases NULL → falls through to live
lookup (defends against the half-enriched state)
# Verification
- 31/31 service tests pass (8 new + 23 prior)
- Ruff clean
Issue #442 — MusicBrainz exposes alternate-spelling aliases (Japanese
kanji `澤野弘之` for `Hiroyuki Sawano`, Cyrillic `Сергей Лазарев` for
`Sergey Lazarev`, etc.) on every artist record. SoulSync's MB
enrichment worker had access to this data via `get_artist(mbid,
includes=['aliases'])` but wasn't reading or persisting it.
This commit wires the alias fetch into the worker's existing
artist-match path, persists to the new `artists.aliases` column
added in the prior commit, and adds a verifier-friendly read-by-
name lookup so the AcoustID verifier (next commit) can resolve
aliases without an MB round-trip when the artist is in the library.
# New service methods
- `fetch_artist_aliases(mbid) -> list[str]` — calls
`mb_client.get_artist(mbid, includes=['aliases'])`, parses the
alias array, dedupes case-insensitively. Returns empty list on
any failure (missing key, network error, malformed response) so
transient MB outages never trigger stricter quarantine decisions
than the pre-fix behaviour. Empty mbid → no API call.
- `update_artist_aliases(artist_id, aliases)` — persists as JSON
array to `artists.aliases`. Idempotent — overwrites prior value.
Empty list clears the column. None artist_id is a no-op.
- `get_artist_aliases(artist_name) -> list[str]` — reads back by
artist NAME (not id), case-insensitive. Used by the verifier
where the expected artist comes from track metadata — there's no
library row id at quarantine time. Returns empty list for unknown
artists, missing data, or corrupt JSON (defensive against legacy
rows).
# Worker integration
`MusicBrainzWorker._process_item` artist branch:
- After `update_artist_mbid` succeeds, fetch aliases for the matched
MBID and persist via `update_artist_aliases`.
- Best-effort: alias fetch wrapped in try/except, failure logs at
debug level, doesn't regress the match outcome.
- No alias call when the artist didn't match an MBID (nothing to
enrich).
# Tests (23)
- `fetch_artist_aliases`: extracts names from MB response,
case-insensitive dedup, skips empty/null entries, missing-key
fallback, network failure → empty, empty mbid no API call,
verifies `inc=aliases` request param.
- `update_artist_aliases`: persists as JSON, idempotent overwrite,
empty list clears column, None id is no-op.
- `get_artist_aliases`: returns aliases for known artist,
case-insensitive lookup, empty for unknown artist / no-aliases
row, handles corrupt JSON + non-list shape gracefully.
- Worker integration: matched artist triggers fetch + persist,
no alias call when not matched, alias-fetch failure doesn't
break the match outcome.
# Verification
- 23/23 new tests pass
- Ruff clean
Broque Thomas