yellowjacket/.planning/plans/completed/004-wanted-list.md

004 — Wanted list

Status: implemented Branch: main Created: 2026-07-29 Follows: 003-download-clients

Problem

Plan 003 shipped a request as a heavyweight row: library, anchors, cached tracklist, state machine, error text, cascading items. That is the right shape for one attempt to acquire something and the wrong shape for the user wanting something, and 003 used it for both.

The consequences showed up immediately. A request that found nothing was marked failed, which is a lie — the album exists, no source had it today. Retrying meant the user remembering to press a button. Wanting an artist's future releases was not expressible at all. And a user who acquired an album by other means kept a failed row about it forever.

The model

A want is an MBID, what that MBID names, and retry bookkeeping. That is all.

download_wants(mbid, entity, library_id, scope, secondary, state,
               parent_id, attempts, last_error, next_try_at,
               external_ids)

entity is the only type distinction, and it carries all the policy:

entity	meaning
artist	a subscription. Never satisfied; each pass expands the discography into child wants
release-group	an album in the abstract — any release satisfies it
release	one specific edition
recording	one track

UNIQUE(mbid, library_id) is load-bearing: it is what makes artist expansion idempotent, so a subscription can re-run every pass and add only what is genuinely new.

Requests did not go away — they became what they always were, the ephemeral record of one attempt, with a nullable want_id back-link. The lifetimes are now opposite and explicit: a request is history, a want is intent.

Nothing here fails

There is no failed want state. An attempt can fail; a want cannot. A want that found nothing gets attempts + 1, a reason the user can read, and a longer backoff — 6h doubling to a 7-day ceiling, jittered so a list added in one sitting does not come due in one burst.

Satisfaction is ownership, not download

A want retires when the library owns what it names, however it got there — bought, ripped, copied in. Inferring satisfaction from our own completed downloads would keep hunting for music already on disk.

Artist scope defaults to future

Following an artist takes new releases only, and skips compilations, live albums and remixes. all backfills the discography, and the user can widen it from the wanted list. Subscribing should not silently queue forty albums.

The reconciler

A 6-hourly loop (plus on-demand, plus a 3-minute startup delay so the explore index has loaded). Four steps, in this order:

1. Expand artist subscriptions into album wants — first, so step 2 sees them this pass rather than next.
2. Retire wants the library already owns.
3. Sync to clients that keep their own list.
4. Attempt a bounded batch (25) of due wants.

Everything the loop needs about music comes through a four-method CatalogPort, adapted to the explore index in backend/downloadcatalog.go — the composition root, so neither package learns about the other.

Unattended grabs, and what stops them

Manager.Attempt is Start without the parking: it searches, and grabs only if AutoPickable clears. When it does not, nothing is persisted — no request row. A want retried weekly for a year would otherwise leave fifty identical failed rows, none of them anything the user can act on.

AutoPickable gained one condition: an anchored request with an empty Expected is refused. An anchor with no tracklist behind it is an anchor in name only, and match then rests on album/artist text — exactly the evidence a wrong-album candidate also has. Nobody is watching a reconcile pass.

Per-provider concurrency

Downloads.MaxConcurrent was the only limit, and was never actually applied (SetMaxConcurrent did not exist). Now:

• slskd defaults to 1. A Soulseek peer serves one file at a time from one person's upload slot; asking for more gets you queued behind everyone else at best. One is both the polite number and usually the fastest.
• yt-dlp 2, torrent/usenet clients 4, overridable per provider via a maxConcurrent field that Register appends automatically to any descriptor declaring CanTransport.
• A grab takes its provider's slot before the global one, so a queue on a busy slskd cannot sit on a global slot a usenet transfer could have used. The transport is resolved before either slot is taken; delegates take neither, since the transfer is happening inside another system that is doing its own limiting.

The Lister role

The fourth role, alongside Searcher/Transporter/Delegator. Lidarr already models a want — a monitored artist or album — and it is always on, where a desktop player is not. A subscription mirrored there keeps working while the app is closed.

• artist → Lidarr artist, monitor: future|missing per scope
• release-group/release → monitored album
• recording → not pushed. Lidarr cannot say "one track", and monitoring the album to get it downloads far more than was asked.

Sync is push-only in the loop; pulling happens only when the user explicitly imports ("adopt the artists Lidarr already monitors", which arrive at future scope). Removal unmonitors, never deletes — the user's Lidarr may predate this app.

Frontend

• Wanted view in the sidebar: Following / Looking for / Paused / Found, with pause, remove, scope toggle and "Check now".
• "Want this" on the album page, "Follow for new releases" on the artist page. The want button shows whether or not a client is connected — wanting is durable and stays queued until one exists.
• WantedListChanged event, since a background pass changes the list without the UI doing anything.

Files

backend/download/want.go, wantstore.go, reconcile.go, provider_lidarr_list.go; backend/downloadcatalog.go; schema download_wants.sql + migration 48 for the two new download_requests columns; frontend/src/components/wanted-view/.

Deferred

• Release-group wants are not retired by ownership of a specific release. The library indexes release groups and recordings, not editions, so a release want is only satisfied by its own download completing.
• No recording lookup on the explore index, so a track want relies on the title the UI passed in. A want added as a bare recording MBID has no tracklist and waits.
• Quality profiles and upgrade-if-better (from 003).
• Resume across restart (from 003) — still the largest gap, and it now matters more: an unattended grab that dies on restart is retried by the reconciler, but from zero bytes.