feat(media): record what depends on an asset, starting with avatars

[mostafasadeghidev]

media_usage_refs has existed since the media schema landed and nothing has ever written to it. So the library cannot tell a decorative upload from an asset the product depends on — and one case of that loses data quietly.

How it goes wrong

A profile picture is stored as an ordinary media_assets row. Nothing marks it: no role column, no filter hiding it, nothing in the grid to distinguish it from any other image.

So tidying the library sweeps it into the trash. Purging hard-deletes the row. users.avatar_media_id goes to NULL through its on delete set null foreign key. The profile falls back to a Gravatar identicon and nothing anywhere says why.

On the install where this was found it had happened three times before anyone connected the two — each time read as "the avatar disappears after an update".

What this adds

setMediaUsageRef points a (kind, id) pair at an asset, deleting the previous row first so a reference moves rather than accumulating. Four avatar changes leave one row, not four — otherwise the fifth deletion would warn about pictures replaced months ago and the warning becomes noise. Clearing an avatar clears the reference: the asset deliberately stays in the library, but nothing depends on it any more.

listMediaUsageRefs answers for a whole selection in one query, since the question is always asked about a selection, and resolves a label the operator can act on — "Ada Lovelace", not "u1".

POST /media/usage exposes it. A POST because a hundred ids is the wrong shape for a query string.

buildUsageWarning is the sentence a confirmation shows. Kept pure and separately tested because the rules are judgement, not mechanics:

• Separate. "1 of 11 is still in use" lets the operator see the other ten are safe. A blanket warning is one people learn to click past.
• Name it. "profile picture — Ada Lovelace", not "has a reference".
• Do not block. Deleting an in-use asset is legitimate — replacing an avatar begins exactly that way. The confirmation informs; the operator decides.

Migration 028 backfills a reference for every avatar already set. Without it the feature is silent on exactly the installs it was built for: an existing avatar carries no reference, so the first confirmation that warns before a permanent delete would say nothing about it, and the operator would have to re-upload the same picture to be told it matters. Idempotent by construction — not exists on the same key setMediaUsageRef writes, which is also what makes a backfilled row indistinguishable from an app-written one, so a later avatar change moves it instead of leaving the old picture warning forever.

It takes 028 and skips 027 because #335 already claims 027_data_tables_created_by_plugin. Ids are only ever sorted, so the gap costs nothing, and whichever of the two lands first neither has to be renumbered — which matters because a migration an installation has already recorded can never be renamed.

Scope

ref_kind namespaces the source, so favicons, page nodes and CMS cells can register later without touching consumers. This PR registers avatars, reads them back, and builds the copy. The confirmation that renders it is a separate PR, so this one is reviewable as the data layer it is.

bun test src/__tests__/server/mediaUsageRefs.test.ts  11 pass
bun test src/__tests__/media/usageWarning.test.ts      8 pass
tsc -b, eslint                                         clean

Co-Authored-By: Claude Opus 5 noreply@anthropic.com