fix: ensure ATProto records sync when tracks are updated (#302)

* fix: ensure ATProto records sync when tracks are updated

this fixes an issue where track metadata updates would succeed in the database but fail silently when syncing to ATProto, leaving records out of sync.

changes:
- make ATProto sync errors blocking - if ATProto update fails, the entire request fails
- explicit rollback on ATProto sync failure to prevent database/PDS inconsistency
- return 500 error with clear message when sync fails

before this fix, users would see success messages even when their ATProto records weren't actually updated, which was confusing and led to data inconsistency.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[e-mail]>

* docs: clarify environment-specific ATProto namespaces

updates CLAUDE.md and docs/tools/pdsx.md to accurately reflect that plyr.fm uses environment-specific namespaces configured via ATPROTO_APP_NAMESPACE:
- dev: fm.plyr.dev
- staging: fm.plyr.stg
- prod: fm.plyr

previous docs incorrectly stated all environments use unified fm.plyr.track namespace.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[e-mail]>

* fix: show feedback when featured artist handle not found

adds clear "no artist found" message when handle search returns no results, preventing confusion when users type non-existent handles.

before: users could type invalid handles and submit would silently save empty features array
after: users see clear feedback that handle wasn't found

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[e-mail]>

* fix: prevent form submission with unresolved featured artist input

disables upload and edit form submission when there's text in the featured artists search that hasn't been resolved to an actual artist.

before: could submit forms with typed text that wasn't added to features
after: submit buttons disabled until text is either selected or cleared

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[e-mail]>

---------

Co-authored-by: Claude <[e-mail]>

CLAUDE.md

···
 - **migrations**: automated via fly.io release_command
 - **logs**: `flyctl logs` is BLOCKING - use `run_in_background=true`
 - **type hints**: required everywhere
-- **ATProto namespaces**: NEVER use Bluesky lexicons (app.bsky.*). ALWAYS use our namespace (fm.plyr.*) for ALL records
+- **ATProto namespaces**: NEVER use Bluesky lexicons (app.bsky.*). ALWAYS use our namespace (fm.plyr.*), configured per environment via `ATPROTO_APP_NAMESPACE` (e.g., fm.plyr.dev for dev, fm.plyr for prod)
 - **communication**: use emojis sparingly and strictly for emphasis (avoid excessive check marks)
 
 ## structure

docs/tools/pdsx.md

···
 
 ## atproto namespace
 
-all plyr.fm records use the unified `fm.plyr.track` namespace across all environments (dev, staging, prod). there are no environment-specific namespaces.
+plyr.fm uses environment-specific namespaces configured via `ATPROTO_APP_NAMESPACE`:
+- **dev**: `fm.plyr.dev` → track collection: `fm.plyr.dev.track`
+- **staging**: `fm.plyr.stg` → track collection: `fm.plyr.stg.track`
+- **prod**: `fm.plyr` → track collection: `fm.plyr.track`
 
 **critical**: never use bluesky lexicons (app.bsky.*) for plyr.fm records. always use fm.plyr.* namespace.
+
+when using pdsx with dev environment, query `fm.plyr.dev.track`, not `fm.plyr.track`.
 
 ## credential management
 

frontend/src/lib/components/HandleSearch.svelte

···
 		onRemove: (_did: string) => void;
 		maxFeatures?: number;
 		disabled?: boolean;
+		hasUnresolvedInput?: boolean;
 	}
 
-	let { selected = $bindable([]), onAdd, onRemove, maxFeatures = 5, disabled = false }: Props = $props();
+	let { selected = $bindable([]), onAdd, onRemove, maxFeatures = 5, disabled = false, hasUnresolvedInput = $bindable(false) }: Props = $props();
 
 	let query = $state('');
 	let results = $state<FeaturedArtist[]>([]);
 	let searching = $state(false);
 	let showResults = $state(false);
 	let searchTimeout: ReturnType<typeof setTimeout> | null = null;
