Reworked settings page

.gitignore

@@ -2,3 +2,6 @@
 /nul
 /.claude
 /media
+/federation
+/similarity-models
+/federation-cache

Cargo.toml

@@ -1,18 +1,24 @@
 [package]
 name = "furumusic"
-version = "0.4.8"
+version = "0.10.2"
 edition = "2024"
 description = "Reusable web-app boilerplate: auth, OIDC/SSO, admin panel, user management, i18n, PostgreSQL"
 
 [dependencies]
-cot = { version = "0.6.0", features = ["postgres", "json", "openapi", "swagger-ui"] }
+# default-features off: cot's defaults include the sqlite backend, whose old
+# libsqlite3-sys collides with music-dht's rusqlite (one native sqlite3 per
+# binary). This server only ever talks PostgreSQL.
+cot = { version = "0.6.0", default-features = false, features = ["postgres", "json", "openapi", "swagger-ui"] }
 schemars = { version = "0.9", features = ["derive"] }
 serde = { version = "1", features = ["derive"] }
 openidconnect = "4.0"
-reqwest = { version = "0.12", default-features = false, features = ["rustls-tls", "json"] }
+reqwest = { version = "0.12", default-features = false, features = ["rustls-tls", "json", "stream"] }
 tokio = { version = "1", features = ["sync", "fs", "io-util"] }
+async-stream = "0.3"
+bytes = "1"
 tower = "0.5"
 base64 = "0.22"
+blake3 = "1"
 serde_json = "1"
 tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
@@ -25,8 +31,16 @@ md-5 = "0.10"
 image = { version = "0.25", default-features = false, features = ["jpeg", "png", "webp", "gif", "bmp"] }
 sqlx = { version = "0.8", features = ["runtime-tokio-rustls", "postgres"] }
 anyhow = "1.0"
+futures-util = "0.3"
+rodio = { version = "0.22.2", default-features = false, features = ["mp3", "flac", "vorbis", "wav", "symphonia-aac", "symphonia-isomp4", "symphonia-alac", "symphonia-adpcm", "symphonia-aiff", "symphonia-mkv", "symphonia-pcm"] }
+rustfft = "6.4.1"
+tract-onnx = "0.23.4"
 tokio-cron-scheduler = "0.15"
 croner = "3"
 async-trait = "0.1"
+postcard = { version = "1", features = ["alloc"] }
 uuid = "1"
 librqbit = { version = "8.1.1", features = ["disable-upload"] }
+# P2P federation: publishes the library into a shared DHT and serves audio /
+# catalogs to furumi peers (TUI clients) over the frid stack.
+music-dht = "0.4.0"

README.md

@@ -1,5 +1,12 @@
 # furumusic
 
+Furumusic can join the decentralized Furumi federation while remaining a
+complete local web player. Optional similarity search stores versioned audio
+embeddings in PostgreSQL and uses signed two-level LSH summaries in a separate
+DHT to discover compatible peers without a central recommendation index. The
+shared `music-dht` layer owns routing and wire compatibility; model inference
+and exact cosine ranking stay local to each instance.
+
 Reusable web-app boilerplate: auth, OIDC/SSO, admin panel, user management, i18n, PostgreSQL.
 
 Built with Rust ([cot](https://cot.rs) framework).

flake.lock

@@ -0,0 +1,27 @@
+{
+  "nodes": {
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1786106723,
+        "narHash": "sha256-zDSUbpoeo/9ZmD2+wXnzxoo1+uhL8vxc0b8yuYMKYq0=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "f13ff45afd1bb73e640eaa08a7066dbed07e3238",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "nixpkgs": "nixpkgs"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

flake.nix

@@ -0,0 +1,38 @@
+{
+  description = "Furumusic development environment";
+
+  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+
+  outputs = { nixpkgs, ... }:
+    let
+      supportedSystems = [
+        "x86_64-linux"
+        "aarch64-linux"
+        "x86_64-darwin"
+        "aarch64-darwin"
+      ];
+      forEachSystem = function:
+        nixpkgs.lib.genAttrs supportedSystems (system:
+          function (import nixpkgs { inherit system; }));
+    in
+    {
+      devShells = forEachSystem (pkgs: {
+        default = pkgs.mkShell {
+          nativeBuildInputs = with pkgs; [
+            cargo
+            clippy
+            pkg-config
+            rustc
+            rustfmt
+          ];
+
+          buildInputs = with pkgs; [
+            cacert
+            openssl
+          ] ++ lib.optionals stdenv.isDarwin [ libiconv ];
+
+          RUST_SRC_PATH = "${pkgs.rustPlatform.rustLibSrc}";
+        };
+      });
+    };
+}

src/admin/mod.rs

@@ -415,6 +415,52 @@ impl App for AdminApp {
                 }),
                 "admin_v2_settings_probe",
             ),
+            Route::with_handler_and_name(
+                "/v2/api/federation",
+                get(move |session: Session, db: Database| async move {
+                    v2::federation_status(session, db).await
+                }),
+                "admin_v2_federation_status",
+            ),
+            Route::with_handler_and_name(
+                "/v2/api/similarity",
+                get(move |session: Session, db: Database| async move {
+                    v2::similarity_status(session, db).await
+                }),
+                "admin_v2_similarity_status",
+            ),
+            Route::with_handler_and_name(
+                "/v2/api/similarity/clear",
+                cot::router::method::post(move |session: Session, db: Database| async move {
+                    v2::similarity_clear(session, db).await
+                }),
+                "admin_v2_similarity_clear",
+            ),
+            Route::with_handler_and_name(
+                "/v2/api/federation/sync",
+                cot::router::method::post(move |session: Session, db: Database| async move {
+                    v2::federation_sync(session, db).await
+                }),
+                "admin_v2_federation_sync",
+            ),
+            Route::with_handler_and_name(
+                "/v2/api/federation/ticket",
+                get(move |session: Session, db: Database| async move {
+                    v2::federation_ticket(session, db).await
+                }),
+                "admin_v2_federation_ticket",
+            ),
+            Route::with_handler_and_name(
+                "/v2/api/federation/connect",
+                cot::router::method::post(
+                    move |session: Session,
+                          db: Database,
+                          json: Json<v2::FederationConnectRequest>| async move {
+                        v2::federation_connect(session, db, json).await
+                    },
+                ),
+                "admin_v2_federation_connect",
+            ),
             Route::with_handler_and_name(
                 "/v2/api/jobs/{name}/toggle",
                 cot::router::method::post({

src/admin/v2.rs

@@ -448,6 +448,20 @@ struct AdminSettingsValues {
     agent_confidence_threshold: String,
     agent_context_limit: String,
     agent_concurrency: String,
+    #[serde(default)]
+    federation_enabled: bool,
+    #[serde(default)]
+    federation_network_id: String,
+    #[serde(default)]
+    federation_save_on_listen: bool,
+    #[serde(default)]
+    similarity_enabled: bool,
+    #[serde(default = "default_similarity_model")]
+    similarity_model: String,
+    #[serde(default = "default_similarity_profile")]
+    similarity_profile: String,
+    #[serde(default = "default_similarity_workers")]
+    similarity_workers: String,
 }
 
 #[derive(Debug, Clone, Serialize, JsonSchema)]
@@ -472,6 +486,13 @@ struct AdminSettingsSources {
     agent_confidence_threshold: &'static str,
     agent_context_limit: &'static str,
     agent_concurrency: &'static str,
+    federation_enabled: &'static str,
+    federation_network_id: &'static str,
+    federation_save_on_listen: &'static str,
+    similarity_enabled: &'static str,
+    similarity_model: &'static str,
+    similarity_profile: &'static str,
+    similarity_workers: &'static str,
 }
 
 #[derive(Debug, Deserialize)]
@@ -496,6 +517,32 @@ pub(super) struct UpdateSettingsRequest {
     agent_confidence_threshold: String,
     agent_context_limit: String,
     agent_concurrency: String,
+    #[serde(default)]
+    federation_enabled: bool,
+    #[serde(default)]
+    federation_network_id: String,
+    #[serde(default)]
+    federation_save_on_listen: bool,
+    #[serde(default)]
+    similarity_enabled: bool,
+    #[serde(default = "default_similarity_model")]
+    similarity_model: String,
+    #[serde(default = "default_similarity_profile")]
+    similarity_profile: String,
+    #[serde(default = "default_similarity_workers")]
+    similarity_workers: String,
+}
+
+fn default_similarity_model() -> String {
+    crate::similarity::DEFAULT_MODEL_ID.to_owned()
+}
+
+fn default_similarity_profile() -> String {
+    crate::similarity::DEFAULT_PROFILE_ID.to_owned()
+}
+
+fn default_similarity_workers() -> String {
+    "1".to_owned()
 }
 
 #[derive(Debug, Serialize, JsonSchema)]
@@ -933,6 +980,29 @@ pub async fn update_settings(
     if let Err(response) = require_admin_json(&session, &db).await {
         return Ok(response);
     }
+    let similarity_model = body.similarity_model.trim();
+    if crate::similarity::model_by_id(similarity_model).is_none() {
+        return Ok(json_error(
+            StatusCode::BAD_REQUEST,
+            "unknown similarity model",
+        ));
+    }
+    let similarity_profile = body.similarity_profile.trim();
+    if crate::similarity::profile_by_id(similarity_profile).is_none() {
+        return Ok(json_error(
+            StatusCode::BAD_REQUEST,
+            "unknown similarity preprocessing profile",
+        ));
+    }
+    let similarity_workers = match body.similarity_workers.trim().parse::<u64>() {
+        Ok(workers @ 1..=16) => workers,
+        _ => {
+            return Ok(json_error(
+                StatusCode::BAD_REQUEST,
+                "similarity workers must be an integer from 1 to 16",
+            ));
+        }
+    };
     let fields = [
         (
             "auth_password_enabled",
@@ -978,6 +1048,19 @@ pub async fn update_settings(
             "agent_concurrency",
             body.agent_concurrency.trim().to_string(),
         ),
+        ("federation_enabled", body.federation_enabled.to_string()),
+        (
+            "federation_network_id",
+            body.federation_network_id.trim().to_string(),
+        ),
+        (
+            "federation_save_on_listen",
+            body.federation_save_on_listen.to_string(),
+        ),
+        ("similarity_enabled", body.similarity_enabled.to_string()),
+        ("similarity_model", similarity_model.to_string()),
+        ("similarity_profile", similarity_profile.to_string()),
+        ("similarity_workers", similarity_workers.to_string()),
     ];
     for (key, value) in fields {
         let mut entry = ConfigEntry::new(key.to_string(), value);
@@ -986,9 +1069,130 @@ pub async fn update_settings(
             .await
             .map_err(|e| cot::Error::internal(e.to_string()))?;
     }
+    // Federation applies on the fly: (re)start or stop the node to match
+    // the freshly saved settings — no server restart involved.
+    let (fresh, _) = AppConfig::load_with_db(&db).await;
+    tokio::spawn(async move {
+        crate::similarity::handle().apply(&fresh);
+        crate::federation::handle().apply(&fresh).await;
+    });
     Json(serde_json::json!({ "ok": true })).into_response()
 }
 
+// ---------------------------------------------------------------------------
+// Federation (status + manual controls)
+// ---------------------------------------------------------------------------
+
+pub async fn federation_status(
+    session: Session,
+    db: Database,
+) -> cot::Result<cot::response::Response> {
+    if let Err(response) = require_admin_json(&session, &db).await {
+        return Ok(response);
+    }
+    Json(crate::federation::handle().status().await).into_response()
+}
+
+pub async fn similarity_status(
+    session: Session,
+    db: Database,
+) -> cot::Result<cot::response::Response> {
+    if let Err(response) = require_admin_json(&session, &db).await {
+        return Ok(response);
+    }
+    let manager = crate::similarity::handle();
+    let status = manager.status();
+    let model_id = if status.model.is_empty() {
+        crate::similarity::DEFAULT_MODEL_ID
+    } else {
+        &status.model
+    };
+    let profiles = crate::similarity::PROFILES
+        .iter()
+        .map(|profile| {
+            serde_json::json!({
+                "id": profile.id,
+                "title": profile.title,
+                "details": crate::similarity::profile_details(
+                    profile.id,
+                    model_id,
+                ).unwrap_or_default(),
+            })
+        })
+        .collect::<Vec<_>>();
+    Json(serde_json::json!({
+        "status": status,
+        "models": crate::similarity::MODELS,
+        "profiles": profiles,
+    }))
+    .into_response()
+}
+
+pub async fn similarity_clear(
+    session: Session,
+    db: Database,
+) -> cot::Result<cot::response::Response> {
+    if let Err(response) = require_admin_json(&session, &db).await {
+        return Ok(response);
+    }
+    match crate::similarity::handle().clear().await {
+        Ok(()) => Json(serde_json::json!({ "ok": true })).into_response(),
+        Err(error) => Ok(json_error(
+            StatusCode::INTERNAL_SERVER_ERROR,
+            &format!("embedding cleanup failed: {error:#}"),
+        )),
+    }
+}
+
+pub async fn federation_sync(
+    session: Session,
+    db: Database,
+) -> cot::Result<cot::response::Response> {
+    if let Err(response) = require_admin_json(&session, &db).await {
+        return Ok(response);
+    }
+    let fed = crate::federation::handle();
+    if let Err(err) = fed.sync_now().await {
+        return Ok(json_error(
+            StatusCode::BAD_REQUEST,
+            &format!("sync failed: {err:#}"),
+        ));
+    }
+    Json(fed.status().await).into_response()
+}
+
+pub async fn federation_ticket(
+    session: Session,
+    db: Database,
+) -> cot::Result<cot::response::Response> {
+    if let Err(response) = require_admin_json(&session, &db).await {
+        return Ok(response);
+    }
+    match crate::federation::handle().ticket().await {
+        Ok(ticket) => Json(serde_json::json!({ "ticket": ticket })).into_response(),
+        Err(err) => Ok(json_error(StatusCode::BAD_REQUEST, &format!("{err:#}"))),
+    }
+}
+
+#[derive(Debug, Deserialize, JsonSchema)]
+pub(super) struct FederationConnectRequest {
+    ticket: String,
+}
+
+pub async fn federation_connect(
+    session: Session,
+    db: Database,
+    Json(body): Json<FederationConnectRequest>,
+) -> cot::Result<cot::response::Response> {
+    if let Err(response) = require_admin_json(&session, &db).await {
+        return Ok(response);
+    }
+    match crate::federation::handle().connect(&body.ticket).await {
+        Ok(peer) => Json(serde_json::json!({ "connected": peer })).into_response(),
+        Err(err) => Ok(json_error(StatusCode::BAD_REQUEST, &format!("{err:#}"))),
+    }
+}
+
 pub async fn settings_probe(
     session: Session,
     db: Database,
@@ -1057,6 +1261,13 @@ fn settings_dto(config: AppConfig, sources: ConfigSources) -> AdminSettingsDto {
             agent_confidence_threshold: config.agent_confidence_threshold.to_string(),
             agent_context_limit: config.agent_context_limit.to_string(),
             agent_concurrency: config.agent_concurrency.to_string(),
+            federation_enabled: config.federation_enabled,
+            federation_network_id: config.federation_network_id,
+            federation_save_on_listen: config.federation_save_on_listen,
+            similarity_enabled: config.similarity_enabled,
+            similarity_model: config.similarity_model,
+            similarity_profile: config.similarity_profile,
+            similarity_workers: config.similarity_workers.to_string(),
         },
         sources: AdminSettingsSources {
             auth_password_enabled: sources.auth_password_enabled.code(),
@@ -1079,6 +1290,13 @@ fn settings_dto(config: AppConfig, sources: ConfigSources) -> AdminSettingsDto {
             agent_confidence_threshold: sources.agent_confidence_threshold.code(),
             agent_context_limit: sources.agent_context_limit.code(),
             agent_concurrency: sources.agent_concurrency.code(),
+            federation_enabled: sources.federation_enabled.code(),
+            federation_network_id: sources.federation_network_id.code(),
+            federation_save_on_listen: sources.federation_save_on_listen.code(),
+            similarity_enabled: sources.similarity_enabled.code(),
+            similarity_model: sources.similarity_model.code(),
+            similarity_profile: sources.similarity_profile.code(),
+            similarity_workers: sources.similarity_workers.code(),
         },
     }
 }

src/config.rs

@@ -135,6 +135,13 @@ pub struct ConfigSources {
     pub agent_concurrency: ConfigSource,
     pub lastfm_api_key: ConfigSource,
     pub lastfm_shared_secret: ConfigSource,
+    pub federation_enabled: ConfigSource,
+    pub federation_network_id: ConfigSource,
+    pub federation_save_on_listen: ConfigSource,
+    pub similarity_enabled: ConfigSource,
+    pub similarity_model: ConfigSource,
+    pub similarity_profile: ConfigSource,
+    pub similarity_workers: ConfigSource,
 }
 
 impl Default for ConfigSources {
@@ -162,6 +169,13 @@ impl Default for ConfigSources {
             agent_concurrency: ConfigSource::Default,
             lastfm_api_key: ConfigSource::Default,
             lastfm_shared_secret: ConfigSource::Default,
+            federation_enabled: ConfigSource::Default,
+            federation_network_id: ConfigSource::Default,
+            federation_save_on_listen: ConfigSource::Default,
+            similarity_enabled: ConfigSource::Default,
+            similarity_model: ConfigSource::Default,
+            similarity_profile: ConfigSource::Default,
+            similarity_workers: ConfigSource::Default,
         }
     }
 }
@@ -270,6 +284,23 @@ pub struct AppConfig {
     pub lastfm_api_key: String,
     /// Last.fm shared secret for authenticated scrobbling calls.
     pub lastfm_shared_secret: String,
+    /// Whether this server participates in the furumi federation (publishes
+    /// its library into the shared DHT and serves audio to peers).
+    pub federation_enabled: bool,
+    /// Federation network id — the shared secret every peer of the network
+    /// uses to find the others.
+    pub federation_network_id: String,
+    /// Whether a federated track requested for playback is imported into the
+    /// shared local library. This is a server-wide administrator policy.
+    pub federation_save_on_listen: bool,
+    /// Whether local embedding calculation and similarity search are enabled.
+    pub similarity_enabled: bool,
+    /// Embedding model selected by the administrator.
+    pub similarity_model: String,
+    /// Audio preprocessing profile selected by the administrator.
+    pub similarity_profile: String,
+    /// Maximum number of concurrent CPU embedding workers.
+    pub similarity_workers: u64,
 }
 
 impl Default for AppConfig {
@@ -297,6 +328,15 @@ impl Default for AppConfig {
             agent_concurrency: 2,
             lastfm_api_key: String::new(),
             lastfm_shared_secret: String::new(),
+            federation_enabled: false,
+            federation_network_id: String::new(),
+            federation_save_on_listen: false,
+            similarity_enabled: false,
+            similarity_model: "discogs-effnet-bsdynamic-1".into(),
+            similarity_profile: "furumi-full-track-v1".into(),
+            similarity_workers: std::thread::available_parallelism()
+                .map(|count| (count.get() / 2).clamp(1, 4) as u64)
+                .unwrap_or(1),
         }
     }
 }
@@ -325,6 +365,13 @@ impl_env_overrides!(
     agent_concurrency,
     lastfm_api_key,
     lastfm_shared_secret,
+    federation_enabled,
+    federation_network_id,
+    federation_save_on_listen,
+    similarity_enabled,
+    similarity_model,
+    similarity_profile,
+    similarity_workers,
 );
 
 impl AppConfig {
@@ -452,6 +499,13 @@ impl AppConfig {
         apply_db_field!(agent_concurrency);
         apply_db_field!(lastfm_api_key);
         apply_db_field!(lastfm_shared_secret);
+        apply_db_field!(federation_enabled);
+        apply_db_field!(federation_network_id);
+        apply_db_field!(federation_save_on_listen);
+        apply_db_field!(similarity_enabled);
+        apply_db_field!(similarity_model);
+        apply_db_field!(similarity_profile);
+        apply_db_field!(similarity_workers);
     }
 }
 
@@ -471,6 +525,13 @@ mod tests {
         let cfg = AppConfig::default();
         assert!(cfg.database_url.is_empty());
         assert_eq!(cfg.log_level, "info");
+        assert!(!cfg.similarity_enabled);
+        assert_eq!(cfg.similarity_model, crate::similarity::DEFAULT_MODEL_ID);
+        assert_eq!(
+            cfg.similarity_profile,
+            crate::similarity::DEFAULT_PROFILE_ID
+        );
+        assert!((1..=4).contains(&cfg.similarity_workers));
     }
 
     #[test]

src/federation/capabilities.rs

@@ -0,0 +1,80 @@
+//! Informational publication of the protocol versions exposed by this peer.
+
+use std::time::Duration;
+
+use anyhow::Result;
+use music_dht::StreamAcceptor;
+use music_dht::capabilities::{
+    CAPABILITIES_PROTOCOL_VERSION, CapabilityManifest, CapabilityMessage, JAM_ID, SIMILARITY_ID,
+    read_message, write_message,
+};
+
+use super::serve::AUDIO_PROTOCOL_VERSION;
+
+fn local_manifest() -> CapabilityManifest {
+    CapabilityManifest::frid("furumusic", env!("CARGO_PKG_VERSION"))
+        // The web server does not expose federation Jam yet.
+        .without_protocol(JAM_ID)
+        .with_protocol("audio", AUDIO_PROTOCOL_VERSION)
+        .with_protocol(
+            SIMILARITY_ID,
+            music_dht::similarity::SIMILARITY_PROTOCOL_VERSION,
+        )
+}
+
+pub async fn serve(mut acceptor: StreamAcceptor) {
+    while let Some(stream) = acceptor.accept().await {
+        tokio::spawn(async move {
+            if let Err(error) = serve_one(stream).await {
+                tracing::debug!("capability stream failed: {error:#}");
+            }
+        });
+    }
+}
+
+async fn serve_one(mut stream: music_dht::ByteStream) -> Result<()> {
+    let response = match read_message(&mut stream).await? {
+        CapabilityMessage::Get {
+            version: CAPABILITIES_PROTOCOL_VERSION,
+        } => CapabilityMessage::Manifest {
+            manifest: local_manifest(),
+        },
+        CapabilityMessage::Get { version } => CapabilityMessage::Error {
+            message: format!("unsupported capability protocol {version}"),
+        },
+        _ => CapabilityMessage::Error {
+            message: "expected capability request".to_string(),
+        },
+    };
+    write_message(&mut stream, &response).await?;
+    stream.send.finish()?;
+    let _ = tokio::time::timeout(Duration::from_secs(2), stream.send.stopped()).await;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn manifest_describes_only_supported_player_protocols() {
+        let manifest = local_manifest();
+        assert_eq!(manifest.application, "furumusic");
+        assert_eq!(
+            manifest.protocols.get("audio"),
+            Some(&AUDIO_PROTOCOL_VERSION)
+        );
+        assert!(!manifest.protocols.contains_key(JAM_ID));
+        assert_eq!(
+            manifest.protocols.get(SIMILARITY_ID),
+            Some(&music_dht::similarity::SIMILARITY_PROTOCOL_VERSION)
+        );
+        assert_eq!(
+            manifest
+                .protocols
+                .get(music_dht::capabilities::SIMILARITY_DHT_ID),
+            Some(&music_dht::similarity_lsh::SIMILARITY_DHT_PROTOCOL_VERSION)
+        );
+        manifest.validate().unwrap();
+    }
+}

src/federation/client.rs

@@ -0,0 +1,600 @@
+//! Receiving side of music federation.
+//!
+//! User-facing identity is content-addressed. An `(owner, item_id)` pair is
+//! only a source locator and several locators may resolve the same track.
+
+use std::collections::HashMap;
+
+use anyhow::{Context, Result};
+use music_dht::{ItemKind, LibraryItem, normalize_content_id};
+use serde::Serialize;
+use serde_json::{Value, json};
+use sqlx::Row as _;
+use tokio::io::AsyncReadExt;
+
+use super::{Federation, now_iso};
+
+const MAX_CATALOG_BYTES: u64 = 4 * 1024 * 1024;
+
+#[derive(Debug, Clone, Serialize)]
+pub struct TrackKeyDto {
+    pub content_id: String,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct ArtistKeyDto {
+    pub normalized_name: String,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct ArtistRefDto {
+    pub key: ArtistKeyDto,
+    pub name: String,
+    pub local_id: Option<i64>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct ReleaseKeyDto {
+    pub normalized_title: String,
+    pub primary_artists: Vec<String>,
+    pub release_type: Option<String>,
+    pub year: Option<i32>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct ReleaseRefDto {
+    pub key: ReleaseKeyDto,
+    pub local_id: Option<i64>,
+    pub title: String,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct FederationSourceDto {
+    pub owner: String,
+    pub item_id: String,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct LocalAvailabilityDto {
+    pub track_id: i64,
+    pub stream_url: String,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct TrackMetadataDto {
+    pub title: String,
+    pub artists: Vec<ArtistRefDto>,
+    pub featured_artists: Vec<ArtistRefDto>,
+    pub release: Option<ReleaseRefDto>,
+    pub year: Option<i32>,
+    pub duration_seconds: Option<f64>,
+    pub track_number: Option<i32>,
+    pub disc_number: Option<i32>,
+    pub cover_url: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct TrackAvailabilityDto {
+    pub state: &'static str,
+    pub local: Option<LocalAvailabilityDto>,
+    pub federation: Vec<FederationSourceDto>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct TrackDto {
+    pub key: TrackKeyDto,
+    pub metadata: TrackMetadataDto,
+    pub availability: TrackAvailabilityDto,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub similarity_score: Option<f32>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct SearchEvent {
+    pub search_id: String,
+    pub sequence: u64,
+    pub kind: &'static str,
+    pub peer: Option<String>,
+    pub entity_key: Value,
+    pub entity: Value,
+}
+
+impl Federation {
+    pub async fn prepare_similarity_tracks(
+        &self,
+        tracks: Vec<super::similarity::RemoteSimilarityTrack>,
+    ) -> Result<Vec<TrackDto>> {
+        let pool = self.pool().await?;
+        let mut prepared = Vec::new();
+        for track in tracks {
+            let Some(content_id) = track.content_id.as_deref().and_then(normalize_content_id)
+            else {
+                continue;
+            };
+            let local = local_availability(&pool, &content_id).await?;
+            // A local result is already present in the first result section.
+            if local.is_some() {
+                continue;
+            }
+            let owner = track.owner;
+            let item_id = track.item_id;
+            let dto = TrackDto {
+                key: TrackKeyDto {
+                    content_id: content_id.clone(),
+                },
+                metadata: TrackMetadataDto {
+                    title: track.title,
+                    artists: artist_refs(&track.artist_names),
+                    featured_artists: artist_refs(&track.featured_artist_names),
+                    release: track.release_title.map(|title| ReleaseRefDto {
+                        key: ReleaseKeyDto {
+                            normalized_title: music_dht::normalize_name(&title),
+                            primary_artists: track
+                                .artist_names
+                                .iter()
+                                .map(|artist| music_dht::normalize_name(artist))
+                                .collect(),
+                            release_type: None,
+                            year: track.year,
+                        },
+                        local_id: None,
+                        title,
+                    }),
+                    year: track.year,
+                    duration_seconds: track.duration_seconds.map(|value| value as f64),
+                    track_number: track.track_number,
+                    disc_number: track.disc_number,
+                    cover_url: Some(format!(
+                        "/api/player/federation/tracks/artwork?owner={owner}&item_id={item_id}"
+                    )),
+                },
+                availability: TrackAvailabilityDto {
+                    state: "federated",
+                    local: None,
+                    federation: vec![FederationSourceDto { owner, item_id }],
+                },
+                similarity_score: Some(track.similarity_score),
+            };
+            persist_track_ref(&pool, &dto).await?;
+            prepared.push(dto);
+        }
+        Ok(prepared)
+    }
+
+    pub fn stream_artist_catalogs(
+        self: &std::sync::Arc<Self>,
+        name: String,
+    ) -> tokio::sync::mpsc::UnboundedReceiver<Result<(String, music_dht::catalog::CatalogArtist)>>
+    {
+        let (sender, receiver) = tokio::sync::mpsc::unbounded_channel();
+        let federation = std::sync::Arc::clone(self);
+        tokio::spawn(async move {
+            let result = async {
+                let service = federation.service().await?;
+                let normalized = music_dht::normalize_name(&name);
+                let outcome = service
+                    .search_network(&name)
+                    .await
+                    .map_err(|err| anyhow::anyhow!("federated artist search failed: {err}"))?;
+                let owners: std::collections::HashSet<_> = outcome
+                    .network_results
+                    .iter()
+                    .filter(|item| {
+                        (item.kind == ItemKind::Artist && item.normalized_name == normalized)
+                            || item
+                                .artist_names
+                                .iter()
+                                .chain(&item.featured_artist_names)
+                                .any(|artist| music_dht::normalize_name(artist) == normalized)
+                    })
+                    .map(|item| item.owner)
+                    .collect();
+                for owner in owners {
+                    let service = std::sync::Arc::clone(&service);
+                    let sender = sender.clone();
+                    let name = name.clone();
+                    tokio::spawn(async move {
+                        let result = tokio::time::timeout(
+                            std::time::Duration::from_secs(8),
+                            fetch_artist_catalog(&service, owner, &name),
+                        )
+                        .await
+                        .map_err(|_| anyhow::anyhow!("catalog request timed out"))
+                        .and_then(|result| result)
+                        .map(|artist| (owner.to_string(), artist));
+                        let _ = sender.send(result);
+                    });
+                }
+                Ok::<(), anyhow::Error>(())
+            }
+            .await;
+            if let Err(err) = result {
+                let _ = sender.send(Err(err));
+            }
+        });
+        receiver
+    }
+
+    /// Performs one bounded DHT search and returns entity upserts. The HTTP
+    /// layer streams each upsert independently; catalog fan-out can append
+    /// events to the same contract without changing the browser model.
+    pub async fn search_events(&self, search_id: &str, query: &str) -> Result<Vec<SearchEvent>> {
+        let query = query.trim();
+        anyhow::ensure!(!query.is_empty(), "search query is empty");
+        anyhow::ensure!(query.chars().count() <= 200, "search query is too long");
+
+        let started = std::time::Instant::now();
+        let service = self.service().await?;
+        tracing::info!(
+            search_id,
+            query,
+            connected_peers = service.connected_peers().len(),
+            known_contacts = service.known_peers().len(),
+            "federated search started"
+        );
+        let own = service.endpoint_id();
+        let result = tokio::time::timeout(
+            std::time::Duration::from_secs(20),
+            service.search_network(query),
+        )
+        .await
+        .map_err(|_| anyhow::anyhow!("federated search timed out after 20 seconds"))?
+        .map_err(|err| anyhow::anyhow!("federated search failed: {err}"))?;
+        tracing::info!(
+            search_id,
+            query,
+            local_results = result.local_results.len(),
+            network_results = result.network_results.len(),
+            queried_nodes = result.queried_nodes,
+            elapsed_ms = started.elapsed().as_millis() as u64,
+            "federated DHT search finished"
+        );
+        let all_items: Vec<LibraryItem> = result
+            .local_results
+            .into_iter()
+            .chain(result.network_results)
+            .collect();
+
+        let pool = self.pool().await?;
+        let mut by_content: HashMap<String, TrackDto> = HashMap::new();
+        for item in all_items.iter().filter(|item| item.kind == ItemKind::Track) {
+            let Some(content_id) = item.content_id.as_deref().and_then(normalize_content_id) else {
+                // A globally usable track reference must be verifiable.
+                continue;
+            };
+            let local = local_availability(&pool, &content_id).await?;
+            let source = FederationSourceDto {
+                owner: item.owner.to_string(),
+                item_id: hex(item.id.as_bytes()),
+            };
+            let entry = by_content.entry(content_id.clone()).or_insert_with(|| {
+                track_from_item(content_id.clone(), item, local, item.owner == own)
+            });
+            if !entry.availability.federation.iter().any(|candidate| {
+                candidate.owner == source.owner && candidate.item_id == source.item_id
+            }) {
+                entry.availability.federation.push(source);
+            }
+            if entry.availability.local.is_some() {
+                entry.availability.state = "local";
+            }
+        }
+
+        let mut tracks: Vec<_> = by_content.into_values().collect();
+        tracks.sort_by(|left, right| {
+            left.metadata
+                .title
+                .to_lowercase()
+                .cmp(&right.metadata.title.to_lowercase())
+        });
+
+        let mut events = Vec::with_capacity(all_items.len());
+        for (index, track) in tracks.into_iter().enumerate() {
+            persist_track_ref(&pool, &track).await?;
+            let peer = track
+                .availability
+                .federation
+                .first()
+                .map(|source| source.owner.clone());
+            events.push(SearchEvent {
+                search_id: search_id.to_owned(),
+                sequence: index as u64 + 1,
+                kind: "federation.track",
+                peer,
+                entity_key: serde_json::to_value(&track.key)?,
+                entity: serde_json::to_value(track)?,
+            });
+        }
+        let mut artist_peers: HashMap<String, (String, Vec<String>)> = HashMap::new();
+        let mut releases: HashMap<String, Value> = HashMap::new();
+        for item in &all_items {
+            match item.kind {
+                ItemKind::Artist => {
+                    let key = music_dht::normalize_name(&item.name);
+                    let entry = artist_peers
+                        .entry(key)
+                        .or_insert_with(|| (item.name.clone(), Vec::new()));
+                    let owner = item.owner.to_string();
+                    if !entry.1.contains(&owner) {
+                        entry.1.push(owner);
+                    }
+                }
+                ItemKind::Release => {
+                    let artist_keys: Vec<String> = item
+                        .artist_names
+                        .iter()
+                        .map(|name| music_dht::normalize_name(name))
+                        .collect();
+                    let normalized_title = music_dht::normalize_name(&item.name);
+                    let cover_url = all_items
+                        .iter()
+                        .find(|track| {
+                            track.kind == ItemKind::Track
+                                && track.release_title.as_deref().is_some_and(|title| {
+                                    music_dht::normalize_name(title) == normalized_title
+                                })
+                                && track.year == item.year
+                        })
+                        .map(|track| {
+                            format!(
+                                "/api/player/federation/tracks/artwork?owner={}&item_id={}",
+                                track.owner,
+                                hex(track.id.as_bytes())
+                            )
+                        });
+                    let key = format!(
+                        "{}|{}|{}",
+                        normalized_title,
+                        artist_keys.join(","),
+                        item.year.map_or_else(String::new, |year| year.to_string())
+                    );
+                    releases.entry(key.clone()).or_insert_with(|| {
+                        json!({
+                            "key": {
+                                "normalized_title": music_dht::normalize_name(&item.name),
+                                "primary_artists": artist_keys,
+                                "release_type": null,
+                                "year": item.year,
+                            },
+                            "title": item.name,
+                            "artists": item.artist_names,
+                            "year": item.year,
+                            "cover_url": cover_url,
+                            "sources": [{
+                                "owner": item.owner.to_string(),
+                                "item_id": hex(item.id.as_bytes()),
+                            }],
+                        })
+                    });
+                }
+                ItemKind::Track => {}
+            }
+        }
+        for (key, (name, peers)) in artist_peers {
+            let sequence = events.len() as u64 + 1;
+            events.push(SearchEvent {
+                search_id: search_id.to_owned(),
+                sequence,
+                kind: "federation.artist",
+                peer: peers.first().cloned(),
+                entity_key: json!({ "normalized_name": key }),
+                entity: json!({
+                    "key": { "normalized_name": key },
+                    "name": name,
+                    "image_url": null,
+                    "peers": peers,
+                }),
+            });
+        }
+        for (key, release) in releases {
+            let sequence = events.len() as u64 + 1;
+            events.push(SearchEvent {
+                search_id: search_id.to_owned(),
+                sequence,
+                kind: "federation.release",
+                peer: None,
+                entity_key: json!({ "composite": key }),
+                entity: release,
+            });
+        }
+        tracing::info!(
+            search_id,
+            query,
+            events = events.len(),
+            elapsed_ms = started.elapsed().as_millis() as u64,
+            "federated search response ready"
+        );
+        Ok(events)
+    }
+}
+
+async fn fetch_artist_catalog(
+    service: &music_dht::MusicDhtService,
+    owner: music_dht::EndpointId,
+    artist: &str,
+) -> Result<music_dht::catalog::CatalogArtist> {
+    let mut stream = service
+        .open_stream(owner, super::CATALOG_ALPN)
+        .await
+        .map_err(|err| anyhow::anyhow!("cannot reach catalog peer: {err}"))?;
+    let mut request = serde_json::to_vec(&music_dht::catalog::CatalogRequest {
+        artist: artist.to_owned(),
+        want: Some("catalog".to_owned()),
+        ..Default::default()
+    })?;
+    request.push(b'\n');
+    stream.send.write_all(&request).await?;
+    stream.send.finish()?;
+    let mut payload = Vec::new();
+    stream
+        .recv
+        .take(MAX_CATALOG_BYTES + 1)
+        .read_to_end(&mut payload)
+        .await?;
+    anyhow::ensure!(
+        payload.len() as u64 <= MAX_CATALOG_BYTES,
+        "catalog response is too large"
+    );
+    let response: music_dht::catalog::CatalogResponse =
+        serde_json::from_slice(&payload).context("invalid catalog response")?;
+    anyhow::ensure!(
+        response.ok,
+        "peer refused catalog: {}",
+        response.error.unwrap_or_else(|| "unknown error".to_owned())
+    );
+    response.artist.context("peer returned no artist catalog")
+}
+
+fn track_from_item(
+    content_id: String,
+    item: &LibraryItem,
+    local: Option<LocalAvailabilityDto>,
+    own: bool,
+) -> TrackDto {
+    let owner = item.owner.to_string();
+    let item_id = hex(item.id.as_bytes());
+    let artists = artist_refs(&item.artist_names);
+    let featured_artists = artist_refs(&item.featured_artist_names);
+    let release = item.release_title.as_ref().map(|title| ReleaseRefDto {
+        key: ReleaseKeyDto {
+            normalized_title: music_dht::normalize_name(title),
+            primary_artists: item
+                .artist_names
+                .iter()
+                .map(|artist| music_dht::normalize_name(artist))
+                .collect(),
+            release_type: None,
+            year: item.year,
+        },
+        local_id: None,
+        title: title.clone(),
+    });
+    let state = if local.is_some() || own {
+        "local"
+    } else {
+        "federated"
+    };
+    TrackDto {
+        key: TrackKeyDto { content_id },
+        metadata: TrackMetadataDto {
+            title: item.name.clone(),
+            artists,
+            featured_artists,
+            release,
+            year: item.year,
+            duration_seconds: item.duration_seconds,
+            track_number: item.track_number,
+            disc_number: item.disc_number,
+            cover_url: Some(format!(
+                "/api/player/federation/tracks/artwork?owner={owner}&item_id={item_id}"
+            )),
+        },
+        availability: TrackAvailabilityDto {
+            state,
+            local,
+            federation: vec![FederationSourceDto { owner, item_id }],
+        },
+        similarity_score: None,
+    }
+}
+
+fn artist_refs(names: &[String]) -> Vec<ArtistRefDto> {
+    names
+        .iter()
+        .map(|name| ArtistRefDto {
+            key: ArtistKeyDto {
+                normalized_name: music_dht::normalize_name(name),
+            },
+            name: name.clone(),
+            local_id: None,
+        })
+        .collect()
+}
+
+async fn local_availability(
+    pool: &sqlx::PgPool,
+    content_id: &str,
+) -> Result<Option<LocalAvailabilityDto>> {
+    let row = sqlx::query(
+        "SELECT t.id
+           FROM furumusic__federation_content_id_cache c
+           JOIN furumusic__track t ON t.audio_file_id = c.media_file_id
+          WHERE c.content_id = $1 AND t.is_hidden = false
+          LIMIT 1",
+    )
+    .bind(content_id)
+    .fetch_optional(pool)
+    .await?;
+    Ok(row.map(|row| {
+        let track_id: i64 = row.get(0);
+        LocalAvailabilityDto {
+            track_id,
+            stream_url: format!("/api/player/stream/{track_id}"),
+        }
+    }))
+}
+
+async fn persist_track_ref(pool: &sqlx::PgPool, track: &TrackDto) -> Result<()> {
+    let metadata = serde_json::to_value(&track.metadata)?;
+    let local_id = track
+        .availability
+        .local
+        .as_ref()
+        .map(|local| local.track_id);
+    let row = sqlx::query(
+        "INSERT INTO furumusic__track_ref
+            (content_id, local_track_id, title, release_title, year,
+             duration_seconds, metadata_json, metadata_authority, created_at, updated_at)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, 'federation', $8, $8)
+         ON CONFLICT (content_id) DO UPDATE SET
+            local_track_id = COALESCE(furumusic__track_ref.local_track_id, EXCLUDED.local_track_id),
+            title = EXCLUDED.title,
+            release_title = EXCLUDED.release_title,
+            year = EXCLUDED.year,
+            duration_seconds = EXCLUDED.duration_seconds,
+            metadata_json = EXCLUDED.metadata_json,
+            updated_at = EXCLUDED.updated_at
+         RETURNING id",
+    )
+    .bind(&track.key.content_id)
+    .bind(local_id)
+    .bind(&track.metadata.title)
+    .bind(
+        track
+            .metadata
+            .release
+            .as_ref()
+            .map(|release| &release.title),
+    )
+    .bind(track.metadata.year)
+    .bind(track.metadata.duration_seconds)
+    .bind(metadata)
+    .bind(now_iso())
+    .fetch_one(pool)
+    .await
+    .context("persisting content-addressed track reference failed")?;
+    let track_ref_id: i64 = row.get(0);
+    for source in &track.availability.federation {
+        sqlx::query(
+            "INSERT INTO furumusic__federation_track_source
+                (track_ref_id, owner_peer_id, item_id, last_seen_ms, metadata_json)
+             VALUES ($1, $2, $3, $4, $5)
+             ON CONFLICT (owner_peer_id, item_id) DO UPDATE SET
+                track_ref_id = EXCLUDED.track_ref_id,
+                last_seen_ms = EXCLUDED.last_seen_ms,
+                metadata_json = EXCLUDED.metadata_json",
+        )
+        .bind(track_ref_id)
+        .bind(&source.owner)
+        .bind(&source.item_id)
+        .bind(chrono::Utc::now().timestamp_millis())
+        .bind(json!({ "track": track.metadata }))
+        .execute(pool)
+        .await?;
+    }
+    Ok(())
+}
+
+fn hex(bytes: &[u8]) -> String {
+    bytes.iter().map(|byte| format!("{byte:02x}")).collect()
+}

src/federation/serve.rs

@@ -0,0 +1,775 @@
+//! Serve side of the federation wire protocols (audio + catalog), backed by
+//! the PostgreSQL library and the media storage directory. Wire compatible
+//! with the furumi TUI client and any other furumi peer.
+
+use std::path::{Path, PathBuf};
+use std::sync::Arc;
+
+use anyhow::Result;
+pub use music_dht::catalog::CATALOG_ALPN;
+use music_dht::catalog::{
+    CatalogArtist, CatalogArtistPreview, CatalogImageHeader as ImageHeader, CatalogRelease,
+    CatalogRequest, CatalogResponse, CatalogTrack,
+};
+use music_dht::{ByteStream, EndpointId, ItemId, ItemKind, StreamAcceptor, normalize_name};
+use serde::{Deserialize, Serialize};
+use sqlx::PgPool;
+use sqlx::Row as _;
+use tokio::io::{AsyncRead, AsyncReadExt, AsyncSeekExt, AsyncWriteExt};
+
+use super::{TransportStats, record_stream_transport};
+
+/// ALPN of the peer-to-peer audio streaming protocol.
+pub const AUDIO_ALPN: &[u8] = b"furumi-fd/audio/1";
+/// Version of the peer-to-peer audio streaming protocol.
+pub const AUDIO_PROTOCOL_VERSION: u16 = 1;
+
+/// Maximum size of a JSON protocol line (request or response header).
+const MAX_PROTOCOL_LINE: usize = 4096;
+/// Images above this size are skipped rather than transferred.
+const MAX_IMAGE_BYTES: u64 = 16 * 1024 * 1024;
+
+// ---------------------------------------------------------------------------
+// Wire shapes (shared with the furumi TUI client)
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Deserialize)]
+struct AudioRequest {
+    item_id: String,
+    #[serde(default)]
+    offset: u64,
+    #[serde(default)]
+    want_cover: bool,
+}
+
+#[derive(Debug, Default, Serialize)]
+struct AudioResponseHeader {
+    ok: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    error: Option<String>,
+    mime_type: String,
+    total_size: u64,
+    offset: u64,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    metadata: Option<TrackMetadata>,
+    cover_size: u64,
+    cover_mime: String,
+    artist_image_size: u64,
+    artist_image_mime: String,
+}
+
+#[derive(Debug, Clone, Default, Serialize)]
+struct TrackMetadata {
+    title: String,
+    artists: Vec<String>,
+    featured_artists: Vec<String>,
+    album_artists: Vec<String>,
+    release_title: String,
+    release_type: Option<String>,
+    year: Option<i32>,
+    track_number: Option<i32>,
+    disc_number: Option<i32>,
+}
+
+// ---------------------------------------------------------------------------
+// Framing helpers
+// ---------------------------------------------------------------------------
+
+fn hex_encode(bytes: &[u8]) -> String {
+    bytes.iter().map(|b| format!("{b:02x}")).collect()
+}
+
+fn hex_decode_item_id(value: &str) -> Option<ItemId> {
+    if value.len() != 64 {
+        return None;
+    }
+    let mut bytes = [0u8; 32];
+    for (i, byte) in bytes.iter_mut().enumerate() {
+        *byte = u8::from_str_radix(&value[i * 2..i * 2 + 2], 16).ok()?;
+    }
+    Some(ItemId::from_bytes(bytes))
+}
+
+async fn read_line<R: AsyncRead + Unpin>(reader: &mut R) -> Result<Vec<u8>> {
+    let mut line = Vec::new();
+    let mut byte = [0u8; 1];
+    loop {
+        let n = reader.read(&mut byte).await?;
+        if n == 0 {
+            anyhow::bail!("stream ended before the protocol line was complete");
+        }
+        if byte[0] == b'\n' {
+            return Ok(line);
+        }
+        line.push(byte[0]);
+        if line.len() > MAX_PROTOCOL_LINE {
+            anyhow::bail!("protocol line exceeds {MAX_PROTOCOL_LINE} bytes");
+        }
+    }
+}
+
+async fn write_line<W: AsyncWriteExt + Unpin>(
+    writer: &mut W,
+    value: &impl Serialize,
+) -> Result<()> {
+    let mut line = serde_json::to_vec(value)?;
+    line.push(b'\n');
+    writer.write_all(&line).await?;
+    Ok(())
+}
+
+fn item_id_of(own: &EndpointId, track_id: i64) -> String {
+    hex_encode(ItemId::derive(own, ItemKind::Track, &format!("track:{track_id}")).as_bytes())
+}
+
+fn resolve_media_path(storage_dir: &str, file_path: &str) -> PathBuf {
+    crate::media_paths::resolve_media_file_path(storage_dir, file_path)
+}
+
+fn guess_mime(path: &Path) -> &'static str {
+    match path
+        .extension()
+        .and_then(|e| e.to_str())
+        .unwrap_or_default()
+        .to_ascii_lowercase()
+        .as_str()
+    {
+        "mp3" => "audio/mpeg",
+        "flac" => "audio/flac",
+        "ogg" | "oga" => "audio/ogg",
+        "opus" => "audio/opus",
+        "wav" => "audio/wav",
+        "m4a" | "mp4" | "alac" => "audio/mp4",
+        "aac" => "audio/aac",
+        "aiff" | "aif" => "audio/aiff",
+        _ => "application/octet-stream",
+    }
+}
+
+/// Reads an image media file from disk, bounded by [`MAX_IMAGE_BYTES`].
+async fn read_image(
+    storage_dir: &str,
+    media: Option<(String, String)>,
+) -> Option<(Vec<u8>, String)> {
+    let (file_path, mime) = media?;
+    let path = resolve_media_path(storage_dir, &file_path);
+    let size = tokio::fs::metadata(&path).await.ok()?.len();
+    if size == 0 || size > MAX_IMAGE_BYTES {
+        return None;
+    }
+    let bytes = tokio::fs::read(&path).await.ok()?;
+    let mime = if mime.trim().is_empty() {
+        "image/jpeg".to_string()
+    } else {
+        mime
+    };
+    Some((bytes, mime))
+}
+
+// ---------------------------------------------------------------------------
+// Library lookups (PostgreSQL)
+// ---------------------------------------------------------------------------
+
+/// Finds the visible track whose derived DHT item id matches `item_id`.
+async fn resolve_track_id(pool: &PgPool, own: &EndpointId, item_id: ItemId) -> Result<Option<i64>> {
+    let rows = sqlx::query(
+        "SELECT t.id FROM furumusic__track t
+         JOIN furumusic__release r ON r.id = t.release_id
+         WHERE t.is_hidden = false AND r.is_hidden = false",
+    )
+    .fetch_all(pool)
+    .await?;
+    for row in rows {
+        let track_id: i64 = row.get(0);
+        if ItemId::derive(own, ItemKind::Track, &format!("track:{track_id}")) == item_id {
+            return Ok(Some(track_id));
+        }
+    }
+    Ok(None)
+}
+
+/// (file_path, mime_type) of the track's audio media file.
+async fn track_audio_file(pool: &PgPool, track_id: i64) -> Result<Option<(String, String)>> {
+    let row = sqlx::query(
+        "SELECT m.file_path, m.mime_type FROM furumusic__track t
+         JOIN furumusic__media_file m ON m.id = t.audio_file_id
+         WHERE t.id = $1",
+    )
+    .bind(track_id)
+    .fetch_optional(pool)
+    .await?;
+    Ok(row.map(|row| (row.get(0), row.get(1))))
+}
+
+/// Track cover (falling back to the release cover) as (file_path, mime).
+async fn track_cover_file(pool: &PgPool, track_id: i64) -> Result<Option<(String, String)>> {
+    let row = sqlx::query(
+        "SELECT m.file_path, m.mime_type FROM furumusic__track t
+         JOIN furumusic__release r ON r.id = t.release_id
+         JOIN furumusic__media_file m ON m.id = COALESCE(t.cover_file_id, r.cover_file_id)
+         WHERE t.id = $1",
+    )
+    .bind(track_id)
+    .fetch_optional(pool)
+    .await?;
+    Ok(row.map(|row| (row.get(0), row.get(1))))
+}
+
+/// The main artist's image of a track as (file_path, mime).
+async fn track_artist_image_file(pool: &PgPool, track_id: i64) -> Result<Option<(String, String)>> {
+    let row = sqlx::query(
+        "SELECT m.file_path, m.mime_type FROM furumusic__track_artist ta
+         JOIN furumusic__artist a ON a.id = ta.artist_id
+         JOIN furumusic__media_file m ON m.id = a.image_file_id
+         WHERE ta.track_id = $1 AND ta.role = 'main'
+         ORDER BY ta.position LIMIT 1",
+    )
+    .bind(track_id)
+    .fetch_optional(pool)
+    .await?;
+    Ok(row.map(|row| (row.get(0), row.get(1))))
+}
+
+async fn track_catalog_artist_names(
+    pool: &PgPool,
+    track_id: i64,
+) -> Result<(Vec<String>, Vec<String>)> {
+    let mut artists = Vec::new();
+    let mut featured = Vec::new();
+    let rows = sqlx::query(
+        "SELECT a.name, ta.role FROM furumusic__track_artist ta
+         JOIN furumusic__artist a ON a.id = ta.artist_id
+         WHERE ta.track_id = $1 ORDER BY ta.position",
+    )
+    .bind(track_id)
+    .fetch_all(pool)
+    .await?;
+    for row in rows {
+        let name: String = row.get(0);
+        match row.get::<String, _>(1).as_str() {
+            "featuring" => featured.push(name),
+            "main" => artists.push(name),
+            _ => {}
+        }
+    }
+    Ok((artists, featured))
+}
+
+async fn track_metadata(pool: &PgPool, track_id: i64) -> Result<Option<TrackMetadata>> {
+    let Some(track) = sqlx::query(
+        "SELECT t.title, t.track_number, t.disc_number, COALESCE(t.year, r.year),
+                t.release_id, r.title, r.release_type
+         FROM furumusic__track t
+         JOIN furumusic__release r ON r.id = t.release_id
+         WHERE t.id = $1",
+    )
+    .bind(track_id)
+    .fetch_optional(pool)
+    .await?
+    else {
+        return Ok(None);
+    };
+    let release_id: i64 = track.get(4);
+
+    let mut artists = Vec::new();
+    let mut featured = Vec::new();
+    let artist_rows = sqlx::query(
+        "SELECT a.name, ta.role FROM furumusic__track_artist ta
+         JOIN furumusic__artist a ON a.id = ta.artist_id
+         WHERE ta.track_id = $1 ORDER BY ta.position",
+    )
+    .bind(track_id)
+    .fetch_all(pool)
+    .await?;
+    for row in artist_rows {
+        let name: String = row.get(0);
+        match row.get::<String, _>(1).as_str() {
+            "featuring" => featured.push(name),
+            "main" => artists.push(name),
+            _ => {}
+        }
+    }
+    let album_artists: Vec<String> = sqlx::query(
+        "SELECT a.name FROM furumusic__release_artist ra
+         JOIN furumusic__artist a ON a.id = ra.artist_id
+         WHERE ra.release_id = $1 ORDER BY ra.position",
+    )
+    .bind(release_id)
+    .fetch_all(pool)
+    .await?
+    .into_iter()
+    .map(|row| row.get(0))
+    .collect();
+
+    Ok(Some(TrackMetadata {
+        title: track.get(0),
+        artists,
+        featured_artists: featured,
+        album_artists,
+        release_title: track.get(5),
+        release_type: Some(track.get(6)),
+        year: track.get(3),
+        track_number: track.get(1),
+        disc_number: track.get(2),
+    }))
+}
+
+// ---------------------------------------------------------------------------
+// Audio protocol
+// ---------------------------------------------------------------------------
+
+/// Runs the audio accept loop until the acceptor closes. Every visible
+/// track of the library is streamable by every peer of the network.
+pub async fn serve_audio(
+    mut acceptor: StreamAcceptor,
+    pool: PgPool,
+    storage_dir: String,
+    own: EndpointId,
+    transport_stats: Arc<TransportStats>,
+) {
+    while let Some(stream) = acceptor.accept().await {
+        let pool = pool.clone();
+        let storage_dir = storage_dir.clone();
+        let transport_stats = Arc::clone(&transport_stats);
+        tokio::spawn(async move {
+            let peer = stream.peer_id;
+            if let Err(err) = serve_audio_one(stream, pool, storage_dir, own, transport_stats).await
+            {
+                tracing::warn!(peer = %peer, "federation audio stream failed: {err:#}");
+            }
+        });
+    }
+}
+
+async fn serve_audio_one(
+    mut stream: ByteStream,
+    pool: PgPool,
+    storage_dir: String,
+    own: EndpointId,
+    transport_stats: Arc<TransportStats>,
+) -> Result<()> {
+    record_stream_transport(&transport_stats, "audio", "inbound", "open", &stream);
+    let request: AudioRequest = serde_json::from_slice(&read_line(&mut stream.recv).await?)?;
+    tracing::info!(
+        peer = %stream.peer_id,
+        item = %request.item_id,
+        offset = request.offset,
+        "federation peer requested audio"
+    );
+
+    let track_id = match hex_decode_item_id(&request.item_id) {
+        Some(item_id) => match resolve_track_id(&pool, &own, item_id).await {
+            Ok(Some(track_id)) => track_id,
+            Ok(None) => return refuse_audio(stream, "track not found in the library").await,
+            Err(err) => {
+                return refuse_audio(stream, &format!("library lookup failed: {err:#}")).await;
+            }
+        },
+        None => return refuse_audio(stream, "malformed item_id").await,
+    };
+
+    let Some((file_path, mime_type)) = track_audio_file(&pool, track_id).await? else {
+        return refuse_audio(stream, "audio file record is missing").await;
+    };
+    let path = resolve_media_path(&storage_dir, &file_path);
+    let mut file = match tokio::fs::File::open(&path).await {
+        Ok(file) => file,
+        Err(err) => {
+            return refuse_audio(stream, &format!("audio file is not readable: {err}")).await;
+        }
+    };
+    let total_size = file.metadata().await?.len();
+    let offset = request.offset.min(total_size);
+    if offset > 0 {
+        file.seek(std::io::SeekFrom::Start(offset)).await?;
+    }
+
+    let metadata = match track_metadata(&pool, track_id).await {
+        Ok(metadata) => metadata,
+        Err(err) => {
+            tracing::warn!(track_id, "federation metadata lookup failed: {err:#}");
+            None
+        }
+    };
+    let (cover, artist_image) = if request.want_cover {
+        (
+            read_image(
+                &storage_dir,
+                track_cover_file(&pool, track_id).await.ok().flatten(),
+            )
+            .await,
+            read_image(
+                &storage_dir,
+                track_artist_image_file(&pool, track_id)
+                    .await
+                    .ok()
+                    .flatten(),
+            )
+            .await,
+        )
+    } else {
+        (None, None)
+    };
+
+    let mime_type = if mime_type.trim().is_empty() {
+        guess_mime(&path).to_string()
+    } else {
+        mime_type
+    };
+    write_line(
+        &mut stream.send,
+        &AudioResponseHeader {
+            ok: true,
+            error: None,
+            mime_type,
+            total_size,
+            offset,
+            metadata,
+            cover_size: cover.as_ref().map_or(0, |(bytes, _)| bytes.len() as u64),
+            cover_mime: cover
+                .as_ref()
+                .map(|(_, mime)| mime.clone())
+                .unwrap_or_default(),
+            artist_image_size: artist_image
+                .as_ref()
+                .map_or(0, |(bytes, _)| bytes.len() as u64),
+            artist_image_mime: artist_image
+                .as_ref()
+                .map(|(_, mime)| mime.clone())
+                .unwrap_or_default(),
+        },
+    )
+    .await?;
+    if let Some((bytes, _)) = &cover {
+        stream.send.write_all(bytes).await?;
+    }
+    if let Some((bytes, _)) = &artist_image {
+        stream.send.write_all(bytes).await?;
+    }
+    tokio::io::copy(&mut file, &mut stream.send).await?;
+    stream.send.finish()?;
+    // Wait until the peer read everything before dropping the stream,
+    // otherwise the tail of the file is lost.
+    let _ = stream.send.stopped().await;
+    record_stream_transport(&transport_stats, "audio", "inbound", "done", &stream);
+    Ok(())
+}
+
+async fn refuse_audio(mut stream: ByteStream, message: &str) -> Result<()> {
+    write_line(
+        &mut stream.send,
+        &AudioResponseHeader {
+            ok: false,
+            error: Some(message.to_string()),
+            ..AudioResponseHeader::default()
+        },
+    )
+    .await?;
+    stream.send.finish()?;
+    let _ = stream.send.stopped().await;
+    anyhow::bail!("refused audio request: {message}");
+}
+
+// ---------------------------------------------------------------------------
+// Catalog protocol
+// ---------------------------------------------------------------------------
+
+/// Runs the catalog accept loop until the acceptor closes.
+pub async fn serve_catalog(
+    mut acceptor: StreamAcceptor,
+    pool: PgPool,
+    storage_dir: String,
+    own: EndpointId,
+    transport_stats: Arc<TransportStats>,
+) {
+    while let Some(stream) = acceptor.accept().await {
+        let pool = pool.clone();
+        let storage_dir = storage_dir.clone();
+        let transport_stats = Arc::clone(&transport_stats);
+        tokio::spawn(async move {
+            let peer = stream.peer_id;
+            if let Err(err) =
+                serve_catalog_one(stream, pool, storage_dir, own, transport_stats).await
+            {
+                tracing::warn!(peer = %peer, "federation catalog request failed: {err:#}");
+            }
+        });
+    }
+}
+
+async fn serve_catalog_one(
+    mut stream: ByteStream,
+    pool: PgPool,
+    storage_dir: String,
+    own: EndpointId,
+    transport_stats: Arc<TransportStats>,
+) -> Result<()> {
+    record_stream_transport(&transport_stats, "catalog", "inbound", "open", &stream);
+    let request: CatalogRequest = serde_json::from_slice(&read_line(&mut stream.recv).await?)?;
+    tracing::info!(
+        peer = %stream.peer_id,
+        artist = %request.artist,
+        want = request.want.as_deref().unwrap_or("catalog"),
+        "federation peer requested a catalog"
+    );
+
+    match request.want.as_deref() {
+        None | Some("catalog") => {
+            let response = match build_catalog(&pool, &own, &request.artist).await {
+                Ok(response) => response,
+                Err(err) => CatalogResponse {
+                    ok: false,
+                    error: Some(format!("catalog lookup failed: {err:#}")),
+                    ..CatalogResponse::default()
+                },
+            };
+            stream
+                .send
+                .write_all(&serde_json::to_vec(&response)?)
+                .await?;
+        }
+        Some("artists") => {
+            let cursor = request.cursor.clone();
+            let limit = request.limit.unwrap_or(64).clamp(1, 200);
+            let response = match build_artist_slice(&pool, cursor, limit).await {
+                Ok(response) => response,
+                Err(err) => CatalogResponse {
+                    ok: false,
+                    error: Some(format!("artist slice lookup failed: {err:#}")),
+                    ..CatalogResponse::default()
+                },
+            };
+            stream
+                .send
+                .write_all(&serde_json::to_vec(&response)?)
+                .await?;
+        }
+        Some(want @ ("artist_image" | "release_cover")) => {
+            let media = if want == "release_cover" {
+                release_cover_by_names(
+                    &pool,
+                    &request.artist,
+                    request.release.as_deref().unwrap_or_default(),
+                )
+                .await?
+            } else {
+                artist_image_by_name(&pool, &request.artist).await?
+            };
+            let image = read_image(&storage_dir, media).await;
+            let header = match &image {
+                Some((bytes, mime)) => ImageHeader {
+                    ok: true,
+                    error: None,
+                    mime_type: mime.clone(),
+                    size: bytes.len() as u64,
+                },
+                None => ImageHeader {
+                    ok: false,
+                    error: Some("no image".to_string()),
+                    ..ImageHeader::default()
+                },
+            };
+            write_line(&mut stream.send, &header).await?;
+            if let Some((bytes, _)) = &image {
+                stream.send.write_all(bytes).await?;
+            }
+        }
+        Some(other) => {
+            let response = CatalogResponse {
+                ok: false,
+                error: Some(format!("unknown request kind '{other}'")),
+                ..CatalogResponse::default()
+            };
+            stream
+                .send
+                .write_all(&serde_json::to_vec(&response)?)
+                .await?;
+        }
+    }
+    stream.send.finish()?;
+    let _ = stream.send.stopped().await;
+    record_stream_transport(&transport_stats, "catalog", "inbound", "done", &stream);
+    Ok(())
+}
+
+async fn build_catalog(pool: &PgPool, own: &EndpointId, artist: &str) -> Result<CatalogResponse> {
+    let Some(artist_row) = sqlx::query(
+        "SELECT id, name FROM furumusic__artist
+         WHERE LOWER(name) = LOWER($1) AND is_hidden = false
+         LIMIT 1",
+    )
+    .bind(artist)
+    .fetch_optional(pool)
+    .await?
+    else {
+        return Ok(CatalogResponse {
+            ok: false,
+            error: Some("artist not found in the library".to_string()),
+            ..CatalogResponse::default()
+        });
+    };
+    let artist_id: i64 = artist_row.get(0);
+
+    let release_rows = sqlx::query(
+        "SELECT r.id, r.title, r.release_type, r.year
+         FROM furumusic__release r
+         JOIN furumusic__release_artist ra ON ra.release_id = r.id
+         WHERE ra.artist_id = $1 AND r.is_hidden = false
+         ORDER BY r.year NULLS LAST, r.title",
+    )
+    .bind(artist_id)
+    .fetch_all(pool)
+    .await?;
+    let mut releases = Vec::new();
+    for release_row in release_rows {
+        let release_id: i64 = release_row.get(0);
+        let track_rows = sqlx::query(
+            "SELECT t.id, t.title, t.track_number, t.disc_number, t.duration_seconds,
+                    c.content_id
+             FROM furumusic__track t
+             JOIN furumusic__media_file m ON m.id = t.audio_file_id
+             LEFT JOIN furumusic__federation_content_id_cache c
+                    ON c.media_file_id = m.id AND c.sha256_hash = m.sha256_hash
+             WHERE t.release_id = $1 AND t.is_hidden = false
+             ORDER BY t.disc_number NULLS FIRST, t.track_number NULLS LAST, t.title",
+        )
+        .bind(release_id)
+        .fetch_all(pool)
+        .await?;
+        let mut tracks = Vec::with_capacity(track_rows.len());
+        for row in track_rows {
+            let track_id: i64 = row.get(0);
+            let duration: f64 = row.get(4);
+            let (artists, featured_artists) = track_catalog_artist_names(pool, track_id).await?;
+            tracks.push(CatalogTrack {
+                title: row.get(1),
+                artists,
+                featured_artists,
+                track_number: row.get(2),
+                disc_number: row.get(3),
+                duration_seconds: (duration > 0.0).then_some(duration),
+                content_id: row.get(5),
+                item_id: item_id_of(own, track_id),
+            });
+        }
+        releases.push(CatalogRelease {
+            title: release_row.get(1),
+            release_type: release_row.get(2),
+            year: release_row.get(3),
+            tracks,
+        });
+    }
+
+    Ok(CatalogResponse {
+        ok: true,
+        artist: Some(CatalogArtist {
+            name: artist_row.get(1),
+            releases,
+            appears_on: Vec::new(),
+        }),
+        ..CatalogResponse::default()
+    })
+}
+
+async fn build_artist_slice(
+    pool: &PgPool,
+    cursor: Option<String>,
+    limit: usize,
+) -> Result<CatalogResponse> {
+    let offset = cursor
+        .as_deref()
+        .and_then(|value| value.parse::<i64>().ok())
+        .unwrap_or(0)
+        .max(0);
+    let rows = sqlx::query(
+        r#"SELECT a.name::text AS name,
+                  mf.file_path::text AS image_path,
+                  COALESCE(s.release_count, 0)::bigint AS release_count,
+                  COALESCE(s.track_count, 0)::bigint AS track_count
+           FROM furumusic__artist a
+           LEFT JOIN furumusic__media_file mf ON mf.id = a.image_file_id
+           LEFT JOIN (
+               SELECT appearance.artist_id,
+                      COUNT(DISTINCT appearance.release_id) FILTER (WHERE appearance.is_primary_release_artist) AS release_count,
+                      COUNT(DISTINCT appearance.track_id) AS track_count
+                 FROM (
+                        SELECT ta.artist_id,
+                               t.id AS track_id,
+                               r.id AS release_id,
+                               primary_release.artist_id IS NOT NULL AS is_primary_release_artist
+                          FROM furumusic__track_artist ta
+                          JOIN furumusic__track t ON t.id = ta.track_id AND t.is_hidden = false
+                          JOIN furumusic__release r ON r.id = t.release_id AND r.is_hidden = false
+                          LEFT JOIN furumusic__release_artist primary_release
+                            ON primary_release.release_id = r.id
+                           AND primary_release.artist_id = ta.artist_id
+                           AND primary_release.position = 0
+                      ) appearance
+                GROUP BY appearance.artist_id
+           ) s ON s.artist_id = a.id
+           WHERE a.is_hidden = false
+             AND COALESCE(s.track_count, 0) > 0
+           ORDER BY (COALESCE(s.release_count, 0) > 0) DESC,
+                    COALESCE(s.release_count, 0) DESC,
+                    COALESCE(s.track_count, 0) DESC,
+                    a.name_sort
+           LIMIT $1 OFFSET $2"#,
+    )
+    .bind(limit as i64 + 1)
+    .bind(offset)
+    .fetch_all(pool)
+    .await?;
+
+    let mut artists = Vec::with_capacity(rows.len().min(limit));
+    let has_more = rows.len() > limit;
+    for row in rows.into_iter().take(limit) {
+        let name: String = row.get(0);
+        artists.push(CatalogArtistPreview {
+            artist_key: normalize_name(&name),
+            name,
+            image_path: row.get(1),
+            release_count: row.get(2),
+            track_count: row.get(3),
+        });
+    }
+    let next_cursor = has_more.then(|| (offset + artists.len() as i64).to_string());
+    Ok(CatalogResponse {
+        ok: true,
+        artists,
+        next_cursor,
+        ..CatalogResponse::default()
+    })
+}
+
+async fn artist_image_by_name(pool: &PgPool, artist: &str) -> Result<Option<(String, String)>> {
+    let row = sqlx::query(
+        "SELECT m.file_path, m.mime_type FROM furumusic__artist a
+         JOIN furumusic__media_file m ON m.id = a.image_file_id
+         WHERE LOWER(a.name) = LOWER($1) AND a.is_hidden = false
+         LIMIT 1",
+    )
+    .bind(artist)
+    .fetch_optional(pool)
+    .await?;
+    Ok(row.map(|row| (row.get(0), row.get(1))))
+}
+
+async fn release_cover_by_names(
+    pool: &PgPool,
+    artist: &str,
+    release: &str,
+) -> Result<Option<(String, String)>> {
+    let row = sqlx::query(
+        "SELECT m.file_path, m.mime_type FROM furumusic__release r
+         JOIN furumusic__release_artist ra ON ra.release_id = r.id
+         JOIN furumusic__artist a ON a.id = ra.artist_id
+         JOIN furumusic__media_file m ON m.id = r.cover_file_id
+         WHERE LOWER(a.name) = LOWER($1) AND LOWER(r.title) = LOWER($2)
+         LIMIT 1",
+    )
+    .bind(artist)
+    .bind(release)
+    .fetch_optional(pool)
+    .await?;
+    Ok(row.map(|row| (row.get(0), row.get(1))))
+}

src/federation/similarity.rs

@@ -0,0 +1,398 @@
+//! Furumusic policy and PostgreSQL adapter for the shared similarity protocol.
+
+use std::collections::{HashMap, HashSet};
+use std::sync::Arc;
+use std::time::Duration;
+
+use anyhow::{Context as _, Result};
+use futures_util::stream::{self, StreamExt as _};
+use music_dht::similarity::{self as wire, SimilarityHit, SimilarityRequest, SimilarityResponse};
+use music_dht::similarity_dht::SimilarityDht;
+use music_dht::{
+    ByteStream, EndpointId, ItemId, ItemKind, MusicDhtService, PeerTicket, StreamAcceptor,
+};
+
+use crate::similarity::{Manager, QueryVector};
+
+use super::TransportStats;
+
+pub use music_dht::similarity::SIMILARITY_ALPN;
+
+const INITIAL_QUERY_PEERS: usize = 16;
+const MAX_QUERY_PEERS: usize = 48;
+const QUERY_CONCURRENCY: usize = 8;
+const QUERY_TIMEOUT: Duration = Duration::from_secs(5);
+const ROUTING_TIMEOUT: Duration = Duration::from_secs(5);
+const MAX_PER_ARTIST: usize = 3;
+const MAX_NEAR_DUPLICATE_SIGNATURE_DISTANCE: u32 = 8;
+
+#[derive(Debug, Clone)]
+pub struct RemoteSimilarityTrack {
+    pub owner: String,
+    pub item_id: String,
+    pub title: String,
+    pub artist_names: Vec<String>,
+    pub featured_artist_names: Vec<String>,
+    pub year: Option<i32>,
+    pub duration_seconds: Option<i64>,
+    pub content_id: Option<String>,
+    pub release_title: Option<String>,
+    pub track_number: Option<i32>,
+    pub disc_number: Option<i32>,
+    pub similarity_score: f32,
+}
+
+pub struct SimilaritySearchOutcome {
+    pub tracks: Vec<RemoteSimilarityTrack>,
+    pub queried_peers: usize,
+}
+
+pub async fn serve_peers(
+    mut acceptor: StreamAcceptor,
+    manager: Arc<Manager>,
+    own: EndpointId,
+    transport: Arc<TransportStats>,
+) {
+    while let Some(stream) = acceptor.accept().await {
+        let manager = Arc::clone(&manager);
+        let transport = Arc::clone(&transport);
+        tokio::spawn(async move {
+            let peer = stream.peer_id;
+            if let Err(error) = serve_one(stream, manager, own, transport).await {
+                tracing::warn!(peer = %peer, "similarity request failed: {error:#}");
+            }
+        });
+    }
+}
+
+async fn serve_one(
+    mut stream: ByteStream,
+    manager: Arc<Manager>,
+    own: EndpointId,
+    transport: Arc<TransportStats>,
+) -> Result<()> {
+    super::record_stream_transport(&transport, "similarity", "inbound", "open", &stream);
+    let request = wire::read_request(&mut stream).await?;
+    let response = if !manager.enabled() {
+        SimilarityResponse::refused("similarity search is disabled on this instance")?
+    } else {
+        let profile_id = request.profile_id;
+        let vector = request.vector;
+        let limit = request.limit;
+        let rank_manager = Arc::clone(&manager);
+        let ranked = tokio::task::spawn_blocking(move || {
+            rank_manager.rank_vector(&profile_id, &vector, None, None, limit)
+        })
+        .await
+        .context("local similarity task failed")
+        .and_then(|result| result);
+        match ranked {
+            Ok(ranked) => {
+                let ids = ranked
+                    .iter()
+                    .map(|track| track.track_id)
+                    .collect::<Vec<_>>();
+                match manager.metadata_for_tracks(&ids).await {
+                    Ok(metadata) => {
+                        let by_id = ranked
+                            .into_iter()
+                            .map(|track| (track.track_id, track))
+                            .collect::<HashMap<_, _>>();
+                        let hits = metadata
+                            .into_iter()
+                            .filter_map(|track| {
+                                let ranked = by_id.get(&track.track_id)?;
+                                let hit = SimilarityHit {
+                                    score: ranked.score,
+                                    item_id: hex(
+                                        ItemId::derive(
+                                            &own,
+                                            ItemKind::Track,
+                                            &format!("track:{}", track.track_id),
+                                        )
+                                        .as_bytes(),
+                                    ),
+                                    title: track.title,
+                                    artist_names: track.artist_names,
+                                    featured_artist_names: track.featured_artist_names,
+                                    year: track.year,
+                                    duration_seconds: Some(track.duration_seconds.round() as i64),
+                                    content_id: track.content_id,
+                                    release_title: Some(track.release_title),
+                                    track_number: track.track_number,
+                                    disc_number: track.disc_number,
+                                    embedding_signature: Some(ranked.embedding_signature),
+                                };
+                                match hit.validate() {
+                                    Ok(()) => Some(hit),
+                                    Err(error) => {
+                                        tracing::debug!(%error, "invalid local similarity metadata skipped");
+                                        None
+                                    }
+                                }
+                            })
+                            .collect();
+                        SimilarityResponse::success(hits)?
+                    }
+                    Err(error) => SimilarityResponse::refused(format!(
+                        "similarity metadata is unavailable: {error:#}"
+                    ))?,
+                }
+            }
+            Err(error) => {
+                SimilarityResponse::refused(format!("similarity query is unavailable: {error:#}"))?
+            }
+        }
+    };
+    wire::write_response(&mut stream, &response).await?;
+    stream.send.finish()?;
+    let _ = stream.send.stopped().await;
+    super::record_stream_transport(&transport, "similarity", "inbound", "done", &stream);
+    Ok(())
+}
+
+pub async fn search(
+    service: Arc<MusicDhtService>,
+    routing: Arc<SimilarityDht>,
+    query: QueryVector,
+    limit: usize,
+    transport: Arc<TransportStats>,
+) -> Result<SimilaritySearchOutcome> {
+    let own = service.endpoint_id();
+    let routed = match tokio::time::timeout(
+        ROUTING_TIMEOUT,
+        routing.find_peers(&query.profile_id, &query.vector, MAX_QUERY_PEERS),
+    )
+    .await
+    {
+        Ok(Ok(peers)) => peers,
+        Err(_) => {
+            tracing::debug!("similarity DHT lookup timed out; using known peers");
+            Vec::new()
+        }
+        Ok(Err(error)) => {
+            tracing::debug!(%error, "similarity DHT lookup unavailable; using known peers");
+            Vec::new()
+        }
+    };
+    let mut seen = HashSet::new();
+    let mut peers: Vec<QueryPeer> = routed
+        .into_iter()
+        .filter_map(|ticket| {
+            let owner = ticket.endpoint_id();
+            (owner != own && seen.insert(owner)).then_some(QueryPeer {
+                owner,
+                ticket: Some(ticket),
+            })
+        })
+        .collect();
+    for peer in service
+        .connected_peers()
+        .into_iter()
+        .chain(service.known_peers().into_iter().map(|peer| peer.peer_id))
+    {
+        if peer != own && seen.insert(peer) {
+            peers.push(QueryPeer {
+                owner: peer,
+                ticket: None,
+            });
+        }
+        if peers.len() >= MAX_QUERY_PEERS {
+            break;
+        }
+    }
+    let query_signature = wire::embedding_signature(&query.vector)?;
+    let request = Arc::new(SimilarityRequest::new(
+        query.profile_id,
+        query.vector,
+        limit.clamp(1, wire::MAX_SIMILARITY_RESULTS),
+    )?);
+
+    let mut hits = Vec::new();
+    let initial = peers.len().min(INITIAL_QUERY_PEERS);
+    let mut queried_peers = initial;
+    let responses = query_peers(
+        Arc::clone(&service),
+        &peers[..initial],
+        Arc::clone(&request),
+        Arc::clone(&transport),
+    )
+    .await;
+    let mut successful = 0usize;
+    for response in responses {
+        match response {
+            Ok(peer_hits) => {
+                successful += 1;
+                hits.extend(peer_hits);
+            }
+            Err(error) => tracing::debug!(%error, "similarity peer query skipped"),
+        }
+    }
+    if initial < peers.len() && (hits.len() < limit || successful < initial.min(4)) {
+        queried_peers += peers.len() - initial;
+        for response in query_peers(
+            Arc::clone(&service),
+            &peers[initial..],
+            Arc::clone(&request),
+            Arc::clone(&transport),
+        )
+        .await
+        {
+            match response {
+                Ok(peer_hits) => hits.extend(peer_hits),
+                Err(error) => tracing::debug!(%error, "fallback similarity peer query skipped"),
+            }
+        }
+    }
+    hits.sort_by(|left, right| right.1.total_cmp(&left.1));
+    let mut dedup = HashSet::new();
+    let mut signatures = vec![query_signature];
+    let mut artist_counts: HashMap<String, usize> = HashMap::new();
+    let mut tracks = Vec::new();
+    for (track, _, signature) in hits {
+        if query
+            .source_content_id
+            .as_deref()
+            .is_some_and(|source| track.content_id.as_deref() == Some(source))
+        {
+            continue;
+        }
+        let key = track
+            .content_id
+            .clone()
+            .unwrap_or_else(|| format!("{}:{}", track.owner, track.item_id));
+        if !dedup.insert(key) {
+            continue;
+        }
+        if signature.is_some_and(|candidate| {
+            signatures.iter().any(|existing| {
+                wire::signature_distance(&candidate, existing)
+                    <= MAX_NEAR_DUPLICATE_SIGNATURE_DISTANCE
+            })
+        }) {
+            continue;
+        }
+        let artist = track
+            .artist_names
+            .first()
+            .map(|name| music_dht::normalize_name(name))
+            .unwrap_or_default();
+        let count = artist_counts.entry(artist.clone()).or_default();
+        if !artist.is_empty() && *count >= MAX_PER_ARTIST {
+            continue;
+        }
+        *count += 1;
+        if let Some(signature) = signature {
+            signatures.push(signature);
+        }
+        tracks.push(track);
+        if tracks.len() >= limit.min(wire::MAX_SIMILARITY_RESULTS) {
+            break;
+        }
+    }
+    Ok(SimilaritySearchOutcome {
+        tracks,
+        queried_peers,
+    })
+}
+
+type PeerHits = Vec<(
+    RemoteSimilarityTrack,
+    f32,
+    Option<[u8; wire::SIMILARITY_SIGNATURE_BYTES]>,
+)>;
+
+#[derive(Clone)]
+struct QueryPeer {
+    owner: EndpointId,
+    ticket: Option<PeerTicket>,
+}
+
+async fn query_peers(
+    service: Arc<MusicDhtService>,
+    peers: &[QueryPeer],
+    request: Arc<SimilarityRequest>,
+    transport: Arc<TransportStats>,
+) -> Vec<Result<PeerHits>> {
+    stream::iter(peers.iter().cloned().map(|peer| {
+        let service = Arc::clone(&service);
+        let request = Arc::clone(&request);
+        let transport = Arc::clone(&transport);
+        async move {
+            tokio::time::timeout(
+                QUERY_TIMEOUT,
+                query_peer(service, peer, &request, transport),
+            )
+            .await
+            .map_err(|_| anyhow::anyhow!("similarity peer timed out"))?
+        }
+    }))
+    .buffer_unordered(QUERY_CONCURRENCY)
+    .collect()
+    .await
+}
+
+async fn query_peer(
+    service: Arc<MusicDhtService>,
+    peer: QueryPeer,
+    request: &SimilarityRequest,
+    transport: Arc<TransportStats>,
+) -> Result<PeerHits> {
+    let owner = peer.owner;
+    let mut stream = match peer.ticket {
+        Some(ticket) => service.open_stream_to(&ticket, SIMILARITY_ALPN).await,
+        None => service.open_stream(owner, SIMILARITY_ALPN).await,
+    }
+    .map_err(|error| anyhow::anyhow!("cannot reach similarity peer: {error}"))?;
+    super::record_stream_transport(&transport, "similarity", "outbound", "open", &stream);
+    let response = wire::exchange(&mut stream, request).await?;
+    super::record_stream_transport(&transport, "similarity", "outbound", "done", &stream);
+    anyhow::ensure!(
+        response.ok,
+        "peer refused similarity query: {}",
+        response.error.unwrap_or_default()
+    );
+    Ok(response
+        .hits
+        .into_iter()
+        .map(|hit| {
+            let score = hit.score;
+            let signature = hit.embedding_signature;
+            (
+                RemoteSimilarityTrack {
+                    owner: owner.to_string(),
+                    item_id: hit.item_id,
+                    title: hit.title,
+                    artist_names: hit.artist_names,
+                    featured_artist_names: hit.featured_artist_names,
+                    year: hit.year,
+                    duration_seconds: hit.duration_seconds,
+                    content_id: hit.content_id,
+                    release_title: hit.release_title,
+                    track_number: hit.track_number,
+                    disc_number: hit.disc_number,
+                    similarity_score: score,
+                },
+                score,
+                signature,
+            )
+        })
+        .collect())
+}
+
+fn hex(bytes: &[u8]) -> String {
+    bytes.iter().map(|byte| format!("{byte:02x}")).collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn hamming_threshold_keeps_exact_and_near_duplicates_out() {
+        let query = [0u8; wire::SIMILARITY_SIGNATURE_BYTES];
+        let mut near = query;
+        near[0] = 0b0000_0111;
+        assert!(wire::signature_distance(&query, &near) <= MAX_NEAR_DUPLICATE_SIGNATURE_DISTANCE);
+    }
+}

src/federation/storage.rs

@@ -0,0 +1,349 @@
+use std::str::FromStr;
+
+use async_trait::async_trait;
+use music_dht::{
+    DhtKey, EndpointId, LibraryItem, MAX_RECORDS_PER_RESPONSE, MusicDhtError, MusicDhtStorage,
+    NodeContact, NodeId, SecretKey, StoreDecision, StoredRecord, decide_store,
+};
+use sqlx::{PgPool, Row as _};
+
+const IDENTITY_NAME: &str = "default";
+
+const SCHEMA: &[&str] = &[
+    "CREATE TABLE IF NOT EXISTS furumusic__federation_identity (
+        name        TEXT PRIMARY KEY,
+        secret_key  BYTEA NOT NULL,
+        created_at  TEXT NOT NULL,
+        updated_at  TEXT NOT NULL
+    )",
+    "CREATE TABLE IF NOT EXISTS furumusic__federation_local_item (
+        id              BYTEA PRIMARY KEY,
+        normalized_name TEXT NOT NULL,
+        revision        BIGINT NOT NULL,
+        deleted         BOOLEAN NOT NULL DEFAULT false,
+        updated_at_ms   BIGINT NOT NULL,
+        payload         BYTEA NOT NULL
+    )",
+    "CREATE INDEX IF NOT EXISTS idx_furumusic_federation_local_item_normalized_name
+        ON furumusic__federation_local_item(normalized_name)",
+    "CREATE TABLE IF NOT EXISTS furumusic__federation_dht_record (
+        dht_key          BYTEA NOT NULL,
+        item_id          BYTEA NOT NULL,
+        owner_peer_id    TEXT NOT NULL,
+        payload          BYTEA NOT NULL,
+        revision         BIGINT NOT NULL,
+        deleted          BOOLEAN NOT NULL,
+        expires_at_ms    BIGINT NOT NULL,
+        PRIMARY KEY (dht_key, item_id, owner_peer_id)
+    )",
+    "CREATE INDEX IF NOT EXISTS idx_furumusic_federation_dht_record_expires_at
+        ON furumusic__federation_dht_record(expires_at_ms)",
+    "CREATE TABLE IF NOT EXISTS furumusic__federation_known_peer (
+        peer_id       TEXT PRIMARY KEY,
+        node_id       BYTEA NOT NULL,
+        ticket        TEXT NOT NULL,
+        last_seen_ms  BIGINT NOT NULL
+    )",
+    "CREATE TABLE IF NOT EXISTS furumusic__federation_content_id_cache (
+        media_file_id  BIGINT PRIMARY KEY,
+        sha256_hash    TEXT NOT NULL,
+        content_id     TEXT NOT NULL,
+        updated_at     TEXT NOT NULL
+    )",
+    "CREATE INDEX IF NOT EXISTS idx_furumusic_federation_content_id_cache_content_id
+        ON furumusic__federation_content_id_cache(content_id)",
+];
+
+#[derive(Debug, Clone)]
+pub struct PostgresFederationStorage {
+    pool: PgPool,
+}
+
+impl PostgresFederationStorage {
+    pub async fn new(pool: PgPool) -> music_dht::Result<Self> {
+        let storage = Self { pool };
+        storage.ensure_schema().await?;
+        Ok(storage)
+    }
+
+    pub async fn load_or_create_secret_key(&self) -> music_dht::Result<SecretKey> {
+        if let Some(bytes) = sqlx::query_scalar::<_, Vec<u8>>(
+            "SELECT secret_key FROM furumusic__federation_identity WHERE name = $1",
+        )
+        .bind(IDENTITY_NAME)
+        .fetch_optional(&self.pool)
+        .await
+        .map_err(db_error)?
+        {
+            return secret_from_bytes(bytes);
+        }
+
+        let key = SecretKey::generate();
+        let key_bytes = key.to_bytes();
+        let now = now_iso();
+        let inserted = sqlx::query(
+            "INSERT INTO furumusic__federation_identity
+             (name, secret_key, created_at, updated_at)
+             VALUES ($1, $2, $3, $4)
+             ON CONFLICT (name) DO NOTHING",
+        )
+        .bind(IDENTITY_NAME)
+        .bind(key_bytes.as_slice())
+        .bind(&now)
+        .bind(&now)
+        .execute(&self.pool)
+        .await
+        .map_err(db_error)?
+        .rows_affected();
+        if inserted == 1 {
+            return Ok(key);
+        }
+
+        let bytes = sqlx::query_scalar::<_, Vec<u8>>(
+            "SELECT secret_key FROM furumusic__federation_identity WHERE name = $1",
+        )
+        .bind(IDENTITY_NAME)
+        .fetch_one(&self.pool)
+        .await
+        .map_err(db_error)?;
+        secret_from_bytes(bytes)
+    }
+
+    async fn ensure_schema(&self) -> music_dht::Result<()> {
+        for sql in SCHEMA {
+            sqlx::query(sql)
+                .execute(&self.pool)
+                .await
+                .map_err(db_error)?;
+        }
+        Ok(())
+    }
+}
+
+#[async_trait]
+impl MusicDhtStorage for PostgresFederationStorage {
+    async fn upsert_local_item(&self, item: &LibraryItem) -> music_dht::Result<()> {
+        let payload = postcard::to_stdvec(item).map_err(db_error)?;
+        sqlx::query(
+            "INSERT INTO furumusic__federation_local_item
+             (id, normalized_name, revision, deleted, updated_at_ms, payload)
+             VALUES ($1, $2, $3, $4, $5, $6)
+             ON CONFLICT (id) DO UPDATE SET
+                normalized_name = EXCLUDED.normalized_name,
+                revision = EXCLUDED.revision,
+                deleted = EXCLUDED.deleted,
+                updated_at_ms = EXCLUDED.updated_at_ms,
+                payload = EXCLUDED.payload",
+        )
+        .bind(item.id.as_bytes().as_slice())
+        .bind(&item.normalized_name)
+        .bind(item.revision as i64)
+        .bind(item.deleted)
+        .bind(item.updated_at_ms as i64)
+        .bind(payload)
+        .execute(&self.pool)
+        .await
+        .map_err(db_error)?;
+        Ok(())
+    }
+
+    async fn list_local_items(&self, include_deleted: bool) -> music_dht::Result<Vec<LibraryItem>> {
+        let rows = sqlx::query(
+            "SELECT payload
+             FROM furumusic__federation_local_item
+             WHERE $1 OR deleted = false
+             ORDER BY normalized_name",
+        )
+        .bind(include_deleted)
+        .fetch_all(&self.pool)
+        .await
+        .map_err(db_error)?;
+        Ok(rows
+            .into_iter()
+            .filter_map(|row| postcard::from_bytes::<LibraryItem>(&row.get::<Vec<u8>, _>(0)).ok())
+            .collect())
+    }
+
+    async fn store_dht_record(&self, key: DhtKey, record: StoredRecord) -> music_dht::Result<bool> {
+        let mut conn = self.pool.acquire().await.map_err(db_error)?;
+        store_record_in_conn(&mut conn, &key, &record).await
+    }
+
+    async fn store_dht_records(
+        &self,
+        entries: Vec<(DhtKey, StoredRecord)>,
+    ) -> music_dht::Result<Vec<bool>> {
+        let mut tx = self.pool.begin().await.map_err(db_error)?;
+        let mut stored = Vec::with_capacity(entries.len());
+        for (key, record) in &entries {
+            stored.push(store_record_in_conn(&mut tx, key, record).await?);
+        }
+        tx.commit().await.map_err(db_error)?;
+        Ok(stored)
+    }
+
+    async fn dht_records_by_key(
+        &self,
+        key: DhtKey,
+        now_ms: u64,
+    ) -> music_dht::Result<Vec<StoredRecord>> {
+        let rows = sqlx::query(
+            "SELECT payload
+             FROM furumusic__federation_dht_record
+             WHERE dht_key = $1 AND expires_at_ms > $2
+             ORDER BY expires_at_ms DESC, item_id
+             LIMIT $3",
+        )
+        .bind(key.as_bytes().as_slice())
+        .bind(now_ms as i64)
+        .bind(MAX_RECORDS_PER_RESPONSE as i64)
+        .fetch_all(&self.pool)
+        .await
+        .map_err(db_error)?;
+        Ok(rows
+            .into_iter()
+            .filter_map(|row| postcard::from_bytes::<StoredRecord>(&row.get::<Vec<u8>, _>(0)).ok())
+            .collect())
+    }
+
+    async fn delete_expired_records(&self, now_ms: u64) -> music_dht::Result<usize> {
+        let result =
+            sqlx::query("DELETE FROM furumusic__federation_dht_record WHERE expires_at_ms <= $1")
+                .bind(now_ms as i64)
+                .execute(&self.pool)
+                .await
+                .map_err(db_error)?;
+        Ok(result.rows_affected() as usize)
+    }
+
+    async fn upsert_known_peer(&self, contact: &NodeContact) -> music_dht::Result<()> {
+        sqlx::query(
+            "INSERT INTO furumusic__federation_known_peer
+             (peer_id, node_id, ticket, last_seen_ms)
+             VALUES ($1, $2, $3, $4)
+             ON CONFLICT (peer_id) DO UPDATE SET
+                node_id = EXCLUDED.node_id,
+                ticket = EXCLUDED.ticket,
+                last_seen_ms = EXCLUDED.last_seen_ms",
+        )
+        .bind(contact.peer_id.to_string())
+        .bind(contact.node_id.as_bytes().as_slice())
+        .bind(&contact.ticket)
+        .bind(contact.last_seen_ms as i64)
+        .execute(&self.pool)
+        .await
+        .map_err(db_error)?;
+        Ok(())
+    }
+
+    async fn delete_known_peer(&self, peer_id: EndpointId) -> music_dht::Result<()> {
+        sqlx::query("DELETE FROM furumusic__federation_known_peer WHERE peer_id = $1")
+            .bind(peer_id.to_string())
+            .execute(&self.pool)
+            .await
+            .map_err(db_error)?;
+        Ok(())
+    }
+
+    async fn load_known_peers(&self) -> music_dht::Result<Vec<NodeContact>> {
+        let rows = sqlx::query(
+            "SELECT peer_id, node_id, ticket, last_seen_ms
+             FROM furumusic__federation_known_peer",
+        )
+        .fetch_all(&self.pool)
+        .await
+        .map_err(db_error)?;
+        let mut contacts = Vec::new();
+        for row in rows {
+            let peer_id: String = row.get(0);
+            let node_id: Vec<u8> = row.get(1);
+            let ticket: String = row.get(2);
+            let last_seen_ms: i64 = row.get(3);
+            let Ok(peer_id) = EndpointId::from_str(&peer_id) else {
+                continue;
+            };
+            let Ok(node_id) = <[u8; 32]>::try_from(node_id.as_slice()) else {
+                continue;
+            };
+            contacts.push(NodeContact {
+                node_id: NodeId::from_bytes(node_id),
+                peer_id,
+                ticket,
+                last_seen_ms: last_seen_ms as u64,
+            });
+        }
+        Ok(contacts)
+    }
+}
+
+fn now_iso() -> String {
+    chrono::Utc::now().format("%Y-%m-%dT%H:%M:%SZ").to_string()
+}
+
+fn secret_from_bytes(bytes: Vec<u8>) -> music_dht::Result<SecretKey> {
+    let bytes: [u8; 32] = bytes
+        .as_slice()
+        .try_into()
+        .map_err(|_| MusicDhtError::Database("stored federation identity is corrupted".into()))?;
+    Ok(SecretKey::from_bytes(&bytes))
+}
+
+/// Applies one validated record following the revision/tombstone rules.
+/// Returns `true` if the record was written or refreshed. Runs against a
+/// pooled connection or an open transaction.
+async fn store_record_in_conn(
+    conn: &mut sqlx::PgConnection,
+    key: &DhtKey,
+    record: &StoredRecord,
+) -> music_dht::Result<bool> {
+    let existing = sqlx::query(
+        "SELECT revision, deleted, expires_at_ms
+         FROM furumusic__federation_dht_record
+         WHERE dht_key = $1 AND item_id = $2 AND owner_peer_id = $3",
+    )
+    .bind(key.as_bytes().as_slice())
+    .bind(record.item.id.as_bytes().as_slice())
+    .bind(record.item.owner.to_string())
+    .fetch_optional(&mut *conn)
+    .await
+    .map_err(db_error)?
+    .map(|row| {
+        (
+            row.get::<i64, _>(0) as u64,
+            row.get::<bool, _>(1),
+            row.get::<i64, _>(2) as u64,
+        )
+    });
+
+    match decide_store(existing, record) {
+        StoreDecision::Ignore => return Ok(false),
+        StoreDecision::Write | StoreDecision::RefreshExpiry(_) => {}
+    }
+
+    let payload = postcard::to_stdvec(record).map_err(db_error)?;
+    sqlx::query(
+        "INSERT INTO furumusic__federation_dht_record
+         (dht_key, item_id, owner_peer_id, payload, revision, deleted, expires_at_ms)
+         VALUES ($1, $2, $3, $4, $5, $6, $7)
+         ON CONFLICT (dht_key, item_id, owner_peer_id) DO UPDATE SET
+            payload = EXCLUDED.payload,
+            revision = EXCLUDED.revision,
+            deleted = EXCLUDED.deleted,
+            expires_at_ms = EXCLUDED.expires_at_ms",
+    )
+    .bind(key.as_bytes().as_slice())
+    .bind(record.item.id.as_bytes().as_slice())
+    .bind(record.item.owner.to_string())
+    .bind(payload)
+    .bind(record.item.revision as i64)
+    .bind(record.item.deleted)
+    .bind(record.expires_at_ms as i64)
+    .execute(&mut *conn)
+    .await
+    .map_err(db_error)?;
+    Ok(true)
+}
+
+fn db_error(err: impl std::fmt::Display) -> MusicDhtError {
+    MusicDhtError::Database(err.to_string())
+}

src/i18n/phrases.rs

@@ -96,9 +96,9 @@ translations! {
     settings_swagger:         "Swagger UI"                    , "Swagger UI";
     settings_swagger_help:    "Serves interactive API docs at /swagger/ (requires restart)" , "Интерактивная документация API на /swagger/ (требуется перезапуск)";
     settings_lastfm_api_key:  "Last.fm API key"               , "API ключ Last.fm";
-    settings_lastfm_api_key_help: "Used for Last.fm popularity and account connection" , "Используется для популярности Last.fm и подключения аккаунта";
+    settings_lastfm_api_key_help: "Identifies this application to Last.fm and enables metadata, popularity data, and user account connection" , "Идентифицирует приложение в Last.fm и включает метаданные, данные о популярности и подключение аккаунтов";
     settings_lastfm_shared_secret: "Last.fm shared secret"    , "Shared secret Last.fm";
-    settings_lastfm_shared_secret_help: "Required for signed Last.fm scrobbling requests" , "Нужен для подписанных запросов скробблинга Last.fm";
+    settings_lastfm_shared_secret_help: "Authenticates signed Last.fm requests, including scrobbling. Keep this value private" , "Подтверждает подписанные запросы Last.fm, включая скробблинг. Не раскрывайте это значение";
 
     // OIDC login errors
     login_oidc_error:         "SSO login failed. Please try again." , "Ошибка входа через SSO. Попробуйте ещё раз.";
@@ -298,6 +298,9 @@ translations! {
     player_likes_playlist:   "Likes"                           , "Лайки";
     player_listened:         "listened"                        , "прослушано";
     player_search_placeholder: "Search artists, releases, tracks..." , "Поиск артистов, релизов, треков...";
+    player_search_similar_to: "Search similar to:"                , "Поиск похожих на:";
+    player_find_similar:      "Find similar tracks"                , "Найти похожие треки";
+    player_similarity_failed: "Similarity search failed"           , "Не удалось найти похожие треки";
     player_connection_lost: "Server connection lost"             , "Нет соединения с сервером";
     player_connection_lost_detail: "Player cannot reach the server. Retrying..." , "Плеер не может связаться с сервером. Повторяю...";
     player_active_device:   "Active device"                   , "Активный девайс";
@@ -309,10 +312,14 @@ translations! {
     player_cancel:           "Cancel"                          , "Отмена";
     player_create:           "Create"                          , "Создать";
     player_save:             "Save"                            , "Сохранить";
+    player_done:             "Done"                            , "Готово";
     player_delete:           "Delete"                          , "Удалить";
     player_delete_playlist_confirm: "Delete this playlist?"     , "Удалить этот плейлист?";
     player_rename:           "Rename"                          , "Переименовать";
     player_close:            "Close"                           , "Закрыть";
+    player_interface_language: "Interface language"             , "Язык интерфейса";
+    player_language_description: "Choose the language used by the web player." , "Выберите язык интерфейса веб-плеера.";
+    player_switch_language:  "Русский"                         , "English";
     player_log_out:          "Log out"                         , "Выйти";
     player_admin_panel:      "Admin Panel"                     , "Админка";
     player_info:             "Info"                            , "Информация";

src/lastfm.rs

@@ -447,17 +447,17 @@ async fn fetch_pending_scrobbles(
                   o.duration_seconds,
                   o.attempt_count,
                   a.session_key::text AS session_key,
-                  t.title::text AS title,
-                  r.title::text AS album_title,
+                  COALESCE(o.track_title, t.title::text) AS title,
+                  COALESCE(o.album_title, r.title::text) AS album_title,
                   t.track_number,
-                  (
+                  COALESCE(o.artist_name, (
                     SELECT ar.name::text
                       FROM furumusic__track_artist ta
                       JOIN furumusic__artist ar ON ar.id = ta.artist_id
                      WHERE ta.track_id = t.id AND ta.role <> 'featuring'
                      ORDER BY ta.position
                      LIMIT 1
-                  ) AS artist_name,
+                  )) AS artist_name,
                   (
                     SELECT ar.name::text
                       FROM furumusic__release_artist ra
@@ -468,7 +468,7 @@ async fn fetch_pending_scrobbles(
                   ) AS album_artist_name
              FROM furumusic__lastfm_scrobble_outbox o
              JOIN furumusic__lastfm_account a ON a.user_id = o.user_id
-             JOIN furumusic__track t ON t.id = o.track_id
+             LEFT JOIN furumusic__track t ON t.id = o.track_id
              LEFT JOIN furumusic__release r ON r.id = t.release_id
             WHERE o.user_id = $1
               AND o.status IN ('pending', 'retry')

src/main.rs

@@ -3,6 +3,7 @@ mod agent;
 mod api;
 mod auth;
 mod config;
+mod federation;
 mod i18n;
 mod jobs;
 mod lastfm;
@@ -12,6 +13,7 @@ mod music;
 mod oidc;
 mod player;
 mod scheduler;
+mod similarity;
 mod torrents;
 mod user;
 
@@ -559,6 +561,20 @@ impl Project for FuruProject {
                 .await;
         });
 
+        // Join the federation at boot when it was left enabled (the settings
+        // live in the config KV table; changes apply live from the admin).
+        let fed_config = Arc::clone(&self.app_config);
+        tokio::spawn(async move {
+            federation::handle().boot(&fed_config).await;
+        });
+
+        // Embedding calculation is an independent, server-wide background
+        // service. It remains useful locally when federation is disabled.
+        let similarity_config = Arc::clone(&self.app_config);
+        tokio::spawn(async move {
+            similarity::handle().boot(&similarity_config).await;
+        });
+
         apps.register(cot::session::db::SessionApp::new());
         apps.register_with_views(
             FuruApp {

src/metrics.rs

@@ -883,6 +883,7 @@ const KNOWN_HTTP_ROUTES: &[&str] = &[
     "/api/player/lastfm/now-playing",
     "/api/player/lastfm/scrobble",
     "/api/player/agent-queue",
+    "/api/player/offline/manifest",
     "/api/player/torrents",
     "/api/player/torrents/session/{id}",
     "/api/player/torrents/preview",

src/music/mod.rs

@@ -1951,6 +1951,624 @@ pub mod db_migrations {
             &[Operation::custom(create_playlist_share_links).build()];
     }
 
+    #[cot::db::migrations::migration_op]
+    async fn create_fed_device_sync(ctx: migrations::MigrationContext<'_>) -> cot::db::Result<()> {
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__federation_content_id_cache (
+                    media_file_id BIGINT PRIMARY KEY,
+                    sha256_hash TEXT NOT NULL,
+                    content_id TEXT NOT NULL,
+                    updated_at TEXT NOT NULL
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE INDEX IF NOT EXISTS idx_furumusic_federation_content_id_cache_content_id
+                   ON furumusic__federation_content_id_cache (content_id)",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__fed_device_identity (
+                    user_id BIGINT PRIMARY KEY,
+                    device_id TEXT NOT NULL UNIQUE,
+                    group_id TEXT NOT NULL,
+                    device_name TEXT NOT NULL,
+                    local_seq BIGINT NOT NULL DEFAULT 0,
+                    last_hlc_ms BIGINT NOT NULL DEFAULT 0,
+                    local_seeded_at_ms BIGINT NOT NULL DEFAULT 0,
+                    last_sync TEXT,
+                    last_error TEXT
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__fed_device (
+                    user_id BIGINT NOT NULL,
+                    device_id TEXT NOT NULL,
+                    name TEXT NOT NULL DEFAULT '',
+                    client_version TEXT NOT NULL DEFAULT '',
+                    protocol_version INTEGER NOT NULL DEFAULT 1,
+                    endpoint_id TEXT NOT NULL DEFAULT '',
+                    endpoint_ticket TEXT NOT NULL DEFAULT '',
+                    trusted_at_ms BIGINT,
+                    last_seen_ms BIGINT,
+                    revoked_at_ms BIGINT,
+                    revoked_by TEXT,
+                    revoke_cutoff_seq BIGINT,
+                    PRIMARY KEY (user_id, device_id)
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE UNIQUE INDEX IF NOT EXISTS idx_fed_device_single_user
+                   ON furumusic__fed_device (device_id)
+                 WHERE trusted_at_ms IS NOT NULL",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__fed_device_invite (
+                    invite_id TEXT PRIMARY KEY,
+                    user_id BIGINT NOT NULL,
+                    secret_hash TEXT NOT NULL,
+                    expires_at_ms BIGINT NOT NULL,
+                    created_at_ms BIGINT NOT NULL,
+                    used_at_ms BIGINT
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__fed_pending_pairing (
+                    request_id TEXT PRIMARY KEY,
+                    user_id BIGINT NOT NULL,
+                    device_id TEXT NOT NULL,
+                    name TEXT NOT NULL,
+                    client_version TEXT NOT NULL,
+                    endpoint_id TEXT NOT NULL,
+                    endpoint_ticket TEXT NOT NULL,
+                    invite_id TEXT NOT NULL,
+                    created_at_ms BIGINT NOT NULL,
+                    answered_at_ms BIGINT,
+                    status TEXT NOT NULL,
+                    requester_group_id TEXT,
+                    requester_group_active_devices BIGINT NOT NULL DEFAULT 1,
+                    requester_group_devices_json TEXT NOT NULL DEFAULT '[]',
+                    use_requester_group BOOLEAN NOT NULL DEFAULT false
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE INDEX IF NOT EXISTS idx_fed_pending_pairing_user_status
+                   ON furumusic__fed_pending_pairing (user_id, status, created_at_ms DESC)",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__fed_sync_ops (
+                    user_id BIGINT NOT NULL,
+                    op_id TEXT NOT NULL,
+                    origin_device_id TEXT NOT NULL,
+                    seq BIGINT NOT NULL,
+                    kind TEXT NOT NULL,
+                    payload_json JSONB NOT NULL,
+                    hlc_ms BIGINT NOT NULL,
+                    received_at_ms BIGINT NOT NULL,
+                    tombstone BOOLEAN NOT NULL DEFAULT false,
+                    PRIMARY KEY (user_id, op_id)
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE INDEX IF NOT EXISTS idx_fed_sync_ops_origin_seq
+                   ON furumusic__fed_sync_ops (user_id, origin_device_id, seq)",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE INDEX IF NOT EXISTS idx_fed_sync_ops_tombstone
+                   ON furumusic__fed_sync_ops (user_id, tombstone)",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__fed_sync_vector (
+                    user_id BIGINT NOT NULL,
+                    device_id TEXT NOT NULL,
+                    max_seq BIGINT NOT NULL,
+                    PRIMARY KEY (user_id, device_id)
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__fed_peer_ack (
+                    user_id BIGINT NOT NULL,
+                    peer_device_id TEXT NOT NULL,
+                    origin_device_id TEXT NOT NULL,
+                    max_seq BIGINT NOT NULL,
+                    updated_at_ms BIGINT NOT NULL,
+                    PRIMARY KEY (user_id, peer_device_id, origin_device_id)
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__fed_state_like (
+                    user_id BIGINT NOT NULL,
+                    content_id TEXT NOT NULL,
+                    liked BOOLEAN NOT NULL,
+                    hlc_ms BIGINT NOT NULL,
+                    op_id TEXT NOT NULL,
+                    local_track_id BIGINT,
+                    fed_json JSONB,
+                    PRIMARY KEY (user_id, content_id)
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__fed_state_playlist (
+                    user_id BIGINT NOT NULL,
+                    playlist_id TEXT NOT NULL,
+                    local_playlist_id BIGINT,
+                    title TEXT NOT NULL,
+                    deleted BOOLEAN NOT NULL DEFAULT false,
+                    hlc_ms BIGINT NOT NULL,
+                    op_id TEXT NOT NULL,
+                    PRIMARY KEY (user_id, playlist_id)
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE UNIQUE INDEX IF NOT EXISTS idx_fed_state_playlist_local
+                   ON furumusic__fed_state_playlist (user_id, local_playlist_id)
+                 WHERE local_playlist_id IS NOT NULL",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__fed_state_playlist_item (
+                    user_id BIGINT NOT NULL,
+                    playlist_id TEXT NOT NULL,
+                    content_id TEXT NOT NULL,
+                    present BOOLEAN NOT NULL DEFAULT true,
+                    position BIGINT NOT NULL DEFAULT 0,
+                    hlc_ms BIGINT NOT NULL,
+                    op_id TEXT NOT NULL,
+                    local_track_id BIGINT,
+                    fed_json JSONB,
+                    PRIMARY KEY (user_id, playlist_id, content_id)
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE INDEX IF NOT EXISTS idx_fed_state_playlist_item_playlist
+                   ON furumusic__fed_state_playlist_item
+                      (user_id, playlist_id, present, position)",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__fed_playback_applied (
+                    user_id BIGINT NOT NULL,
+                    op_id TEXT NOT NULL,
+                    applied_at_ms BIGINT NOT NULL,
+                    PRIMARY KEY (user_id, op_id)
+                )",
+            )
+            .await?;
+        Ok(())
+    }
+
+    #[derive(Debug, Copy, Clone)]
+    pub struct M0038CreateFedDeviceSync;
+
+    impl migrations::Migration for M0038CreateFedDeviceSync {
+        const APP_NAME: &'static str = "furumusic";
+        const MIGRATION_NAME: &'static str = "m_0038_create_fed_device_sync";
+        const DEPENDENCIES: &'static [migrations::MigrationDependency] =
+            &[migrations::MigrationDependency::migration(
+                "furumusic",
+                "m_0037_create_playlist_share_links",
+            )];
+        const OPERATIONS: &'static [Operation] =
+            &[Operation::custom(create_fed_device_sync).build()];
+    }
+
+    #[cot::db::migrations::migration_op]
+    async fn ensure_federation_content_id_cache(
+        ctx: migrations::MigrationContext<'_>,
+    ) -> cot::db::Result<()> {
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__federation_content_id_cache (
+                    media_file_id BIGINT PRIMARY KEY,
+                    sha256_hash TEXT NOT NULL,
+                    content_id TEXT NOT NULL,
+                    updated_at TEXT NOT NULL
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE INDEX IF NOT EXISTS idx_furumusic_federation_content_id_cache_content_id
+                   ON furumusic__federation_content_id_cache (content_id)",
+            )
+            .await?;
+        Ok(())
+    }
+
+    #[derive(Debug, Copy, Clone)]
+    pub struct M0039EnsureFederationContentIdCache;
+
+    impl migrations::Migration for M0039EnsureFederationContentIdCache {
+        const APP_NAME: &'static str = "furumusic";
+        const MIGRATION_NAME: &'static str = "m_0039_ensure_federation_content_id_cache";
+        const DEPENDENCIES: &'static [migrations::MigrationDependency] =
+            &[migrations::MigrationDependency::migration(
+                "furumusic",
+                "m_0038_create_fed_device_sync",
+            )];
+        const OPERATIONS: &'static [Operation] =
+            &[Operation::custom(ensure_federation_content_id_cache).build()];
+    }
+
+    #[cot::db::migrations::migration_op]
+    async fn create_content_addressed_music_refs(
+        ctx: migrations::MigrationContext<'_>,
+    ) -> cot::db::Result<()> {
+        // A track reference is durable user-facing identity. `local_track_id`
+        // is availability, not identity: it may become non-NULL after a
+        // federated track is materialized without changing likes/playlists.
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__track_ref (
+                    id BIGSERIAL PRIMARY KEY,
+                    content_id TEXT NOT NULL UNIQUE,
+                    local_track_id BIGINT UNIQUE,
+                    title TEXT NOT NULL,
+                    release_title TEXT,
+                    year INTEGER,
+                    duration_seconds DOUBLE PRECISION,
+                    metadata_json JSONB NOT NULL DEFAULT '{}'::jsonb,
+                    metadata_authority TEXT NOT NULL DEFAULT 'local',
+                    created_at TEXT NOT NULL,
+                    updated_at TEXT NOT NULL
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE INDEX IF NOT EXISTS idx_track_ref_local_track
+                   ON furumusic__track_ref (local_track_id)
+                 WHERE local_track_id IS NOT NULL",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__federation_track_source (
+                    track_ref_id BIGINT NOT NULL REFERENCES furumusic__track_ref(id)
+                        ON DELETE CASCADE,
+                    owner_peer_id TEXT NOT NULL,
+                    item_id TEXT NOT NULL,
+                    last_seen_ms BIGINT NOT NULL,
+                    metadata_json JSONB NOT NULL DEFAULT '{}'::jsonb,
+                    PRIMARY KEY (owner_peer_id, item_id)
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE INDEX IF NOT EXISTS idx_federation_track_source_ref
+                   ON furumusic__federation_track_source (track_ref_id, last_seen_ms DESC)",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "ALTER TABLE furumusic__user_liked_track
+                   ADD COLUMN IF NOT EXISTS track_ref_id BIGINT
+                       REFERENCES furumusic__track_ref(id)",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE UNIQUE INDEX IF NOT EXISTS idx_user_liked_track_ref_uniq
+                   ON furumusic__user_liked_track (user_id, track_ref_id)
+                 WHERE track_ref_id IS NOT NULL",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "ALTER TABLE furumusic__playlist_track
+                   ADD COLUMN IF NOT EXISTS track_ref_id BIGINT
+                       REFERENCES furumusic__track_ref(id)",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE INDEX IF NOT EXISTS idx_playlist_track_ref
+                   ON furumusic__playlist_track (track_ref_id)
+                 WHERE track_ref_id IS NOT NULL",
+            )
+            .await?;
+        // History deliberately remains local-track based. Only the web
+        // player's existing playback report records history and triggers
+        // Last.fm scrobbling.
+        Ok(())
+    }
+
+    #[derive(Debug, Copy, Clone)]
+    pub struct M0040CreateContentAddressedMusicRefs;
+
+    impl migrations::Migration for M0040CreateContentAddressedMusicRefs {
+        const APP_NAME: &'static str = "furumusic";
+        const MIGRATION_NAME: &'static str = "m_0040_create_content_addressed_music_refs";
+        const DEPENDENCIES: &'static [migrations::MigrationDependency] =
+            &[migrations::MigrationDependency::migration(
+                "furumusic",
+                "m_0039_ensure_federation_content_id_cache",
+            )];
+        const OPERATIONS: &'static [Operation] =
+            &[Operation::custom(create_content_addressed_music_refs).build()];
+    }
+
+    #[cot::db::migrations::migration_op]
+    async fn create_synced_listen_history(
+        ctx: migrations::MigrationContext<'_>,
+    ) -> cot::db::Result<()> {
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__listen_event (
+                    user_id BIGINT NOT NULL,
+                    listen_id TEXT NOT NULL,
+                    content_id TEXT NOT NULL,
+                    local_track_id BIGINT,
+                    origin_device_id TEXT NOT NULL,
+                    started_at_ms BIGINT NOT NULL,
+                    listened_ms BIGINT NOT NULL,
+                    track_duration_ms BIGINT,
+                    ended_reason TEXT NOT NULL,
+                    qualified BOOLEAN NOT NULL,
+                    metadata_json JSONB NOT NULL,
+                    created_at TEXT NOT NULL,
+                    PRIMARY KEY (user_id, listen_id)
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE INDEX IF NOT EXISTS idx_listen_event_user_time
+                   ON furumusic__listen_event (user_id, started_at_ms DESC, listen_id)",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE INDEX IF NOT EXISTS idx_listen_event_content
+                   ON furumusic__listen_event (user_id, content_id)",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "INSERT INTO furumusic__listen_event
+                    (user_id, listen_id, content_id, local_track_id,
+                     origin_device_id, started_at_ms, listened_ms,
+                     track_duration_ms, ended_reason, qualified,
+                     metadata_json, created_at)
+                 SELECT ph.user_id,
+                        'legacy-web:' || ph.id::text,
+                        tr.content_id,
+                        ph.track_id,
+                        ident.device_id,
+                        (EXTRACT(EPOCH FROM ph.played_at::timestamptz) * 1000)::bigint,
+                        COALESCE(ph.duration_listened, 0)::bigint * 1000,
+                        (t.duration_seconds * 1000)::bigint,
+                        CASE WHEN ph.completed THEN '\"finished\"' ELSE '\"unknown\"' END,
+                        ph.completed,
+                        jsonb_build_object(
+                            'title', t.title::text,
+                            'artist_names', COALESCE((
+                                SELECT jsonb_agg(a.name::text ORDER BY ta.position)
+                                  FROM furumusic__track_artist ta
+                                  JOIN furumusic__artist a ON a.id = ta.artist_id
+                                 WHERE ta.track_id = t.id
+                                   AND ta.role <> 'featuring'
+                            ), '[]'::jsonb),
+                            'featured_artist_names', COALESCE((
+                                SELECT jsonb_agg(a.name::text ORDER BY ta.position)
+                                  FROM furumusic__track_artist ta
+                                  JOIN furumusic__artist a ON a.id = ta.artist_id
+                                 WHERE ta.track_id = t.id
+                                   AND ta.role = 'featuring'
+                            ), '[]'::jsonb),
+                            'release_title', r.title::text
+                        ),
+                        ph.played_at::text
+                   FROM furumusic__play_history ph
+                   JOIN furumusic__track t ON t.id = ph.track_id
+                   JOIN furumusic__track_ref tr ON tr.local_track_id = ph.track_id
+                   JOIN furumusic__fed_device_identity ident
+                     ON ident.user_id = ph.user_id
+                   LEFT JOIN furumusic__release r ON r.id = t.release_id
+                 ON CONFLICT (user_id, listen_id) DO NOTHING",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "ALTER TABLE furumusic__lastfm_scrobble_outbox
+                   ALTER COLUMN track_id DROP NOT NULL",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "ALTER TABLE furumusic__lastfm_scrobble_outbox
+                   ADD COLUMN IF NOT EXISTS track_title TEXT,
+                   ADD COLUMN IF NOT EXISTS artist_name TEXT,
+                   ADD COLUMN IF NOT EXISTS album_title TEXT",
+            )
+            .await?;
+        Ok(())
+    }
+
+    #[derive(Debug, Copy, Clone)]
+    pub struct M0041CreateSyncedListenHistory;
+
+    impl migrations::Migration for M0041CreateSyncedListenHistory {
+        const APP_NAME: &'static str = "furumusic";
+        const MIGRATION_NAME: &'static str = "m_0041_create_synced_listen_history";
+        const DEPENDENCIES: &'static [migrations::MigrationDependency] =
+            &[migrations::MigrationDependency::migration(
+                "furumusic",
+                "m_0040_create_content_addressed_music_refs",
+            )];
+        const OPERATIONS: &'static [Operation] =
+            &[Operation::custom(create_synced_listen_history).build()];
+    }
+
+    #[cot::db::migrations::migration_op]
+    async fn repair_legacy_listen_qualification(
+        ctx: migrations::MigrationContext<'_>,
+    ) -> cot::db::Result<()> {
+        ctx.db
+            .raw(
+                "UPDATE furumusic__listen_event le
+                    SET qualified = (
+                        ph.completed
+                        OR (
+                            COALESCE(ph.duration_listened, 0) >= 5
+                            AND COALESCE(t.duration_seconds, 0) > 0
+                            AND COALESCE(ph.duration_listened, 0) >= LEAST(
+                                COALESCE(t.duration_seconds, 0) / 2.0,
+                                240.0
+                            )
+                        )
+                    )
+                   FROM furumusic__play_history ph
+                   JOIN furumusic__track t ON t.id = ph.track_id
+                  WHERE le.user_id = ph.user_id
+                    AND le.listen_id = 'legacy-web:' || ph.id::text",
+            )
+            .await?;
+        Ok(())
+    }
+
+    #[derive(Debug, Copy, Clone)]
+    pub struct M0042RepairLegacyListenQualification;
+
+    impl migrations::Migration for M0042RepairLegacyListenQualification {
+        const APP_NAME: &'static str = "furumusic";
+        const MIGRATION_NAME: &'static str = "m_0042_repair_legacy_listen_qualification";
+        const DEPENDENCIES: &'static [migrations::MigrationDependency] =
+            &[migrations::MigrationDependency::migration(
+                "furumusic",
+                "m_0041_create_synced_listen_history",
+            )];
+        const OPERATIONS: &'static [Operation] =
+            &[Operation::custom(repair_legacy_listen_qualification).build()];
+    }
+
+    #[cot::db::migrations::migration_op]
+    async fn create_similarity_embeddings(
+        ctx: migrations::MigrationContext<'_>,
+    ) -> cot::db::Result<()> {
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__similarity_profile (
+                    profile_id TEXT PRIMARY KEY,
+                    model_id TEXT NOT NULL,
+                    model_version TEXT NOT NULL,
+                    model_sha256 TEXT NOT NULL,
+                    preprocessing TEXT NOT NULL,
+                    dimensions INTEGER NOT NULL,
+                    active BOOLEAN NOT NULL DEFAULT FALSE,
+                    created_at TEXT NOT NULL
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE UNIQUE INDEX IF NOT EXISTS idx_similarity_profile_active
+                   ON furumusic__similarity_profile (active)
+                 WHERE active = TRUE",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__track_embedding (
+                    track_id BIGINT NOT NULL REFERENCES furumusic__track(id)
+                        ON DELETE CASCADE,
+                    profile_id TEXT NOT NULL REFERENCES furumusic__similarity_profile(profile_id)
+                        ON DELETE CASCADE,
+                    dimensions INTEGER NOT NULL,
+                    vector BYTEA NOT NULL,
+                    source_sha256 TEXT NOT NULL,
+                    source_content_id TEXT,
+                    computed_at TEXT NOT NULL,
+                    PRIMARY KEY (track_id, profile_id)
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE INDEX IF NOT EXISTS idx_track_embedding_profile
+                   ON furumusic__track_embedding (profile_id, track_id)",
+            )
+            .await?;
+        Ok(())
+    }
+
+    #[derive(Debug, Copy, Clone)]
+    pub struct M0043CreateSimilarityEmbeddings;
+
+    impl migrations::Migration for M0043CreateSimilarityEmbeddings {
+        const APP_NAME: &'static str = "furumusic";
+        const MIGRATION_NAME: &'static str = "m_0043_create_similarity_embeddings";
+        const DEPENDENCIES: &'static [migrations::MigrationDependency] =
+            &[migrations::MigrationDependency::migration(
+                "furumusic",
+                "m_0042_repair_legacy_listen_qualification",
+            )];
+        const OPERATIONS: &'static [Operation] =
+            &[Operation::custom(create_similarity_embeddings).build()];
+    }
+
+    #[cot::db::migrations::migration_op]
+    async fn add_similarity_routing_signature(
+        ctx: migrations::MigrationContext<'_>,
+    ) -> cot::db::Result<()> {
+        ctx.db
+            .raw(
+                "ALTER TABLE furumusic__track_embedding
+                 ADD COLUMN IF NOT EXISTS routing_signature BYTEA",
+            )
+            .await?;
+        Ok(())
+    }
+
+    #[derive(Debug, Copy, Clone)]
+    pub struct M0044AddSimilarityRoutingSignature;
+
+    impl migrations::Migration for M0044AddSimilarityRoutingSignature {
+        const APP_NAME: &'static str = "furumusic";
+        const MIGRATION_NAME: &'static str = "m_0044_add_similarity_routing_signature";
+        const DEPENDENCIES: &'static [migrations::MigrationDependency] =
+            &[migrations::MigrationDependency::migration(
+                "furumusic",
+                "m_0043_create_similarity_embeddings",
+            )];
+        const OPERATIONS: &'static [Operation] =
+            &[Operation::custom(add_similarity_routing_signature).build()];
+    }
+
     pub const MIGRATIONS: &[&SyncDynMigration] = &[
         &M0006CreateMediaFile,
         &M0007CreateArtist,
@@ -1979,5 +2597,12 @@ pub mod db_migrations {
         &M0035CreateEntityGenreTags,
         &M0036CreateExternalMetadataIds,
         &M0037CreatePlaylistShareLinks,
+        &M0038CreateFedDeviceSync,
+        &M0039EnsureFederationContentIdCache,
+        &M0040CreateContentAddressedMusicRefs,
+        &M0041CreateSyncedListenHistory,
+        &M0042RepairLegacyListenQualification,
+        &M0043CreateSimilarityEmbeddings,
+        &M0044AddSimilarityRoutingSignature,
     ];
 }

src/player/dto.rs

@@ -51,6 +51,7 @@ pub(super) struct ArtistRef {
 #[derive(Debug, Clone, Serialize, JsonSchema)]
 pub(super) struct TrackItem {
     pub(super) id: i64,
+    pub(super) content_id: Option<String>,
     pub(super) title: String,
     pub(super) track_number: Option<i32>,
     pub(super) disc_number: Option<i32>,
@@ -74,6 +75,15 @@ pub(super) struct TrackItem {
     pub(super) lastfm_updated_at: Option<String>,
 }
 
+#[derive(Debug, Serialize, JsonSchema)]
+pub(super) struct PlaylistTrackItem {
+    pub(super) playlist_track_id: Option<i64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) sort_key: Option<i64>,
+    #[serde(flatten)]
+    pub(super) track: TrackItem,
+}
+
 #[derive(Debug, Serialize, JsonSchema)]
 pub(super) struct ArtistAppearanceTrack {
     pub(super) id: i64,
@@ -265,6 +275,24 @@ pub(super) struct PlayerDevicesResponse {
     pub(super) playback_state: Option<PlayerDevicePlaybackStateDto>,
 }
 
+#[derive(Debug, Deserialize, JsonSchema)]
+pub(super) struct FedDeviceConnectRequest {
+    pub(super) invite: String,
+}
+
+#[derive(Debug, Deserialize, JsonSchema)]
+pub(super) struct FedDevicePairingAnswerRequest {
+    pub(super) request_id: String,
+    pub(super) accept: bool,
+    #[serde(default)]
+    pub(super) use_requester_group: bool,
+}
+
+#[derive(Debug, Deserialize, JsonSchema)]
+pub(super) struct FedDeviceRevokeRequest {
+    pub(super) device_id: String,
+}
+
 #[derive(Debug, Serialize, JsonSchema)]
 pub(super) struct PlayerDevicePollResponse {
     pub(super) device_id: String,
@@ -286,7 +314,7 @@ pub(super) struct PlaylistDetail {
     pub(super) is_public: bool,
     pub(super) is_saved: bool,
     pub(super) kind: String,
-    pub(super) tracks: Vec<TrackItem>,
+    pub(super) tracks: Vec<PlaylistTrackItem>,
 }
 
 #[derive(Debug, Serialize, JsonSchema)]
@@ -325,6 +353,45 @@ pub(super) struct UserProfile {
     pub(super) stats: UserStats,
 }
 
+#[derive(Debug, Serialize, JsonSchema)]
+pub(super) struct OfflineManifestResponse {
+    pub(super) generated_at: String,
+    pub(super) tracks: Vec<OfflineTrackManifestItem>,
+    pub(super) playlists: Vec<OfflinePlaylistManifestItem>,
+    pub(super) liked_track_ids: Vec<i64>,
+    pub(super) followed_artist_ids: Vec<i64>,
+}
+
+#[derive(Debug, Serialize, JsonSchema)]
+pub(super) struct OfflineTrackManifestItem {
+    pub(super) id: i64,
+    pub(super) updated_at: String,
+    pub(super) stream_url: String,
+    pub(super) audio_file_id: i64,
+    pub(super) audio_hash: String,
+    pub(super) audio_size_bytes: i64,
+    pub(super) audio_mime_type: String,
+    pub(super) audio_updated_at: String,
+    pub(super) cover_file_id: Option<i64>,
+    pub(super) cover_url: Option<String>,
+    pub(super) cover_hash: Option<String>,
+    pub(super) cover_updated_at: Option<String>,
+}
+
+#[derive(Debug, Serialize, JsonSchema)]
+pub(super) struct OfflinePlaylistManifestItem {
+    pub(super) id: i64,
+    pub(super) title: String,
+    pub(super) description: Option<String>,
+    pub(super) updated_at: String,
+    pub(super) is_own: bool,
+    pub(super) owner_name: Option<String>,
+    pub(super) is_public: bool,
+    pub(super) is_saved: bool,
+    pub(super) kind: String,
+    pub(super) track_ids: Vec<i64>,
+}
+
 #[derive(Debug, Serialize, JsonSchema)]
 pub(super) struct LastfmStatus {
     pub(super) configured: bool,
@@ -474,14 +541,16 @@ pub(super) struct UserUploadReviewUpdateRequest {
 
 #[derive(Debug, Serialize, JsonSchema)]
 pub(super) struct PlayHistoryItem {
-    pub(super) id: i64,
-    pub(super) track_id: i64,
+    pub(super) id: String,
+    pub(super) track_id: Option<i64>,
     pub(super) track_title: String,
     pub(super) release_title: Option<String>,
-    pub(super) track: TrackItem,
+    pub(super) track: serde_json::Value,
     pub(super) played_at: String,
     pub(super) duration_listened: Option<i32>,
     pub(super) completed: bool,
+    pub(super) device_id: String,
+    pub(super) device_name: String,
 }
 
 #[derive(Debug, Serialize, JsonSchema)]
@@ -497,6 +566,46 @@ pub(super) struct LikeStatus {
     pub(super) liked: bool,
 }
 
+#[derive(Debug, Deserialize, JsonSchema)]
+pub(super) struct ContentTrackMutation {
+    pub(super) content_id: String,
+    pub(super) liked: Option<bool>,
+    pub(super) playlist_id: Option<i64>,
+    pub(super) position: Option<i64>,
+    pub(super) federation: Option<serde_json::Value>,
+}
+
+#[derive(Debug, Deserialize, JsonSchema)]
+pub(super) struct PrepareFederatedTrackRequest {
+    pub(super) content_id: String,
+    pub(super) owner: Option<String>,
+    pub(super) item_id: Option<String>,
+}
+
+#[derive(Debug, Deserialize, JsonSchema)]
+pub(super) struct FederationArtworkQuery {
+    pub(super) owner: String,
+    pub(super) item_id: String,
+}
+
+#[derive(Debug, Deserialize, JsonSchema)]
+pub(super) struct FederationArtistQuery {
+    pub(super) name: String,
+}
+
+#[derive(Debug, Deserialize, JsonSchema)]
+pub(super) struct FederationCatalogArtworkQuery {
+    pub(super) owner: String,
+    pub(super) artist: String,
+    pub(super) release: Option<String>,
+}
+
+#[derive(Debug, Deserialize, JsonSchema)]
+pub(super) struct FederationArtworkDiscoveryQuery {
+    pub(super) artist: String,
+    pub(super) release: Option<String>,
+}
+
 #[derive(Debug, Serialize, JsonSchema)]
 pub(super) struct LikedIds {
     pub(super) track_ids: Vec<i64>,

src/player/queries.rs

@@ -3,9 +3,11 @@ use serde::Deserialize;
 #[derive(Debug, Deserialize)]
 pub(super) struct HistoryEntry {
     pub(super) track_id: i64,
+    pub(super) listen_id: Option<String>,
     pub(super) started_at: Option<i64>,
     pub(super) duration_listened: Option<i32>,
     pub(super) completed: bool,
+    pub(super) ended_reason: Option<String>,
 }
 
 #[derive(Debug, Deserialize)]
@@ -42,7 +44,13 @@ pub(super) struct AddTracksRequest {
 
 #[derive(Debug, Deserialize)]
 pub(super) struct RemoveTrackRequest {
-    pub(super) track_id: i64,
+    pub(super) track_id: Option<i64>,
+    pub(super) playlist_track_id: Option<i64>,
+}
+
+#[derive(Debug, Deserialize)]
+pub(super) struct ReorderPlaylistRequest {
+    pub(super) playlist_track_ids: Vec<i64>,
 }
 
 #[derive(Debug, Deserialize)]

src/player/rows.rs

@@ -56,6 +56,8 @@ pub(super) struct MediaFileRow {
     pub(super) file_path: String,
     pub(super) mime_type: String,
     pub(super) file_size_bytes: i64,
+    pub(super) sha256_hash: String,
+    pub(super) created_at: String,
 }
 
 #[derive(sqlx::FromRow)]
@@ -93,6 +95,7 @@ pub(super) struct PlaylistInfoRow {
 
 #[derive(sqlx::FromRow)]
 pub(super) struct PlaylistTrackRow {
+    pub(super) playlist_track_id: Option<i64>,
     pub(super) id: i64,
     pub(super) title: String,
     pub(super) track_number: Option<i32>,
@@ -251,34 +254,6 @@ pub(super) struct ReleaseUploaderRow {
     pub(super) track_count: i64,
 }
 
-#[derive(sqlx::FromRow)]
-pub(super) struct PlayHistoryTrackRow {
-    pub(super) history_id: i64,
-    pub(super) played_at: String,
-    pub(super) duration_listened: Option<i32>,
-    pub(super) completed: bool,
-    pub(super) id: i64,
-    pub(super) title: String,
-    pub(super) track_number: Option<i32>,
-    pub(super) disc_number: Option<i32>,
-    pub(super) duration_seconds: f64,
-    pub(super) cover_file_id: Option<i64>,
-    pub(super) release_cover_file_id: Option<i64>,
-    pub(super) release_id: i64,
-    pub(super) release_title: String,
-    pub(super) release_year: Option<i32>,
-    pub(super) uploader_name: String,
-    pub(super) audio_format: Option<String>,
-    pub(super) audio_bitrate: Option<i32>,
-    pub(super) audio_sample_rate: Option<i32>,
-    pub(super) audio_bit_depth: Option<i32>,
-    pub(super) file_size_bytes: Option<i64>,
-    pub(super) lastfm_listeners: Option<i64>,
-    pub(super) lastfm_playcount: Option<i64>,
-    pub(super) lastfm_rating: Option<f64>,
-    pub(super) lastfm_updated_at: Option<String>,
-}
-
 #[derive(sqlx::FromRow)]
 pub(super) struct ReleaseInfoRow {
     pub(super) id: i64,
@@ -287,3 +262,30 @@ pub(super) struct ReleaseInfoRow {
     pub(super) year: Option<i32>,
     pub(super) cover_file_id: Option<i64>,
 }
+
+#[derive(sqlx::FromRow)]
+pub(super) struct OfflineTrackManifestRow {
+    pub(super) id: i64,
+    pub(super) updated_at: String,
+    pub(super) audio_file_id: i64,
+    pub(super) audio_hash: String,
+    pub(super) audio_size_bytes: i64,
+    pub(super) audio_mime_type: String,
+    pub(super) audio_updated_at: String,
+    pub(super) cover_file_id: Option<i64>,
+    pub(super) cover_hash: Option<String>,
+    pub(super) cover_updated_at: Option<String>,
+}
+
+#[derive(sqlx::FromRow)]
+pub(super) struct OfflinePlaylistManifestRow {
+    pub(super) id: i64,
+    pub(super) title: String,
+    pub(super) description: Option<String>,
+    pub(super) updated_at: String,
+    pub(super) is_own: bool,
+    pub(super) owner_name: String,
+    pub(super) is_public: bool,
+    pub(super) is_saved: bool,
+    pub(super) track_ids: Vec<i64>,
+}

templates/admin/v2.html

@@ -806,35 +806,68 @@ tbody tr:hover {
 }
 
 .settings-page {
-    max-width: none;
+    max-width: 1440px;
+    margin: 0 auto;
 }
 
 .settings-layout {
     display: grid;
-    grid-template-columns: minmax(620px, 1fr) minmax(360px, 440px);
-    gap: 14px;
-    align-items: start;
+    grid-template-columns: repeat(12, minmax(0, 1fr));
+    grid-template-areas:
+        "access access access access oidc oidc oidc oidc oidc oidc oidc oidc"
+        "agent agent agent agent agent agent agent agent agentstatus agentstatus agentstatus agentstatus"
+        "similarity similarity similarity similarity similarity similarity similarity similarity similaritystatus similaritystatus similaritystatus similaritystatus"
+        "federation federation federation federation federation federation federation federation federation federation federation federation"
+        "lastfm lastfm lastfm lastfm lastfm lastfm lastfm lastfm developer developer developer developer"
+        "actions actions actions actions actions actions actions actions actions actions actions actions";
+    gap: 16px;
+    align-items: stretch;
 }
 
 .settings-column {
-    display: grid;
-    gap: 14px;
-    align-content: start;
+    display: contents;
 }
 
-.settings-side .settings-grid {
+.settings-section {
+    min-width: 0;
+    margin: 0;
+}
+.settings-access { grid-area: access; }
+.settings-oidc { grid-area: oidc; }
+.settings-agent { grid-area: agent; }
+.settings-agent-status { grid-area: agentstatus; }
+.settings-similarity { grid-area: similarity; }
+.settings-similarity-status { grid-area: similaritystatus; }
+.settings-federation { grid-area: federation; }
+.settings-lastfm { grid-area: lastfm; }
+.settings-developer { grid-area: developer; }
+.settings-section-narrow { border-left: 2px solid rgba(29, 185, 84, 0.55); }
+
+.settings-access .settings-grid,
+.settings-developer .settings-grid {
     grid-template-columns: minmax(0, 1fr);
 }
 
+.settings-section-narrow .panel-head {
+    background: rgba(29, 185, 84, 0.035);
+}
+
 .settings-actions {
-    grid-column: 1 / -1;
+    grid-area: actions;
+    position: sticky;
+    bottom: 0;
+    z-index: 5;
+    border: 1px solid var(--border-color);
+    border-radius: 8px;
+    background: rgba(35, 35, 35, 0.96);
+    backdrop-filter: blur(10px);
 }
 
 .settings-grid {
     display: grid;
     grid-template-columns: repeat(2, minmax(0, 1fr));
-    gap: 10px;
-    padding: 14px;
+    gap: 14px 16px;
+    padding: 16px;
 }
 
 .settings-card {
@@ -843,22 +876,26 @@ tbody tr:hover {
 
 .setting-field {
     min-width: 0;
+    max-width: 480px;
 }
 
+.setting-field.settings-short { max-width: 150px; }
+.settings-wide { max-width: 680px; }
+
 .setting-field label,
 .setting-toggle label {
     display: flex;
     align-items: center;
     justify-content: space-between;
     gap: 8px;
-    margin-bottom: 6px;
+    margin-bottom: 7px;
     color: var(--text-secondary);
-    font-size: 11px;
-    font-weight: 800;
-    text-transform: uppercase;
+    font-size: 12px;
+    font-weight: 700;
 }
 
-.setting-field input {
+.setting-field input,
+.setting-field select {
     width: 100%;
     height: 34px;
     padding: 0 10px;
@@ -869,13 +906,27 @@ tbody tr:hover {
     outline: none;
 }
 
-.setting-field input:focus {
+.setting-field textarea {
+    width: 100%;
+    min-height: 68px;
+    padding: 8px 10px;
+    border: 1px solid var(--border-color);
+    border-radius: 6px;
+    background: var(--bg-primary);
+    color: var(--text-primary);
+    outline: none;
+    resize: vertical;
+}
+
+.setting-field input:focus,
+.setting-field select:focus,
+.setting-field textarea:focus {
     border-color: var(--accent);
 }
 
 .setting-toggle {
-    min-height: 74px;
-    padding: 12px;
+    min-height: 68px;
+    padding: 11px 12px;
     border: 1px solid var(--border-color);
     border-radius: 8px;
     background: var(--bg-primary);
@@ -894,9 +945,12 @@ tbody tr:hover {
     font-weight: 800;
 }
 
-.setting-toggle input {
+.setting-toggle input,
+.setting-toggle-row input[type="checkbox"] {
+    flex: 0 0 auto;
     width: 18px;
     height: 18px;
+    padding: 0;
     accent-color: var(--accent);
 }
 
@@ -904,7 +958,8 @@ tbody tr:hover {
     margin-top: 6px;
     color: var(--text-subdued);
     font-size: 11px;
-    line-height: 1.4;
+    line-height: 1.45;
+    max-width: 68ch;
 }
 
 .source-pill {
@@ -929,6 +984,101 @@ tbody tr:hover {
     grid-column: 1 / -1;
 }
 
+.settings-federation-body {
+    display: grid;
+    grid-template-columns: minmax(360px, 4fr) minmax(580px, 8fr);
+    gap: 20px;
+    padding: 16px;
+}
+
+.settings-federation-body > .settings-grid,
+.settings-federation-body > .probe-body {
+    padding: 0;
+}
+
+.federation-status-grid {
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    gap: 12px;
+}
+
+.transport-log {
+    grid-column: 1 / -1;
+    min-width: 0;
+}
+
+.transport-log-head {
+    display: flex;
+    align-items: end;
+    justify-content: space-between;
+    gap: 12px;
+    margin: 14px 0 7px;
+}
+
+.transport-log-head strong { font-size: 12px; }
+.transport-log-head span { color: var(--text-subdued); font-size: 11px; }
+
+.transport-log-scroll {
+    max-height: 210px;
+    overflow: auto;
+    border: 1px solid var(--border-color);
+    border-radius: 7px;
+    background: var(--bg-primary);
+}
+
+.transport-row {
+    display: grid;
+    grid-template-columns: 68px minmax(100px, 1.2fr) 84px 72px 54px 64px 64px 66px 66px 66px;
+    gap: 8px;
+    align-items: center;
+    min-width: 850px;
+    min-height: 30px;
+    padding: 5px 9px;
+    border-bottom: 1px solid rgba(255, 255, 255, 0.055);
+    color: var(--text-secondary);
+    font: 11px/1.2 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+    font-variant-numeric: tabular-nums;
+    white-space: nowrap;
+}
+
+.transport-row:last-child { border-bottom: 0; }
+.transport-row.transport-header {
+    position: sticky;
+    top: 0;
+    z-index: 1;
+    color: var(--text-subdued);
+    background: var(--bg-elevated);
+    font-size: 10px;
+    font-weight: 850;
+    text-transform: uppercase;
+}
+.transport-row > span { overflow: hidden; text-overflow: ellipsis; }
+.transport-number { text-align: right; }
+
+@media (max-width: 1000px) {
+    .settings-layout {
+        grid-template-columns: 1fr;
+        grid-template-areas:
+            "access"
+            "oidc"
+            "agent"
+            "agentstatus"
+            "similarity"
+            "similaritystatus"
+            "federation"
+            "lastfm"
+            "developer"
+            "actions";
+    }
+    .settings-federation-body { grid-template-columns: 1fr; }
+}
+
+@media (max-width: 700px) {
+    .settings-grid,
+    .federation-status-grid { grid-template-columns: 1fr; }
+    .setting-field { max-width: none; }
+}
+
 .settings-note {
     padding: 14px;
     color: var(--text-secondary);
@@ -937,7 +1087,7 @@ tbody tr:hover {
 }
 
 .probe-body {
-    padding: 14px;
+    padding: 16px;
 }
 
 .probe-intro {
@@ -955,9 +1105,43 @@ tbody tr:hover {
 }
 
 .probe-row {
-    display: flex;
-    justify-content: space-between;
-    gap: 10px;
+    display: grid;
+    grid-template-columns: minmax(0, 1fr) auto;
+    align-items: baseline;
+    gap: 12px;
+    min-height: 22px;
+}
+
+.probe-row strong {
+    max-width: 210px;
+    overflow: hidden;
+    text-align: right;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+
+.similarity-profile-details {
+    margin-top: 12px;
+    padding-top: 12px;
+    border-top: 1px solid var(--border-color);
+}
+
+.similarity-profile-details > span {
+    display: block;
+    margin-bottom: 5px;
+    color: var(--text-subdued);
+    font-size: 10px;
+    font-weight: 800;
+    text-transform: uppercase;
+}
+
+.similarity-profile-details pre {
+    margin: 0;
+    color: var(--text-secondary);
+    font: inherit;
+    font-size: 11px;
+    line-height: 1.45;
+    white-space: pre-wrap;
 }
 
 .library-row {
@@ -1560,7 +1744,7 @@ tbody tr:hover {
                 <p x-text="pageSubtitle()"></p>
             </div>
             <div class="top-actions">
-                <button class="btn" @click="refreshAll()">
+                <button class="btn" @click="refreshAll()" x-show="activeView !== 'settings'">
                     <i data-lucide="refresh-cw"></i>
                     Refresh
                 </button>
@@ -2059,7 +2243,7 @@ tbody tr:hover {
             <div class="settings-page">
                 <form class="settings-layout" @submit.prevent="saveSettings()">
                     <div class="settings-column">
-                        <section class="panel">
+                        <section class="panel settings-section settings-section-wide settings-oidc">
                             <div class="panel-head">
                                 <div class="panel-title">
                                     <strong>OIDC</strong>
@@ -2070,6 +2254,7 @@ tbody tr:hover {
                                 <div class="setting-field settings-wide">
                                     <label>Callback URL</label>
                                     <input readonly :value="callbackUrl()" />
+                                    <div class="setting-help">Register this exact redirect URL in your identity provider.</div>
                                 </div>
                                 <div class="setting-field">
                                     <label>
@@ -2105,6 +2290,7 @@ tbody tr:hover {
                                         <span class="source-pill" :class="sourceClass('oidc_admin_groups')" x-text="settingSource('oidc_admin_groups')"></span>
                                     </label>
                                     <input x-model="settingsDraft.oidc_admin_groups" placeholder="/admin,/furumusic-admins" />
+                                    <div class="setting-help">Comma-separated identity-provider groups whose members receive administrator access.</div>
                                 </div>
                                 <div class="setting-field">
                                     <label>
@@ -2112,11 +2298,12 @@ tbody tr:hover {
                                         <span class="source-pill" :class="sourceClass('oidc_user_groups')" x-text="settingSource('oidc_user_groups')"></span>
                                     </label>
                                     <input x-model="settingsDraft.oidc_user_groups" />
+                                    <div class="setting-help">Comma-separated groups allowed to sign in. Leave empty to allow any authenticated OIDC user.</div>
                                 </div>
                             </div>
                         </section>
 
-                        <section class="panel">
+                        <section class="panel settings-section settings-section-wide settings-agent">
                             <div class="panel-head">
                                 <div class="panel-title">
                                     <strong>Agent</strong>
@@ -2134,12 +2321,13 @@ tbody tr:hover {
                                         <input type="checkbox" x-model="settingsDraft.agent_enabled" />
                                     </div>
                                 </div>
-                                <div class="setting-field">
+                                <div class="setting-field settings-short">
                                     <label>
                                         <span>Concurrency</span>
                                         <span class="source-pill" :class="sourceClass('agent_concurrency')" x-text="settingSource('agent_concurrency')"></span>
                                     </label>
                                     <input type="number" min="1" max="32" x-model="settingsDraft.agent_concurrency" />
+                                    <div class="setting-help">Maximum number of inbox items processed at the same time. Higher values use more CPU and LLM capacity.</div>
                                 </div>
                                 <div class="setting-field settings-wide">
                                     <label>
@@ -2161,6 +2349,7 @@ tbody tr:hover {
                                         <span class="source-pill" :class="sourceClass('agent_llm_url')" x-text="settingSource('agent_llm_url')"></span>
                                     </label>
                                     <input x-model="settingsDraft.agent_llm_url" />
+                                    <div class="setting-help">Base URL of an OpenAI-compatible service. The agent sends chat requests to its <code>/v1/chat/completions</code> endpoint.</div>
                                 </div>
                                 <div class="setting-field">
                                     <label>
@@ -2168,6 +2357,7 @@ tbody tr:hover {
                                         <span class="source-pill" :class="sourceClass('agent_llm_model')" x-text="settingSource('agent_llm_model')"></span>
                                     </label>
                                     <input x-model="settingsDraft.agent_llm_model" />
+                                    <div class="setting-help">Model identifier sent to the configured LLM service, for example the name exposed by your local model server.</div>
                                 </div>
                                 <div class="setting-field">
                                     <label>
@@ -2175,6 +2365,7 @@ tbody tr:hover {
                                         <span class="source-pill" :class="sourceClass('agent_llm_auth')" x-text="settingSource('agent_llm_auth')"></span>
                                     </label>
                                     <input type="password" x-model="settingsDraft.agent_llm_auth" autocomplete="off" />
+                                    <div class="setting-help">Complete HTTP Authorization value expected by the LLM endpoint, for example <code>Bearer …</code>.</div>
                                 </div>
                                 <div class="setting-field">
                                     <label>
@@ -2182,6 +2373,7 @@ tbody tr:hover {
                                         <span class="source-pill" :class="sourceClass('agent_confidence_threshold')" x-text="settingSource('agent_confidence_threshold')"></span>
                                     </label>
                                     <input x-model="settingsDraft.agent_confidence_threshold" />
+                                    <div class="setting-help">Minimum confidence required to accept generated metadata automatically. Lower-confidence results are sent for review.</div>
                                 </div>
                                 <div class="setting-field">
                                     <label>
@@ -2189,13 +2381,71 @@ tbody tr:hover {
                                         <span class="source-pill" :class="sourceClass('agent_context_limit')" x-text="settingSource('agent_context_limit')"></span>
                                     </label>
                                     <input x-model="settingsDraft.agent_context_limit" />
+                                    <div class="setting-help">Maximum model context budget in tokens. Reduce it for smaller models or increase it when processing large batches.</div>
+                                </div>
+                            </div>
+                        </section>
+
+                        <section class="panel settings-section settings-section-wide settings-similarity">
+                            <div class="panel-head">
+                                <div class="panel-title">
+                                    <strong>Similarity Search</strong>
+                                    <span>Local audio embeddings and federated nearest-track search</span>
+                                </div>
+                            </div>
+                            <div class="settings-grid">
+                                <div class="setting-toggle settings-wide">
+                                    <label>
+                                        <span>Similarity search enabled</span>
+                                        <span class="source-pill" :class="sourceClass('similarity_enabled')" x-text="settingSource('similarity_enabled')"></span>
+                                    </label>
+                                    <div class="setting-toggle-row">
+                                        <span x-text="settingsDraft.similarity_enabled ? 'Enabled for this instance' : 'Disabled'"></span>
+                                        <input type="checkbox" x-model="settingsDraft.similarity_enabled" />
+                                    </div>
+                                    <div class="setting-help">Builds an audio fingerprint index for finding musically similar tracks. When federation is enabled, compatible peers can also participate in searches.</div>
+                                </div>
+                                <div class="setting-field settings-wide">
+                                    <label>
+                                        <span>Embedding model</span>
+                                        <span class="source-pill" :class="sourceClass('similarity_model')" x-text="settingSource('similarity_model')"></span>
+                                    </label>
+                                    <select x-model="settingsDraft.similarity_model">
+                                        <template x-for="model in similarityStatus.models || []" :key="model.id">
+                                            <option :value="model.id" x-text="`${model.id} · ${model.dimensions}d`"></option>
+                                        </template>
+                                    </select>
+                                    <div class="setting-help">
+                                        <span>The model converts audio into vectors used for comparison. Changing it rebuilds the search index.</span>
+                                        <span x-show="(similarityStatus.models || []).find(model => model.id === settingsDraft.similarity_model)?.license" x-text="' License: ' + (similarityStatus.models || []).find(model => model.id === settingsDraft.similarity_model)?.license"></span>
+                                    </div>
+                                </div>
+                                <div class="setting-field settings-wide">
+                                    <label>
+                                        <span>Preprocessing profile</span>
+                                        <span class="source-pill" :class="sourceClass('similarity_profile')" x-text="settingSource('similarity_profile')"></span>
+                                    </label>
+                                    <select x-model="settingsDraft.similarity_profile">
+                                        <template x-for="profile in similarityStatus.profiles || []" :key="profile.id">
+                                            <option :value="profile.id" x-text="profile.title"></option>
+                                        </template>
+                                    </select>
+                                    <div class="setting-help">Controls how audio is decoded and normalized before comparison. Changing it rebuilds the search index.</div>
+                                </div>
+                                <div class="setting-field settings-short">
+                                    <label>
+                                        <span>Background workers</span>
+                                        <span class="source-pill" :class="sourceClass('similarity_workers')" x-text="settingSource('similarity_workers')"></span>
+                                    </label>
+                                    <input type="number" min="1" max="16" step="1" x-model="settingsDraft.similarity_workers" />
+                                    <div class="setting-help">Number of tracks indexed in parallel. Higher values finish sooner but use more CPU and memory.</div>
                                 </div>
                             </div>
                         </section>
                     </div>
 
                     <div class="settings-column settings-side">
-                        <section class="panel">
+                        <section class="panel settings-section settings-section-narrow settings-access">
                             <div class="panel-head">
                                 <div class="panel-title">
                                     <strong>Authentication</strong>
@@ -2226,26 +2476,15 @@ tbody tr:hover {
                             </div>
                         </section>
 
-                        <section class="panel">
+                        <section class="panel settings-section settings-lastfm">
                             <div class="panel-head">
                                 <div class="panel-title">
-                                    <strong>API</strong>
-                                    <span>Developer and enrichment integrations</span>
+                                    <strong>Last.fm Integration</strong>
+                                    <span>Metadata enrichment and scrobbling credentials</span>
                                 </div>
                                 <span class="badge" :class="settings.lastfm_scrobbling_configured ? 'ok' : 'disabled'" x-text="settings.lastfm_scrobbling_configured ? 'Last.fm configured' : 'Last.fm missing'"></span>
                             </div>
                             <div class="settings-grid">
-                                <div class="setting-toggle">
-                                    <label>
-                                        <span>Swagger UI</span>
-                                        <span class="source-pill" :class="sourceClass('swagger_enabled')" x-text="settingSource('swagger_enabled')"></span>
-                                    </label>
-                                    <div class="setting-toggle-row">
-                                        <span x-text="settingsDraft.swagger_enabled ? 'Enabled' : 'Disabled'"></span>
-                                        <input type="checkbox" x-model="settingsDraft.swagger_enabled" />
-                                    </div>
-                                    <div class="setting-help">Interactive API docs at /swagger/ after restart.</div>
-                                </div>
                                 <div class="setting-field">
                                     <label>
                                         <span>{{ t.settings_lastfm_api_key }}</span>
@@ -2265,7 +2504,183 @@ tbody tr:hover {
                             </div>
                         </section>
 
-                        <section class="panel">
+                        <section class="panel settings-section settings-developer">
+                            <div class="panel-head">
+                                <div class="panel-title">
+                                    <strong>Developer API</strong>
+                                    <span>Interactive API documentation</span>
+                                </div>
+                            </div>
+                            <div class="settings-grid">
+                                <div class="setting-toggle settings-wide">
+                                    <label>
+                                        <span>Swagger UI</span>
+                                        <span class="source-pill" :class="sourceClass('swagger_enabled')" x-text="settingSource('swagger_enabled')"></span>
+                                    </label>
+                                    <div class="setting-toggle-row">
+                                        <span x-text="settingsDraft.swagger_enabled ? 'Available at /swagger/' : 'Disabled' "></span>
+                                        <input type="checkbox" x-model="settingsDraft.swagger_enabled" />
+                                    </div>
+                                    <div class="setting-help">Exposes interactive API documentation at <code>/swagger/</code> for developers and integrations.</div>
+                                </div>
+                            </div>
+                        </section>
+
+                        <section class="panel settings-section settings-section-full settings-federation">
+                            <div class="panel-head">
+                                <div class="panel-title">
+                                    <strong>Federation</strong>
+                                    <span>Publish this library into the furumi P2P network</span>
+                                </div>
+                                <span class="badge" :class="federationStatus.node && federationStatus.node.running ? 'ok' : 'disabled'" x-text="federationStatus.node && federationStatus.node.running ? 'running' : 'stopped'"></span>
+                            </div>
+                            <div class="settings-federation-body">
+                            <div class="settings-grid">
+                                <div class="setting-toggle">
+                                    <label>
+                                        <span>Federation enabled</span>
+                                        <span class="source-pill" :class="sourceClass('federation_enabled')" x-text="settingSource('federation_enabled')"></span>
+                                    </label>
+                                    <div class="setting-toggle-row">
+                                        <span x-text="settingsDraft.federation_enabled ? 'Enabled' : 'Disabled'"></span>
+                                        <input type="checkbox" x-model="settingsDraft.federation_enabled" />
+                                    </div>
+                                    <div class="setting-help">Lets other peers in this logical network discover the visible library and request audio streams from this instance.</div>
+                                </div>
+                                <div class="setting-field settings-wide">
+                                    <label>
+                                        <span>Network ID (shared secret)</span>
+                                        <span class="source-pill" :class="sourceClass('federation_network_id')" x-text="settingSource('federation_network_id')"></span>
+                                    </label>
+                                    <input x-model="settingsDraft.federation_network_id" placeholder="my-crew-music-7f3a" autocomplete="off" />
+                                    <div class="setting-help">Peers with the same Network ID form one isolated logical network and discover each other automatically. You may choose any private value; use the exact same value on every peer that should join this network.</div>
+                                </div>
+                                <div class="setting-field settings-wide">
+                                    <label>
+                                        <span>Save federated tracks on play</span>
+                                        <span class="source-pill" :class="sourceClass('federation_save_on_listen')" x-text="settingSource('federation_save_on_listen')"></span>
+                                    </label>
+                                    <div class="setting-toggle-row">
+                                        <span x-text="settingsDraft.federation_save_on_listen ? 'Import into the shared library' : 'Use temporary cache'"></span>
+                                        <input type="checkbox" x-model="settingsDraft.federation_save_on_listen" />
+                                    </div>
+                                    <div class="setting-help">When enabled, a federated track is permanently imported after playback and becomes available to every local user. Otherwise it remains only in the temporary cache. Imported peer metadata is trusted as provided and does not enter AI review.</div>
+                                </div>
+                            </div>
+                            <div class="probe-body" x-show="federationStatus.node">
+                                <div class="federation-status-grid">
+                                <div class="probe-table" x-show="federationStatus.node && federationStatus.node.running">
+                                    <div class="probe-row"><span>Endpoint</span><strong x-text="fedShort(federationStatus.node && federationStatus.node.endpoint_id)"></strong></div>
+                                    <div class="probe-row"><span>Network</span><strong x-text="(federationStatus.node && federationStatus.node.network) || '-'"></strong></div>
+                                    <div class="probe-row"><span>Connected peers</span><strong x-text="federationStatus.node && federationStatus.node.connected_peers ? federationStatus.node.connected_peers.length : 0"></strong></div>
+                                    <div class="probe-row"><span>Known contacts</span><strong x-text="(federationStatus.node && federationStatus.node.known_contacts) ?? '-'"></strong></div>
+                                    <div class="probe-row"><span>Similarity routing peers</span><strong x-text="(federationStatus.node && federationStatus.node.similarity_routing_peers) ?? '-'"></strong></div>
+                                    <div class="probe-row"><span>Published items</span><strong x-text="(federationStatus.node && federationStatus.node.published_items) ?? '-'"></strong></div>
+                                    <div class="probe-row"><span>Last sync</span><strong x-text="federationStatus.last_sync || 'not yet'"></strong></div>
+                                </div>
+                                <div class="probe-table" x-show="fedTransport().total_samples > 0">
+                                    <div class="probe-row">
+                                        <span>Transport path</span>
+                                        <strong>
+                                            <span class="badge" :class="fedPathBadge(fedTransport().last_path)" x-text="fedTransport().last_path || 'unknown'"></span>
+                                        </strong>
+                                    </div>
+                                    <div class="probe-row"><span>RTT</span><strong x-text="fedRtt(fedTransport().last_rtt_ms)"></strong></div>
+                                    <div class="probe-row"><span>Path samples</span><strong x-text="`${fedTransport().direct_samples || 0} direct · ${fedTransport().relay_samples || 0} relay · ${fedTransport().custom_samples || 0} custom · ${fedTransport().unknown_samples || 0} unknown`"></strong></div>
+                                    <div class="probe-row"><span>Protocols</span><strong x-text="`${fedTransport().audio_samples || 0} audio · ${fedTransport().catalog_samples || 0} catalog · ${fedTransport().similarity_samples || 0} similarity · ${fedTransport().sync_samples || 0} sync`"></strong></div>
+                                    <div class="probe-row"><span>Last peer</span><strong x-text="fedShort(fedTransport().last_peer)"></strong></div>
+                                </div>
+                                <div class="transport-log" x-show="fedTransport().last && fedTransport().last.length">
+                                    <div class="transport-log-head">
+                                        <strong>Recent transport operations</strong>
+                                        <span>Newest first · updates automatically</span>
+                                    </div>
+                                    <div class="transport-log-scroll">
+                                        <div class="transport-row transport-header">
+                                            <span>Time</span><span>User / peer</span><span>Protocol</span><span>Direction</span><span>Phase</span><span>Path</span><span class="transport-number">RTT</span><span class="transport-number">TX</span><span class="transport-number">RX</span><span class="transport-number">Lost</span>
+                                        </div>
+                                        <template x-for="(sample, index) in fedTransport().last" :key="`${sample.at}-${sample.protocol}-${sample.direction}-${sample.phase}-${sample.peer_id}-${index}`">
+                                            <div class="transport-row">
+                                                <span :title="sample.at" x-text="formatTransportTime(sample.at)"></span>
+                                                <span :title="sample.user_name || sample.peer_id" x-text="sample.user_name || fedShort(sample.peer_id)"></span>
+                                                <span x-text="sample.protocol || '-'"></span>
+                                                <span x-text="sample.direction || '-'"></span>
+                                                <span x-text="sample.phase || '-'"></span>
+                                                <span x-text="sample.selected_path || 'unknown'"></span>
+                                                <span class="transport-number" x-text="fedRtt(sample.selected_rtt_ms)"></span>
+                                                <span class="transport-number" x-text="formatBytes(sample.total_tx_bytes || 0)"></span>
+                                                <span class="transport-number" x-text="formatBytes(sample.total_rx_bytes || 0)"></span>
+                                                <span class="transport-number" x-text="formatBytes(sample.lost_bytes || 0)"></span>
+                                            </div>
+                                        </template>
+                                    </div>
+                                </div>
+                                </div>
+                                <p class="probe-intro muted" x-show="federationStatus.last_error" x-text="federationStatus.last_error"></p>
+                                <div class="toolbar" style="margin-top:14px; flex-wrap:wrap; gap:8px">
+                                    <button class="btn" type="button" @click="fedSyncNow()" :disabled="federationLoading || !(federationStatus.node && federationStatus.node.running)">
+                                        <i data-lucide="upload-cloud"></i>
+                                        Publish now
+                                    </button>
+                                    <button class="btn" type="button" @click="fedShowTicket()" :disabled="federationLoading || !(federationStatus.node && federationStatus.node.running)">
+                                        <i data-lucide="ticket"></i>
+                                        Show ticket
+                                    </button>
+                                </div>
+                                <div class="setting-field settings-wide" x-show="federationTicket" style="margin-top:10px">
+                                    <label>Connection ticket (share with a peer)</label>
+                                    <textarea readonly rows="3" style="width:100%; font-family:monospace; font-size:11px" x-text="federationTicket"></textarea>
+                                </div>
+                                <div class="setting-field settings-wide" x-show="federationStatus.node && federationStatus.node.running" style="margin-top:10px">
+                                    <label>Connect to a peer by ticket</label>
+                                    <div style="display:flex; gap:8px">
+                                        <input x-model="fedConnectTicket" placeholder="fnet..." style="flex:1" autocomplete="off" />
+                                        <button class="btn" type="button" @click="fedConnect()" :disabled="federationLoading || !fedConnectTicket.trim()">Connect</button>
+                                    </div>
+                                </div>
+                            </div>
+                            </div>
+                        </section>
+
+                        <section class="panel settings-section settings-section-narrow settings-similarity-status">
+                            <div class="panel-head">
+                                <div class="panel-title">
+                                    <strong>Search Index Statistics</strong>
+                                    <span>Similarity model, indexing progress, and storage</span>
+                                </div>
+                                <span class="badge" :class="similarityBadge()" x-text="similarityStatus.status?.phase || 'disabled'"></span>
+                            </div>
+                            <div class="probe-body">
+                                <div class="probe-table">
+                                    <div class="probe-row"><span>Model</span><strong x-text="similarityStatus.status?.model || settingsDraft.similarity_model || '-' "></strong></div>
+                                    <div class="probe-row"><span>Active profile</span><strong :title="similarityStatus.status?.active_profile || ''" x-text="similarityStatus.status?.active_profile ? similarityStatus.status.active_profile.slice(0, 22) + '…' : 'not ready'"></strong></div>
+                                    <div class="probe-row" x-show="similarityStatus.status?.target_profile && similarityStatus.status?.target_profile !== similarityStatus.status?.active_profile">
+                                        <span>Processing profile</span><strong :title="similarityStatus.status?.target_profile || ''" x-text="similarityStatus.status?.target_profile?.slice(0, 22) + '…'"></strong>
+                                    </div>
+                                    <div class="probe-row"><span>Visible tracks</span><strong x-text="similarityStatus.status?.total_tracks ?? 0"></strong></div>
+                                    <div class="probe-row"><span>Processed</span><strong x-text="`${similarityStatus.status?.completed_tracks || 0} · ${similarityProgress()}%`"></strong></div>
+                                    <div class="probe-row"><span>Failed</span><strong x-text="similarityStatus.status?.failed_tracks || 0"></strong></div>
+                                    <div class="probe-row"><span>Stored</span><strong x-text="`${similarityStatus.status?.stored_vectors || 0} vectors · ${formatBytes(similarityStatus.status?.stored_bytes || 0)}`"></strong></div>
+                                    <div class="probe-row" x-show="similarityStatus.status?.current_track"><span>Current track</span><strong x-text="similarityStatus.status?.current_track"></strong></div>
+                                </div>
+                                <div class="similarity-profile-details">
+                                    <span>Selected preprocessing profile</span>
+                                    <pre x-text="selectedSimilarityProfile()?.details || 'Profile information is not available.'"></pre>
+                                </div>
+                                <div style="height:6px;background:rgba(255,255,255,.08);border-radius:999px;overflow:hidden;margin-top:12px" x-show="similarityStatus.status?.phase === 'processing'">
+                                    <div style="height:100%;background:var(--accent);transition:width .25s" :style="`width:${similarityProgress()}%`"></div>
+                                </div>
+                                <p class="probe-intro muted" x-show="similarityStatus.status?.last_error" x-text="similarityStatus.status?.last_error"></p>
+                                <div class="toolbar" style="margin-top:14px;flex-wrap:wrap;gap:8px">
+                                    <button class="btn danger" type="button" @click="clearSimilarityEmbeddings()" :disabled="similarityLoading || !(similarityStatus.status?.stored_vectors > 0)">
+                                        <i data-lucide="trash-2"></i>
+                                        Clear all embeddings
+                                    </button>
+                                </div>
+                            </div>
+                        </section>
+
+                        <section class="panel settings-section settings-section-narrow settings-agent-status">
                             <div class="panel-head">
                                 <div class="panel-title">
                                     <strong>Agent Status</strong>
@@ -2296,10 +2711,6 @@ tbody tr:hover {
                     <div class="action-strip settings-actions">
                         <span class="selection-summary">Settings are stored as database overrides unless an environment variable wins.</span>
                         <div class="toolbar">
-                            <button class="btn" type="button" @click="loadSettings()">
-                                <i data-lucide="refresh-cw"></i>
-                                Reload
-                            </button>
                             <button class="btn primary" type="submit" :disabled="settingsSaving">
                                 <i :data-lucide="settingsSaving ? 'loader-circle' : 'save'"></i>
                                 <span x-text="settingsSaving ? 'Saving...' : 'Save settings'"></span>
@@ -2371,7 +2782,7 @@ tbody tr:hover {
                             <div class="user-activity-row">
                                 <div class="user-activity-cover">
                                     <template x-if="play.cover_url">
-                                        <img :src="play.cover_url" :alt="play.release_title || play.title" loading="lazy">
+                                        <img :src="play.cover_url" alt="" aria-hidden="true" loading="lazy">
                                     </template>
                                     <template x-if="!play.cover_url">
                                         <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><rect x="3" y="3" width="18" height="18" rx="2"/><circle cx="12" cy="12" r="4"/></svg>
@@ -2832,10 +3243,23 @@ function adminV2() {
             agent_llm_auth: '',
             agent_confidence_threshold: '',
             agent_context_limit: '',
-            agent_concurrency: ''
+            agent_concurrency: '',
+            federation_enabled: false,
+            federation_network_id: '',
+            federation_save_on_listen: false,
+            similarity_enabled: false,
+            similarity_model: 'discogs-effnet-bsdynamic-1',
+            similarity_profile: 'furumi-full-track-v1',
+            similarity_workers: '1'
         },
         settingsProbe: { status: 'idle', ok: false },
         settingsProbeLoading: false,
+        federationStatus: {},
+        federationLoading: false,
+        federationTicket: '',
+        fedConnectTicket: '',
+        similarityStatus: { status: { phase: 'disabled' }, models: [], profiles: [] },
+        similarityLoading: false,
         settingsSaving: false,
         routeReady: false,
         poller: null,
@@ -2899,6 +3323,11 @@ function adminV2() {
                 ]);
             } else if (this.activeView === 'users') {
                 await Promise.allSettled([this.loadUsers(false)]);
+            } else if (this.activeView === 'settings') {
+                await Promise.allSettled([
+                    this.loadFederation(false),
+                    this.loadSimilarity(false)
+                ]);
             } else {
                 await Promise.allSettled([this.loadJobs(false), this.loadReviews(false)]);
             }
@@ -2961,6 +3390,10 @@ function adminV2() {
             } else if (this.activeView === 'settings') {
                 if (updateRoute) this.setRoute('#settings');
                 await this.loadSettings();
+                await Promise.allSettled([
+                    this.loadFederation(false),
+                    this.loadSimilarity(false)
+                ]);
                 if (!this.settingsProbe.status || this.settingsProbe.status === 'idle') {
                     await this.loadSettingsProbe(false);
                 }
@@ -3108,6 +3541,21 @@ function adminV2() {
 
         async saveSettings() {
             if (this.settingsSaving) return;
+            const networkSimilarityWasEnabled = Boolean(
+                this.settings.values?.similarity_enabled
+                && this.settings.values?.federation_enabled
+            );
+            const networkSimilarityWillBeEnabled = Boolean(
+                this.settingsDraft.similarity_enabled
+                && this.settingsDraft.federation_enabled
+            );
+            if (!networkSimilarityWasEnabled && networkSimilarityWillBeEnabled) {
+                const accepted = window.confirm(
+                    'Similarity searches send an anonymized embedding of the selected track to federation peers. '
+                    + 'Peers do not receive a user identity, but the query can technically reveal what is being searched. Enable this for the instance?'
+                );
+                if (!accepted) return;
+            }
             this.settingsSaving = true;
             try {
                 await this.request(`${this.apiBase}/settings`, {
@@ -3115,6 +3563,8 @@ function adminV2() {
                     body: JSON.stringify(this.settingsDraft)
                 });
                 await this.loadSettings(false);
+                await this.loadFederation(false);
+                await this.loadSimilarity(false);
                 this.showToast('Settings saved');
             } catch (error) {
                 this.showToast(error.message);
@@ -3128,11 +3578,150 @@ function adminV2() {
             this.activeView = 'settings';
             this.setRoute('#settings');
             await this.loadSettings();
+            await this.loadFederation(false);
+            await this.loadSimilarity(false);
             if (!this.settingsProbe.status || this.settingsProbe.status === 'idle') {
                 await this.loadSettingsProbe(false);
             }
         },
 
+        async loadFederation(showErrors = true) {
+            this.federationLoading = true;
+            try {
+                this.federationStatus = await this.request(`${this.apiBase}/federation`);
+            } catch (error) {
+                if (showErrors) this.showToast(error.message);
+            } finally {
+                this.federationLoading = false;
+                this.icons();
+            }
+        },
+
+        async loadSimilarity(showErrors = true) {
+            this.similarityLoading = true;
+            try {
+                this.similarityStatus = await this.request(`${this.apiBase}/similarity`);
+            } catch (error) {
+                if (showErrors) this.showToast(error.message);
+            } finally {
+                this.similarityLoading = false;
+                this.icons();
+            }
+        },
+
+        async clearSimilarityEmbeddings() {
+            if (!window.confirm('Delete embeddings for every model and preprocessing profile? Audio files are not affected.')) return;
+            this.similarityLoading = true;
+            try {
+                await this.request(`${this.apiBase}/similarity/clear`, {
+                    method: 'POST',
+                    body: '{}'
+                });
+                await this.loadSimilarity(false);
+                this.showToast('All embeddings cleared');
+            } catch (error) {
+                this.showToast(error.message);
+            } finally {
+                this.similarityLoading = false;
+                this.icons();
+            }
+        },
+
+        selectedSimilarityProfile() {
+            return (this.similarityStatus.profiles || []).find(
+                profile => profile.id === this.settingsDraft.similarity_profile
+            ) || null;
+        },
+
+        similarityBadge() {
+            const phase = this.similarityStatus.status?.phase || 'disabled';
+            if (phase === 'ready') return 'ok';
+            if (phase === 'error') return 'failed';
+            if (['downloading', 'loading', 'processing'].includes(phase)) return 'running';
+            return 'disabled';
+        },
+
+        similarityProgress() {
+            const status = this.similarityStatus.status || {};
+            const total = Number(status.total_tracks || 0);
+            const completed = Number(status.completed_tracks || 0);
+            return total > 0 ? Math.min(100, Math.round(completed * 100 / total)) : 0;
+        },
+
+        async fedSyncNow() {
+            this.federationLoading = true;
+            try {
+                this.federationStatus = await this.request(`${this.apiBase}/federation/sync`, { method: 'POST', body: '{}' });
+                this.showToast('Library published to the federation');
+            } catch (error) {
+                this.showToast(error.message);
+            } finally {
+                this.federationLoading = false;
+                this.icons();
+            }
+        },
+
+        async fedShowTicket() {
+            this.federationLoading = true;
+            try {
+                const data = await this.request(`${this.apiBase}/federation/ticket`);
+                this.federationTicket = data.ticket || '';
+            } catch (error) {
+                this.showToast(error.message);
+            } finally {
+                this.federationLoading = false;
+                this.icons();
+            }
+        },
+
+        async fedConnect() {
+            this.federationLoading = true;
+            try {
+                const data = await this.request(`${this.apiBase}/federation/connect`, {
+                    method: 'POST',
+                    body: JSON.stringify({ ticket: this.fedConnectTicket.trim() })
+                });
+                this.fedConnectTicket = '';
+                this.showToast(`Connected to ${(data.connected || '').slice(0, 12)}…`);
+                await this.loadFederation(false);
+            } catch (error) {
+                this.showToast(error.message);
+            } finally {
+                this.federationLoading = false;
+                this.icons();
+            }
+        },
+
+        fedShort(id) {
+            return id ? `${id.slice(0, 12)}…` : '-';
+        },
+
+        fedTransport() {
+            return (this.federationStatus.node && this.federationStatus.node.transport) || {};
+        },
+
+        fedPathBadge(path) {
+            if (path === 'direct') return 'ok';
+            if (path === 'relay') return 'pending';
+            if (path === 'custom') return 'running';
+            return 'disabled';
+        },
+
+        fedRtt(ms) {
+            return ms != null ? `${Math.round(Number(ms))} ms` : '-';
+        },
+
+        formatTransportTime(value) {
+            const date = new Date(value);
+            if (!value || Number.isNaN(date.getTime())) return '-';
+            return date.toLocaleTimeString([], {
+                hour: '2-digit',
+                minute: '2-digit',
+                second: '2-digit',
+                hour12: false
+            });
+        },
+
         async loadSettingsProbe(showErrors = true) {
             this.settingsProbeLoading = true;
             try {

templates/base.html

@@ -3,6 +3,7 @@
 <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <link rel="icon" type="image/svg+xml" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'%3E%3Crect width='64' height='64' rx='14' fill='%23111827'/%3E%3Cpath d='M27 15v31.5a9 9 0 1 1-5-8.1V22l27-6v24.5a9 9 0 1 1-5-8.1V15.9L27 20.5' fill='%2367e8f9'/%3E%3C/svg%3E">
     <title>{% block title %}{{ t.site_name }}{% endblock title %}</title>
     {% block head_extra %}{% endblock head_extra %}
 </head>

templates/player/modals.html

@@ -636,6 +636,155 @@
         </div>
     </template>
 
+    <!-- User Settings Modal -->
+    <template x-if="$store.user.settingsOpen">
+        <div class="modal-overlay" @click.self="$store.user.closeSettings()">
+            <div class="modal-box user-settings-modal">
+                <div class="user-settings-head">
+                    <div>
+                        <h3>User settings</h3>
+                        <p>Personal services, listening history and trusted devices.</p>
+                    </div>
+                    <button class="mobile-list-action" @click="$store.user.closeSettings()" title="{{ t.player_close }}">
+                        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                            <line x1="18" y1="6" x2="6" y2="18"/>
+                            <line x1="6" y1="6" x2="18" y2="18"/>
+                        </svg>
+                    </button>
+                </div>
+
+                <section class="user-settings-section">
+                    <div class="user-settings-section-head">
+                        <div>
+                            <h4>{{ t.player_interface_language }}</h4>
+                            <p>{{ t.player_language_description }}</p>
+                        </div>
+                        <button class="settings-secondary-btn"
+                                onclick="location.href='/set-lang?lang={% if t.lang.code() == "en" %}ru{% else %}en{% endif %}&next='+encodeURIComponent(location.pathname+location.search+location.hash)">{{ t.player_switch_language }}</button>
+                    </div>
+                </section>
+
+                <section class="user-settings-section">
+                    <div class="user-settings-section-head">
+                        <div>
+                            <h4>Listening history</h4>
+                            <p>Review plays recorded by this web player.</p>
+                        </div>
+                        <button class="settings-secondary-btn" @click="$store.user.openHistoryFromSettings()">Open history</button>
+                    </div>
+                </section>
+
+                <section class="user-settings-section">
+                    <div class="user-settings-section-head">
+                        <div>
+                            <h4>Last.fm</h4>
+                            <p x-text="$store.user.lastfmStatusLabel()"></p>
+                        </div>
+                        <button class="settings-secondary-btn"
+                                :class="$store.user.lastfmClass()"
+                                :disabled="$store.user.lastfmBusy || !$store.user.lastfm?.configured"
+                                @click="$store.user.handleLastfm()"
+                                x-text="$store.user.lastfm?.connected && !$store.user.lastfm?.reauth_required ? 'Disconnect' : 'Connect'"></button>
+                    </div>
+                </section>
+
+                <section class="user-settings-section user-settings-devices">
+                    <div class="user-settings-section-head">
+                        <div>
+                            <h4>Connected devices</h4>
+                            <p x-text="$store.devices.fedSummary()"></p>
+                        </div>
+                        <button class="settings-secondary-btn"
+                                :disabled="$store.devices.fedBusy"
+                                @click="$store.devices.syncFedDevices()">Sync now</button>
+                    </div>
+                    <template x-if="$store.devices.fedError">
+                        <div class="fed-device-error" x-text="$store.devices.fedError"></div>
+                    </template>
+
+                    <div class="settings-device-group">
+                        <div class="settings-device-label">Web player sessions</div>
+                        <template x-for="device in $store.devices.webDevices()" :key="'settings-web-' + device.id">
+                            <div class="settings-device-row">
+                                <span class="device-row-icon">
+                                    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                                        <rect x="3" y="4" width="18" height="12" rx="2"/>
+                                        <path d="M8 20h8M12 16v4"/>
+                                    </svg>
+                                </span>
+                                <span class="fed-device-main">
+                                    <span class="fed-device-name" x-text="device.name"></span>
+                                    <span class="fed-device-meta"
+                                          x-text="device.is_current ? 'This browser session' : (device.is_active ? 'Active web session' : 'Web session')"></span>
+                                </span>
+                            </div>
+                        </template>
+                    </div>
+
+                    <div class="settings-device-group">
+                        <div class="settings-device-label">Trusted federation devices</div>
+                        <template x-for="request in $store.devices.fedPending()" :key="request.request_id">
+                            <div class="fed-pairing-card">
+                                <div class="fed-pairing-title" x-text="request.name || request.device_id"></div>
+                                <div class="fed-pairing-meta"
+                                     x-text="request.requester_group_id ? 'Already belongs to another sync group' : (request.client_version || 'Waiting for approval')"></div>
+                                <div class="fed-device-actions">
+                                    <button class="fed-action-btn primary"
+                                            @click="$store.devices.answerFedPairing(request, true, !!request.requester_group_id)"
+                                            x-text="request.requester_group_id ? 'Use existing group' : 'Approve'"></button>
+                                    <button class="fed-action-btn"
+                                            @click="$store.devices.answerFedPairing(request, false, false)">Reject</button>
+                                </div>
+                            </div>
+                        </template>
+                        <template x-for="device in $store.devices.fedDevices()" :key="'settings-fed-' + device.device_id">
+                            <div class="settings-device-row federation">
+                                <span class="device-row-icon federation-device-icon">
+                                    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8">
+                                        <circle cx="12" cy="12" r="3"/>
+                                        <path d="M5.6 8.5a7.5 7.5 0 000 7M18.4 8.5a7.5 7.5 0 010 7"/>
+                                        <path d="M2.8 5.8a11 11 0 000 12.4M21.2 5.8a11 11 0 010 12.4"/>
+                                    </svg>
+                                </span>
+                                <span class="fed-device-main">
+                                    <span class="fed-device-name" x-text="device.name || device.device_id"></span>
+                                    <span class="fed-device-meta"
+                                          x-text="device.is_self ? 'This web player' : (device.client_version || 'Trusted device')"></span>
+                                </span>
+                                <button class="fed-revoke-btn"
+                                        x-show="!device.is_self"
+                                        :disabled="$store.devices.fedBusy"
+                                        @click="$store.devices.revokeFedDevice(device)">Revoke</button>
+                            </div>
+                        </template>
+                    </div>
+
+                    <div class="settings-pairing-actions">
+                        <button class="settings-primary-btn"
+                                :disabled="$store.devices.fedBusy"
+                                @click="$store.devices.generateFedInvite()">Invite a device</button>
+                        <template x-if="$store.devices.fedInvite">
+                            <input class="fed-device-input"
+                                   readonly
+                                   :value="$store.devices.fedInvite"
+                                   @focus="$event.target.select()">
+                        </template>
+                        <div class="fed-connect-row">
+                            <input class="fed-device-input"
+                                   type="text"
+                                   placeholder="Paste frid:// invite"
+                                   x-model="$store.devices.fedInviteInput"
+                                   @keydown.enter.prevent="$store.devices.connectFedInvite()">
+                            <button class="settings-secondary-btn"
+                                    :disabled="$store.devices.fedBusy || !$store.devices.fedInviteInput.trim()"
+                                    @click="$store.devices.connectFedInvite()">Connect</button>
+                        </div>
+                    </div>
+                </section>
+            </div>
+        </div>
+    </template>
+
     <!-- Play History Modal -->
     <template x-if="$store.history.modal">
         <div class="modal-overlay" @click.self="$store.history.close()">
@@ -676,14 +825,19 @@
                                     @click.stop="$store.history.playFrom(idx)"
                                     :title="item.track?.title || item.track_title">
                                 <template x-if="item.track && item.track.cover_url">
-                                    <img :src="item.track.cover_url" :alt="item.track.title" loading="lazy">
+                                    <img :src="item.track.cover_url" alt="" aria-hidden="true" loading="lazy">
                                 </template>
                                 <template x-if="!item.track || !item.track.cover_url">
                                     <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><rect x="3" y="3" width="18" height="18" rx="2"/><circle cx="12" cy="12" r="4"/></svg>
                                 </template>
                             </button>
                             <div class="track-info">
-                                <div class="track-title" x-text="item.track?.title || item.track_title"></div>
+                                <div class="track-title">
+                                    <span x-text="item.track?.title || item.track_title"></span>
+                                    <span class="history-device-badge"
+                                          :title="item.device_id"
+                                          x-text="item.device_name"></span>
+                                </div>
                                 <div class="track-artists-inline">
                                     <template x-for="(artist, artistIdx) in $store.library.trackArtistLinks(item.track)" :key="artist.label + '-' + artist.id + '-' + artistIdx">
                                         <span>

templates/player/styles.html

@@ -67,11 +67,17 @@ body {
 
 .user-widget-main {
     display: grid;
-    grid-template-columns: 36px minmax(0, 1fr) 32px;
+    grid-template-columns: 36px minmax(0, 1fr) auto;
     align-items: center;
     gap: 10px;
 }
 
+.user-widget-actions {
+    display: flex;
+    align-items: center;
+    gap: 2px;
+}
+
 .user-avatar {
     width: 36px;
     height: 36px;
@@ -444,22 +450,6 @@ button.user-stat:hover {
     letter-spacing: 0.3px;
 }
 
-.sidebar-bottom {
-    padding: 12px 16px;
-    border-top: 1px solid var(--border-color);
-}
-
-.sidebar-bottom a {
-    color: var(--text-subdued);
-    text-decoration: none;
-    font-size: 12px;
-    display: flex;
-    align-items: center;
-    gap: 6px;
-}
-
-.sidebar-bottom a:hover { color: var(--text-secondary); }
-
 /* Center Content */
 .center-content {
     flex: 1;
@@ -489,6 +479,25 @@ button.user-stat:hover {
     font-size: 13px;
 }
 
+.playlist-detail-heading {
+    display: flex;
+    align-items: flex-start;
+    justify-content: space-between;
+    gap: 12px;
+    margin-bottom: 14px;
+}
+
+.playlist-detail-heading .section-title {
+    min-width: 0;
+    margin-bottom: 0;
+    overflow-wrap: anywhere;
+}
+
+.playlist-edit-toggle {
+    flex: 0 0 auto;
+    margin-top: 4px;
+}
+
 .breadcrumb {
     display: flex;
     align-items: center;
@@ -651,6 +660,42 @@ button.user-stat:hover {
     margin-bottom: 14px;
     text-transform: capitalize;
 }
+.artist-release-group-heading {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 16px;
+    margin-bottom: 14px;
+}
+.artist-release-group-heading .artist-release-group-title {
+    margin-bottom: 0;
+}
+.artist-top-tracks-toggle {
+    border: 0;
+    background: transparent;
+    color: var(--text-subdued);
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    padding: 5px 7px;
+    border-radius: 5px;
+    font: inherit;
+    font-size: 12px;
+    font-weight: 700;
+    cursor: pointer;
+}
+.artist-top-tracks-toggle:hover {
+    color: var(--text-primary);
+    background: var(--bg-hover);
+}
+.artist-top-tracks-toggle svg {
+    width: 15px;
+    height: 15px;
+    transition: transform 0.18s ease;
+}
+.artist-top-tracks-toggle svg.expanded {
+    transform: rotate(180deg);
+}
 
 /* Release detail header */
 .release-header {
@@ -735,6 +780,93 @@ button.user-stat:hover {
 .track-row:hover { background: var(--bg-hover); }
 .track-row.playing { color: var(--accent); }
 .track-row.playing .track-num { color: var(--accent); }
+.playlist-track-list-header.editing,
+.playlist-track-row.editing {
+    grid-template-columns: 32px 40px minmax(0, 1fr) minmax(0, 1fr) 154px 60px;
+}
+
+.playlist-track-row.editing {
+    cursor: grab;
+}
+
+.playlist-track-row.editing:active {
+    cursor: grabbing;
+}
+
+.playlist-track-row.dragging {
+    opacity: 0.45;
+}
+
+.playlist-track-row.drag-over {
+    border-top: 2px solid var(--accent);
+    margin-top: -2px;
+}
+
+.playlist-track-remove {
+    width: 28px;
+    height: 28px;
+    border: 0;
+    border-radius: 4px;
+    background: transparent;
+    color: var(--text-subdued);
+    cursor: pointer;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding: 0;
+    transition: color 0.15s, background 0.15s;
+}
+
+.playlist-track-remove:hover {
+    color: var(--text-primary);
+    background: var(--bg-active);
+}
+
+.playlist-track-remove svg {
+    width: 16px;
+    height: 16px;
+}
+
+.playlist-track-info {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+}
+
+.playlist-track-copy {
+    min-width: 0;
+    overflow: hidden;
+}
+
+.playlist-drag-handle {
+    width: 24px;
+    height: 28px;
+    border: 0;
+    background: transparent;
+    color: var(--text-subdued);
+    cursor: grab;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    flex: 0 0 24px;
+    padding: 0;
+    touch-action: none;
+    user-select: none;
+}
+
+.playlist-drag-handle:active {
+    cursor: grabbing;
+}
+
+.playlist-drag-handle:hover {
+    color: var(--text-primary);
+}
+
+.playlist-drag-handle svg {
+    width: 14px;
+    height: 14px;
+}
+
 .track-row.shared-target {
     background: rgba(29, 185, 84, 0.12);
     box-shadow: inset 3px 0 0 var(--accent);
@@ -1251,20 +1383,50 @@ button.user-stat:hover {
 }
 
 .queue-track-cover {
+    position: relative;
     width: 40px;
     height: 40px;
     border-radius: 4px;
     background: var(--bg-elevated);
-    overflow: hidden;
+    overflow: visible;
     flex-shrink: 0;
     display: flex;
     align-items: center;
     justify-content: center;
 }
 
-.queue-track-cover img { width: 100%; height: 100%; object-fit: cover; }
+.queue-track-cover img { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; border-radius: inherit; }
 .queue-track-cover svg { width: 20px; height: 20px; color: var(--text-subdued); }
 
+.queue-track-cover .queue-federation-status {
+    position: absolute;
+    right: 2px;
+    bottom: 2px;
+    z-index: 3;
+    width: 18px;
+    min-width: 18px;
+    max-width: 18px;
+    height: 18px;
+    min-height: 18px;
+    max-height: 18px;
+    box-sizing: border-box;
+    flex: none;
+    border-radius: 50%;
+    background: var(--bg-elevated);
+    box-shadow: 0 0 0 1px var(--bg-secondary);
+}
+.queue-track-cover .queue-federation-status > svg {
+    width: 13px;
+    height: 13px;
+}
+.queue-track-cover .queue-federation-status .federation-download-progress,
+.queue-track-cover .queue-federation-status .federation-download-progress svg {
+    width: 18px !important;
+    min-width: 18px;
+    height: 18px !important;
+    min-height: 18px;
+}
+
 .queue-track-info { overflow: hidden; flex: 1; }
 .queue-track-title {
     font-size: 13px;
@@ -1750,9 +1912,9 @@ button.user-stat:hover {
     position: absolute;
     right: 0;
     bottom: 38px;
-    width: 260px;
+    width: 320px;
     max-width: calc(100vw - 24px);
-    max-height: min(320px, calc(100dvh - var(--player-bar-space) - 24px));
+    max-height: min(440px, calc(100dvh - var(--player-bar-space) - 24px));
     overflow-y: auto;
     padding: 6px;
     border: 1px solid var(--border-color);
@@ -1849,6 +2011,169 @@ button.user-stat:hover {
     text-transform: uppercase;
 }
 
+.device-group-divider {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    margin: 7px 8px 3px;
+    color: #b8d6ff;
+    font-size: 10px;
+    font-weight: 750;
+    text-transform: uppercase;
+}
+.device-group-divider::before,
+.device-group-divider::after {
+    content: "";
+    height: 1px;
+    flex: 1;
+    background: var(--border-color);
+}
+.device-group-divider span {
+    white-space: nowrap;
+}
+.federation-device-row {
+    color: #c9dcff;
+}
+.federation-device-icon {
+    color: #78a9ff;
+}
+
+.fed-section-label {
+    margin-top: 4px;
+    color: #b8d6ff;
+}
+
+.fed-device-panel {
+    margin: 2px 2px 6px;
+    padding: 8px;
+    border: 1px solid rgba(82,145,255,0.18);
+    border-radius: 6px;
+    background: rgba(82,145,255,0.045);
+    display: grid;
+    gap: 7px;
+}
+
+.fed-device-status,
+.fed-device-error,
+.fed-pairing-note {
+    color: var(--text-subdued);
+    font-size: 11px;
+    line-height: 1.35;
+}
+
+.fed-device-error {
+    color: #ffb2b2;
+}
+
+.fed-device-row {
+    min-height: 32px;
+    display: grid;
+    grid-template-columns: 9px minmax(0, 1fr) auto;
+    align-items: center;
+    gap: 8px;
+}
+
+.fed-device-dot {
+    width: 7px;
+    height: 7px;
+    border-radius: 999px;
+    background: #73d795;
+}
+
+.fed-device-dot.self {
+    background: #ffd166;
+}
+
+.fed-device-main {
+    min-width: 0;
+    display: grid;
+    gap: 1px;
+}
+
+.fed-device-name,
+.fed-pairing-title {
+    color: var(--text-primary);
+    font-size: 12px;
+    font-weight: 750;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+
+.fed-device-meta,
+.fed-pairing-meta {
+    color: var(--text-subdued);
+    font-size: 11px;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+
+.fed-pairing-card {
+    padding: 7px;
+    border-radius: 5px;
+    background: rgba(255,255,255,0.04);
+    display: grid;
+    gap: 5px;
+}
+
+.fed-device-actions,
+.fed-connect-row {
+    display: flex;
+    gap: 6px;
+    min-width: 0;
+}
+
+.fed-connect-row .fed-device-input {
+    flex: 1;
+}
+
+.fed-action-btn,
+.fed-revoke-btn {
+    height: 28px;
+    border: 0;
+    border-radius: 4px;
+    background: rgba(255,255,255,0.08);
+    color: var(--text-secondary);
+    padding: 0 8px;
+    font-size: 12px;
+    font-weight: 700;
+    cursor: pointer;
+}
+
+.fed-action-btn:hover,
+.fed-revoke-btn:hover {
+    background: rgba(255,255,255,0.13);
+    color: var(--text-primary);
+}
+
+.fed-action-btn.primary {
+    background: rgba(82,145,255,0.16);
+    color: #c9dcff;
+}
+
+.fed-action-btn:disabled {
+    opacity: 0.45;
+    cursor: default;
+}
+
+.fed-revoke-btn {
+    background: rgba(255,96,96,0.1);
+    color: #ffb2b2;
+}
+
+.fed-device-input {
+    width: 100%;
+    min-width: 0;
+    height: 30px;
+    border: 1px solid rgba(82,145,255,0.2);
+    border-radius: 4px;
+    background: rgba(0,0,0,0.18);
+    color: var(--text-primary);
+    padding: 0 8px;
+    font-size: 12px;
+}
+
 .jam-section-label,
 .jam-row,
 .start-jam-row,
@@ -2132,7 +2457,16 @@ button.user-stat:hover {
     line-height: 1;
     font-weight: 500;
     text-align: center;
-    pointer-events: none;
+    text-decoration: none;
+    pointer-events: auto;
+    transition: opacity 120ms ease;
+}
+
+.player-version-chip:hover,
+.player-version-chip:focus-visible {
+    color: var(--text-subdued);
+    opacity: 0.9;
+    text-decoration: none;
 }
 
 .mobile-account-chip {
@@ -2194,11 +2528,18 @@ button.user-stat:hover {
 }
 
 .mobile-account-logout {
-    width: 100%;
-    margin-top: 12px;
+    flex: 1;
+    margin: 0;
     justify-content: center;
 }
 
+.mobile-account-actions {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    margin-top: 12px;
+}
+
 .torrent-import-btn {
     display: flex;
     align-items: center;
@@ -2390,12 +2731,225 @@ button.user-stat:hover {
 
 /* Search results */
 .search-section { margin-bottom: 24px; }
+.federation-search-section {
+    border-top: 1px solid var(--border);
+    padding-top: 18px;
+}
+.federation-search-section.similarity-federation-merged {
+    margin-top: -24px;
+    padding-top: 0;
+    border-top: 0;
+}
+.similarity-unified-results {
+    display: flex;
+    flex-direction: column;
+}
+.similarity-unified-results > .search-section {
+    display: contents;
+}
+.similarity-unified-results .search-section-title { order: -1000002; }
+.similarity-unified-results .track-list-header { order: -1000001; }
+.similarity-unified-results .federation-search-status { order: 1000001; }
+.similarity-search-inline-progress {
+    order: 1000000;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 9px;
+    min-height: 42px;
+    margin-top: 4px;
+    border-top: 1px solid var(--border);
+    color: var(--text-muted);
+    font-size: 12px;
+}
+.similarity-search-inline-spinner {
+    width: 14px;
+    height: 14px;
+    border: 2px solid rgba(255, 255, 255, .16);
+    border-top-color: var(--accent);
+    border-radius: 999px;
+    animation: federation-progress-spin .8s linear infinite;
+}
+.federation-live-badge {
+    margin-left: 8px;
+    color: var(--accent);
+    font-size: 10px;
+    letter-spacing: .12em;
+}
+.federation-search-status {
+    color: var(--text-muted);
+    padding: 12px 0;
+}
+.federation-search-status.error { color: var(--danger, #e66); }
+.federation-track-status {
+    position: relative;
+    z-index: 1;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+}
+.federation-track-status > svg {
+    width: 18px;
+    height: 18px;
+    color: var(--accent);
+}
+.federation-error-badge {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 18px;
+    height: 18px;
+    border: 1px solid rgba(235, 105, 105, .7);
+    border-radius: 999px;
+    background: rgba(190, 55, 55, .18);
+    color: #ffb0b0;
+    font-size: 11px;
+    font-weight: 850;
+    line-height: 1;
+    cursor: help;
+}
+.queue-federation-status .federation-error-badge {
+    width: 16px;
+    height: 16px;
+    font-size: 10px;
+}
+.federation-download-progress {
+    position: relative;
+    display: inline-flex;
+    width: 22px;
+    height: 22px;
+    align-items: center;
+    justify-content: center;
+}
+.federation-download-progress svg {
+    width: 22px !important;
+    height: 22px !important;
+    transform: rotate(-90deg);
+    overflow: hidden;
+}
+.federation-download-progress circle {
+    fill: none;
+    stroke-width: 2;
+}
+.federation-download-progress .progress-track {
+    stroke: color-mix(in srgb, var(--text-muted) 28%, transparent);
+}
+.federation-download-progress .progress-value {
+    stroke: var(--accent);
+    stroke-linecap: round;
+    stroke-dasharray: 50.27;
+    transition: stroke-dashoffset 160ms linear;
+}
+.federation-download-progress.indeterminate .progress-value {
+    stroke-dasharray: 12.57 37.70;
+    transform-box: fill-box;
+    transform-origin: center;
+    animation: federation-progress-spin .8s linear infinite;
+}
+.federation-download-progress .progress-percent {
+    position: absolute;
+    color: var(--text);
+    font-size: 7px;
+    font-weight: 700;
+    line-height: 1;
+}
+.federation-download-tooltip {
+    position: absolute;
+    z-index: 1000;
+    left: calc(100% + 10px);
+    top: 50%;
+    width: max-content;
+    max-width: 290px;
+    padding: 6px 8px;
+    border: 1px solid var(--border);
+    border-radius: 6px;
+    background: var(--bg-elevated);
+    box-shadow: 0 6px 18px rgba(0, 0, 0, .28);
+    color: var(--text);
+    font-size: 11px;
+    font-weight: 500;
+    line-height: 1.35;
+    opacity: 0;
+    pointer-events: none;
+    transform: translate(3px, -50%);
+    transition: opacity 120ms ease, transform 120ms ease;
+}
+.federation-download-progress:hover .federation-download-tooltip {
+    opacity: 1;
+    transform: translate(0, -50%);
+}
+@keyframes federation-progress-spin {
+    to { transform: rotate(360deg); }
+}
+.federation-source-count {
+    color: var(--text-muted);
+    font-size: 12px;
+}
 .search-section-title {
     font-size: 18px;
     font-weight: 700;
     margin-bottom: 12px;
 }
 
+.search-similarity-heading {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 18px;
+    margin: 0 0 20px;
+}
+.search-similarity-title {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: baseline;
+    gap: 8px;
+    min-width: 0;
+    margin: 0;
+    color: var(--text-muted);
+    font-size: 16px;
+    font-weight: 500;
+}
+.search-similarity-title strong {
+    color: var(--text);
+    font-size: 20px;
+}
+.search-similarity-progress {
+    flex: 0 0 auto;
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    min-height: 30px;
+    padding: 5px 10px;
+    border: 1px solid var(--border);
+    border-radius: 7px;
+    background: var(--bg-secondary);
+    color: var(--text-muted);
+    font-size: 11px;
+    font-variant-numeric: tabular-nums;
+    white-space: nowrap;
+}
+.search-similarity-progress.loading { border-color: rgba(29, 185, 84, .38); }
+.search-progress-live {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    color: var(--accent);
+}
+.search-progress-live i {
+    width: 7px;
+    height: 7px;
+    border-radius: 999px;
+    background: currentColor;
+    animation: similarity-search-pulse 1.1s ease-in-out infinite;
+}
+@keyframes similarity-search-pulse {
+    50% { opacity: .3; transform: scale(.75); }
+}
+@media (max-width: 720px) {
+    .search-similarity-heading { align-items: flex-start; flex-direction: column; }
+    .search-similarity-progress { max-width: 100%; flex-wrap: wrap; white-space: normal; }
+}
+
 .search-artists-row {
     display: flex;
     gap: 16px;
@@ -2433,7 +2987,7 @@ button.user-stat:hover {
     position: relative;
 }
 
-.search-artist-img img { width: 100%; height: 100%; object-fit: cover; }
+.search-artist-img img { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; }
 .search-artist-img svg { width: 32px; height: 32px; color: var(--text-subdued); }
 
 .search-artist-name {
@@ -2468,6 +3022,7 @@ button.user-stat:hover {
 .search-release-card:hover { background: var(--bg-elevated); }
 
 .search-release-cover {
+    position: relative;
     width: 100%;
     aspect-ratio: 1;
     border-radius: 6px;
@@ -2479,9 +3034,12 @@ button.user-stat:hover {
     justify-content: center;
 }
 
-.search-release-cover img { width: 100%; height: 100%; object-fit: cover; }
+.search-release-cover img { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; }
 .search-release-cover svg { width: 40px; height: 40px; color: var(--text-subdued); }
 
+.artwork-image { z-index: 1; opacity: 0; }
+.artwork-image.artwork-loaded { opacity: 1; }
+
 /* Like button */
 .like-btn {
     background: none;
@@ -3129,6 +3687,105 @@ button.user-stat:hover {
     max-width: 980px;
 }
 
+.user-settings-modal {
+    width: min(760px, calc(100vw - 32px));
+    max-width: 760px;
+    max-height: min(86dvh, 820px);
+    overflow-y: auto;
+}
+.user-settings-head,
+.user-settings-section-head {
+    display: flex;
+    align-items: flex-start;
+    justify-content: space-between;
+    gap: 16px;
+}
+.user-settings-head {
+    margin-bottom: 16px;
+}
+.user-settings-head h3,
+.user-settings-section h4 {
+    margin: 0;
+}
+.user-settings-head p,
+.user-settings-section p {
+    margin: 4px 0 0;
+    color: var(--text-subdued);
+    font-size: 12px;
+    line-height: 1.45;
+}
+.user-settings-section {
+    padding: 16px 0;
+    border-top: 1px solid var(--border-color);
+}
+.user-settings-devices {
+    display: grid;
+    gap: 12px;
+}
+.settings-device-group {
+    overflow: hidden;
+    border: 1px solid var(--border-color);
+    border-radius: 8px;
+    background: var(--bg-primary);
+}
+.settings-device-label {
+    padding: 8px 11px;
+    border-bottom: 1px solid var(--border-color);
+    color: var(--text-subdued);
+    font-size: 10px;
+    font-weight: 800;
+    text-transform: uppercase;
+}
+.settings-device-row {
+    min-height: 48px;
+    padding: 8px 11px;
+    display: grid;
+    grid-template-columns: 28px minmax(0, 1fr) auto;
+    align-items: center;
+    gap: 10px;
+    border-bottom: 1px solid rgba(255, 255, 255, 0.055);
+}
+.settings-device-row:last-child {
+    border-bottom: 0;
+}
+.settings-device-row.federation {
+    background: rgba(82, 145, 255, 0.035);
+}
+.settings-primary-btn,
+.settings-secondary-btn {
+    min-height: 34px;
+    padding: 7px 12px;
+    border: 1px solid var(--border-color);
+    border-radius: 6px;
+    background: var(--bg-hover);
+    color: var(--text-primary);
+    cursor: pointer;
+    font-size: 12px;
+    font-weight: 750;
+    white-space: nowrap;
+}
+.settings-primary-btn {
+    border-color: rgba(82, 145, 255, 0.4);
+    background: rgba(82, 145, 255, 0.18);
+    color: #d5e4ff;
+}
+.settings-primary-btn:hover,
+.settings-secondary-btn:hover {
+    filter: brightness(1.12);
+}
+.settings-primary-btn:disabled,
+.settings-secondary-btn:disabled {
+    cursor: default;
+    opacity: .55;
+}
+.settings-pairing-actions {
+    display: grid;
+    gap: 8px;
+}
+.settings-pairing-actions > .settings-primary-btn {
+    justify-self: start;
+}
+
 .history-head {
     display: flex;
     align-items: flex-start;
@@ -3171,6 +3828,18 @@ button.user-stat:hover {
 }
 
 .history-row:last-child { border-bottom: 0; }
+.history-device-badge {
+    display: inline-block;
+    margin-left: .45rem;
+    padding: .08rem .38rem;
+    border: 1px solid color-mix(in srgb, currentColor 28%, transparent);
+    border-radius: 999px;
+    color: var(--text-muted);
+    font-size: .68rem;
+    font-weight: 500;
+    line-height: 1.2;
+    vertical-align: .12rem;
+}
 
 .history-cover {
     width: 40px;
@@ -4233,6 +4902,16 @@ button.user-stat:hover {
         justify-content: flex-end;
     }
 
+    .playlist-track-list-header.editing,
+    .playlist-track-row.editing {
+        grid-template-columns: 30px 32px minmax(0, 1fr) auto 54px;
+    }
+
+    .playlist-track-list-header.editing span:nth-child(4),
+    .playlist-track-row.editing > span:nth-child(4) {
+        display: none;
+    }
+
     .history-table-head,
     .history-row.track-row {
         grid-template-columns: 44px minmax(0, 1fr) auto;
@@ -4973,6 +5652,7 @@ button.user-stat:hover {
     }
 
     .mobile-expanded-queue-cover {
+        position: relative;
         width: 42px;
         height: 42px;
         border-radius: 5px;
@@ -4984,6 +5664,8 @@ button.user-stat:hover {
     }
 
     .mobile-expanded-queue-cover img {
+        position: absolute;
+        inset: 0;
         width: 100%;
         height: 100%;
         object-fit: cover;
@@ -5158,6 +5840,26 @@ button.user-stat:hover {
         padding: 10px 6px;
     }
 
+    .playlist-detail-heading {
+        align-items: center;
+        gap: 8px;
+        margin-bottom: 12px;
+    }
+
+    .playlist-edit-toggle {
+        padding: 8px 10px;
+        margin-top: 0;
+    }
+
+    .playlist-track-row.editing {
+        grid-template-columns: 30px minmax(0, 1fr) auto;
+    }
+
+    .playlist-track-row.editing .track-num,
+    .playlist-track-row.editing > span:nth-child(4) {
+        display: none;
+    }
+
     .track-row > span:nth-child(3),
     .track-duration {
         display: none;