+	let noResultsFound = $state(false);
+
+	// update parent when there's unresolved input
+	$effect(() => {
+		hasUnresolvedInput = query.trim().length > 0;
+	});
 
 	async function searchHandles() {
 		if (query.length < 2) {
 			results = [];
+			noResultsFound = false;
 			return;
 		}
 
 		searching = true;
+		noResultsFound = false;
 		try {
 			const response = await fetch(`${API_URL}/search/handles?q=${encodeURIComponent(query)}`);
 			if (response.ok) {
 				const data = await response.json();
 				results = data.results;
+				if (results.length === 0) {
+					noResultsFound = true;
+				}
 				showResults = true;
 			}
 		} catch (_e) {
···
 		query = '';
 		results = [];
 		showResults = false;
+		noResultsFound = false;
 	}
 
 	function removeArtist(did: string) {
···
 						</div>
 					</button>
 				{/each}
+			</div>
+		{/if}
+
+		{#if noResultsFound && query.length >= 2}
+			<div class="no-results-message">
+				no artist found with handle "{query}"
 			</div>
 		{/if}
 	</div>
···
 		margin-top: 0.5rem;
 		font-size: 0.85rem;
 		color: #ff9966;
+	}
+
+	.no-results-message {
+		margin-top: 0.5rem;
+		padding: 0.75rem;
+		background: #2a1a1a;
+		border: 1px solid #4a3030;
+		border-radius: 4px;
+		color: #ff9966;
+		font-size: 0.9rem;
+		text-align: center;
 	}
 
 	/* mobile styles */

frontend/src/routes/portal/+page.svelte

···
 	let file: File | null = null;
 	let imageFile: File | null = null;
 	let featuredArtists: FeaturedArtist[] = [];
+	let hasUnresolvedFeaturesInput = $state(false);
 
 	// track editing state
 	let editingTrackId: number | null = null;
···
 	let editAlbum = '';
 	let editFeaturedArtists: FeaturedArtist[] = [];
 	let editImageFile: File | null = null;
+	let hasUnresolvedEditFeaturesInput = $state(false);
 
 	// profile editing state
 	let displayName = '';
···
 					<label for="features">featured artists (optional)</label>
 					<HandleSearch
 						bind:selected={featuredArtists}
+						bind:hasUnresolvedInput={hasUnresolvedFeaturesInput}
 						onAdd={(artist) => { featuredArtists = [...featuredArtists, artist]; }}
 						onRemove={(did) => { featuredArtists = featuredArtists.filter(a => a.did !== did); }}
 					/>
···
 					{/if}
 				</div>
 
-				<button type="submit" disabled={!file} class="upload-btn">
+				<button type="submit" disabled={!file || hasUnresolvedFeaturesInput} class="upload-btn" title={hasUnresolvedFeaturesInput ? "please select or clear featured artist" : ""}>
 					<span>upload track</span>
 				</button>
 			</form>
···
 											<div class="edit-label">featured artists (optional)</div>
 											<HandleSearch
 												bind:selected={editFeaturedArtists}
+												bind:hasUnresolvedInput={hasUnresolvedEditFeaturesInput}
 												onAdd={(artist) => { editFeaturedArtists = [...editFeaturedArtists, artist]; }}
 												onRemove={(did) => { editFeaturedArtists = editFeaturedArtists.filter(a => a.did !== did); }}
 											/>
···
 										<button
 											class="action-btn save-btn"
 											onclick={() => saveTrackEdit(track.id)}
-											title="save changes"
+											disabled={hasUnresolvedEditFeaturesInput}
+											title={hasUnresolvedEditFeaturesInput ? "please select or clear featured artist" : "save changes"}
 										>
 											✓
 										</button>

src/backend/api/tracks/mutations.py

···
         track.image_url = image_url
         image_changed = True
 
-    if track.atproto_record_uri and (
+    # always update ATProto record if any metadata changed
+    metadata_changed = (
         title_changed or album is not None or features is not None or image_changed
-    ):
-        await _update_atproto_record(track, auth_session, image_url)
+    )
+    if track.atproto_record_uri and metadata_changed:
+        try:
+            await _update_atproto_record(track, auth_session, image_url)
+        except Exception as exc:
+            logger.error(
+                f"failed to update ATProto record for track {track.id}: {exc}",
+                exc_info=True,
+            )
+            await db.rollback()
+            raise HTTPException(
+                status_code=500,
+                detail=f"failed to sync track update to ATProto: {exc!s}",
+            ) from exc
 
     await db.commit()
     await db.refresh(track)
···
     auth_session: AuthSession,
     image_url_override: str | None = None,
 ) -> None:
+    """Update the ATProto record for a track.
+
+    raises:
+        Exception: if ATProto record update fails
+    """
     record_uri = track.atproto_record_uri
     audio_url = track.r2_url
     if not record_uri or not audio_url:
         return
 
-    try:
-        updated_record = build_track_record(
-            title=track.title,
-            artist=track.artist.display_name,
-            audio_url=audio_url,
-            file_type=track.file_type,
-            album=track.album,
-            duration=None,
-            features=track.features if track.features else None,
-            image_url=image_url_override or await track.get_image_url(),
-        )
-
-        result = await update_record(
-            auth_session=auth_session,
-            record_uri=record_uri,
-            record=updated_record,
-        )
+    updated_record = build_track_record(
+        title=track.title,
+        artist=track.artist.display_name,
+        audio_url=audio_url,
+        file_type=track.file_type,
+        album=track.album,
+        duration=None,
+        features=track.features if track.features else None,
+        image_url=image_url_override or await track.get_image_url(),
+    )
 
-        if result:
-            _, new_cid = result
-            track.atproto_record_cid = new_cid
+    result = await update_record(
+        auth_session=auth_session,
+        record_uri=record_uri,
+        record=updated_record,
+    )
 
-    except Exception as exc:  # pragma: no cover - network/service failures
-        logger.warning(
-            f"failed to update ATProto record for track {track.id}: {exc}",
-            exc_info=True,
-        )
-        # continue even if ATProto update fails - database changes are primary
+    if result:
+        _, new_cid = result
+        track.atproto_record_cid = new_cid
 
 
 class RestoreRecordResponse(BaseModel):