From bf9a04fb687e067ebac07142fd081c78f02552fe Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Mon, 10 Aug 2026 15:23:45 +0200
Subject: [PATCH 01/14] docs(rfcs): accept RFC-005, the remote source and
 user-data sync v2

The desktop talks a protocol the server no longer implements. RFC-005
records the replacement and, more importantly, the decision that was
written nowhere: synchronized state describes the server's playlists,
favourites and ratings, which reference the server's tracks. Those have
no local counterpart, and matching one is deliberately out of scope.

Writing that projection into the local tables would leave two options,
both wrong -- fabricate local rows for content that only exists on the
server, or silently drop every entry. The first corrupts the library,
the second makes a broken sync report success. So the projection gets
its own reconstructible tables, and local playlists stop travelling
between machines: a real capability lost, and one that cannot come back
without the matching layer.

Numbered 005 on purpose. Two documents were numbered RFC-003, one per
repository, describing unrelated designs; the desktop's is now marked
superseded and carries the warning in its header.

Claude-Session: https://claude.ai/code/session_01N9WXrurarkoiT2jgimvyj1
---
 docs/README.md                                |   3 +-
 docs/architecture/invariants.md               |  14 +
 docs/rfcs/RFC-003-sync-architecture.md        |  12 +-
 .../rfcs/RFC-005-remote-source-and-sync-v2.md | 261 ++++++++++++++++++
 4 files changed, 288 insertions(+), 2 deletions(-)
 create mode 100644 docs/rfcs/RFC-005-remote-source-and-sync-v2.md

diff --git a/docs/README.md b/docs/README.md
index 06608d6f..9d7ee367 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -34,8 +34,9 @@ Long-form design documents that lock in cross-cutting architectural decisions be
 | ------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------- |
 | [RFC-001 — WaveFlow Server](rfcs/RFC-001-waveflow-server.md)        | Accepted | Server, web, auth, sync, streaming, Phase 1 delivery plan                                                |
 | [RFC-002 — Plugin SDK](rfcs/RFC-002-plugin-sdk.md)                  | Draft    | WASM Component Model plugins for sources / metadata / UI, sideload distribution, desktop + server parity |
-| [RFC-003 — Sync architecture v2](rfcs/RFC-003-sync-architecture.md) | Draft    | Backfill, HLC ordering, per-entity CRDT conflict resolution, status UI. Supersedes RFC-001 §1.f.         |
+| [RFC-003 — Sync architecture v2](rfcs/RFC-003-sync-architecture.md) | Superseded by RFC-005 | Backfill, HLC ordering, per-entity CRDT conflict resolution. **Not** the server's RFC-003 — see [RFC-005](rfcs/RFC-005-remote-source-and-sync-v2.md#the-rfc-003-naming-trap). |
 | [RFC-004 — Community-DB](rfcs/RFC-004-community-database.md)        | Draft    | Opt-in shared metadata pool (lyrics, bios, BPM, etc.), LRCLIB pattern. Schema + endpoints + privacy.     |
+| [RFC-005 — Remote source + sync v2](rfcs/RFC-005-remote-source-and-sync-v2.md) | Accepted | The server catalogue as a separate remote source, `MusicServer` / `SyncProvider` seam, PKCE, journal-based user-data sync. |
 
 ## Contributing
 
diff --git a/docs/architecture/invariants.md b/docs/architecture/invariants.md
index 17093417..b2e58af4 100644
--- a/docs/architecture/invariants.md
+++ b/docs/architecture/invariants.md
@@ -152,6 +152,20 @@ Default it into the overflow ("⋯") menu via [`MoreActionsMenu`](../../src/comp
 
 Every outbound HTTP path (Deezer, Last.fm, similar, LRCLIB, the plugin registry) checks `offline::is_offline()` first and short-circuits to an empty payload or the cache. Persisted in `app_setting['network.offline_mode']`. **Treat new HTTP code paths the same way.**
 
+### Remote user data never lands in the local tables
+
+[RFC-005](../rfcs/RFC-005-remote-source-and-sync-v2.md). Synchronized state describes the **server's** playlists, favourites, ratings, history, queue and shares, and those reference the **server's** tracks — which have no local counterpart. Writing them into `playlist` / `liked_track` / `track.rating` would leave two options, both wrong: fabricate local track rows for content that only exists on the server, or silently drop every entry. The first corrupts the library, the second makes sync look broken while reporting success.
+
+The projection therefore lives in its own `remote_*` tables and is **reconstructible**: dropping it and re-fetching `GET /api/v2/sync/snapshot` is always a valid recovery, and is what the apply path does when it meets a known event it cannot apply. `remote_mutation` is the one exception — it holds writes the server has not seen yet, so it must survive a projection reset.
+
+Matching a local file to a server track is deliberately out of scope and needs its own RFC.
+
+**Two RFCs are numbered 003.** The desktop's [RFC-003](../rfcs/RFC-003-sync-architecture.md) (hybrid logical clocks, superseded) has nothing to do with the server's RFC-003 (sync v2, accepted). Any instruction naming "RFC-003" must name the repository too, or it will be read as the wrong document. On the desktop side the accepted design is **RFC-005**.
+
+### The three sections below describe the retired v1 protocol
+
+They are accurate for `crate::sync` under the `sync_v1` feature, which is off by default and talks to a server generation that no longer exists. They stay until the v2 snapshot bootstrap is proven, because they are the only documented recovery path from a divergence. **Do not use them as a model for new work** — see the section above.
+
 ### Outbound `playlist + field: "tracks"` ops carry a snapshot map
 
 Phase 1.j.b. Every command in [`commands/playlist.rs`](../../src-tauri/crates/app/src/commands/playlist.rs) that inserts tracks (`add_track_to_playlist`, `add_tracks_to_playlist`, `add_source_to_playlist`) calls [`sync::track_snapshots::build_snapshots(conn, &track_ids)`](../../src-tauri/crates/app/src/sync/track_snapshots.rs) inside the same SQLite transaction and folds the result into the outbound payload as `snapshots: { "<id_str>": { title, artist?, duration_ms? } }`.
diff --git a/docs/rfcs/RFC-003-sync-architecture.md b/docs/rfcs/RFC-003-sync-architecture.md
index 4fcc1a5d..2457b58c 100644
--- a/docs/rfcs/RFC-003-sync-architecture.md
+++ b/docs/rfcs/RFC-003-sync-architecture.md
@@ -1,6 +1,16 @@
 # RFC-003 — Sync architecture v2
 
-- **Status**: Draft
+> **Superseded on 2026-08-10 by [RFC-005](RFC-005-remote-source-and-sync-v2.md).**
+> The server it was designed against no longer exists: hybrid logical clocks,
+> per-entity CRDT arbitration and digest reconciliation are all dropped in favour
+> of a server-authoritative ordered journal. Kept for the problem statement
+> below, which is still an accurate account of why the v1 protocol failed.
+>
+> **This is not the server's RFC-003.** `waveflow-server` has its own document
+> with that number, describing the accepted v2 protocol. Any instruction
+> mentioning "RFC-003" must name the repository.
+
+- **Status**: Superseded by RFC-005
 - **Date**: 2026-06-12
 - **Authors**: @InstaZDLL
 - **Supersedes**: RFC-001 §Phase 1.f sync (the practical parts — apply pipeline + ops log stay; semantics and protocol are redesigned).
diff --git a/docs/rfcs/RFC-005-remote-source-and-sync-v2.md b/docs/rfcs/RFC-005-remote-source-and-sync-v2.md
new file mode 100644
index 00000000..b7d857c1
--- /dev/null
+++ b/docs/rfcs/RFC-005-remote-source-and-sync-v2.md
@@ -0,0 +1,261 @@
+# RFC-005 — Remote music source and user-data sync v2
+
+- **Status**: Accepted
+- **Date**: 2026-08-10
+- **Authors**: @InstaZDLL
+- **Supersedes**: [RFC-003](RFC-003-sync-architecture.md) (desktop) — hybrid logical clocks, per-entity CRDT arbitration and digest reconciliation are all dropped, see [Why the v1 design retires](#why-the-v1-design-retires).
+- **Server-side counterpart**: `waveflow-server` `docs/rfcs/RFC-003-waveflow-sync-v2.md` (accepted 2026-08-09) — **a different document with the same number**, see [the naming trap](#the-rfc-003-naming-trap).
+- **Implementation**: `crate::remote` behind the `sync_v2` Cargo feature.
+
+---
+
+## The situation this RFC answers
+
+The desktop's synchronization layer talks to a server protocol that no longer
+exists. All six routes it consumes have zero occurrences in the server's current
+source, and its sign-in flow depends on a web front-end that was removed. The
+server is now authoritative over an ordered journal; the desktop was written
+against a peer-to-peer model where clients arbitrated concurrent writes among
+themselves.
+
+This is not an adaptation. It is a replacement of the protocol, and — more
+consequentially — a change in **what synchronization means for the user**.
+
+## Decision 1 — the remote catalogue is a separate source, never merged
+
+The single most important consequence, and the one that reshapes the UI:
+
+> Synchronized state describes the **server's** playlists, favourites, ratings,
+> history, queue and shares. Those reference the **server's** tracks. A server
+> track has no local counterpart, and this protocol never invents one.
+
+So the incoming projection cannot be written into `playlist`, `liked_track` or
+`track.rating`. Doing so would either fabricate local tracks for rows that only
+exist on the server, or silently drop every entry — the first corrupts the local
+library, the second makes sync look broken. The projection therefore lands in
+its **own tables** (`remote_*`), is presented as a distinct source in the
+sidebar, and is reconstructible: dropping it and re-fetching a snapshot is
+always a valid recovery.
+
+Matching a local file to a server track is **out of scope** and needs its own
+RFC. When it comes, the only automatic link allowed is an exact, unique
+content-hash match; a MusicBrainz identifier is a suggestion the user confirms;
+matching by title/artist/duration is explicitly forbidden.
+
+**What this costs.** Local playlists no longer travel between machines. That
+capability existed in the v1 design and is genuinely lost. It cannot be
+recovered without the matching layer above, because a local playlist is a list
+of local files and nothing in the protocol can name those on another install.
+
+## Decision 2 — two seams, so sync stays a capability
+
+The desktop must be able to connect to any server speaking the Subsonic
+protocol, not only to WaveFlow. That requirement drives the shape: one
+mandatory interface for what every server does, one optional interface for what
+only WaveFlow offers.
+
+```text
+   MusicServer (mandatory)              SyncProvider (optional)
+   catalogue, search, playback,         snapshot, changes, ack, socket
+   user-data per capability
+          │                                      │
+   ┌──────┴────────┐                             │
+SubsonicSource   WaveflowSource ─────────────────┘
+  /rest/*          /api/v2/*  (native end to end)
+```
+
+Between WaveFlow Desktop and WaveFlow Server we go through `/api/v2`
+**always** — catalogue and playback included, not just synchronization. Routing
+our own traffic through the compatibility façade would forfeit three things we
+already have: mutation idempotency (only the v2 routes read the operation-id
+header), full-text search (the façade still filters in memory), and native
+pagination with typed projections.
+
+`WaveflowSource` is therefore an independent implementation, not a
+`SubsonicSource` with sync bolted on.
+
+**Detection.** A Subsonic `ping` against WaveFlow answers `type="waveflow"`.
+That field — not the extension list — decides whether `SyncProvider` is
+available.
+
+> **Verified trap.** `getOpenSubsonicExtensions` returns an *empty* container
+> today. A client that probed capabilities that way would conclude the server
+> offers nothing, while it in fact offers the entire v2 API.
+
+## Decision 3 — remote identity is polymorphic
+
+```rust
+enum RemoteIdentity {
+    Waveflow { account_id: Uuid, device_id: Uuid, cursor: i64 },
+    Subsonic { username: String },
+}
+```
+
+A third-party server has no account UUID, no device notion and no cursor.
+Putting those three fields in a shared struct would make them optional
+everywhere and spread `unwrap` over cases that cannot occur.
+
+One desktop profile binds to one server account. A profile stays the local unit
+of identity and session; a library is a content resource, so an account exposing
+several libraries selects one (`active_library_id`) rather than spawning
+artificial profiles.
+
+## Decision 4 — remote identifiers are opaque strings
+
+WaveFlow serializes its UUIDs, which makes its two surfaces interchangeable
+without a translation table. Other servers emit textual identifiers of another
+shape. So: never parse a remote identifier into a `Uuid`, index on the composite
+key `(profile_id, remote_id)` — two servers can legitimately emit the same
+string — and keep the catalogue cache separate from synchronized state, since
+one is reconstructible and the other is not.
+
+## Decision 5 — Authorization Code + PKCE on loopback
+
+The desktop is a public client. It opens `<server>/authorize` in the system
+browser with `client_id`, `redirect_uri`, `code_challenge` (S256), `state` and
+`device_name`; the consent screen posts them back with the browser session
+attached and follows the redirect the server computes. The loopback listener
+then exchanges `code` + `code_verifier` at `/api/v2/oauth/token`.
+
+The loopback listener and the random generator already exist for another
+provider; only the protocol changes.
+
+> **Verified trap.** A code is **spent on first presentation**, whatever the
+> outcome. A wrong verifier burns it. Retrying the same code is not a recovery
+> path — the flow restarts from the beginning.
+
+A third-party server authenticates by username/password, token/salt or API key
+instead. That is a second authentication shape to carry, not a degraded first.
+
+## Decision 6 — playback carries a Bearer header
+
+`GET /api/v2/tracks/{id}/stream` with `Authorization: Bearer`, accepting
+`format`, `bitrate` and `offset_ms`, answering 206/416 on ranges. Sealed tickets
+exist for consumers that cannot set a header — a browser `<audio src>` — which
+is not our case. `MusicServer` therefore exposes a stream URL *and the header to
+attach*, never a hard-coded route.
+
+## Decision 7 — the queue holds replayable business mutations
+
+Offline writing stays. What changes is the payload: no longer generic ops but
+typed, replayable REST calls, each carrying a stable `operation_id`.
+
+```rust
+enum Mutation {
+    SetFavorite { operation_id: Uuid, entity: RemoteEntity, id: String, starred: bool },
+    SetRating   { operation_id: Uuid, entity: RemoteEntity, id: String, rating: u8 },
+    UpdatePlaylist { operation_id: Uuid, playlist_id: String, /* … */ },
+}
+```
+
+Three server properties constrain this queue, and ignoring them fails in
+perfectly ordinary situations:
+
+- **A queued entry is immutable.** The server stores a canonical fingerprint of
+  the action, target and normalized payload. Reusing an `operation_id` with a
+  different fingerprint is *rejected as a conflict*, not treated as a replay. So
+  if the user corrects a gesture before the queue drains — renaming an
+  already-queued playlist — we emit a second mutation with a **new**
+  `operation_id`, or merge the two before enqueueing and regenerate the
+  identifier. Mutating a pending entry in place breaks.
+
+- **Replaying a share creation returns the same URL.** The share token is
+  derived deterministically from the identifier, so share creation replays like
+  any other mutation, with no special casing and no second URL.
+
+- **The ACK is not a prerequisite.** It feeds observability and future
+  retention, not read authorization. A failing ACK must never block
+  synchronization.
+
+**Permanent versus transient failure.** The server answers `422
+validation_error` both for a malformed payload and for an operation-id conflict.
+Both are permanent: a retry cannot change the outcome. The queue marks such an
+entry as failed and surfaces it, instead of retrying forever. Only 5xx, 429 and
+transport errors are retried.
+
+## Decision 8 — v2 lands beside v1, not on top of it
+
+The v1 surface (~12 400 lines across `sync/`, `commands/sync.rs`,
+`server_client.rs`, `commands/share.rs`) sits behind the `sync_v1` feature,
+which **is not in `default`** — it is already absent from shipped binaries, and
+`sync_stub.rs` keeps the ~70 CRUD emit call sites compiling.
+
+So v2 is a new tree, `crate::remote`, behind a new `sync_v2` feature, also off
+by default. Consequences worth stating:
+
+- the ~70 emit call sites are **not touched** — under v2 they keep resolving to
+  the stub, which is correct, since local-entity CRUD is no longer synchronized;
+- v1 keeps compiling and stays available as the only recovery path while the
+  snapshot bootstrap is unproven;
+- **`digest/` and `backfill/` are not deleted until a working bootstrap
+  exists.** Those 2 500 lines become pointless, but until their replacement is
+  proven they are the only way back from a divergence.
+
+## Local schema
+
+Per-profile, since the binding is per-profile:
+
+| Table | Role |
+| --- | --- |
+| `remote_binding` | server flavour, `account_id`, `device_id`, cursor, `active_library_id` |
+| `remote_playlist` + `remote_playlist_track` | projected playlists, ordered |
+| `remote_favorite` | `(entity_type, entity_id)` |
+| `remote_rating` | `(entity_type, entity_id, rating)` |
+| `remote_history` | scrobbles, append-only |
+| `remote_queue` | single row, the server's saved queue |
+| `remote_share` | non-secret share fields; **never** token or URL |
+| `remote_mutation` | outbound queue, typed, keyed by `operation_id` |
+
+Tokens keep using `auth_credential` under the existing `waveflow_server`
+provider, which already carries a refresh token and an expiry.
+
+## Target sequence
+
+```text
+LOGIN ──▶ account_id + device_id
+   │
+BOOTSTRAP ──▶ GET /sync/snapshot ──▶ atomic replace ──▶ cursor ──▶ ACK
+   │
+SYNC ──▶ GET /sync/changes?after=cursor ──▶ apply ──▶ cursor ──▶ ACK
+   │
+WS {"cursor": N} ──▶ if N > local cursor ──▶ GET /sync/changes?after=cursor
+```
+
+Upstream: optimistic local write, enqueue, then the business endpoint with
+`X-WaveFlow-Operation-Id` and `X-WaveFlow-Device-Id`. The server applies or
+recognizes the replay; the change comes back through `/changes`.
+
+Unknown entity types, actions and payload fields are ignored. A client that
+cannot apply a **known** event drops its projection and re-fetches a snapshot.
+
+## Why the v1 design retires
+
+Every mechanism below exists because v1 accepted concurrent writes arbitrated
+client-side. The v2 journal is strictly ordered and server-authoritative;
+keeping them would carry complexity the protocol no longer asks for.
+
+- **Logical clocks** (`lamport`, `hlc`) — the journal cursor is the global order.
+- **Digest reconciliation** — a snapshot the client swaps in atomically replaces
+  fingerprint comparison.
+- **Last-writer-wins backfill** — a conflict is no longer arbitrated locally: a
+  reused operation identifier with a different fingerprint is rejected, and a
+  client that cannot apply a known event takes a fresh snapshot.
+- **Compaction and `410 Gone`** — the v2.0 journal is append-only, and any
+  future retention is gated on a snapshot floor. This path disappears, but it is
+  **replaced by snapshot recovery**, not removed without a substitute.
+
+## The RFC-003 naming trap
+
+The desktop's own [RFC-003](RFC-003-sync-architecture.md) (hybrid logical
+clocks, Draft, 2026-06-12) has nothing to do with the server's RFC-003 (sync v2,
+Accepted, 2026-08-09). Comments in `sync/mod.rs` point at the **desktop** one.
+Any instruction mentioning "RFC-003" must name the repository, or it will be
+read as the wrong document. This RFC exists partly to end that ambiguity: on the
+desktop side, the accepted design is **RFC-005**.
+
+## Out of scope
+
+- Matching local files to server tracks (own RFC, needs the exact-hash rule).
+- Full third-party Subsonic implementation: the seam is defined here and
+  `WaveflowSource` implements it; the other branch is its own slice.
+- Retention and compaction of the server journal.

From e2d66270454ac42eac09db7d36fdaa92f8248104 Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Mon, 10 Aug 2026 15:23:57 +0200
Subject: [PATCH 02/14] feat(remote): foundations for the remote source and
 sync v2

Lands the projection schema and the HTTP surface RFC-005 needs, behind a
new off-by-default sync_v2 feature. Independent of crate::sync, which
stays behind sync_v1: v2 does not synchronize local-entity CRUD, so the
~70 emit call sites keep resolving to the stub and are untouched. The v1
digest and backfill paths stay compilable on purpose -- until the
snapshot bootstrap is proven they are the only way back from a
divergence.

The migration was replayed against a real database with foreign keys on,
not a fixture: the CHECK constraints are half of what the binding relies
on. Two of them are deliberately asymmetric. The favourite entity type
carries no CHECK, because pinning today's list would turn a
forward-compatible server change into an aborted transaction -- and an
event the client cannot apply forces a fresh snapshot, whose replay
would abort on the same row, looping forever. The rating range does
carry one, because the apply path clamps before binding, so it can only
fire on our own bug.

Two traps paid for along the way. The v2 access tokens are opaque
(wfa_/wfr_), so v1's "three dot-separated segments" check would reject
every one of them. And refreshing held the profile pool lease across a
30-second request; it now captures the profile id and re-acquires
against it, losing a rotated pair rather than writing one account's
credentials into another profile's database.

CI gained a job for the feature. Without it not one line of this tree
would be compiled, and it would rot silently until the day it is
switched on.

Claude-Session: https://claude.ai/code/session_01N9WXrurarkoiT2jgimvyj1
---
 .github/workflows/ci.yml                      |  15 +
 CLAUDE.md                                     |   2 +-
 src-tauri/crates/app/Cargo.toml               |   8 +
 src-tauri/crates/app/src/lib.rs               |   6 +
 src-tauri/crates/app/src/remote/binding.rs    | 395 +++++++++++++
 src-tauri/crates/app/src/remote/client.rs     | 538 ++++++++++++++++++
 src-tauri/crates/app/src/remote/mod.rs        |  55 ++
 src-tauri/crates/app/src/remote/probe.rs      | 236 ++++++++
 src-tauri/crates/app/src/remote/tokens.rs     | 320 +++++++++++
 ...0260810120000_remote_source_projection.sql | 253 ++++++++
 10 files changed, 1827 insertions(+), 1 deletion(-)
 create mode 100644 src-tauri/crates/app/src/remote/binding.rs
 create mode 100644 src-tauri/crates/app/src/remote/client.rs
 create mode 100644 src-tauri/crates/app/src/remote/mod.rs
 create mode 100644 src-tauri/crates/app/src/remote/probe.rs
 create mode 100644 src-tauri/crates/app/src/remote/tokens.rs
 create mode 100644 src-tauri/migrations/profile/20260810120000_remote_source_projection.sql

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b84e19dd..80d8106e 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -105,6 +105,21 @@ jobs:
           --no-default-features
           --features postgres
 
+      - name: cargo check + test (sync_v2 — off by default, so unchecked otherwise)
+        # `crate::remote` (RFC-005) lives behind an off-by-default feature
+        # while its slices land, which means the step above never compiles
+        # a line of it. Without this step the whole tree would rot
+        # silently until the day it is switched on. Linux only: it adds no
+        # platform-specific code, and the Windows slot cannot run the app
+        # crate's test binary anyway (see below).
+        if: runner.os == 'Linux'
+        run: >-
+          cargo test
+          --manifest-path src-tauri/Cargo.toml
+          -p waveflow
+          --features sync_v2
+          --all-targets
+
       - name: cargo test (full workspace)
         if: runner.os == 'Linux'
         run: cargo test --manifest-path src-tauri/Cargo.toml --workspace
diff --git a/CLAUDE.md b/CLAUDE.md
index 91a7d0a3..f890b22f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -56,7 +56,7 @@ Inside `crates/app/src/`:
 
 - **`commands/`** — one module per domain (`library`, `playlist`, `smart_playlists`, `track`, `browse`, `player`, `scan`, `edit`, `profile`, `analysis`, `deezer`, `similar`, `lyrics`, `stats`, `wrapped`, `maintenance`, `radio`, `duplicates`, `preferences`, `plugins`, `canvas`, …), all registered in `lib.rs::generate_handler![]`. CRUD delegates to `waveflow_core::repository::sqlite::*`; IPC + state + filesystem + emit glue stays in the command.
 - **`audio/`** — 3-thread lock-free engine: `decoder.rs` (symphonia + rubato), `output.rs` (cpal callback on its own thread, SPSC `rtrb` ring), `state.rs` (`SharedPlayback` atomics), `analytics.rs`, `crossfade.rs`, `eq.rs`, `spectrum.rs`, `wasapi_exclusive.rs`. Topology: [`docs/architecture/audio.md`](docs/architecture/audio.md).
-- **`dlna/`** (axum + SSDP, opt-in) · **`mpd/`** (TCP MPD protocol, opt-in) · **`media_controls.rs`** (souvlaki → SMTC / MPRIS / MediaRemote) · **`discord_presence.rs`** · **`queue.rs`** · **`player_actions.rs`** (shared control sequence) · **`sync/`** (outbound op emit) · **`backup.rs`** · **`db/`** (pool wiring + `migration_heal`).
+- **`dlna/`** (axum + SSDP, opt-in) · **`mpd/`** (TCP MPD protocol, opt-in) · **`media_controls.rs`** (souvlaki → SMTC / MPRIS / MediaRemote) · **`discord_presence.rs`** · **`queue.rs`** · **`player_actions.rs`** (shared control sequence) · **`remote/`** (remote source + sync v2, feature `sync_v2`) · **`sync/`** (retired v1 protocol, feature `sync_v1` — both features off by default) · **`backup.rs`** · **`db/`** (pool wiring + `migration_heal`).
 - **Scanner** — the orchestrator `scan_folder_inner` stays app-side (it emits `scan:progress`); every pure helper lives in `waveflow_core::scanner::{extract, upserts}`.
 - **Database** — per-profile SQLite via sqlx + a global `app.db` for the profile list and app-wide settings. Migrations at `src-tauri/migrations/{app,profile}/`, compiled in via `sqlx::migrate!`. Layout: [`docs/architecture/storage.md`](docs/architecture/storage.md).
 
diff --git a/src-tauri/crates/app/Cargo.toml b/src-tauri/crates/app/Cargo.toml
index ac501c78..35da9d7f 100644
--- a/src-tauri/crates/app/Cargo.toml
+++ b/src-tauri/crates/app/Cargo.toml
@@ -36,6 +36,14 @@ updater = ["dep:tauri-plugin-updater"]
 # hash builder are all excluded from the binary. Re-enable in 1.6.0
 # once the heal migration + apply pipeline gaps close.
 sync_v1 = []
+# Remote music source + user-data sync v2 (RFC-005). Replaces `sync_v1`,
+# which talks a protocol the server no longer implements. OFF while the
+# slices land: the two trees are independent (`crate::remote` vs
+# `crate::sync`), so both can be absent from a shipped build, and
+# `sync_v1` stays available as the only recovery path from a divergence
+# until the snapshot bootstrap here is proven. Enabling BOTH is
+# supported but pointless — they bind to different server generations.
+sync_v2 = []
 
 [build-dependencies]
 tauri-build = { version = "2", features = [] }
diff --git a/src-tauri/crates/app/src/lib.rs b/src-tauri/crates/app/src/lib.rs
index d7a345ce..634920e2 100644
--- a/src-tauri/crates/app/src/lib.rs
+++ b/src-tauri/crates/app/src/lib.rs
@@ -21,6 +21,12 @@ mod offline;
 mod paths;
 mod player_actions;
 mod queue;
+// Remote music source + user-data sync v2 (RFC-005). Independent of
+// `mod sync` below, which implements the retired v1 protocol: v2 does
+// not synchronize local-entity CRUD at all, so the ~70 emit call sites
+// keep resolving to the stub and this tree never touches them.
+#[cfg(feature = "sync_v2")]
+mod remote;
 mod scrobbler;
 #[cfg(feature = "sync_v1")]
 mod server_client;
diff --git a/src-tauri/crates/app/src/remote/binding.rs b/src-tauri/crates/app/src/remote/binding.rs
new file mode 100644
index 00000000..aa1c9d9d
--- /dev/null
+++ b/src-tauri/crates/app/src/remote/binding.rs
@@ -0,0 +1,395 @@
+//! Which server the active profile talks to, and where it is up to.
+//!
+//! One row, pinned by `CHECK (id = 1)` in the migration: a profile
+//! binds to exactly one server account (RFC-005 §Decision 3). The
+//! binding is per-profile rather than app-wide — which is where v1 kept
+//! the server URL — because with a universal client two profiles may
+//! legitimately point at two different servers, and a cursor is
+//! meaningless across accounts.
+
+use chrono::Utc;
+use serde::{Deserialize, Serialize};
+use sqlx::{Row, SqliteConnection};
+
+use crate::error::{AppError, AppResult};
+
+/// What kind of server sits behind the URL, and therefore which
+/// identity fields carry meaning.
+///
+/// A third-party Subsonic server has no account UUID, no device notion
+/// and no journal cursor. Modelling that as one struct with three
+/// optional fields would spread `unwrap` over cases that cannot occur;
+/// the enum makes the impossible states unrepresentable instead.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "flavour", rename_all = "lowercase")]
+pub enum RemoteIdentity {
+    /// Native WaveFlow account. The only branch with a journal.
+    Waveflow {
+        /// The account the tokens belong to. Opaque to us beyond
+        /// equality — used to detect that the user signed into a
+        /// *different* account, which invalidates the whole projection.
+        account_id: String,
+        /// The non-revoked device this install registered. Sent on
+        /// every mutation and used as the ACK key; the server rejects a
+        /// device owned by another account.
+        device_id: String,
+        /// Journal position. `0` means "never bootstrapped".
+        cursor: i64,
+    },
+    /// Any server speaking the Subsonic protocol.
+    Subsonic { username: String },
+}
+
+impl RemoteIdentity {
+    /// Canonical TEXT for the `flavour` column. Stable once persisted —
+    /// changing a value would need a migration.
+    pub fn flavour(&self) -> &'static str {
+        match self {
+            RemoteIdentity::Waveflow { .. } => "waveflow",
+            RemoteIdentity::Subsonic { .. } => "subsonic",
+        }
+    }
+
+    /// The journal position, or `None` for a server that has no
+    /// journal. Callers must treat `None` as "this capability does not
+    /// exist here", never as "start from zero".
+    pub fn cursor(&self) -> Option<i64> {
+        match self {
+            RemoteIdentity::Waveflow { cursor, .. } => Some(*cursor),
+            RemoteIdentity::Subsonic { .. } => None,
+        }
+    }
+
+    /// The device identifier to stamp mutations with, when there is one.
+    pub fn device_id(&self) -> Option<&str> {
+        match self {
+            RemoteIdentity::Waveflow { device_id, .. } => Some(device_id),
+            RemoteIdentity::Subsonic { .. } => None,
+        }
+    }
+}
+
+/// The persisted binding row.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct RemoteBinding {
+    /// Base URL, without a trailing slash.
+    pub server_url: String,
+    pub identity: RemoteIdentity,
+    /// Optional library filter. An account with access to several
+    /// libraries picks one rather than spawning artificial profiles.
+    pub active_library_id: Option<String>,
+    /// `None` until the first snapshot has been applied.
+    ///
+    /// This is what separates "no data because we never asked" from "no
+    /// data because the account is empty" — without it the two are
+    /// indistinguishable, and a failed bootstrap would present as a
+    /// successfully synchronized empty account.
+    pub bootstrapped_at: Option<i64>,
+}
+
+fn now_ms() -> i64 {
+    Utc::now().timestamp_millis()
+}
+
+/// Read the binding, or `None` when this profile is not bound to any
+/// server. Local-only is the normal case, not an error.
+pub async fn read(conn: &mut SqliteConnection) -> AppResult<Option<RemoteBinding>> {
+    let row = sqlx::query(
+        "SELECT server_url, flavour, account_id, device_id, username,
+                cursor, active_library_id, bootstrapped_at
+           FROM remote_binding WHERE id = 1",
+    )
+    .fetch_optional(&mut *conn)
+    .await?;
+    let Some(row) = row else { return Ok(None) };
+
+    let flavour: String = row.try_get("flavour")?;
+    let identity = match flavour.as_str() {
+        "waveflow" => RemoteIdentity::Waveflow {
+            // The migration's CHECK guarantees both columns are present
+            // on this branch, so a NULL here is a corrupt row rather
+            // than a state the protocol allows.
+            account_id: row.try_get("account_id")?,
+            device_id: row.try_get("device_id")?,
+            cursor: row.try_get("cursor")?,
+        },
+        "subsonic" => RemoteIdentity::Subsonic {
+            username: row.try_get("username")?,
+        },
+        other => {
+            return Err(AppError::Other(format!(
+                "remote_binding.flavour holds an unknown value {other:?}"
+            )))
+        }
+    };
+
+    Ok(Some(RemoteBinding {
+        server_url: row.try_get("server_url")?,
+        identity,
+        active_library_id: row.try_get("active_library_id")?,
+        bootstrapped_at: row.try_get("bootstrapped_at")?,
+    }))
+}
+
+/// Create or replace the binding.
+///
+/// Replacing is a deliberate whole-row overwrite rather than a merge:
+/// binding to a different server, or to a different account on the same
+/// server, must not inherit the previous cursor. Callers that rebind are
+/// responsible for clearing the projection in the same transaction —
+/// a cursor from another account would otherwise be read as a valid
+/// position in a journal it never belonged to.
+pub async fn write(conn: &mut SqliteConnection, binding: &RemoteBinding) -> AppResult<()> {
+    let now = now_ms();
+    let (account_id, device_id, cursor, username) = match &binding.identity {
+        RemoteIdentity::Waveflow {
+            account_id,
+            device_id,
+            cursor,
+        } => (
+            Some(account_id.as_str()),
+            Some(device_id.as_str()),
+            *cursor,
+            None,
+        ),
+        RemoteIdentity::Subsonic { username } => (None, None, 0, Some(username.as_str())),
+    };
+
+    sqlx::query(
+        "INSERT INTO remote_binding
+            (id, server_url, flavour, account_id, device_id, username,
+             cursor, active_library_id, bootstrapped_at, created_at, updated_at)
+         VALUES (1, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(id) DO UPDATE SET
+            server_url        = excluded.server_url,
+            flavour           = excluded.flavour,
+            account_id        = excluded.account_id,
+            device_id         = excluded.device_id,
+            username          = excluded.username,
+            cursor            = excluded.cursor,
+            active_library_id = excluded.active_library_id,
+            bootstrapped_at   = excluded.bootstrapped_at,
+            updated_at        = excluded.updated_at",
+    )
+    .bind(binding.server_url.trim_end_matches('/'))
+    .bind(binding.identity.flavour())
+    .bind(account_id)
+    .bind(device_id)
+    .bind(username)
+    .bind(cursor)
+    .bind(binding.active_library_id.as_deref())
+    .bind(binding.bootstrapped_at)
+    .bind(now)
+    .bind(now)
+    .execute(&mut *conn)
+    .await?;
+    Ok(())
+}
+
+/// Advance the journal cursor.
+///
+/// Monotonic by construction: `MAX(cursor, ?)` in SQL rather than a
+/// read-modify-write in Rust. Two passes can legitimately finish out of
+/// order — a socket-triggered catch-up racing a periodic one — and the
+/// lower of the two must not drag the position backwards, which would
+/// replay events the client has already applied.
+pub async fn advance_cursor(conn: &mut SqliteConnection, cursor: i64) -> AppResult<()> {
+    sqlx::query(
+        "UPDATE remote_binding
+            SET cursor = MAX(cursor, ?), updated_at = ?
+          WHERE id = 1 AND flavour = 'waveflow'",
+    )
+    .bind(cursor)
+    .bind(now_ms())
+    .execute(&mut *conn)
+    .await?;
+    Ok(())
+}
+
+/// Stamp the binding as bootstrapped, and pin the cursor the snapshot
+/// was consistent at.
+///
+/// The cursor is set outright here, not `MAX`-ed: a snapshot is a
+/// whole-projection replacement, so its cursor is authoritative even if
+/// it is lower than a position reached before the projection was
+/// discarded. That case is exactly the recovery path — a client that
+/// could not apply a known event throws its projection away and starts
+/// again from a fresh snapshot.
+pub async fn mark_bootstrapped(conn: &mut SqliteConnection, cursor: i64) -> AppResult<()> {
+    let now = now_ms();
+    sqlx::query(
+        "UPDATE remote_binding
+            SET cursor = ?, bootstrapped_at = ?, updated_at = ?
+          WHERE id = 1 AND flavour = 'waveflow'",
+    )
+    .bind(cursor)
+    .bind(now)
+    .bind(now)
+    .execute(&mut *conn)
+    .await?;
+    Ok(())
+}
+
+/// Drop the binding. Leaves the projection and the outbound queue
+/// alone — the caller decides whether unbinding also discards pending
+/// writes, which is a user-visible choice, not a storage detail.
+pub async fn clear(conn: &mut SqliteConnection) -> AppResult<()> {
+    sqlx::query("DELETE FROM remote_binding WHERE id = 1")
+        .execute(&mut *conn)
+        .await?;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use sqlx::sqlite::SqlitePoolOptions;
+    use sqlx::SqlitePool;
+
+    /// Real schema, not a hand-rolled fixture: the CHECK constraints are
+    /// half of what this module relies on, and a fixture without them
+    /// would prove nothing.
+    async fn pool() -> SqlitePool {
+        let pool = SqlitePoolOptions::new()
+            .max_connections(1)
+            .connect(":memory:")
+            .await
+            .unwrap();
+        sqlx::raw_sql(include_str!(
+            "../../../../migrations/profile/20260810120000_remote_source_projection.sql"
+        ))
+        .execute(&pool)
+        .await
+        .unwrap();
+        pool
+    }
+
+    fn waveflow_binding(cursor: i64) -> RemoteBinding {
+        RemoteBinding {
+            server_url: "https://music.example".into(),
+            identity: RemoteIdentity::Waveflow {
+                account_id: "acc-1".into(),
+                device_id: "dev-1".into(),
+                cursor,
+            },
+            active_library_id: None,
+            bootstrapped_at: None,
+        }
+    }
+
+    #[tokio::test]
+    async fn unbound_profile_reads_as_none() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        assert_eq!(read(&mut conn).await.unwrap(), None);
+    }
+
+    #[tokio::test]
+    async fn waveflow_binding_round_trips() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        let binding = waveflow_binding(7);
+        write(&mut conn, &binding).await.unwrap();
+        assert_eq!(read(&mut conn).await.unwrap(), Some(binding));
+    }
+
+    #[tokio::test]
+    async fn subsonic_binding_round_trips_without_a_cursor() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        let binding = RemoteBinding {
+            server_url: "https://other.example".into(),
+            identity: RemoteIdentity::Subsonic {
+                username: "bob".into(),
+            },
+            active_library_id: Some("lib-3".into()),
+            bootstrapped_at: None,
+        };
+        write(&mut conn, &binding).await.unwrap();
+        let read_back = read(&mut conn).await.unwrap().unwrap();
+        assert_eq!(read_back, binding);
+        assert_eq!(read_back.identity.cursor(), None);
+        assert_eq!(read_back.identity.device_id(), None);
+    }
+
+    #[tokio::test]
+    async fn trailing_slash_is_stripped_so_paths_never_double_up() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        let mut binding = waveflow_binding(0);
+        binding.server_url = "https://music.example/".into();
+        write(&mut conn, &binding).await.unwrap();
+        assert_eq!(
+            read(&mut conn).await.unwrap().unwrap().server_url,
+            "https://music.example"
+        );
+    }
+
+    #[tokio::test]
+    async fn a_late_lower_cursor_does_not_drag_the_position_backwards() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        write(&mut conn, &waveflow_binding(0)).await.unwrap();
+
+        advance_cursor(&mut conn, 42).await.unwrap();
+        // A catch-up pass that started earlier finishing later.
+        advance_cursor(&mut conn, 11).await.unwrap();
+
+        assert_eq!(read(&mut conn).await.unwrap().unwrap().identity.cursor(), Some(42));
+    }
+
+    #[tokio::test]
+    async fn a_snapshot_pins_its_cursor_even_when_lower() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        write(&mut conn, &waveflow_binding(0)).await.unwrap();
+        advance_cursor(&mut conn, 42).await.unwrap();
+
+        // The recovery path: the projection was discarded, so the
+        // position it had reached is meaningless.
+        mark_bootstrapped(&mut conn, 11).await.unwrap();
+
+        let binding = read(&mut conn).await.unwrap().unwrap();
+        assert_eq!(binding.identity.cursor(), Some(11));
+        assert!(binding.bootstrapped_at.is_some());
+    }
+
+    #[tokio::test]
+    async fn rebinding_replaces_rather_than_merges() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        write(&mut conn, &waveflow_binding(0)).await.unwrap();
+        advance_cursor(&mut conn, 99).await.unwrap();
+
+        // Signing into a different account must not inherit a cursor
+        // into a journal it never belonged to.
+        write(&mut conn, &waveflow_binding(0)).await.unwrap();
+        assert_eq!(read(&mut conn).await.unwrap().unwrap().identity.cursor(), Some(0));
+    }
+
+    #[tokio::test]
+    async fn advancing_a_subsonic_binding_is_a_no_op() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        write(
+            &mut conn,
+            &RemoteBinding {
+                server_url: "https://other.example".into(),
+                identity: RemoteIdentity::Subsonic {
+                    username: "bob".into(),
+                },
+                active_library_id: None,
+                bootstrapped_at: None,
+            },
+        )
+        .await
+        .unwrap();
+
+        advance_cursor(&mut conn, 42).await.unwrap();
+        mark_bootstrapped(&mut conn, 42).await.unwrap();
+
+        let binding = read(&mut conn).await.unwrap().unwrap();
+        assert_eq!(binding.identity.cursor(), None);
+        assert_eq!(binding.bootstrapped_at, None);
+    }
+}
diff --git a/src-tauri/crates/app/src/remote/client.rs b/src-tauri/crates/app/src/remote/client.rs
new file mode 100644
index 00000000..a3709bb3
--- /dev/null
+++ b/src-tauri/crates/app/src/remote/client.rs
@@ -0,0 +1,538 @@
+//! HTTP surface for the native `/api/v2` server.
+//!
+//! Four jobs, none of which the caller should have to think about:
+//!
+//! 1. **Bearer on every request**, base URL prepended once.
+//! 2. **Idempotency headers on mutations** — `X-WaveFlow-Operation-Id`
+//!    and `X-WaveFlow-Device-Id`, which is what lets the outbound queue
+//!    re-issue a call after a lost response without duplicating the
+//!    effect. Only the `/api/v2` routes read them, which is the direct
+//!    reason RFC-005 §Decision 2 forbids routing our own traffic through
+//!    the compatibility façade.
+//! 3. **Refresh once on a 401**, single-flighted process-wide.
+//! 4. **Classify failures** as permanent or transient, so the queue
+//!    knows whether retrying can ever help.
+//!
+//! ## Why refresh has to be single-flighted
+//!
+//! Refresh tokens rotate: spending one mints a new pair and kills the
+//! old. Two tasks that 401 at the same moment and both refresh do not
+//! merely duplicate work — the second presents a token the first has
+//! already spent, gets a 401 back, and concludes the profile is signed
+//! out while the server holds a perfectly valid session.
+//!
+//! The gate is process-wide rather than per-client because two clients
+//! built from the same profile share the credential row. After taking
+//! the gate, [`refresh`] **re-reads** the stored pair: if it changed
+//! while we queued, somebody else already refreshed and we adopt their
+//! result instead of spending our now-stale token. Without that second
+//! read the gate would only serialize the damage, not prevent it.
+
+use std::sync::OnceLock;
+use std::time::Duration;
+
+use serde::Deserialize;
+use tokio::sync::Mutex;
+
+use crate::{
+    error::{AppError, AppResult},
+    offline,
+    remote::{
+        binding::{self, RemoteBinding, RemoteIdentity},
+        tokens::{self, TokenPair},
+    },
+    state::AppState,
+};
+
+/// Header the server reads to recognize a replayed mutation.
+const OPERATION_ID_HEADER: &str = "X-WaveFlow-Operation-Id";
+/// Header identifying the device a mutation originated from. The server
+/// rejects a device owned by another account.
+const DEVICE_ID_HEADER: &str = "X-WaveFlow-Device-Id";
+
+/// Refresh this long before the access token actually lapses. A token
+/// with two seconds left passes a naive validity test and then 401s
+/// mid-flight; one spare round-trip is cheaper than that retry.
+const REFRESH_MARGIN_MS: i64 = 30_000;
+
+/// Matches the server's own request timeout, so a client-side abort
+/// does not race a response that was about to arrive.
+const REQUEST_TIMEOUT: Duration = Duration::from_secs(30);
+
+/// Process-wide refresh gate. See the module docs.
+fn refresh_gate() -> &'static Mutex<()> {
+    static GATE: OnceLock<Mutex<()>> = OnceLock::new();
+    GATE.get_or_init(|| Mutex::new(()))
+}
+
+/// Why a request failed, reduced to the only distinction the caller
+/// actually acts on.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum FailureKind {
+    /// Retrying cannot change the outcome. The caller stops and
+    /// surfaces the problem.
+    ///
+    /// This covers the idempotency conflict: reusing an operation
+    /// identifier with a different fingerprint answers `422`, the same
+    /// status as a malformed payload. The two are indistinguishable on
+    /// the wire and, usefully, call for the same handling.
+    Permanent,
+    /// The condition may clear on its own — congestion, a restart, a
+    /// flaky link. Worth retrying with backoff.
+    Transient,
+    /// Credentials were refused. Handled internally by one refresh; if
+    /// it reaches the caller, the profile is genuinely signed out.
+    Unauthorized,
+}
+
+/// Classify an HTTP status.
+///
+/// `408` and `429` sit with the 5xx range rather than with the other
+/// 4xx: they describe a moment, not a malformed request.
+pub fn classify_status(status: u16) -> Option<FailureKind> {
+    match status {
+        200..=299 => None,
+        401 => Some(FailureKind::Unauthorized),
+        408 | 429 => Some(FailureKind::Transient),
+        500..=599 => Some(FailureKind::Transient),
+        _ => Some(FailureKind::Permanent),
+    }
+}
+
+/// A failed call, with enough context to be actionable in a log or a
+/// diagnostics panel.
+#[derive(Debug, Clone)]
+pub struct RemoteFailure {
+    pub kind: FailureKind,
+    pub status: Option<u16>,
+    pub message: String,
+}
+
+impl std::fmt::Display for RemoteFailure {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self.status {
+            Some(status) => write!(f, "{status}: {}", self.message),
+            None => write!(f, "{}", self.message),
+        }
+    }
+}
+
+impl RemoteFailure {
+    fn transport(error: reqwest::Error) -> Self {
+        Self {
+            // A transport error is a statement about the link, never
+            // about the request's validity — always worth retrying.
+            kind: FailureKind::Transient,
+            status: None,
+            message: error.to_string(),
+        }
+    }
+}
+
+/// The server's error body. Both fields are always present.
+#[derive(Debug, Deserialize)]
+struct ErrorBody {
+    code: String,
+    message: String,
+}
+
+/// Shape returned by `/auth/login`, `/auth/refresh` and `/oauth/token`.
+#[derive(Debug, Deserialize)]
+pub struct AuthTokensResponse {
+    pub access_token: String,
+    pub refresh_token: String,
+    pub expires_in: i64,
+    pub device_id: String,
+    pub user: AuthUserResponse,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct AuthUserResponse {
+    pub id: String,
+    pub username: String,
+}
+
+/// A client bound to one profile's server and credentials.
+///
+/// Built per operation rather than held long-term: the credential it
+/// carries is a snapshot, and a client kept across a refresh would go on
+/// presenting a token that has been rotated away.
+pub struct RemoteClient {
+    base_url: String,
+    device_id: Option<String>,
+    access_token: String,
+    http: reqwest::Client,
+}
+
+impl RemoteClient {
+    /// Build against the active profile's binding and tokens, or
+    /// `Ok(None)` when the profile is not bound to a native server.
+    ///
+    /// Returns `None` — not an error — for an unbound profile, a
+    /// signed-out one, or a Subsonic binding: local-only is the normal
+    /// case, and a server without a journal has no business here.
+    pub async fn try_build(state: &AppState) -> AppResult<Option<Self>> {
+        // Capture the profile up front and pin every later acquisition to
+        // it. A switch landing mid-way must fail this call rather than
+        // read one profile's binding and write another profile's tokens.
+        let profile_id = state.require_profile_id().await?;
+
+        let (binding, pair) = {
+            let pool = state.require_profile_pool_for(Some(profile_id)).await?;
+            let mut conn = pool.acquire().await?;
+
+            let Some(binding) = binding::read(&mut conn).await? else {
+                return Ok(None);
+            };
+            if !matches!(binding.identity, RemoteIdentity::Waveflow { .. }) {
+                return Ok(None);
+            }
+            let Some(pair) = tokens::read(&mut conn).await? else {
+                return Ok(None);
+            };
+            (binding, pair)
+            // The lease ends here, before any network call: holding it
+            // across a 30-second request would stall a profile switch for
+            // the whole duration.
+        };
+
+        // Pre-emptive refresh: cheaper than discovering the lapse
+        // mid-request and unwinding.
+        let pair = if pair.needs_refresh(chrono::Utc::now().timestamp_millis(), REFRESH_MARGIN_MS) {
+            refresh(state, profile_id, &binding, &pair).await?
+        } else {
+            pair
+        };
+
+        Ok(Some(Self::from_parts(&binding, &pair)?))
+    }
+
+    fn from_parts(binding: &RemoteBinding, pair: &TokenPair) -> AppResult<Self> {
+        Ok(Self {
+            base_url: binding.server_url.trim_end_matches('/').to_string(),
+            device_id: binding.identity.device_id().map(str::to_owned),
+            access_token: pair.access_token.clone(),
+            http: reqwest::Client::builder()
+                .timeout(REQUEST_TIMEOUT)
+                .build()
+                .map_err(|err| AppError::Other(format!("http client init: {err}")))?,
+        })
+    }
+
+    /// A read request. No idempotency headers — a GET has nothing to
+    /// replay.
+    pub fn get(&self, path: &str) -> reqwest::RequestBuilder {
+        self.http.get(self.url(path)).bearer_auth(&self.access_token)
+    }
+
+    /// A mutation, stamped so the server can recognize a replay.
+    ///
+    /// `operation_id` must be the identifier stored alongside the queued
+    /// entry and must never change for a given logical mutation: the
+    /// server fingerprints the action, target and normalized payload,
+    /// and answers a same-id-different-fingerprint call with a conflict
+    /// rather than a replay.
+    pub fn mutate(
+        &self,
+        method: reqwest::Method,
+        path: &str,
+        operation_id: &str,
+    ) -> reqwest::RequestBuilder {
+        let mut builder = self
+            .http
+            .request(method, self.url(path))
+            .bearer_auth(&self.access_token)
+            .header(OPERATION_ID_HEADER, operation_id);
+        if let Some(device_id) = &self.device_id {
+            builder = builder.header(DEVICE_ID_HEADER, device_id);
+        }
+        builder
+    }
+
+    fn url(&self, path: &str) -> String {
+        if path.starts_with('/') {
+            format!("{}{}", self.base_url, path)
+        } else {
+            format!("{}/{}", self.base_url, path)
+        }
+    }
+
+    pub fn base_url(&self) -> &str {
+        &self.base_url
+    }
+
+    pub fn access_token(&self) -> &str {
+        &self.access_token
+    }
+
+    /// Send a request and decode its JSON body.
+    ///
+    /// Refuses to leave the machine while the process is in offline
+    /// mode, and reports that as transient — offline is a state the user
+    /// toggles back, not a reason to give up on a queued write.
+    pub async fn send_json<T: serde::de::DeserializeOwned>(
+        &self,
+        builder: reqwest::RequestBuilder,
+    ) -> Result<T, RemoteFailure> {
+        let response = self.send(builder).await?;
+        response.json::<T>().await.map_err(|err| RemoteFailure {
+            // A body we cannot parse is not a link problem: the server
+            // answered, and its answer is not what the contract
+            // promises. Retrying re-fetches the same bytes.
+            kind: FailureKind::Permanent,
+            status: None,
+            message: format!("malformed response body: {err}"),
+        })
+    }
+
+    /// Send a request, discarding a successful body. For the `204`
+    /// mutations.
+    pub async fn send_ok(&self, builder: reqwest::RequestBuilder) -> Result<(), RemoteFailure> {
+        self.send(builder).await.map(|_| ())
+    }
+
+    async fn send(
+        &self,
+        builder: reqwest::RequestBuilder,
+    ) -> Result<reqwest::Response, RemoteFailure> {
+        if offline::is_offline() {
+            return Err(RemoteFailure {
+                kind: FailureKind::Transient,
+                status: None,
+                message: "offline mode is on".into(),
+            });
+        }
+
+        let response = builder.send().await.map_err(RemoteFailure::transport)?;
+        let status = response.status().as_u16();
+        match classify_status(status) {
+            None => Ok(response),
+            Some(kind) => {
+                // Read the structured body while we still can — it names
+                // the failure far better than the status alone.
+                let message = match response.json::<ErrorBody>().await {
+                    Ok(body) => format!("{} ({})", body.message, body.code),
+                    Err(_) => "no error body".to_string(),
+                };
+                Err(RemoteFailure {
+                    kind,
+                    status: Some(status),
+                    message,
+                })
+            }
+        }
+    }
+}
+
+/// Exchange the stored refresh token for a fresh pair and persist it.
+///
+/// Single-flighted process-wide, with a re-read after taking the gate so
+/// a task that queued behind another adopts its result rather than
+/// spending a token that has already been rotated away.
+pub async fn refresh(
+    state: &AppState,
+    profile_id: i64,
+    binding: &RemoteBinding,
+    known: &TokenPair,
+) -> AppResult<TokenPair> {
+    let _guard = refresh_gate().lock().await;
+
+    {
+        let pool = state.require_profile_pool_for(Some(profile_id)).await?;
+        let mut conn = pool.acquire().await?;
+
+        // Somebody may have refreshed while we waited for the gate.
+        if let Some(current) = tokens::read(&mut conn).await? {
+            if current.refresh_token != known.refresh_token {
+                return Ok(current);
+            }
+        }
+        // Lease released before the request — see `try_build`.
+    }
+
+    let http = reqwest::Client::builder()
+        .timeout(REQUEST_TIMEOUT)
+        .build()
+        .map_err(|err| AppError::Other(format!("http client init: {err}")))?;
+
+    let url = format!(
+        "{}/api/v2/auth/refresh",
+        binding.server_url.trim_end_matches('/')
+    );
+    let response = http
+        .post(url)
+        .json(&serde_json::json!({ "refresh_token": known.refresh_token }))
+        .send()
+        .await
+        .map_err(|err| AppError::Other(format!("token refresh failed: {err}")))?;
+
+    let status = response.status().as_u16();
+    if classify_status(status).is_some() {
+        return Err(AppError::Other(format!(
+            "token refresh rejected with status {status}"
+        )));
+    }
+
+    let fresh: AuthTokensResponse = response
+        .json()
+        .await
+        .map_err(|err| AppError::Other(format!("malformed refresh response: {err}")))?;
+
+    let pair = TokenPair {
+        access_token: fresh.access_token,
+        refresh_token: fresh.refresh_token,
+        expires_at: tokens::deadline_from_expires_in(fresh.expires_in),
+        username: Some(fresh.user.username),
+    };
+
+    // The server has now rotated: the token we presented is dead, and the
+    // replacement exists only in this function. If the profile switched
+    // while the request was in flight we cannot persist it — its `data.db`
+    // is closed — and the pair is lost, leaving that profile to sign in
+    // again. Losing it is the right side of the trade: the alternative is
+    // writing one account's credentials into another profile's database.
+    let pool = state
+        .require_profile_pool_for(Some(profile_id))
+        .await
+        .inspect_err(|_| {
+            tracing::warn!(
+                profile_id,
+                "profile switched during a token refresh; the rotated pair \
+                 could not be stored and that profile will need to sign in again"
+            );
+        })?;
+    let mut conn = pool.acquire().await?;
+    tokens::write(&mut conn, &pair).await?;
+
+    // The server echoes the device back rather than minting a new one,
+    // so this normally matches what we already hold. Adopting it anyway
+    // costs nothing and keeps a re-issued device from silently
+    // invalidating every subsequent mutation.
+    if let RemoteIdentity::Waveflow {
+        account_id, cursor, ..
+    } = &binding.identity
+    {
+        if binding.identity.device_id() != Some(fresh.device_id.as_str()) {
+            let updated = RemoteBinding {
+                identity: RemoteIdentity::Waveflow {
+                    account_id: account_id.clone(),
+                    device_id: fresh.device_id,
+                    cursor: *cursor,
+                },
+                ..binding.clone()
+            };
+            binding::write(&mut conn, &updated).await?;
+        }
+    }
+
+    Ok(pair)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn success_is_not_a_failure() {
+        for status in [200, 201, 204, 299] {
+            assert_eq!(classify_status(status), None, "status {status}");
+        }
+    }
+
+    #[test]
+    fn credentials_get_their_own_class_so_a_refresh_can_be_tried() {
+        assert_eq!(classify_status(401), Some(FailureKind::Unauthorized));
+    }
+
+    #[test]
+    fn an_idempotency_conflict_is_permanent() {
+        // The server answers 422 both for a malformed payload and for a
+        // reused operation id with a different fingerprint. Neither can
+        // succeed on retry, so the queue must stop rather than spin.
+        assert_eq!(classify_status(422), Some(FailureKind::Permanent));
+    }
+
+    #[test]
+    fn missing_and_forbidden_are_permanent() {
+        assert_eq!(classify_status(403), Some(FailureKind::Permanent));
+        assert_eq!(classify_status(404), Some(FailureKind::Permanent));
+    }
+
+    #[test]
+    fn congestion_and_server_faults_are_worth_retrying() {
+        for status in [408, 429, 500, 502, 503, 504] {
+            assert_eq!(
+                classify_status(status),
+                Some(FailureKind::Transient),
+                "status {status}"
+            );
+        }
+    }
+
+    #[test]
+    fn a_mutation_carries_both_identity_headers() {
+        let binding = RemoteBinding {
+            server_url: "https://music.example".into(),
+            identity: RemoteIdentity::Waveflow {
+                account_id: "acc".into(),
+                device_id: "dev".into(),
+                cursor: 0,
+            },
+            active_library_id: None,
+            bootstrapped_at: None,
+        };
+        let pair = TokenPair {
+            access_token: "wfa_token".into(),
+            refresh_token: "wfr_token".into(),
+            expires_at: None,
+            username: None,
+        };
+        let client = RemoteClient::from_parts(&binding, &pair).unwrap();
+
+        let request = client
+            .mutate(reqwest::Method::PUT, "/api/v2/favorites/track/t1", "op-1")
+            .build()
+            .unwrap();
+
+        assert_eq!(request.headers()[OPERATION_ID_HEADER], "op-1");
+        assert_eq!(request.headers()[DEVICE_ID_HEADER], "dev");
+        assert_eq!(
+            request.headers()[reqwest::header::AUTHORIZATION],
+            "Bearer wfa_token"
+        );
+        assert_eq!(
+            request.url().as_str(),
+            "https://music.example/api/v2/favorites/track/t1"
+        );
+    }
+
+    #[test]
+    fn a_read_carries_no_idempotency_headers() {
+        let binding = RemoteBinding {
+            server_url: "https://music.example/".into(),
+            identity: RemoteIdentity::Waveflow {
+                account_id: "acc".into(),
+                device_id: "dev".into(),
+                cursor: 0,
+            },
+            active_library_id: None,
+            bootstrapped_at: None,
+        };
+        let pair = TokenPair {
+            access_token: "wfa_token".into(),
+            refresh_token: "wfr_token".into(),
+            expires_at: None,
+            username: None,
+        };
+        let client = RemoteClient::from_parts(&binding, &pair).unwrap();
+        let request = client.get("/api/v2/sync/snapshot").build().unwrap();
+
+        assert!(request.headers().get(OPERATION_ID_HEADER).is_none());
+        assert!(request.headers().get(DEVICE_ID_HEADER).is_none());
+        // The trailing slash on the base must not survive into the path.
+        assert_eq!(
+            request.url().as_str(),
+            "https://music.example/api/v2/sync/snapshot"
+        );
+    }
+}
diff --git a/src-tauri/crates/app/src/remote/mod.rs b/src-tauri/crates/app/src/remote/mod.rs
new file mode 100644
index 00000000..7b2da1da
--- /dev/null
+++ b/src-tauri/crates/app/src/remote/mod.rs
@@ -0,0 +1,55 @@
+//! Remote music source + user-data sync v2. Desktop side of
+//! [RFC-005](https://github.com/InstaZDLL/WaveFlow/blob/main/docs/rfcs/RFC-005-remote-source-and-sync-v2.md).
+//!
+//! ## Not to be confused with [`crate::sync`]
+//!
+//! `crate::sync` implements the retired v1 protocol (peer-to-peer ops,
+//! hybrid logical clocks, digest reconciliation) against a server that
+//! no longer exists. It stays in the tree, behind the `sync_v1`
+//! feature, for exactly as long as it takes to prove the snapshot
+//! bootstrap here — until then it is the only path back from a
+//! divergence. This module is its replacement, not its evolution.
+//!
+//! Neither module's docs should be read as describing the other, and
+//! the two RFCs numbered 003 (one per repository) are likewise
+//! unrelated — see RFC-005 §"The RFC-003 naming trap".
+//!
+//! ## Module map
+//!
+//! - [`binding`] — which server this profile talks to and where it is
+//!   up to. Holds [`binding::RemoteIdentity`], the polymorphic identity
+//!   that keeps a third-party server from having to pretend it has an
+//!   account UUID, a device and a journal cursor.
+//!
+//! - [`tokens`] — access / refresh token persistence. Separate from the
+//!   binding because tokens rotate and the binding does not.
+//!
+//! - [`client`] — the HTTP surface. Attaches the Bearer header, stamps
+//!   mutations with their operation and device identifiers, refreshes
+//!   once on a 401, and classifies every failure as permanent or
+//!   transient so the outbound queue knows whether retrying can ever
+//!   help.
+//!
+//! - [`probe`] — server flavour detection. Decides whether the optional
+//!   [`SyncProvider`](#capabilities) surface exists at all.
+//!
+//! ## Capabilities
+//!
+//! The desktop must talk to any server speaking the Subsonic protocol,
+//! so the mandatory surface is what every server does — catalogue,
+//! search, playback — and the journal is an optional capability layered
+//! on top. Only WaveFlow offers it, which is why nothing in this module
+//! may assume it is present without having observed it.
+
+// This slice lands the foundation; its consumers — the PKCE handshake,
+// the snapshot bootstrap, the outbound drain — land in the ones that
+// follow. Until then most of the surface below has no caller and
+// `dead_code` would flag nearly all of it, drowning the warnings that
+// mean something. Same treatment, and the same reason, as
+// `sync/mode.rs`. Drop this once the drain consumes the client.
+#![allow(dead_code)]
+
+pub mod binding;
+pub mod client;
+pub mod probe;
+pub mod tokens;
diff --git a/src-tauri/crates/app/src/remote/probe.rs b/src-tauri/crates/app/src/remote/probe.rs
new file mode 100644
index 00000000..c0ac4074
--- /dev/null
+++ b/src-tauri/crates/app/src/remote/probe.rs
@@ -0,0 +1,236 @@
+//! Server flavour detection.
+//!
+//! Decides whether the URL the user typed is a WaveFlow server — and so
+//! whether the journal capability exists at all — before asking them for
+//! any credential.
+//!
+//! ## Why `ping`, and why it works unauthenticated
+//!
+//! Every server speaking the Subsonic protocol answers `/rest/ping`, and
+//! WaveFlow stamps `type="waveflow"` into that answer. Measured against
+//! a live server (2026-08-10), the discriminating fields are present
+//! **even when the ping itself fails**:
+//!
+//! ```text
+//! GET /rest/ping?f=json                       → 400
+//!   {"subsonic-response":{"error":{"code":10,…},"status":"failed",
+//!    "type":"waveflow","serverVersion":"2.0.0-beta.0","openSubsonic":true}}
+//!
+//! GET /rest/ping?u=nobody&p=nothing&…&f=json  → 401
+//!   {"subsonic-response":{"error":{"code":40,…},"status":"failed",
+//!    "type":"waveflow",…}}
+//! ```
+//!
+//! Two consequences, both load-bearing:
+//!
+//! - detection needs **no credentials**, so the sign-in screen can offer
+//!   the right flow — browser consent for WaveFlow, username and
+//!   password for anything else — before the user types anything;
+//! - the probe must parse the body **regardless of HTTP status**. A
+//!   probe that bailed on a non-2xx response would learn nothing from
+//!   either of the answers above, which are the only two an
+//!   unauthenticated caller can obtain.
+//!
+//! ## What not to use
+//!
+//! Not `getOpenSubsonicExtensions`: it returns an *empty* container
+//! today. A client probing capabilities that way would conclude the
+//! server offers nothing, while it in fact offers the entire v2 API. The
+//! discriminant is `type`, not the extension list.
+
+use std::time::Duration;
+
+use serde::Deserialize;
+
+use crate::{
+    error::{AppError, AppResult},
+    offline,
+};
+
+/// Client name we identify as in the Subsonic query string. Required by
+/// the protocol; servers surface it in their logs.
+const CLIENT_NAME: &str = "WaveFlow";
+/// Protocol version we claim. 1.16.1 is the level the modern extensions
+/// are defined against.
+const PROTOCOL_VERSION: &str = "1.16.1";
+
+/// Short on purpose: this runs while the user waits on a settings
+/// screen, and a wrong URL should say so quickly rather than hang.
+const PROBE_TIMEOUT: Duration = Duration::from_secs(10);
+
+/// What we found at the other end.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ServerFlavour {
+    /// A native WaveFlow server: the journal, per-device ACK and
+    /// mutation idempotency are all available.
+    Waveflow {
+        /// The server's own version string, for display.
+        server_version: Option<String>,
+    },
+    /// A server speaking the Subsonic protocol but not ours. Catalogue
+    /// and playback only — no journal, and no safe blind replay of a
+    /// mutation whose response was lost.
+    Subsonic {
+        /// Whatever the server calls itself, kept verbatim for display.
+        server_type: Option<String>,
+        server_version: Option<String>,
+    },
+}
+
+impl ServerFlavour {
+    /// Whether the optional synchronization surface exists here.
+    pub fn supports_sync(&self) -> bool {
+        matches!(self, ServerFlavour::Waveflow { .. })
+    }
+}
+
+#[derive(Debug, Deserialize)]
+struct PingEnvelope {
+    #[serde(rename = "subsonic-response")]
+    response: Option<PingResponse>,
+}
+
+#[derive(Debug, Deserialize)]
+struct PingResponse {
+    #[serde(rename = "type")]
+    server_type: Option<String>,
+    #[serde(rename = "serverVersion")]
+    server_version: Option<String>,
+}
+
+/// Identify the server behind `base_url`.
+///
+/// Errors only when we could not reach anything that looks like a music
+/// server — a wrong URL, an unreachable host, or a reply that is not a
+/// Subsonic envelope. A *failed* ping from a real server is a success
+/// here: it still identifies itself.
+pub async fn detect(base_url: &str) -> AppResult<ServerFlavour> {
+    if offline::is_offline() {
+        return Err(AppError::Other(
+            "offline mode is on; turn it off to reach a server".into(),
+        ));
+    }
+
+    let url = format!(
+        "{}/rest/ping?{}",
+        base_url.trim_end_matches('/'),
+        url::form_urlencoded::Serializer::new(String::new())
+            .append_pair("v", PROTOCOL_VERSION)
+            .append_pair("c", CLIENT_NAME)
+            .append_pair("f", "json")
+            .finish(),
+    );
+
+    let http = reqwest::Client::builder()
+        .timeout(PROBE_TIMEOUT)
+        .build()
+        .map_err(|err| AppError::Other(format!("http client init: {err}")))?;
+
+    let response = http
+        .get(url)
+        .send()
+        .await
+        .map_err(|err| AppError::Other(format!("could not reach the server: {err}")))?;
+
+    // Deliberately not checking the status — see the module docs. An
+    // unauthenticated ping answers 400 or 401 and still identifies the
+    // server.
+    let body = response
+        .text()
+        .await
+        .map_err(|err| AppError::Other(format!("could not read the server's reply: {err}")))?;
+
+    classify_ping_body(&body)
+}
+
+/// Parse a ping body into a flavour. Split out from the request so the
+/// interesting half is testable without a server.
+pub fn classify_ping_body(body: &str) -> AppResult<ServerFlavour> {
+    let envelope: PingEnvelope = serde_json::from_str(body).map_err(|_| {
+        AppError::Other("this URL did not answer like a music server".to_string())
+    })?;
+
+    let Some(response) = envelope.response else {
+        return Err(AppError::Other(
+            "this URL did not answer like a music server".to_string(),
+        ));
+    };
+
+    match response.server_type.as_deref() {
+        Some(server_type) if server_type.eq_ignore_ascii_case("waveflow") => {
+            Ok(ServerFlavour::Waveflow {
+                server_version: response.server_version,
+            })
+        }
+        // Anything else that answered in the protocol is a third-party
+        // server. It is a perfectly valid target — it simply has no
+        // journal, so `SyncProvider` stays absent.
+        other => Ok(ServerFlavour::Subsonic {
+            server_type: other.map(str::to_owned),
+            server_version: response.server_version,
+        }),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Verbatim body from a live server, missing-parameter branch.
+    const WAVEFLOW_400: &str = r#"{"subsonic-response":{"error":{"code":10,"message":"Required parameter is missing"},"openSubsonic":true,"serverVersion":"2.0.0-beta.0","status":"failed","type":"waveflow","version":"1.16.1"}}"#;
+
+    /// Verbatim body from a live server, bad-credentials branch.
+    const WAVEFLOW_401: &str = r#"{"subsonic-response":{"error":{"code":40,"message":"Wrong username or password"},"openSubsonic":true,"serverVersion":"2.0.0-beta.0","status":"failed","type":"waveflow","version":"1.16.1"}}"#;
+
+    #[test]
+    fn a_failed_ping_still_identifies_a_waveflow_server() {
+        // This is the whole point of the probe: both of these arrive
+        // with a non-2xx status, and both are enough to decide.
+        for body in [WAVEFLOW_400, WAVEFLOW_401] {
+            let flavour = classify_ping_body(body).unwrap();
+            assert_eq!(
+                flavour,
+                ServerFlavour::Waveflow {
+                    server_version: Some("2.0.0-beta.0".into())
+                }
+            );
+            assert!(flavour.supports_sync());
+        }
+    }
+
+    #[test]
+    fn a_third_party_server_is_accepted_without_the_sync_capability() {
+        let body = r#"{"subsonic-response":{"status":"ok","version":"1.16.1","type":"someserver","serverVersion":"1.2.3"}}"#;
+        let flavour = classify_ping_body(body).unwrap();
+        assert_eq!(
+            flavour,
+            ServerFlavour::Subsonic {
+                server_type: Some("someserver".into()),
+                server_version: Some("1.2.3".into()),
+            }
+        );
+        assert!(!flavour.supports_sync());
+    }
+
+    #[test]
+    fn a_server_that_omits_its_type_is_treated_as_third_party() {
+        // Never assume a capability we have not observed: no `type`
+        // means no evidence of the journal.
+        let body = r#"{"subsonic-response":{"status":"ok","version":"1.16.1"}}"#;
+        let flavour = classify_ping_body(body).unwrap();
+        assert!(!flavour.supports_sync());
+    }
+
+    #[test]
+    fn the_type_comparison_ignores_case() {
+        let body = r#"{"subsonic-response":{"status":"ok","type":"WaveFlow"}}"#;
+        assert!(classify_ping_body(body).unwrap().supports_sync());
+    }
+
+    #[test]
+    fn something_that_is_not_a_music_server_is_an_error() {
+        assert!(classify_ping_body("<html>404</html>").is_err());
+        assert!(classify_ping_body("{}").is_err());
+        assert!(classify_ping_body(r#"{"hello":"world"}"#).is_err());
+    }
+}
diff --git a/src-tauri/crates/app/src/remote/tokens.rs b/src-tauri/crates/app/src/remote/tokens.rs
new file mode 100644
index 00000000..ca84168f
--- /dev/null
+++ b/src-tauri/crates/app/src/remote/tokens.rs
@@ -0,0 +1,320 @@
+//! Access / refresh token persistence for the remote binding.
+//!
+//! Kept apart from [`super::binding`] because the two have different
+//! lifetimes: the binding changes when the user picks a server, the
+//! tokens change every fifteen minutes.
+//!
+//! ## These are not JWTs
+//!
+//! The v1 client validated its stored credential by checking it had
+//! three dot-separated segments, because Better Auth minted JWTs. The v2
+//! server issues **opaque** tokens — `wfa_…` for access, `wfr_…` for
+//! refresh, `wfapi_…` for long-lived API tokens — and hashes them
+//! server-side. The v1 check would reject every single one of them, so
+//! this module deliberately validates nothing beyond non-emptiness:
+//! whether a token is good is a question only the server can answer, and
+//! it answers it on the first request.
+//!
+//! ## Rotation is what makes this delicate
+//!
+//! A refresh returns a *new* refresh token and kills the old one. Two
+//! concurrent refreshes therefore do not merely duplicate work — the
+//! second presents a token the first has already spent, fails, and can
+//! leave the profile signed out with a perfectly valid session on the
+//! server. Refreshing is single-flighted in [`super::client`]; this
+//! module's job is to make the write atomic so a crash between the two
+//! tokens cannot strand the pair.
+//!
+//! ## Storage
+//!
+//! `auth_credential` under the existing `waveflow_server` provider —
+//! the same row family as the other integrations, already allowed by the
+//! table's CHECK. The column names say `*_encrypted`; as in v1 the bytes
+//! are stored raw, and moving the pair into the OS keyring is a
+//! hardening pass that will not change this module's surface.
+
+use chrono::Utc;
+use sqlx::{Row, SqliteConnection};
+
+use crate::error::{AppError, AppResult};
+
+/// `auth_credential.provider` value. Must stay in the CHECK constraint
+/// installed by `20260601000000_waveflow_server_auth_provider`.
+pub const PROVIDER: &str = "waveflow_server";
+
+/// A live credential pair.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct TokenPair {
+    pub access_token: String,
+    pub refresh_token: String,
+    /// Epoch milliseconds at which the access token stops being
+    /// accepted, or `None` when the server did not say.
+    pub expires_at: Option<i64>,
+    /// The account's username. Persisted only so the Settings card can
+    /// name the signed-in account without a round-trip.
+    pub username: Option<String>,
+}
+
+impl TokenPair {
+    /// Whether the access token should be refreshed before use.
+    ///
+    /// The margin matters: a token that expires in two seconds passes a
+    /// naive `now < expires_at` test and then 401s in flight. Refreshing
+    /// slightly early costs one extra round-trip; refreshing too late
+    /// costs a failed request and a retry on every call made near the
+    /// boundary.
+    pub fn needs_refresh(&self, now_ms: i64, margin_ms: i64) -> bool {
+        match self.expires_at {
+            Some(expires_at) => now_ms + margin_ms >= expires_at,
+            // No expiry recorded — a long-lived API token, or a server
+            // that declined to say. Assume it is good and let a 401
+            // drive the refresh instead of guessing.
+            None => false,
+        }
+    }
+}
+
+fn now_ms() -> i64 {
+    Utc::now().timestamp_millis()
+}
+
+/// Read the stored pair, or `None` when this profile is signed out.
+pub async fn read(conn: &mut SqliteConnection) -> AppResult<Option<TokenPair>> {
+    let row = sqlx::query(
+        "SELECT token_encrypted, refresh_token_encrypted, expires_at, username
+           FROM auth_credential WHERE provider = ?",
+    )
+    .bind(PROVIDER)
+    .fetch_optional(&mut *conn)
+    .await?;
+    let Some(row) = row else { return Ok(None) };
+
+    let access: Vec<u8> = row.try_get("token_encrypted")?;
+    let refresh: Option<Vec<u8>> = row.try_get("refresh_token_encrypted")?;
+
+    let access_token = decode(access, "access token")?;
+    // A row with no refresh token is a legacy v1 credential, or a
+    // long-lived API token pasted by hand. Both are unusable for the v2
+    // flow, which cannot recover the session once the access token
+    // lapses — treating it as signed out is the honest answer.
+    let Some(refresh_token) = refresh.map(|bytes| decode(bytes, "refresh token")).transpose()?
+    else {
+        return Ok(None);
+    };
+
+    if access_token.is_empty() || refresh_token.is_empty() {
+        return Ok(None);
+    }
+
+    Ok(Some(TokenPair {
+        access_token,
+        refresh_token,
+        expires_at: row.try_get("expires_at")?,
+        username: row.try_get("username")?,
+    }))
+}
+
+fn decode(bytes: Vec<u8>, what: &str) -> AppResult<String> {
+    String::from_utf8(bytes)
+        .map(|value| value.trim().to_string())
+        .map_err(|_| AppError::Other(format!("stored {what} is not valid UTF-8")))
+}
+
+/// Persist a pair, replacing whatever was there.
+///
+/// Both tokens land in one statement on purpose. Writing them
+/// separately would leave a window where a crash strands a new access
+/// token next to a refresh token that has already been spent — the
+/// profile would look signed in and be unable to recover.
+pub async fn write(conn: &mut SqliteConnection, pair: &TokenPair) -> AppResult<()> {
+    if pair.access_token.trim().is_empty() || pair.refresh_token.trim().is_empty() {
+        return Err(AppError::Other(
+            "refusing to store an empty token pair".into(),
+        ));
+    }
+    let now = now_ms();
+    sqlx::query(
+        "INSERT INTO auth_credential
+            (provider, username, token_encrypted, refresh_token_encrypted,
+             expires_at, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(provider) DO UPDATE SET
+            username                = excluded.username,
+            token_encrypted         = excluded.token_encrypted,
+            refresh_token_encrypted = excluded.refresh_token_encrypted,
+            expires_at              = excluded.expires_at,
+            updated_at              = excluded.updated_at",
+    )
+    .bind(PROVIDER)
+    .bind(pair.username.as_deref())
+    .bind(pair.access_token.trim().as_bytes())
+    .bind(pair.refresh_token.trim().as_bytes())
+    .bind(pair.expires_at)
+    .bind(now)
+    .bind(now)
+    .execute(&mut *conn)
+    .await?;
+    Ok(())
+}
+
+/// Turn the server's `expires_in` (seconds) into an absolute deadline.
+///
+/// Absolute rather than relative because the value has to survive a
+/// restart: a stored duration says nothing about how much of it is left.
+pub fn deadline_from_expires_in(expires_in_secs: i64) -> Option<i64> {
+    if expires_in_secs <= 0 {
+        return None;
+    }
+    expires_in_secs
+        .checked_mul(1_000)
+        .and_then(|ms| now_ms().checked_add(ms))
+}
+
+/// Sign out. Idempotent.
+pub async fn clear(conn: &mut SqliteConnection) -> AppResult<()> {
+    sqlx::query("DELETE FROM auth_credential WHERE provider = ?")
+        .bind(PROVIDER)
+        .execute(&mut *conn)
+        .await?;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use sqlx::sqlite::SqlitePoolOptions;
+    use sqlx::SqlitePool;
+
+    async fn pool() -> SqlitePool {
+        let pool = SqlitePoolOptions::new()
+            .max_connections(1)
+            .connect(":memory:")
+            .await
+            .unwrap();
+        // The real table, CHECK included: storing under a provider the
+        // constraint does not allow is exactly the kind of failure a
+        // hand-rolled fixture would hide.
+        sqlx::raw_sql(
+            "CREATE TABLE auth_credential (
+                provider                TEXT PRIMARY KEY
+                                        CHECK (provider IN ('lastfm','listenbrainz','deezer','spotify','waveflow_server')),
+                username                TEXT,
+                token_encrypted         BLOB NOT NULL,
+                refresh_token_encrypted BLOB,
+                expires_at              INTEGER,
+                created_at              INTEGER NOT NULL,
+                updated_at              INTEGER NOT NULL
+            )",
+        )
+        .execute(&pool)
+        .await
+        .unwrap();
+        pool
+    }
+
+    fn pair() -> TokenPair {
+        TokenPair {
+            access_token: "wfa_abc".into(),
+            refresh_token: "wfr_def".into(),
+            expires_at: Some(1_000_000),
+            username: Some("alice".into()),
+        }
+    }
+
+    #[tokio::test]
+    async fn signed_out_profile_reads_as_none() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        assert_eq!(read(&mut conn).await.unwrap(), None);
+    }
+
+    #[tokio::test]
+    async fn opaque_tokens_round_trip() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        write(&mut conn, &pair()).await.unwrap();
+        assert_eq!(read(&mut conn).await.unwrap(), Some(pair()));
+    }
+
+    #[tokio::test]
+    async fn rotation_replaces_both_halves() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        write(&mut conn, &pair()).await.unwrap();
+
+        let rotated = TokenPair {
+            access_token: "wfa_new".into(),
+            refresh_token: "wfr_new".into(),
+            expires_at: Some(2_000_000),
+            username: Some("alice".into()),
+        };
+        write(&mut conn, &rotated).await.unwrap();
+
+        let stored = read(&mut conn).await.unwrap().unwrap();
+        assert_eq!(stored, rotated, "a spent refresh token must not survive");
+    }
+
+    #[tokio::test]
+    async fn a_credential_without_a_refresh_token_reads_as_signed_out() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        // Shape a v1 row left behind by an older build.
+        sqlx::query(
+            "INSERT INTO auth_credential
+                (provider, token_encrypted, refresh_token_encrypted, created_at, updated_at)
+             VALUES (?, ?, NULL, 0, 0)",
+        )
+        .bind(PROVIDER)
+        .bind("header.payload.signature".as_bytes())
+        .execute(&mut *conn)
+        .await
+        .unwrap();
+
+        assert_eq!(read(&mut conn).await.unwrap(), None);
+    }
+
+    #[tokio::test]
+    async fn empty_halves_are_refused_rather_than_stored() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        let mut empty = pair();
+        empty.refresh_token = "   ".into();
+        assert!(write(&mut conn, &empty).await.is_err());
+        assert_eq!(read(&mut conn).await.unwrap(), None);
+    }
+
+    #[test]
+    fn refresh_margin_fires_before_the_token_actually_lapses() {
+        let pair = TokenPair {
+            expires_at: Some(10_000),
+            ..pair()
+        };
+        assert!(!pair.needs_refresh(0, 1_000));
+        // Still valid for half a second, but not for the round-trip.
+        assert!(pair.needs_refresh(9_500, 1_000));
+        assert!(pair.needs_refresh(10_001, 0));
+    }
+
+    #[test]
+    fn a_credential_without_an_expiry_is_never_pre_emptively_refreshed() {
+        let pair = TokenPair {
+            expires_at: None,
+            ..pair()
+        };
+        assert!(!pair.needs_refresh(i64::MAX / 2, 1_000));
+    }
+
+    #[test]
+    fn a_non_positive_expires_in_yields_no_deadline() {
+        assert_eq!(deadline_from_expires_in(0), None);
+        assert_eq!(deadline_from_expires_in(-1), None);
+        assert!(deadline_from_expires_in(900).is_some());
+    }
+
+    #[test]
+    fn an_absurd_expires_in_does_not_overflow_into_the_past() {
+        // A hostile or buggy server answering i64::MAX seconds must not
+        // wrap the deadline around into a value that reads as expired.
+        assert_eq!(deadline_from_expires_in(i64::MAX), None);
+    }
+}
diff --git a/src-tauri/migrations/profile/20260810120000_remote_source_projection.sql b/src-tauri/migrations/profile/20260810120000_remote_source_projection.sql
new file mode 100644
index 00000000..8e933074
--- /dev/null
+++ b/src-tauri/migrations/profile/20260810120000_remote_source_projection.sql
@@ -0,0 +1,253 @@
+-- Remote music source + user-data sync v2 projection. RFC-005.
+--
+-- The server is authoritative over its own catalogue, and this protocol
+-- synchronizes only the state the account owns: playlists, favourites,
+-- ratings, history, queue and shares. Those all reference the SERVER's
+-- tracks, which have no local counterpart — matching a local file to a
+-- server track is deliberately out of scope (RFC-005 §Decision 1).
+--
+-- That is why none of this lands in `playlist` / `liked_track` /
+-- `track.rating`. Writing it there would leave two options, both wrong:
+-- fabricate local track rows for content that only exists on the server,
+-- or silently drop every entry. The first corrupts the library, the
+-- second makes synchronization look broken while reporting success.
+--
+-- So the projection gets its own tables. Everything below is
+-- RECONSTRUCTIBLE: dropping the lot and re-fetching `GET
+-- /api/v2/sync/snapshot` is always a valid recovery, and is exactly what
+-- the apply path does when it meets a known event it cannot apply.
+-- `remote_mutation` is the one exception — it holds writes the user made
+-- offline that the server has not seen yet, so it is NOT reconstructible
+-- and must survive a projection reset.
+--
+-- ## Identifiers are opaque strings
+--
+-- RFC-005 §Decision 4: never parse a remote identifier into a UUID.
+-- WaveFlow happens to serialize UUIDs, but a third-party Subsonic server
+-- emits textual identifiers of another shape, and the desktop must
+-- support both. Every `*_remote_id` column below is therefore TEXT with
+-- no format constraint.
+--
+-- The RFC keys remote entities on `(profile_id, remote_id)` because two
+-- servers can legitimately emit the same identifier. Here the profile
+-- scope is implicit: this migration runs against the per-profile
+-- `data.db`, so `remote_id` alone is already profile-scoped, and one
+-- profile binds to exactly one server account.
+
+-- =============================================================================
+-- 1. Binding — which server this profile talks to, and where it is up to
+-- =============================================================================
+--
+-- Single row, pinned by `CHECK (id = 1)`. The binding is per-profile
+-- rather than app-wide (which is where v1 kept the server URL): with a
+-- universal client, two profiles may legitimately point at two different
+-- servers, and the cursor/device pair is meaningless across accounts.
+--
+-- `flavour` decides which of the identity columns carry meaning, and the
+-- CHECK enforces that rather than trusting the application layer. A
+-- third-party Subsonic server has no account UUID, no device notion and
+-- no journal cursor; a WaveFlow server has all three.
+
+CREATE TABLE remote_binding (
+    id                INTEGER PRIMARY KEY CHECK (id = 1),
+    server_url        TEXT    NOT NULL,
+    flavour           TEXT    NOT NULL CHECK (flavour IN ('waveflow', 'subsonic')),
+    -- WaveFlow branch.
+    account_id        TEXT,
+    device_id         TEXT,
+    -- Subsonic branch.
+    username          TEXT,
+    -- Journal position. 0 means "never bootstrapped"; the snapshot pass
+    -- is what first moves it. Only meaningful on the WaveFlow branch.
+    cursor            INTEGER NOT NULL DEFAULT 0 CHECK (cursor >= 0),
+    -- Optional library filter for the catalogue projections. An account
+    -- with access to several libraries picks one instead of spawning
+    -- artificial profiles (RFC-005 §Decision 3).
+    active_library_id TEXT,
+    -- NULL until the first snapshot has been applied. Distinguishes "no
+    -- data yet because we never asked" from "no data because the account
+    -- is empty" — without it, an empty account and a failed bootstrap
+    -- look identical.
+    bootstrapped_at   INTEGER,
+    created_at        INTEGER NOT NULL,
+    updated_at        INTEGER NOT NULL,
+
+    CHECK (
+        (flavour = 'waveflow' AND account_id IS NOT NULL AND device_id IS NOT NULL)
+     OR (flavour = 'subsonic' AND username IS NOT NULL)
+    )
+);
+
+-- =============================================================================
+-- 2. Projected user data
+-- =============================================================================
+
+CREATE TABLE remote_playlist (
+    remote_id  TEXT PRIMARY KEY,
+    name       TEXT NOT NULL,
+    comment    TEXT,
+    is_public  INTEGER NOT NULL DEFAULT 0 CHECK (is_public IN (0, 1)),
+    created_at INTEGER,
+    updated_at INTEGER
+);
+
+-- Keyed by `(playlist, position)` rather than `(playlist, track)`: the
+-- same track may legitimately appear twice in one playlist, and a PK that
+-- forbade it would abort the apply pass on a perfectly valid server
+-- state.
+CREATE TABLE remote_playlist_track (
+    playlist_remote_id TEXT    NOT NULL
+                       REFERENCES remote_playlist(remote_id) ON DELETE CASCADE,
+    position           INTEGER NOT NULL CHECK (position >= 0),
+    track_remote_id    TEXT    NOT NULL,
+    PRIMARY KEY (playlist_remote_id, position)
+);
+
+CREATE INDEX idx_remote_playlist_track_track
+    ON remote_playlist_track (track_remote_id);
+
+-- `entity_type` is stored free-form ON PURPOSE, with no CHECK.
+--
+-- The server favourites `track`, `album` and `artist` today. A CHECK
+-- pinning that list would turn a future fourth kind into an aborted
+-- transaction — and per RFC-003 (server) an event the client cannot
+-- apply forces it to drop its projection and re-fetch a snapshot, whose
+-- replay would abort on the same row. That is an infinite recovery loop
+-- triggered by a forward-compatible server change. Storing the string
+-- and letting the UI ignore what it cannot render degrades instead.
+CREATE TABLE remote_favorite (
+    entity_type TEXT    NOT NULL,
+    entity_id   TEXT    NOT NULL,
+    starred_at  INTEGER NOT NULL,
+    PRIMARY KEY (entity_type, entity_id)
+);
+
+-- `rating` is constrained to 1..5 because a stored row means "this has a
+-- rating": the wire protocol uses 0 as a CLEAR instruction, which the
+-- apply path turns into a DELETE rather than a stored zero.
+--
+-- Unlike `entity_type` above, this CHECK is safe: the apply path clamps
+-- the incoming value into range before binding it, so the constraint can
+-- only fire on a bug in our own code — which is precisely what a CHECK is
+-- for. An out-of-range value from the server degrades to a clamp, not to
+-- an aborted transaction.
+CREATE TABLE remote_rating (
+    entity_type TEXT    NOT NULL,
+    entity_id   TEXT    NOT NULL,
+    rating      INTEGER NOT NULL CHECK (rating BETWEEN 1 AND 5),
+    updated_at  INTEGER NOT NULL,
+    PRIMARY KEY (entity_type, entity_id)
+);
+
+-- Keyed by `(track, played_at)` — the natural key — rather than by the
+-- scrobble's own identifier.
+--
+-- The reason is a genuine asymmetry in the server contract: a `scrobble`
+-- event on `/sync/changes` carries an `entity_id`, but `snapshot.history[]`
+-- carries only `{track_id, submission, played_at}` with no identifier at
+-- all. A table keyed on the event identifier could therefore not be
+-- populated from a snapshot, and the same scrobble would land twice —
+-- once anonymously from the snapshot, once identified from a later event.
+-- The natural key is present in both shapes, so it is the one that
+-- converges.
+CREATE TABLE remote_history (
+    track_remote_id TEXT    NOT NULL,
+    played_at       INTEGER NOT NULL,
+    submission      INTEGER NOT NULL CHECK (submission IN (0, 1)),
+    PRIMARY KEY (track_remote_id, played_at)
+);
+
+CREATE INDEX idx_remote_history_played_at
+    ON remote_history (played_at DESC);
+
+-- The account's saved queue: one row, same `CHECK (id = 1)` pin as the
+-- binding. Its tracks live in a sibling table so ordering survives
+-- without a serialized blob.
+CREATE TABLE remote_queue (
+    id                INTEGER PRIMARY KEY CHECK (id = 1),
+    current_remote_id TEXT,
+    position_ms       INTEGER NOT NULL DEFAULT 0 CHECK (position_ms >= 0),
+    -- Which client last saved the queue. Purely informational — it is
+    -- what lets the UI say "paused on your phone" instead of pretending
+    -- the position came from here.
+    changed_by        TEXT,
+    updated_at        INTEGER NOT NULL
+);
+
+CREATE TABLE remote_queue_track (
+    position        INTEGER PRIMARY KEY CHECK (position >= 0),
+    track_remote_id TEXT NOT NULL
+);
+
+-- Non-secret share fields only. The journal never carries the bearer
+-- token or the public URL (RFC-003 server, §changes table), so a share
+-- created on another device arrives here WITHOUT a usable link — and it
+-- cannot be derived locally, since the token is keyed on a server-side
+-- instance secret.
+--
+-- `url` is therefore populated only for shares this install created, from
+-- the POST response. It is a bearer capability: anyone holding it can
+-- read the share, which puts it at the same trust level as the access
+-- token already stored in `auth_credential`.
+CREATE TABLE remote_share (
+    remote_id   TEXT PRIMARY KEY,
+    description TEXT,
+    expires_at  INTEGER,
+    visit_count INTEGER NOT NULL DEFAULT 0 CHECK (visit_count >= 0),
+    url         TEXT,
+    created_at  INTEGER,
+    updated_at  INTEGER
+);
+
+CREATE TABLE remote_share_track (
+    share_remote_id TEXT    NOT NULL
+                    REFERENCES remote_share(remote_id) ON DELETE CASCADE,
+    position        INTEGER NOT NULL CHECK (position >= 0),
+    track_remote_id TEXT    NOT NULL,
+    PRIMARY KEY (share_remote_id, position)
+);
+
+-- =============================================================================
+-- 3. Outbound queue
+-- =============================================================================
+--
+-- Replayable business mutations, not generic ops: each row is one REST
+-- call the drain re-issues verbatim under its `operation_id`, which the
+-- server reads from `X-WaveFlow-Operation-Id` to recognize a replay.
+--
+-- `operation_id` is UNIQUE and IMMUTABLE. The server stores a canonical
+-- fingerprint of the action, target and normalized payload; presenting
+-- the same identifier with a different fingerprint is rejected as a
+-- conflict, not accepted as a replay. So a user who corrects a gesture
+-- before the queue drains (renaming an already-queued playlist) needs a
+-- NEW identifier — either a second row, or a merge performed before
+-- enqueueing that regenerates the id. Updating `payload` in place while
+-- keeping `operation_id` is the one thing this table must never do.
+--
+-- `AUTOINCREMENT` for the reason the v1 queue documented: without it
+-- SQLite reuses rowids after deletes, so a drain tracking a
+-- last-processed high-water mark would silently skip rows appended after
+-- the queue fully drained.
+--
+-- `failed_at` marks a PERMANENT failure. The server answers 422
+-- `validation_error` both for a malformed payload and for an
+-- operation-id conflict; neither can succeed on retry, so the row stops
+-- being attempted and is surfaced to the user instead of spinning
+-- forever. Only 5xx, 429 and transport errors keep their retry.
+CREATE TABLE remote_mutation (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    operation_id    TEXT    NOT NULL UNIQUE,
+    kind            TEXT    NOT NULL,
+    payload         TEXT    NOT NULL,
+    created_at      INTEGER NOT NULL,
+    attempt_count   INTEGER NOT NULL DEFAULT 0 CHECK (attempt_count >= 0),
+    last_attempt_at INTEGER,
+    last_error      TEXT,
+    failed_at       INTEGER
+);
+
+-- The drain walks pending rows in FIFO order; the partial index keeps
+-- permanently-failed rows out of that scan while leaving them readable
+-- for the diagnostics surface.
+CREATE INDEX idx_remote_mutation_pending
+    ON remote_mutation (id) WHERE failed_at IS NULL;

From 7ce6802cc2ef095071591a81447366c30e4ea949 Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Mon, 10 Aug 2026 15:35:36 +0200
Subject: [PATCH 03/14] feat(remote): sign in through the browser with
 authorization code + PKCE

Binds a profile to a native server: probe the URL, run the handshake in
the system browser, exchange the code, and store the session. Adds the
five commands the Settings card will need and their typed wrappers. No
UI is mounted yet -- the feature is off by default, and a card that
cannot work in a stock build is worse than no card.

Driven end to end against a live server rather than inferred from the
spec, which corrected two things. The redirect URI is compared as a
string at redemption, so changing only the port answers 401 even though
shape validation ignores it; the listener therefore binds first and the
URI is built once from the port obtained, making the two identical by
construction. And the device name is capped at 120 bytes server-side, so
a long hostname is truncated on a character boundary rather than failing
the sign-in for a reason no user could guess.

The same run confirmed the traps worth keeping in the docs: a wrong
verifier burns the code, and presenting the correct one afterwards still
fails; the refresh token rotates while the device survives it.

Signing out and forgetting a server are deliberately different. Signing
out drops the credentials only, so the cached library stays readable and
a later sign-in resumes from its cursor. Forgetting drops the binding,
the projection and any write that never left the machine -- and binding
to a different account does the same, because a cursor is a position in
that account's journal and a queued mutation names that account's
resources.

Claude-Session: https://claude.ai/code/session_01N9WXrurarkoiT2jgimvyj1
---
 .../rfcs/RFC-005-remote-source-and-sync-v2.md |  26 +-
 src-tauri/crates/app/src/commands/mod.rs      |   4 +
 .../crates/app/src/commands/remote_auth.rs    | 160 ++++++
 src-tauri/crates/app/src/lib.rs               |  10 +
 src-tauri/crates/app/src/remote/auth.rs       | 485 ++++++++++++++++++
 src-tauri/crates/app/src/remote/binding.rs    | 113 +++-
 src-tauri/crates/app/src/remote/mod.rs        |   5 +
 src/lib/tauri/remoteServer.ts                 | 100 ++++
 8 files changed, 899 insertions(+), 4 deletions(-)
 create mode 100644 src-tauri/crates/app/src/commands/remote_auth.rs
 create mode 100644 src-tauri/crates/app/src/remote/auth.rs
 create mode 100644 src/lib/tauri/remoteServer.ts

diff --git a/docs/rfcs/RFC-005-remote-source-and-sync-v2.md b/docs/rfcs/RFC-005-remote-source-and-sync-v2.md
index b7d857c1..46a4e8cc 100644
--- a/docs/rfcs/RFC-005-remote-source-and-sync-v2.md
+++ b/docs/rfcs/RFC-005-remote-source-and-sync-v2.md
@@ -120,9 +120,29 @@ then exchanges `code` + `code_verifier` at `/api/v2/oauth/token`.
 The loopback listener and the random generator already exist for another
 provider; only the protocol changes.
 
-> **Verified trap.** A code is **spent on first presentation**, whatever the
-> outcome. A wrong verifier burns it. Retrying the same code is not a recovery
-> path — the flow restarts from the beginning.
+Three details, all measured against a live server rather than inferred:
+
+> **A code is spent on first presentation**, whatever the outcome. Redeeming
+> with a wrong verifier burns it — presenting the *correct* verifier afterwards
+> still answers 401. Retrying a code is not a recovery path; the flow restarts
+> from the beginning.
+
+> **The redirect URI is compared as a string at redemption.** Shape validation
+> ignores the port, as RFC 8252 §7.3 asks, but the token endpoint compares the
+> grant's URI with the presented one byte for byte — changing only the port
+> answers 401. Binding the loopback listener *first* and building the URI once
+> from the port obtained makes the two identical by construction.
+
+> **The refresh token rotates and the device survives it.** A refresh returns a
+> new refresh token, the old one answers 401, and `device_id` is echoed back
+> unchanged. So a rotation never invalidates queued mutations, and the
+> device-adoption branch in the client is defensive, not routine.
+
+Worth recording as an observation rather than a decision: `/oauth/authorize`
+authenticates with a **Bearer header**, not a browser cookie, so the consent
+step is technically reachable without a browser at all. We still go through the
+browser — it is what keeps the account password out of the desktop process —
+but that is a deliberate choice, not a constraint the server imposes.
 
 A third-party server authenticates by username/password, token/salt or API key
 instead. That is a second authentication shape to carry, not a degraded first.
diff --git a/src-tauri/crates/app/src/commands/mod.rs b/src-tauri/crates/app/src/commands/mod.rs
index 86bf296b..e7354e4a 100644
--- a/src-tauri/crates/app/src/commands/mod.rs
+++ b/src-tauri/crates/app/src/commands/mod.rs
@@ -39,6 +39,10 @@ pub mod preferences;
 pub mod profile;
 pub mod profile_io;
 pub mod radio;
+// Remote server binding + PKCE sign-in (RFC-005). Gated on `sync_v2`,
+// which is off by default while the slices land.
+#[cfg(feature = "sync_v2")]
+pub mod remote_auth;
 pub mod scan;
 // Server account binding (Better Auth JWT capture + URL persistence)
 // — deferred to 1.6.0. See `sync_stub.rs` / `Cargo.toml`.
diff --git a/src-tauri/crates/app/src/commands/remote_auth.rs b/src-tauri/crates/app/src/commands/remote_auth.rs
new file mode 100644
index 00000000..b9bce83f
--- /dev/null
+++ b/src-tauri/crates/app/src/commands/remote_auth.rs
@@ -0,0 +1,160 @@
+//! Tauri commands for binding a profile to a remote server (RFC-005).
+//!
+//! Deliberately small: identifying a server, signing in, and the two
+//! ways of undoing that. Everything the projection does sits behind the
+//! binding these commands establish.
+//!
+//! ## Two ways out, because they are not the same intent
+//!
+//! [`remote_sign_out`] drops the credentials only. The binding and the
+//! projection survive, so the cached remote library stays readable and
+//! signing back into the same account resumes from its cursor.
+//!
+//! [`remote_forget_server`] drops everything, pending writes included.
+//! That is the destructive one, and the UI must present it as such.
+
+use serde::Serialize;
+
+use crate::{
+    error::{AppError, AppResult},
+    remote::{
+        auth,
+        binding::{self, RemoteIdentity},
+        probe::{self, ServerFlavour},
+        tokens,
+    },
+    state::AppState,
+};
+
+/// What the Settings card renders. One round-trip rather than a chain
+/// of `getUrl` + `isSignedIn` calls.
+#[derive(Debug, Clone, Serialize)]
+pub struct RemoteStatus {
+    /// `None` means this profile is local-only, which is the normal
+    /// state, not a fault.
+    pub server_url: Option<String>,
+    /// `"waveflow"` or `"subsonic"`, absent when unbound.
+    pub flavour: Option<String>,
+    /// The signed-in account's name, when we know it.
+    pub username: Option<String>,
+    /// Whether usable credentials exist. Does not prove the server still
+    /// accepts them — that is one HTTP round-trip away and belongs to
+    /// whoever needs the fresher signal.
+    pub signed_in: bool,
+    /// Whether a first snapshot has ever been applied. Distinguishes an
+    /// empty account from a bootstrap that never ran.
+    pub bootstrapped: bool,
+}
+
+/// What a probe found, before any credential is asked for.
+#[derive(Debug, Clone, Serialize)]
+pub struct RemoteProbeResult {
+    pub flavour: String,
+    /// Whatever the server calls itself, kept verbatim for display.
+    pub server_type: Option<String>,
+    pub server_version: Option<String>,
+    /// Whether the journal, per-device acknowledgement and mutation
+    /// idempotency exist here.
+    pub supports_sync: bool,
+}
+
+#[tauri::command]
+pub async fn remote_get_status(state: tauri::State<'_, AppState>) -> AppResult<RemoteStatus> {
+    status(&state).await
+}
+
+/// Identify the server behind a URL without signing in.
+///
+/// Useful before the user commits to anything: a native server signs in
+/// through the browser, a third-party one with a username and password,
+/// and telling them apart afterwards would mean showing the wrong form
+/// first.
+#[tauri::command]
+pub async fn remote_detect_server(url: String) -> AppResult<RemoteProbeResult> {
+    let flavour = probe::detect(url.trim()).await?;
+    Ok(match flavour {
+        ServerFlavour::Waveflow { server_version } => RemoteProbeResult {
+            flavour: "waveflow".into(),
+            server_type: Some("waveflow".into()),
+            server_version,
+            supports_sync: true,
+        },
+        ServerFlavour::Subsonic {
+            server_type,
+            server_version,
+        } => RemoteProbeResult {
+            flavour: "subsonic".into(),
+            server_type,
+            server_version,
+            supports_sync: false,
+        },
+    })
+}
+
+/// Run the browser handshake and bind the active profile.
+///
+/// Blocks for as long as the user takes to consent, up to three minutes.
+/// The frontend should show this as a pending state rather than an
+/// unresponsive one.
+#[tauri::command]
+pub async fn remote_begin_login(
+    state: tauri::State<'_, AppState>,
+    url: String,
+) -> AppResult<RemoteStatus> {
+    auth::begin_login(&state, &url).await?;
+    status(&state).await
+}
+
+/// Drop the credentials, keep everything else.
+#[tauri::command]
+pub async fn remote_sign_out(state: tauri::State<'_, AppState>) -> AppResult<RemoteStatus> {
+    auth::sign_out(&state).await?;
+    status(&state).await
+}
+
+/// Drop the credentials, the binding, the projection and every write
+/// that never reached the server.
+#[tauri::command]
+pub async fn remote_forget_server(state: tauri::State<'_, AppState>) -> AppResult<RemoteStatus> {
+    auth::forget_server(&state).await?;
+    status(&state).await
+}
+
+async fn status(state: &AppState) -> AppResult<RemoteStatus> {
+    // No active profile is a legitimate state here — the onboarding
+    // screens can query this before one exists — so it answers "unbound"
+    // rather than failing. Anything else is a real fault and propagates.
+    let pool = match state.require_profile_pool().await {
+        Ok(pool) => pool,
+        Err(AppError::NoActiveProfile) => {
+            return Ok(RemoteStatus {
+                server_url: None,
+                flavour: None,
+                username: None,
+                signed_in: false,
+                bootstrapped: false,
+            })
+        }
+        Err(err) => return Err(err),
+    };
+    let mut conn = pool.acquire().await?;
+
+    let binding = binding::read(&mut conn).await?;
+    let credentials = tokens::read(&mut conn).await?;
+
+    Ok(RemoteStatus {
+        server_url: binding.as_ref().map(|b| b.server_url.clone()),
+        flavour: binding.as_ref().map(|b| b.identity.flavour().to_string()),
+        username: credentials
+            .as_ref()
+            .and_then(|c| c.username.clone())
+            .or_else(|| match binding.as_ref().map(|b| &b.identity) {
+                Some(RemoteIdentity::Subsonic { username }) => Some(username.clone()),
+                _ => None,
+            }),
+        signed_in: credentials.is_some(),
+        bootstrapped: binding
+            .as_ref()
+            .is_some_and(|b| b.bootstrapped_at.is_some()),
+    })
+}
diff --git a/src-tauri/crates/app/src/lib.rs b/src-tauri/crates/app/src/lib.rs
index 634920e2..5f972575 100644
--- a/src-tauri/crates/app/src/lib.rs
+++ b/src-tauri/crates/app/src/lib.rs
@@ -753,6 +753,16 @@ pub fn run() {
             commands::spotify::spotify_get_queue,
             commands::spotify::spotify_search,
             commands::spotify::spotify_pause_local,
+            #[cfg(feature = "sync_v2")]
+            commands::remote_auth::remote_get_status,
+            #[cfg(feature = "sync_v2")]
+            commands::remote_auth::remote_detect_server,
+            #[cfg(feature = "sync_v2")]
+            commands::remote_auth::remote_begin_login,
+            #[cfg(feature = "sync_v2")]
+            commands::remote_auth::remote_sign_out,
+            #[cfg(feature = "sync_v2")]
+            commands::remote_auth::remote_forget_server,
             #[cfg(feature = "sync_v1")]
             commands::server_auth::server_get_status,
             #[cfg(feature = "sync_v1")]
diff --git a/src-tauri/crates/app/src/remote/auth.rs b/src-tauri/crates/app/src/remote/auth.rs
new file mode 100644
index 00000000..3d79b17e
--- /dev/null
+++ b/src-tauri/crates/app/src/remote/auth.rs
@@ -0,0 +1,485 @@
+//! Authorization Code + PKCE against a native server.
+//!
+//! The desktop is a public client — it ships no secret a user could not
+//! extract — so PKCE is what binds an authorization code to the running
+//! instance that asked for it (RFC 7636). The consent screen is a route
+//! of the server's own web client, which is why granting happens in the
+//! system browser rather than in a window we control.
+//!
+//! ```text
+//! bind 127.0.0.1:0  ──▶ port
+//!         │
+//! open <server>/authorize?client_id&redirect_uri&code_challenge&state&device_name
+//!         │                       (browser session authenticates + consents)
+//!         ▼
+//! 127.0.0.1:<port>/wf/callback?code=…&state=…
+//!         │
+//! POST /api/v2/oauth/token {client_id, code, code_verifier, redirect_uri}
+//!         ▼
+//! access + refresh + device_id + account
+//! ```
+//!
+//! ## Verified trap: a code is spent on first presentation
+//!
+//! Whatever the outcome. A wrong verifier burns it, and retrying the
+//! same code is not a recovery path — the flow restarts from the
+//! beginning. Nothing here retries an exchange.
+//!
+//! ## The port is ephemeral, and the URI is built exactly once
+//!
+//! RFC 8252 §7.3 tells a server not to pin the port of a loopback
+//! redirect, and this one does not: it validates the *shape* — loopback
+//! host, no fragment — and accepts any port. A fixed port would buy
+//! nothing in exchange for two failure modes: anything else already
+//! holding it makes sign-in impossible, and two sign-ins started at once
+//! collide.
+//!
+//! But redemption is stricter than validation. The token endpoint
+//! compares the grant's redirect URI with the one presented **as
+//! strings** — measured against a live server, changing only the port
+//! answers 401. So the value sent to `/authorize` and the value sent to
+//! `/oauth/token` must be byte-identical. Binding first and building the
+//! URI once, from the port we actually got, makes that true by
+//! construction rather than by discipline.
+
+use std::time::Duration;
+
+use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine};
+use serde::Deserialize;
+use sha2::{Digest, Sha256};
+use tiny_http::Server;
+
+use crate::{
+    commands::loopback::html_response,
+    error::{AppError, AppResult},
+    offline,
+    remote::{
+        binding::{self, RemoteBinding, RemoteIdentity},
+        client::AuthTokensResponse,
+        probe::{self, ServerFlavour},
+        tokens::{self, TokenPair},
+    },
+    state::AppState,
+};
+
+/// How we name ourselves to the server. Shown on the consent screen and
+/// stored with the grant, so it has to be recognisable to a human.
+const CLIENT_ID: &str = "waveflow-desktop";
+
+/// Path the browser is redirected back to. Only the port varies.
+const CALLBACK_PATH: &str = "/wf/callback";
+
+/// Long enough to find a password manager, short enough that a
+/// forgotten tab does not hold the listener open forever.
+const CALLBACK_TIMEOUT: Duration = Duration::from_secs(180);
+
+const EXCHANGE_TIMEOUT: Duration = Duration::from_secs(30);
+
+/// What the browser came back with.
+#[derive(Debug, Deserialize)]
+struct CallbackQuery {
+    code: Option<String>,
+    state: Option<String>,
+    error: Option<String>,
+}
+
+/// The S256 challenge for a verifier: `base64url(sha256(verifier))`.
+///
+/// The same four lines exist in the Spotify integration. They are not
+/// shared: that crate is a leaf about one third-party service, and
+/// reaching into it from here for a hash helper would read as a
+/// dependency that means something it does not.
+fn pkce_challenge(verifier: &str) -> String {
+    URL_SAFE_NO_PAD.encode(Sha256::digest(verifier.as_bytes()))
+}
+
+/// 256 bits as 64 hex characters — inside the 43..=128 the server
+/// accepts, with no encoding subtleties to get wrong.
+fn random_token() -> String {
+    format!(
+        "{}{}",
+        uuid::Uuid::new_v4().simple(),
+        uuid::Uuid::new_v4().simple()
+    )
+}
+
+/// Run the whole handshake and bind the active profile to the server.
+///
+/// Returns the identity that was established. Any failure leaves the
+/// previous binding untouched: nothing is written until the exchange has
+/// succeeded.
+pub async fn begin_login(state: &AppState, server_url: &str) -> AppResult<RemoteBinding> {
+    if offline::is_offline() {
+        return Err(AppError::Other(
+            "offline mode is on; turn it off to sign in".into(),
+        ));
+    }
+
+    let server_url = server_url.trim().trim_end_matches('/').to_string();
+    let parsed = url::Url::parse(&server_url)
+        .map_err(|err| AppError::Other(format!("invalid server URL: {err}")))?;
+    if !matches!(parsed.scheme(), "http" | "https") {
+        return Err(AppError::Other("server URL must use http or https".into()));
+    }
+
+    // Refuse early rather than after sending the user to a consent
+    // screen that does not exist.
+    match probe::detect(&server_url).await? {
+        ServerFlavour::Waveflow { .. } => {}
+        ServerFlavour::Subsonic { server_type, .. } => {
+            let name = server_type.unwrap_or_else(|| "this server".into());
+            return Err(AppError::Other(format!(
+                "{name} speaks the Subsonic protocol, which signs in with a username \
+                 and password rather than through the browser"
+            )));
+        }
+    }
+
+    // Bind before anything else: the redirect URI has to carry the port
+    // we actually got, and binding first also removes the race where a
+    // fast browser reaches the callback before the listener is up.
+    let server = Server::http("127.0.0.1:0").map_err(|err| {
+        AppError::Other(format!("could not open a local port for sign-in: {err}"))
+    })?;
+    let port = server
+        .server_addr()
+        .to_ip()
+        .ok_or_else(|| AppError::Other("local sign-in listener has no IP address".into()))?
+        .port();
+    let redirect_uri = format!("http://127.0.0.1:{port}{CALLBACK_PATH}");
+
+    let verifier = random_token();
+    let challenge = pkce_challenge(&verifier);
+    let csrf_state = random_token();
+
+    let device_name = device_name();
+    let authorize_url = format!(
+        "{server_url}/authorize?{}",
+        url::form_urlencoded::Serializer::new(String::new())
+            .append_pair("client_id", CLIENT_ID)
+            .append_pair("redirect_uri", &redirect_uri)
+            .append_pair("code_challenge", &challenge)
+            .append_pair("code_challenge_method", "S256")
+            .append_pair("state", &csrf_state)
+            .append_pair("device_name", &device_name)
+            .finish()
+    );
+
+    let expected_state = csrf_state.clone();
+    let callback =
+        tauri::async_runtime::spawn_blocking(move || wait_for_code(server, &expected_state));
+
+    tauri_plugin_opener::open_url(authorize_url, None::<&str>)
+        .map_err(|err| AppError::Other(format!("could not open the browser: {err}")))?;
+
+    let code = callback
+        .await
+        .map_err(|err| AppError::Other(format!("sign-in listener failed: {err}")))??;
+
+    let tokens = exchange_code(&server_url, &code, &verifier, &redirect_uri).await?;
+
+    persist_session(state, &server_url, tokens).await
+}
+
+/// The server rejects a device name longer than this, and it does so at
+/// `/authorize` — which would fail the sign-in for a reason the user
+/// could not possibly guess from a machine name.
+const MAX_DEVICE_NAME: usize = 120;
+
+/// How this install identifies itself in the account's device list.
+/// The machine's hostname is what a user will recognise; falling back to
+/// a generic label is better than failing the sign-in over it.
+fn device_name() -> String {
+    let name = match hostname() {
+        Some(host) if !host.trim().is_empty() => format!("WaveFlow on {host}"),
+        _ => "WaveFlow Desktop".to_string(),
+    };
+    truncate_device_name(name)
+}
+
+/// Truncate on a character boundary — the server counts bytes, and a
+/// hostname may hold multi-byte characters.
+fn truncate_device_name(mut name: String) -> String {
+    if name.len() <= MAX_DEVICE_NAME {
+        return name;
+    }
+    let mut end = MAX_DEVICE_NAME;
+    while end > 0 && !name.is_char_boundary(end) {
+        end -= 1;
+    }
+    name.truncate(end);
+    name
+}
+
+fn hostname() -> Option<String> {
+    std::env::var("HOSTNAME")
+        .ok()
+        .or_else(|| std::env::var("COMPUTERNAME").ok())
+        .or_else(|| {
+            std::fs::read_to_string("/etc/hostname")
+                .ok()
+                .map(|value| value.trim().to_string())
+        })
+        .filter(|value| !value.is_empty())
+}
+
+/// Block until the browser hits the callback, and hand back the code.
+fn wait_for_code(server: Server, expected_state: &str) -> AppResult<String> {
+    let request = server
+        .recv_timeout(CALLBACK_TIMEOUT)
+        .map_err(|err| AppError::Other(format!("sign-in callback failed: {err}")))?
+        .ok_or_else(|| AppError::Other("sign-in timed out — try again".into()))?;
+
+    let url = request.url().to_string();
+    let query = url.split_once('?').map(|(_, q)| q).unwrap_or("");
+    let parsed = serde_urlencoded::from_str::<CallbackQuery>(query)
+        .map_err(|err| AppError::Other(format!("could not read the callback: {err}")))?;
+
+    match (parsed.code, parsed.error, parsed.state.as_deref()) {
+        // `error` absent is part of the success condition on purpose:
+        // accepting a code that arrived alongside an error claim would
+        // mask a protocol change instead of failing on it.
+        (Some(code), None, state) if state == Some(expected_state) => {
+            let _ = request.respond(html_response(
+                "<!doctype html><title>WaveFlow</title>\
+                 <p>Signed in. You can close this tab and return to WaveFlow.</p>",
+            ));
+            Ok(code)
+        }
+        (_, Some(error), _) => {
+            let _ = request.respond(html_response(
+                "<!doctype html><title>WaveFlow</title>\
+                 <p>Sign-in was cancelled.</p>",
+            ));
+            // The consent screen's Deny button sends exactly this.
+            if error == "access_denied" {
+                Err(AppError::Other("sign-in was declined".into()))
+            } else {
+                Err(AppError::Other(format!("sign-in failed: {error}")))
+            }
+        }
+        _ => {
+            let _ = request.respond(html_response(
+                "<!doctype html><title>WaveFlow</title>\
+                 <p>Sign-in failed: the reply did not match this request. \
+                 Start again from WaveFlow.</p>",
+            ));
+            Err(AppError::Other(
+                "sign-in reply did not match this request (state mismatch)".into(),
+            ))
+        }
+    }
+}
+
+/// Redeem the code. One attempt, by contract — see the module docs.
+async fn exchange_code(
+    server_url: &str,
+    code: &str,
+    verifier: &str,
+    redirect_uri: &str,
+) -> AppResult<AuthTokensResponse> {
+    let http = reqwest::Client::builder()
+        .timeout(EXCHANGE_TIMEOUT)
+        .build()
+        .map_err(|err| AppError::Other(format!("http client init: {err}")))?;
+
+    let response = http
+        .post(format!("{server_url}/api/v2/oauth/token"))
+        // No device name here: it belongs to the grant, which the
+        // consent screen already created from the `/authorize` query.
+        // Repeating it at redemption would be a field the token request
+        // does not define.
+        .json(&serde_json::json!({
+            "client_id": CLIENT_ID,
+            "code": code,
+            "code_verifier": verifier,
+            "redirect_uri": redirect_uri,
+        }))
+        .send()
+        .await
+        .map_err(|err| AppError::Other(format!("could not reach the server: {err}")))?;
+
+    let status = response.status();
+    if !status.is_success() {
+        return Err(AppError::Other(format!(
+            "the server refused the sign-in ({status})"
+        )));
+    }
+
+    response
+        .json::<AuthTokensResponse>()
+        .await
+        .map_err(|err| AppError::Other(format!("unexpected sign-in reply: {err}")))
+}
+
+/// Store the session, and decide what the previous one leaves behind.
+///
+/// Binding to a **different account** discards the projection and the
+/// pending queue in the same transaction as the new binding. Both belong
+/// to the account that produced them: a cursor is a position in that
+/// account's journal, and a queued mutation names that account's
+/// resources. Replaying either against a new account would apply one
+/// user's edits to another's library.
+///
+/// Signing back into the **same** account keeps both, which is what
+/// makes a re-authentication after an expired session cheap: the cursor
+/// resumes and offline writes survive.
+async fn persist_session(
+    state: &AppState,
+    server_url: &str,
+    tokens: AuthTokensResponse,
+) -> AppResult<RemoteBinding> {
+    let profile_id = state.require_profile_id().await?;
+    let pool = state.require_profile_pool_for(Some(profile_id)).await?;
+    let mut tx = pool.begin().await?;
+
+    let previous = binding::read(&mut tx).await?;
+    let same_account = matches!(
+        previous.as_ref().map(|b| &b.identity),
+        Some(RemoteIdentity::Waveflow { account_id, .. }) if account_id == &tokens.user.id
+    );
+
+    if !same_account {
+        binding::clear_account_state(&mut tx).await?;
+    }
+
+    let binding = RemoteBinding {
+        server_url: server_url.to_string(),
+        identity: RemoteIdentity::Waveflow {
+            account_id: tokens.user.id.clone(),
+            device_id: tokens.device_id.clone(),
+            cursor: if same_account {
+                previous
+                    .as_ref()
+                    .and_then(|b| b.identity.cursor())
+                    .unwrap_or(0)
+            } else {
+                0
+            },
+        },
+        active_library_id: if same_account {
+            previous.as_ref().and_then(|b| b.active_library_id.clone())
+        } else {
+            None
+        },
+        bootstrapped_at: if same_account {
+            previous.as_ref().and_then(|b| b.bootstrapped_at)
+        } else {
+            None
+        },
+    };
+    binding::write(&mut tx, &binding).await?;
+
+    tokens::write(
+        &mut tx,
+        &TokenPair {
+            access_token: tokens.access_token,
+            refresh_token: tokens.refresh_token,
+            expires_at: tokens::deadline_from_expires_in(tokens.expires_in),
+            username: Some(tokens.user.username),
+        },
+    )
+    .await?;
+
+    tx.commit().await?;
+    Ok(binding)
+}
+
+/// Sign out without forgetting the server.
+///
+/// Drops the credentials and nothing else. The binding survives, so the
+/// projection stays readable and a later sign-in to the same account
+/// resumes from its cursor instead of re-downloading everything. Use
+/// [`forget_server`] for the destructive version.
+pub async fn sign_out(state: &AppState) -> AppResult<()> {
+    let profile_id = state.require_profile_id().await?;
+    let pool = state.require_profile_pool_for(Some(profile_id)).await?;
+    let mut conn = pool.acquire().await?;
+    tokens::clear(&mut conn).await
+}
+
+/// Forget the server entirely: credentials, binding, projection and any
+/// write that never made it out. One transaction — a half-forgotten
+/// server is worse than either state.
+pub async fn forget_server(state: &AppState) -> AppResult<()> {
+    let profile_id = state.require_profile_id().await?;
+    let pool = state.require_profile_pool_for(Some(profile_id)).await?;
+    let mut tx = pool.begin().await?;
+    tokens::clear(&mut tx).await?;
+    binding::clear_account_state(&mut tx).await?;
+    binding::clear(&mut tx).await?;
+    tx.commit().await?;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn the_challenge_is_what_the_server_will_accept() {
+        // The server validates canonically: exactly 43 characters of
+        // base64url decoding to a 32-byte digest. Anything else is
+        // rejected before a grant is issued.
+        let verifier = random_token();
+        let challenge = pkce_challenge(&verifier);
+        assert_eq!(challenge.len(), 43);
+        assert_eq!(URL_SAFE_NO_PAD.decode(&challenge).unwrap().len(), 32);
+        assert!(!challenge.contains('+') && !challenge.contains('/') && !challenge.contains('='));
+    }
+
+    #[test]
+    fn the_verifier_sits_inside_the_length_the_server_allows() {
+        let verifier = random_token();
+        assert_eq!(verifier.len(), 64);
+        assert!((43..=128).contains(&verifier.len()));
+    }
+
+    #[test]
+    fn each_handshake_draws_fresh_secrets() {
+        assert_ne!(random_token(), random_token());
+    }
+
+    #[test]
+    fn a_known_verifier_hashes_to_its_known_challenge() {
+        // Pinned against the RFC 7636 appendix B vector, so a future
+        // change of encoder or digest cannot pass silently.
+        assert_eq!(
+            pkce_challenge("dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"),
+            "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
+        );
+    }
+
+    #[test]
+    fn the_device_name_never_comes_back_empty() {
+        // It is sent on every sign-in and the server rejects an empty
+        // one, so the fallback matters more than the hostname does.
+        let name = device_name();
+        assert!(!name.trim().is_empty());
+        assert!(name.len() <= MAX_DEVICE_NAME);
+    }
+
+    #[test]
+    fn a_long_hostname_is_trimmed_rather_than_failing_the_sign_in() {
+        let name = truncate_device_name(format!("WaveFlow on {}", "h".repeat(400)));
+        assert_eq!(name.len(), MAX_DEVICE_NAME);
+    }
+
+    #[test]
+    fn truncation_lands_on_a_character_boundary() {
+        // The server counts bytes; a hostname may not be ASCII. Cutting
+        // mid-character would produce invalid UTF-8 and panic on
+        // `truncate`.
+        let name = truncate_device_name(format!("WaveFlow on {}", "é".repeat(200)));
+        assert!(name.len() <= MAX_DEVICE_NAME);
+        assert!(name.chars().next_back().is_some());
+    }
+
+    #[test]
+    fn a_short_name_is_left_alone() {
+        assert_eq!(
+            truncate_device_name("WaveFlow on nas".into()),
+            "WaveFlow on nas"
+        );
+    }
+}
diff --git a/src-tauri/crates/app/src/remote/binding.rs b/src-tauri/crates/app/src/remote/binding.rs
index aa1c9d9d..74bc4af6 100644
--- a/src-tauri/crates/app/src/remote/binding.rs
+++ b/src-tauri/crates/app/src/remote/binding.rs
@@ -230,7 +230,7 @@ pub async fn mark_bootstrapped(conn: &mut SqliteConnection, cursor: i64) -> AppR
     Ok(())
 }
 
-/// Drop the binding. Leaves the projection and the outbound queue
+/// Drop the binding row. Leaves the projection and the outbound queue
 /// alone — the caller decides whether unbinding also discards pending
 /// writes, which is a user-visible choice, not a storage detail.
 pub async fn clear(conn: &mut SqliteConnection) -> AppResult<()> {
@@ -240,6 +240,42 @@ pub async fn clear(conn: &mut SqliteConnection) -> AppResult<()> {
     Ok(())
 }
 
+/// Discard everything that belongs to one account: the whole projection
+/// and every write that never reached the server.
+///
+/// Both are account-scoped in a way that makes carrying them over
+/// actively harmful, not merely stale. A cursor is a position in *that*
+/// account's journal, and a queued mutation names *that* account's
+/// resources by identifier — replaying either against a different
+/// account would apply one user's edits to another's library.
+///
+/// Call this inside the same transaction as the new binding: a
+/// projection that outlives its account for even one commit is a state
+/// no reader can interpret.
+///
+/// The two child tables are dropped explicitly rather than left to
+/// `ON DELETE CASCADE`. The cascade only fires with `foreign_keys` on,
+/// which is a connection-level pragma — depending on it here would make
+/// correctness hinge on how the caller's connection happened to be
+/// configured.
+pub async fn clear_account_state(conn: &mut SqliteConnection) -> AppResult<()> {
+    for statement in [
+        "DELETE FROM remote_playlist_track",
+        "DELETE FROM remote_playlist",
+        "DELETE FROM remote_favorite",
+        "DELETE FROM remote_rating",
+        "DELETE FROM remote_history",
+        "DELETE FROM remote_queue_track",
+        "DELETE FROM remote_queue",
+        "DELETE FROM remote_share_track",
+        "DELETE FROM remote_share",
+        "DELETE FROM remote_mutation",
+    ] {
+        sqlx::query(statement).execute(&mut *conn).await?;
+    }
+    Ok(())
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -367,6 +403,81 @@ mod tests {
         assert_eq!(read(&mut conn).await.unwrap().unwrap().identity.cursor(), Some(0));
     }
 
+    #[tokio::test]
+    async fn clearing_account_state_empties_the_projection_and_the_queue() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+
+        sqlx::raw_sql(
+            "INSERT INTO remote_playlist (remote_id, name) VALUES ('p1', 'P');
+             INSERT INTO remote_playlist_track VALUES ('p1', 0, 't1');
+             INSERT INTO remote_favorite VALUES ('track', 't1', 1);
+             INSERT INTO remote_rating VALUES ('track', 't1', 4, 1);
+             INSERT INTO remote_history VALUES ('t1', 1000, 1);
+             INSERT INTO remote_queue (id, position_ms, updated_at) VALUES (1, 0, 1);
+             INSERT INTO remote_queue_track VALUES (0, 't1');
+             INSERT INTO remote_share (remote_id) VALUES ('s1');
+             INSERT INTO remote_share_track VALUES ('s1', 0, 't1');
+             INSERT INTO remote_mutation (operation_id, kind, payload, created_at)
+                VALUES ('op1', 'k', '{}', 0);",
+        )
+        .execute(&mut *conn)
+        .await
+        .unwrap();
+
+        clear_account_state(&mut conn).await.unwrap();
+
+        for table in [
+            "remote_playlist",
+            "remote_playlist_track",
+            "remote_favorite",
+            "remote_rating",
+            "remote_history",
+            "remote_queue",
+            "remote_queue_track",
+            "remote_share",
+            "remote_share_track",
+            "remote_mutation",
+        ] {
+            // `AssertSqlSafe` because the table name comes from the
+            // literal list above, never from input.
+            let count: i64 = sqlx::query_scalar(sqlx::AssertSqlSafe(format!(
+                "SELECT count(*) FROM {table}"
+            )))
+            .fetch_one(&mut *conn)
+            .await
+            .unwrap();
+            assert_eq!(count, 0, "{table} still holds rows");
+        }
+    }
+
+    #[tokio::test]
+    async fn clearing_account_state_does_not_depend_on_foreign_keys_being_on() {
+        // `foreign_keys` is a per-connection pragma, so a cascade would
+        // make this correctness depend on how the caller connected.
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        sqlx::raw_sql("PRAGMA foreign_keys = OFF")
+            .execute(&mut *conn)
+            .await
+            .unwrap();
+        sqlx::raw_sql(
+            "INSERT INTO remote_playlist (remote_id, name) VALUES ('p1', 'P');
+             INSERT INTO remote_playlist_track VALUES ('p1', 0, 't1');",
+        )
+        .execute(&mut *conn)
+        .await
+        .unwrap();
+
+        clear_account_state(&mut conn).await.unwrap();
+
+        let orphans: i64 = sqlx::query_scalar("SELECT count(*) FROM remote_playlist_track")
+            .fetch_one(&mut *conn)
+            .await
+            .unwrap();
+        assert_eq!(orphans, 0);
+    }
+
     #[tokio::test]
     async fn advancing_a_subsonic_binding_is_a_no_op() {
         let pool = pool().await;
diff --git a/src-tauri/crates/app/src/remote/mod.rs b/src-tauri/crates/app/src/remote/mod.rs
index 7b2da1da..08efc069 100644
--- a/src-tauri/crates/app/src/remote/mod.rs
+++ b/src-tauri/crates/app/src/remote/mod.rs
@@ -16,6 +16,10 @@
 //!
 //! ## Module map
 //!
+//! - [`auth`] — Authorization Code + PKCE in the system browser, and
+//!   the two ways out: sign out (credentials only) versus forget the
+//!   server (credentials, binding, projection and pending writes).
+//!
 //! - [`binding`] — which server this profile talks to and where it is
 //!   up to. Holds [`binding::RemoteIdentity`], the polymorphic identity
 //!   that keeps a third-party server from having to pretend it has an
@@ -49,6 +53,7 @@
 // `sync/mode.rs`. Drop this once the drain consumes the client.
 #![allow(dead_code)]
 
+pub mod auth;
 pub mod binding;
 pub mod client;
 pub mod probe;
diff --git a/src/lib/tauri/remoteServer.ts b/src/lib/tauri/remoteServer.ts
new file mode 100644
index 00000000..39582801
--- /dev/null
+++ b/src/lib/tauri/remoteServer.ts
@@ -0,0 +1,100 @@
+import { invoke } from "@tauri-apps/api/core";
+
+/**
+ * Binding between the active profile and a remote music server
+ * (RFC-005). Replaces the `serverAuth.ts` surface, which talks to a
+ * server generation that no longer exists.
+ *
+ * These commands only exist in a build with the `sync_v2` Cargo feature
+ * on, which is not the default while the slices land. Calling them
+ * against a stock build rejects with "command not found" — mount the UI
+ * behind the same switch rather than catching that at each call site.
+ */
+
+/** Which protocol the bound server speaks. */
+export type RemoteFlavour = "waveflow" | "subsonic";
+
+export interface RemoteStatus {
+  /** `null` means this profile is local-only — the normal state. */
+  server_url: string | null;
+  flavour: RemoteFlavour | null;
+  /** The signed-in account name, when known. */
+  username: string | null;
+  /**
+   * Usable credentials exist. Does NOT prove the server still accepts
+   * them; that costs a round-trip the UI rarely needs.
+   */
+  signed_in: boolean;
+  /**
+   * A first snapshot has been applied at least once. Tells an empty
+   * account apart from a bootstrap that never ran — without it the two
+   * render identically.
+   */
+  bootstrapped: boolean;
+}
+
+export interface RemoteProbeResult {
+  flavour: RemoteFlavour;
+  /** Whatever the server calls itself, verbatim, for display. */
+  server_type: string | null;
+  server_version: string | null;
+  /**
+   * Whether the journal, per-device acknowledgement and mutation
+   * idempotency exist here. Only a native server offers them.
+   */
+  supports_sync: boolean;
+}
+
+/** Snapshot the binding for the Settings card. */
+export function remoteGetStatus(): Promise<RemoteStatus> {
+  return invoke<RemoteStatus>("remote_get_status");
+}
+
+/**
+ * Identify a server without signing in.
+ *
+ * Worth doing before showing any form: a native server signs in through
+ * the browser, a third-party one with a username and password, and
+ * asking for the wrong one first is a dead end for the user. The probe
+ * needs no credentials — the server identifies itself even on a failed
+ * ping.
+ *
+ * Rejects when nothing at that URL answers like a music server.
+ */
+export function remoteDetectServer(url: string): Promise<RemoteProbeResult> {
+  return invoke<RemoteProbeResult>("remote_detect_server", { url });
+}
+
+/**
+ * Run the browser handshake (Authorization Code + PKCE) and bind the
+ * active profile.
+ *
+ * Resolves only once the user has consented in their browser, so this
+ * can sit pending for up to three minutes. Show it as pending, not as a
+ * frozen button.
+ *
+ * Rejects on refusal, timeout, or a reply that does not match the
+ * request. Each rejection carries a message meant to be shown as-is.
+ */
+export function remoteBeginLogin(url: string): Promise<RemoteStatus> {
+  return invoke<RemoteStatus>("remote_begin_login", { url });
+}
+
+/**
+ * Drop the credentials and nothing else. The cached remote library
+ * stays readable and signing back into the same account resumes from
+ * its cursor rather than re-downloading everything.
+ */
+export function remoteSignOut(): Promise<RemoteStatus> {
+  return invoke<RemoteStatus>("remote_sign_out");
+}
+
+/**
+ * Drop the credentials, the binding, the cached library **and any
+ * change made offline that never reached the server**. Destructive —
+ * present it as such, and prefer {@link remoteSignOut} whenever the
+ * intent is merely to stop being signed in.
+ */
+export function remoteForgetServer(): Promise<RemoteStatus> {
+  return invoke<RemoteStatus>("remote_forget_server");
+}

From faa608dfb1410e5630e14f70a219d559ff5e23b6 Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Mon, 10 Aug 2026 15:51:52 +0200
Subject: [PATCH 04/14] feat(remote): bootstrap from a snapshot and walk the
 journal

Adds the read half of the protocol: replace the projection from
GET /sync/snapshot, then walk GET /sync/changes page by page, applying
and advancing the cursor in one transaction so a crash keeps both or
neither. An event this build does not understand is skipped and the
cursor keeps moving; a known event that fails to apply discards the
projection and takes a fresh snapshot, because at that point local state
no longer reflects the journal. The acknowledgement is fire-and-forget --
the protocol says it is not a prerequisite for reading, so a failing one
must not stall anything.

The rule the apply path is built around, and the reason it writes field
by field rather than decoding into a struct of options: an absent key
means unchanged, not null. Measured against a live server, creating a
playlist emits [id, name, track_ids] while updating one emits five keys,
and a share update omits track_ids entirely. Writing every field would
blank a comment on every create-shaped replay and empty a share on every
description edit.

Two tests replay the server's own captured journal and assert it
converges on the server's own snapshot. Those fixtures are bytes the
server produced, not a shape we imagined, which is the only kind that
can catch us having imagined the wrong one.

remote_track is new because the feeds are asymmetric: a snapshot carries
whole song objects, a change event carries bare identifiers. Missing ones
are fetched afterwards, opportunistically -- ordering and identity are
already stored, so a failed fetch costs a placeholder row rather than a
wrong one.

Ratings clamp instead of rejecting. An out-of-range value would abort the
transaction, which forces a fresh snapshot, whose replay hits the same
row -- an unbreakable loop over one bad field.

Claude-Session: https://claude.ai/code/session_01N9WXrurarkoiT2jgimvyj1
---
 .../rfcs/RFC-005-remote-source-and-sync-v2.md |   33 +-
 .../crates/app/src/commands/remote_auth.rs    |   31 +
 src-tauri/crates/app/src/lib.rs               |    2 +
 src-tauri/crates/app/src/remote/client.rs     |   14 +-
 src-tauri/crates/app/src/remote/dto.rs        |  236 ++++
 src-tauri/crates/app/src/remote/mod.rs        |   13 +
 src-tauri/crates/app/src/remote/projection.rs | 1126 +++++++++++++++++
 src-tauri/crates/app/src/remote/sync.rs       |  316 +++++
 .../app/src/remote/testdata/changes.json      |   64 +
 .../app/src/remote/testdata/snapshot.json     |   19 +
 .../20260810140000_remote_track_cache.sql     |   47 +
 src/lib/tauri/remoteServer.ts                 |   28 +
 12 files changed, 1927 insertions(+), 2 deletions(-)
 create mode 100644 src-tauri/crates/app/src/remote/dto.rs
 create mode 100644 src-tauri/crates/app/src/remote/projection.rs
 create mode 100644 src-tauri/crates/app/src/remote/sync.rs
 create mode 100644 src-tauri/crates/app/src/remote/testdata/changes.json
 create mode 100644 src-tauri/crates/app/src/remote/testdata/snapshot.json
 create mode 100644 src-tauri/migrations/profile/20260810140000_remote_track_cache.sql

diff --git a/docs/rfcs/RFC-005-remote-source-and-sync-v2.md b/docs/rfcs/RFC-005-remote-source-and-sync-v2.md
index 46a4e8cc..07bfc6b4 100644
--- a/docs/rfcs/RFC-005-remote-source-and-sync-v2.md
+++ b/docs/rfcs/RFC-005-remote-source-and-sync-v2.md
@@ -223,9 +223,18 @@ Per-profile, since the binding is per-profile:
 | `remote_rating` | `(entity_type, entity_id, rating)` |
 | `remote_history` | scrobbles, append-only |
 | `remote_queue` | single row, the server's saved queue |
-| `remote_share` | non-secret share fields; **never** token or URL |
+| `remote_share` | non-secret share fields; **never** token from the journal |
+| `remote_track` | cached song metadata, derived and droppable |
 | `remote_mutation` | outbound queue, typed, keyed by `operation_id` |
 
+`remote_track` exists because the two feeds are asymmetric: a snapshot
+returns playlists and the queue with **whole song objects**, while a change
+event carries a playlist upsert as bare `track_ids`. Without the cache, a
+playlist edited after the bootstrap would arrive as identifiers with nothing to
+render. Missing identifiers are fetched from `GET /api/v2/tracks/{id}` after a
+pass — opportunistically, since ordering and identity are already stored and a
+failed fetch costs a placeholder row rather than a wrong one.
+
 Tokens keep using `auth_credential` under the existing `waveflow_server`
 provider, which already carries a refresh token and an expiry.
 
@@ -248,6 +257,28 @@ recognizes the replay; the change comes back through `/changes`.
 Unknown entity types, actions and payload fields are ignored. A client that
 cannot apply a **known** event drops its projection and re-fetches a snapshot.
 
+### An absent key means unchanged, not null
+
+The single rule the apply path is built around, because getting it wrong loses
+user data silently. Journal payloads are not uniform — measured against a live
+server:
+
+```text
+cursor=1  playlist/upsert   payload keys = [id, name, track_ids]
+cursor=2  playlist/upsert   payload keys = [comment, id, name, public, track_ids]
+```
+
+The first is a creation, the second an update. A share update likewise omits
+`track_ids`, because updating a share cannot change them. So an apply that
+decoded the payload into a struct of `Option` fields and wrote all of them
+would blank a playlist's comment every time a create-shaped event is replayed,
+and empty a share on every description edit.
+
+Each field is therefore written only when its key is **present**; a key present
+and null is a genuine clear. The projection's tests replay the server's own
+captured journal and assert it converges on the server's own snapshot — the two
+feeds have to agree, or the result would depend on which one happened to run.
+
 ## Why the v1 design retires
 
 Every mechanism below exists because v1 accepted concurrent writes arbitrated
diff --git a/src-tauri/crates/app/src/commands/remote_auth.rs b/src-tauri/crates/app/src/commands/remote_auth.rs
index b9bce83f..858cb89c 100644
--- a/src-tauri/crates/app/src/commands/remote_auth.rs
+++ b/src-tauri/crates/app/src/commands/remote_auth.rs
@@ -120,6 +120,37 @@ pub async fn remote_forget_server(state: tauri::State<'_, AppState>) -> AppResul
     status(&state).await
 }
 
+/// What a synchronization pass did.
+#[derive(Debug, Clone, Serialize)]
+pub struct RemoteSyncReport {
+    pub applied: usize,
+    /// Events this build did not understand and skipped. A non-zero
+    /// count is not a fault — it means the server is newer than us.
+    pub ignored: usize,
+    pub pages: usize,
+    pub cursor: i64,
+    /// Whether the pass had to fall back to a fresh snapshot, either
+    /// because it was the first one or because an event could not be
+    /// applied.
+    pub resnapshotted: bool,
+}
+
+/// Bring the projection up to date, bootstrapping if it never has been.
+///
+/// Answers an empty report when the profile is unbound, signed out, or
+/// bound to a server without a journal — all ordinary states.
+#[tauri::command]
+pub async fn remote_sync_now(state: tauri::State<'_, AppState>) -> AppResult<RemoteSyncReport> {
+    let report = crate::remote::sync::sync_now(&state).await?;
+    Ok(RemoteSyncReport {
+        applied: report.applied,
+        ignored: report.ignored,
+        pages: report.pages,
+        cursor: report.cursor,
+        resnapshotted: report.resnapshotted,
+    })
+}
+
 async fn status(state: &AppState) -> AppResult<RemoteStatus> {
     // No active profile is a legitimate state here — the onboarding
     // screens can query this before one exists — so it answers "unbound"
diff --git a/src-tauri/crates/app/src/lib.rs b/src-tauri/crates/app/src/lib.rs
index 5f972575..41fe2c35 100644
--- a/src-tauri/crates/app/src/lib.rs
+++ b/src-tauri/crates/app/src/lib.rs
@@ -763,6 +763,8 @@ pub fn run() {
             commands::remote_auth::remote_sign_out,
             #[cfg(feature = "sync_v2")]
             commands::remote_auth::remote_forget_server,
+            #[cfg(feature = "sync_v2")]
+            commands::remote_auth::remote_sync_now,
             #[cfg(feature = "sync_v1")]
             commands::server_auth::server_get_status,
             #[cfg(feature = "sync_v1")]
diff --git a/src-tauri/crates/app/src/remote/client.rs b/src-tauri/crates/app/src/remote/client.rs
index a3709bb3..cddda823 100644
--- a/src-tauri/crates/app/src/remote/client.rs
+++ b/src-tauri/crates/app/src/remote/client.rs
@@ -222,7 +222,19 @@ impl RemoteClient {
     /// A read request. No idempotency headers — a GET has nothing to
     /// replay.
     pub fn get(&self, path: &str) -> reqwest::RequestBuilder {
-        self.http.get(self.url(path)).bearer_auth(&self.access_token)
+        self.request(reqwest::Method::GET, path)
+    }
+
+    /// A plain authenticated request, with no idempotency headers.
+    ///
+    /// For the endpoints that are not journalled mutations — the
+    /// acknowledgement above all. Stamping those with an operation
+    /// identifier would advertise a replay guarantee the server does not
+    /// implement for them.
+    pub fn request(&self, method: reqwest::Method, path: &str) -> reqwest::RequestBuilder {
+        self.http
+            .request(method, self.url(path))
+            .bearer_auth(&self.access_token)
     }
 
     /// A mutation, stamped so the server can recognize a replay.
diff --git a/src-tauri/crates/app/src/remote/dto.rs b/src-tauri/crates/app/src/remote/dto.rs
new file mode 100644
index 00000000..78aac407
--- /dev/null
+++ b/src-tauri/crates/app/src/remote/dto.rs
@@ -0,0 +1,236 @@
+//! Wire shapes for the journal endpoints.
+//!
+//! Mirrors what the server actually sends, checked against its OpenAPI
+//! document and its live responses rather than against prose. Every
+//! struct ignores unknown fields by default, which is the forward
+//! compatibility the protocol asks for: a server that grows a field must
+//! not break a client that has not heard of it.
+
+use serde::Deserialize;
+
+/// `GET /api/v2/sync/snapshot`.
+#[derive(Debug, Clone, Deserialize)]
+pub struct SyncSnapshot {
+    pub cursor: i64,
+    #[serde(default)]
+    pub playlists: Vec<PlaylistItem>,
+    #[serde(default)]
+    pub favorites: Vec<StarredEntry>,
+    #[serde(default)]
+    pub ratings: Vec<RatingItem>,
+    #[serde(default)]
+    pub queue: Option<QueueItem>,
+    #[serde(default)]
+    pub history: Vec<HistoryItem>,
+    #[serde(default)]
+    pub shares: Vec<ShareItem>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct PlaylistItem {
+    pub id: String,
+    pub name: String,
+    #[serde(default)]
+    pub comment: Option<String>,
+    #[serde(default)]
+    pub public: bool,
+    #[serde(default)]
+    pub songs: Vec<SongItem>,
+    #[serde(default)]
+    pub created_at: Option<i64>,
+    #[serde(default)]
+    pub updated_at: Option<i64>,
+}
+
+/// A track as the server describes it.
+///
+/// Only `id` is required here even though the server marks more fields
+/// mandatory: a third-party server fills in far less, and refusing the
+/// whole page over a missing `suffix` would trade a sparse catalogue for
+/// no catalogue. `title` falls back at the storage layer.
+#[derive(Debug, Clone, Deserialize)]
+pub struct SongItem {
+    pub id: String,
+    #[serde(default)]
+    pub title: Option<String>,
+    #[serde(default)]
+    pub artist: Option<String>,
+    #[serde(default)]
+    pub album: Option<String>,
+    #[serde(default)]
+    pub album_id: Option<String>,
+    #[serde(default)]
+    pub duration_ms: Option<i64>,
+    #[serde(default)]
+    pub track: Option<i64>,
+    #[serde(default)]
+    pub disc: Option<i64>,
+    #[serde(default)]
+    pub year: Option<i64>,
+    #[serde(default)]
+    pub genre: Option<String>,
+    #[serde(default)]
+    pub suffix: Option<String>,
+    #[serde(default)]
+    pub bitrate: Option<i64>,
+    #[serde(default)]
+    pub size: Option<i64>,
+    #[serde(default)]
+    pub artwork_hash: Option<String>,
+    #[serde(default)]
+    pub library_id: Option<String>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct StarredEntry {
+    pub entity_type: String,
+    pub entity_id: String,
+    pub starred_at: i64,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct RatingItem {
+    pub entity_type: String,
+    pub entity_id: String,
+    pub rating: i64,
+    pub updated_at: i64,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct QueueItem {
+    #[serde(default)]
+    pub songs: Vec<SongItem>,
+    #[serde(default)]
+    pub current: Option<String>,
+    #[serde(default)]
+    pub position_ms: i64,
+    #[serde(default)]
+    pub changed_by: Option<String>,
+    #[serde(default)]
+    pub updated_at: i64,
+}
+
+/// One play.
+///
+/// There is no scrobble identifier anywhere in the protocol: the journal
+/// event's `entity_id` is the **track** id, so two plays of the same
+/// track share it. `(track_id, played_at)` is the only pair that tells
+/// them apart, which is why the projection keys on it.
+#[derive(Debug, Clone, Deserialize)]
+pub struct HistoryItem {
+    pub track_id: String,
+    #[serde(default)]
+    pub submission: bool,
+    pub played_at: i64,
+}
+
+/// A share, without its secret. The journal never carries the bearer
+/// token or the public URL; `url` is only ever populated from our own
+/// creation response.
+#[derive(Debug, Clone, Deserialize)]
+pub struct ShareItem {
+    pub id: String,
+    #[serde(default)]
+    pub description: Option<String>,
+    #[serde(default)]
+    pub expires_at: Option<i64>,
+    #[serde(default)]
+    pub track_ids: Vec<String>,
+    #[serde(default)]
+    pub visit_count: i64,
+    #[serde(default)]
+    pub url: Option<String>,
+    #[serde(default)]
+    pub created_at: Option<i64>,
+}
+
+/// `GET /api/v2/sync/changes`.
+#[derive(Debug, Clone, Deserialize)]
+pub struct SyncPage {
+    #[serde(default)]
+    pub changes: Vec<SyncChange>,
+    #[serde(default)]
+    pub has_more: bool,
+    pub next_cursor: i64,
+}
+
+/// One journal event.
+///
+/// `payload` stays a raw `Value` deliberately. Its shape depends on
+/// `entity_type` **and** on which endpoint produced it — creating a
+/// playlist emits `{id, name, track_ids}` while updating one emits five
+/// fields — so an absent key means "unchanged", not "null". Decoding
+/// into a typed struct with `Option` fields would erase that distinction
+/// and silently blank a comment on every rename.
+#[derive(Debug, Clone, Deserialize)]
+pub struct SyncChange {
+    pub cursor: i64,
+    pub entity_type: String,
+    pub entity_id: String,
+    pub action: String,
+    #[serde(default)]
+    pub payload: serde_json::Value,
+    #[serde(default)]
+    pub origin_device_id: Option<String>,
+    #[serde(default)]
+    pub changed_at: i64,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn a_snapshot_with_only_a_cursor_decodes() {
+        // Every collection defaults, so an account with nothing in it is
+        // a valid snapshot rather than a decode failure.
+        let snapshot: SyncSnapshot = serde_json::from_str(r#"{"cursor": 0}"#).unwrap();
+        assert_eq!(snapshot.cursor, 0);
+        assert!(snapshot.playlists.is_empty());
+        assert!(snapshot.queue.is_none());
+    }
+
+    #[test]
+    fn unknown_fields_are_ignored_rather_than_fatal() {
+        // The protocol requires forward compatibility: a server that
+        // grows a field must not break an older client.
+        let snapshot: SyncSnapshot = serde_json::from_str(
+            r#"{"cursor": 3, "playlists": [], "something_new": {"nested": true}}"#,
+        )
+        .unwrap();
+        assert_eq!(snapshot.cursor, 3);
+    }
+
+    #[test]
+    fn a_song_survives_a_sparse_third_party_server() {
+        // Only the identifier is genuinely required; a server that fills
+        // in less must still yield a usable row.
+        let song: SongItem = serde_json::from_str(r#"{"id": "t1"}"#).unwrap();
+        assert_eq!(song.id, "t1");
+        assert!(song.title.is_none());
+        assert!(song.duration_ms.is_none());
+    }
+
+    #[test]
+    fn a_change_keeps_its_payload_untyped() {
+        let change: SyncChange = serde_json::from_str(
+            r#"{"cursor":7,"entity_type":"playlist","entity_id":"p1","action":"upsert",
+                "payload":{"id":"p1","name":"Mix","track_ids":["a","b"]},
+                "event_id":"e","operation_id":"o","changed_at":10}"#,
+        )
+        .unwrap();
+        assert_eq!(change.cursor, 7);
+        // The distinction this preserves: `comment` is absent, which is
+        // not the same as being null.
+        assert!(change.payload.get("comment").is_none());
+        assert_eq!(change.payload["track_ids"].as_array().unwrap().len(), 2);
+    }
+
+    #[test]
+    fn a_page_that_returns_nothing_still_carries_its_cursor() {
+        let page: SyncPage =
+            serde_json::from_str(r#"{"changes":[],"has_more":false,"next_cursor":42}"#).unwrap();
+        assert_eq!(page.next_cursor, 42);
+        assert!(!page.has_more);
+    }
+}
diff --git a/src-tauri/crates/app/src/remote/mod.rs b/src-tauri/crates/app/src/remote/mod.rs
index 08efc069..84f6250b 100644
--- a/src-tauri/crates/app/src/remote/mod.rs
+++ b/src-tauri/crates/app/src/remote/mod.rs
@@ -34,6 +34,16 @@
 //!   transient so the outbound queue knows whether retrying can ever
 //!   help.
 //!
+//! - [`dto`] — the wire shapes, checked against the server's live
+//!   responses rather than against prose.
+//!
+//! - [`projection`] — writing the server's user data into the local
+//!   `remote_*` tables. Pure database work, testable without a network.
+//!
+//! - [`sync`] — the orchestrator: bootstrap from a snapshot, walk the
+//!   journal, acknowledge, and recover by re-snapshotting when a known
+//!   event cannot be applied.
+//!
 //! - [`probe`] — server flavour detection. Decides whether the optional
 //!   [`SyncProvider`](#capabilities) surface exists at all.
 //!
@@ -56,5 +66,8 @@
 pub mod auth;
 pub mod binding;
 pub mod client;
+pub mod dto;
 pub mod probe;
+pub mod projection;
+pub mod sync;
 pub mod tokens;
diff --git a/src-tauri/crates/app/src/remote/projection.rs b/src-tauri/crates/app/src/remote/projection.rs
new file mode 100644
index 00000000..370ff6c8
--- /dev/null
+++ b/src-tauri/crates/app/src/remote/projection.rs
@@ -0,0 +1,1126 @@
+//! Writing the server's user data into the local projection.
+//!
+//! Pure database work: no HTTP, no client, nothing that needs a network
+//! to test. The orchestrator in [`super::sync`] decides *when* to call
+//! this and fetches whatever metadata is missing afterwards.
+//!
+//! ## The rule that governs every apply: an absent key means unchanged
+//!
+//! Journal payloads are not uniform, and the difference is not cosmetic.
+//! Creating a playlist emits
+//!
+//! ```json
+//! {"id": "…", "name": "Mix", "track_ids": ["…"]}
+//! ```
+//!
+//! while updating one emits `name`, `comment`, `public` and `track_ids`.
+//! A share update omits `track_ids` entirely, because updating a share
+//! cannot change them.
+//!
+//! So decoding a payload into a struct of `Option` fields and writing
+//! all of them would blank a playlist's comment on every rename and
+//! empty a share on every description edit. Each field is written only
+//! when its key is **present**; a key present and null is a genuine
+//! clear, and the two are held apart everywhere below.
+//!
+//! ## Failure has two meanings
+//!
+//! [`Outcome::Ignored`] is an event this build does not understand — an
+//! unknown entity type or action. The protocol says to skip it and keep
+//! the cursor moving; a newer server talking to an older client is
+//! expected, not broken.
+//!
+//! An `Err` is different: a *known* event that could not be applied. The
+//! caller's contract is then to discard the projection and take a fresh
+//! snapshot, because the local state can no longer be trusted to reflect
+//! the journal.
+
+use serde_json::Value;
+use sqlx::SqliteConnection;
+
+use crate::{
+    error::AppResult,
+    remote::dto::{SongItem, SyncChange, SyncSnapshot},
+};
+
+/// What an apply did.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Outcome {
+    Applied,
+    /// Unknown entity type or action. Skipped on purpose — see the
+    /// module docs.
+    Ignored,
+}
+
+/// Ratings are 1..=5 in storage; `0` on the wire means "clear".
+///
+/// Clamping rather than rejecting is deliberate: a value outside the
+/// range would otherwise abort the transaction, and per the protocol
+/// that forces a fresh snapshot — whose replay would abort on the same
+/// row, looping forever. Clamping degrades one field instead.
+fn clamp_rating(rating: i64) -> i64 {
+    rating.clamp(1, 5)
+}
+
+/// Replace the whole projection with one writer-consistent snapshot.
+///
+/// The caller must run this inside a transaction: a projection emptied
+/// but not refilled is a state no reader can interpret, and the whole
+/// point of a snapshot is that it lands at once or not at all.
+///
+/// The pending outbound queue is untouched. It holds writes the server
+/// has not seen, so it is the one thing here that is not
+/// reconstructible.
+pub async fn apply_snapshot(conn: &mut SqliteConnection, snapshot: &SyncSnapshot) -> AppResult<()> {
+    for statement in [
+        "DELETE FROM remote_playlist_track",
+        "DELETE FROM remote_playlist",
+        "DELETE FROM remote_favorite",
+        "DELETE FROM remote_rating",
+        "DELETE FROM remote_history",
+        "DELETE FROM remote_queue_track",
+        "DELETE FROM remote_queue",
+        "DELETE FROM remote_share_track",
+        "DELETE FROM remote_share",
+    ] {
+        sqlx::query(statement).execute(&mut *conn).await?;
+    }
+
+    for playlist in &snapshot.playlists {
+        sqlx::query(
+            "INSERT INTO remote_playlist
+                (remote_id, name, comment, is_public, created_at, updated_at)
+             VALUES (?, ?, ?, ?, ?, ?)",
+        )
+        .bind(&playlist.id)
+        .bind(&playlist.name)
+        .bind(playlist.comment.as_deref())
+        .bind(i64::from(playlist.public))
+        .bind(playlist.created_at)
+        .bind(playlist.updated_at)
+        .execute(&mut *conn)
+        .await?;
+
+        for (position, song) in playlist.songs.iter().enumerate() {
+            cache_song(&mut *conn, song).await?;
+            sqlx::query(
+                "INSERT INTO remote_playlist_track
+                    (playlist_remote_id, position, track_remote_id)
+                 VALUES (?, ?, ?)",
+            )
+            .bind(&playlist.id)
+            .bind(position as i64)
+            .bind(&song.id)
+            .execute(&mut *conn)
+            .await?;
+        }
+    }
+
+    for favorite in &snapshot.favorites {
+        sqlx::query(
+            "INSERT INTO remote_favorite (entity_type, entity_id, starred_at)
+             VALUES (?, ?, ?)
+             ON CONFLICT(entity_type, entity_id) DO UPDATE
+                SET starred_at = excluded.starred_at",
+        )
+        .bind(&favorite.entity_type)
+        .bind(&favorite.entity_id)
+        .bind(favorite.starred_at)
+        .execute(&mut *conn)
+        .await?;
+    }
+
+    for rating in &snapshot.ratings {
+        // A stored zero would mean "rated nothing", which is not a
+        // rating. The wire uses it as an instruction, so it never
+        // reaches storage.
+        if rating.rating <= 0 {
+            continue;
+        }
+        sqlx::query(
+            "INSERT INTO remote_rating (entity_type, entity_id, rating, updated_at)
+             VALUES (?, ?, ?, ?)
+             ON CONFLICT(entity_type, entity_id) DO UPDATE
+                SET rating = excluded.rating, updated_at = excluded.updated_at",
+        )
+        .bind(&rating.entity_type)
+        .bind(&rating.entity_id)
+        .bind(clamp_rating(rating.rating))
+        .bind(rating.updated_at)
+        .execute(&mut *conn)
+        .await?;
+    }
+
+    for play in &snapshot.history {
+        // `INSERT OR REPLACE`: a snapshot may legitimately repeat a
+        // play we already hold, and the natural key is all we have to
+        // recognize it by.
+        sqlx::query(
+            "INSERT OR REPLACE INTO remote_history (track_remote_id, played_at, submission)
+             VALUES (?, ?, ?)",
+        )
+        .bind(&play.track_id)
+        .bind(play.played_at)
+        .bind(i64::from(play.submission))
+        .execute(&mut *conn)
+        .await?;
+    }
+
+    if let Some(queue) = &snapshot.queue {
+        sqlx::query(
+            "INSERT INTO remote_queue (id, current_remote_id, position_ms, changed_by, updated_at)
+             VALUES (1, ?, ?, ?, ?)",
+        )
+        .bind(queue.current.as_deref())
+        .bind(queue.position_ms.max(0))
+        .bind(queue.changed_by.as_deref())
+        .bind(queue.updated_at)
+        .execute(&mut *conn)
+        .await?;
+
+        for (position, song) in queue.songs.iter().enumerate() {
+            cache_song(&mut *conn, song).await?;
+            sqlx::query("INSERT INTO remote_queue_track (position, track_remote_id) VALUES (?, ?)")
+                .bind(position as i64)
+                .bind(&song.id)
+                .execute(&mut *conn)
+                .await?;
+        }
+    }
+
+    for share in &snapshot.shares {
+        sqlx::query(
+            "INSERT INTO remote_share
+                (remote_id, description, expires_at, visit_count, url, created_at)
+             VALUES (?, ?, ?, ?, ?, ?)",
+        )
+        .bind(&share.id)
+        .bind(share.description.as_deref())
+        .bind(share.expires_at)
+        .bind(share.visit_count.max(0))
+        .bind(share.url.as_deref())
+        .bind(share.created_at)
+        .execute(&mut *conn)
+        .await?;
+
+        replace_share_tracks(&mut *conn, &share.id, &share.track_ids).await?;
+    }
+
+    Ok(())
+}
+
+/// Store what we know about a track, without losing what we already had.
+///
+/// `COALESCE(excluded.…, …)` on every optional column: a later sighting
+/// of the same track from a sparser source must not blank fields an
+/// earlier, richer one filled in.
+pub async fn cache_song(conn: &mut SqliteConnection, song: &SongItem) -> AppResult<()> {
+    sqlx::query(
+        "INSERT INTO remote_track
+            (remote_id, title, artist, album, album_id, duration_ms, track_no, disc_no,
+             year, genre, suffix, bitrate, size, artwork_hash, library_id, cached_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(remote_id) DO UPDATE SET
+            title        = excluded.title,
+            artist       = COALESCE(excluded.artist, artist),
+            album        = COALESCE(excluded.album, album),
+            album_id     = COALESCE(excluded.album_id, album_id),
+            duration_ms  = MAX(excluded.duration_ms, duration_ms),
+            track_no     = COALESCE(excluded.track_no, track_no),
+            disc_no      = COALESCE(excluded.disc_no, disc_no),
+            year         = COALESCE(excluded.year, year),
+            genre        = COALESCE(excluded.genre, genre),
+            suffix       = COALESCE(excluded.suffix, suffix),
+            bitrate      = COALESCE(excluded.bitrate, bitrate),
+            size         = COALESCE(excluded.size, size),
+            artwork_hash = COALESCE(excluded.artwork_hash, artwork_hash),
+            library_id   = COALESCE(excluded.library_id, library_id),
+            cached_at    = excluded.cached_at",
+    )
+    .bind(&song.id)
+    // An untitled row is still better than no row: the playlist keeps
+    // its ordering and the identifier is there to re-fetch with.
+    .bind(song.title.as_deref().unwrap_or_default())
+    .bind(song.artist.as_deref())
+    .bind(song.album.as_deref())
+    .bind(song.album_id.as_deref())
+    .bind(song.duration_ms.unwrap_or(0).max(0))
+    .bind(song.track)
+    .bind(song.disc)
+    .bind(song.year)
+    .bind(song.genre.as_deref())
+    .bind(song.suffix.as_deref())
+    .bind(song.bitrate)
+    .bind(song.size)
+    .bind(song.artwork_hash.as_deref())
+    .bind(song.library_id.as_deref())
+    .bind(chrono::Utc::now().timestamp_millis())
+    .execute(&mut *conn)
+    .await?;
+    Ok(())
+}
+
+/// Track identifiers the projection references but has no metadata for.
+///
+/// The gap is structural, not a bug: a snapshot carries whole song
+/// objects, a change event carries bare identifiers. The orchestrator
+/// closes it by fetching these, and until it does the UI has an
+/// identifier and an ordering, which is enough to render a placeholder
+/// rather than nothing.
+pub async fn missing_track_ids(conn: &mut SqliteConnection) -> AppResult<Vec<String>> {
+    let rows: Vec<String> = sqlx::query_scalar(
+        "SELECT track_remote_id FROM remote_playlist_track
+          WHERE track_remote_id NOT IN (SELECT remote_id FROM remote_track)
+         UNION
+         SELECT track_remote_id FROM remote_queue_track
+          WHERE track_remote_id NOT IN (SELECT remote_id FROM remote_track)
+         UNION
+         SELECT track_remote_id FROM remote_share_track
+          WHERE track_remote_id NOT IN (SELECT remote_id FROM remote_track)",
+    )
+    .fetch_all(&mut *conn)
+    .await?;
+    Ok(rows)
+}
+
+/// Apply one journal event.
+pub async fn apply_change(conn: &mut SqliteConnection, change: &SyncChange) -> AppResult<Outcome> {
+    match (change.entity_type.as_str(), change.action.as_str()) {
+        ("playlist", "upsert") => apply_playlist_upsert(conn, change).await,
+        ("playlist", "delete") => {
+            // The child rows go explicitly: `ON DELETE CASCADE` only
+            // fires with `foreign_keys` on, which is a per-connection
+            // pragma, and correctness should not depend on how the
+            // caller happened to connect.
+            sqlx::query("DELETE FROM remote_playlist_track WHERE playlist_remote_id = ?")
+                .bind(&change.entity_id)
+                .execute(&mut *conn)
+                .await?;
+            sqlx::query("DELETE FROM remote_playlist WHERE remote_id = ?")
+                .bind(&change.entity_id)
+                .execute(&mut *conn)
+                .await?;
+            Ok(Outcome::Applied)
+        }
+
+        ("favorite", "upsert") => {
+            let entity_type = payload_str(&change.payload, "entity_type")
+                .unwrap_or("track")
+                .to_string();
+            let entity_id = payload_str(&change.payload, "entity_id")
+                .unwrap_or(&change.entity_id)
+                .to_string();
+            // `starred: false` on an upsert is a removal. The server
+            // already picks the action from the same boolean, but
+            // honouring the payload keeps the two from disagreeing.
+            if change.payload.get("starred").and_then(Value::as_bool) == Some(false) {
+                delete_favorite(conn, &entity_type, &entity_id).await?;
+            } else {
+                sqlx::query(
+                    "INSERT INTO remote_favorite (entity_type, entity_id, starred_at)
+                     VALUES (?, ?, ?)
+                     ON CONFLICT(entity_type, entity_id) DO UPDATE
+                        SET starred_at = excluded.starred_at",
+                )
+                .bind(&entity_type)
+                .bind(&entity_id)
+                .bind(change.changed_at)
+                .execute(&mut *conn)
+                .await?;
+            }
+            Ok(Outcome::Applied)
+        }
+        ("favorite", "delete") => {
+            let entity_type = payload_str(&change.payload, "entity_type")
+                .unwrap_or("track")
+                .to_string();
+            let entity_id = payload_str(&change.payload, "entity_id")
+                .unwrap_or(&change.entity_id)
+                .to_string();
+            delete_favorite(conn, &entity_type, &entity_id).await?;
+            Ok(Outcome::Applied)
+        }
+
+        ("rating", "upsert") | ("rating", "delete") => {
+            let entity_type = payload_str(&change.payload, "entity_type")
+                .unwrap_or("track")
+                .to_string();
+            let entity_id = payload_str(&change.payload, "entity_id")
+                .unwrap_or(&change.entity_id)
+                .to_string();
+            let rating = change
+                .payload
+                .get("rating")
+                .and_then(Value::as_i64)
+                .unwrap_or(0);
+            if change.action == "delete" || rating <= 0 {
+                sqlx::query("DELETE FROM remote_rating WHERE entity_type = ? AND entity_id = ?")
+                    .bind(&entity_type)
+                    .bind(&entity_id)
+                    .execute(&mut *conn)
+                    .await?;
+            } else {
+                sqlx::query(
+                    "INSERT INTO remote_rating (entity_type, entity_id, rating, updated_at)
+                     VALUES (?, ?, ?, ?)
+                     ON CONFLICT(entity_type, entity_id) DO UPDATE
+                        SET rating = excluded.rating, updated_at = excluded.updated_at",
+                )
+                .bind(&entity_type)
+                .bind(&entity_id)
+                .bind(clamp_rating(rating))
+                .bind(change.changed_at)
+                .execute(&mut *conn)
+                .await?;
+            }
+            Ok(Outcome::Applied)
+        }
+
+        ("scrobble", _) => {
+            let track_id = payload_str(&change.payload, "track_id")
+                .unwrap_or(&change.entity_id)
+                .to_string();
+            let played_at = change
+                .payload
+                .get("played_at")
+                .and_then(Value::as_i64)
+                .unwrap_or(change.changed_at);
+            let submission = change
+                .payload
+                .get("submission")
+                .and_then(Value::as_bool)
+                .unwrap_or(true);
+            sqlx::query(
+                "INSERT OR REPLACE INTO remote_history (track_remote_id, played_at, submission)
+                 VALUES (?, ?, ?)",
+            )
+            .bind(&track_id)
+            .bind(played_at)
+            .bind(i64::from(submission))
+            .execute(&mut *conn)
+            .await?;
+            Ok(Outcome::Applied)
+        }
+
+        ("queue", "upsert") => {
+            sqlx::query(
+                "INSERT INTO remote_queue
+                    (id, current_remote_id, position_ms, changed_by, updated_at)
+                 VALUES (1, ?, ?, ?, ?)
+                 ON CONFLICT(id) DO UPDATE SET
+                    current_remote_id = excluded.current_remote_id,
+                    position_ms       = excluded.position_ms,
+                    changed_by        = excluded.changed_by,
+                    updated_at        = excluded.updated_at",
+            )
+            .bind(payload_str(&change.payload, "current"))
+            .bind(
+                change
+                    .payload
+                    .get("position_ms")
+                    .and_then(Value::as_i64)
+                    .unwrap_or(0)
+                    .max(0),
+            )
+            .bind(payload_str(&change.payload, "client"))
+            .bind(change.changed_at)
+            .execute(&mut *conn)
+            .await?;
+
+            if let Some(ids) = payload_ids(&change.payload, "track_ids") {
+                sqlx::query("DELETE FROM remote_queue_track")
+                    .execute(&mut *conn)
+                    .await?;
+                for (position, id) in ids.iter().enumerate() {
+                    sqlx::query(
+                        "INSERT INTO remote_queue_track (position, track_remote_id) VALUES (?, ?)",
+                    )
+                    .bind(position as i64)
+                    .bind(id)
+                    .execute(&mut *conn)
+                    .await?;
+                }
+            }
+            Ok(Outcome::Applied)
+        }
+
+        ("share", "upsert") => apply_share_upsert(conn, change).await,
+        ("share", "delete") => {
+            sqlx::query("DELETE FROM remote_share_track WHERE share_remote_id = ?")
+                .bind(&change.entity_id)
+                .execute(&mut *conn)
+                .await?;
+            sqlx::query("DELETE FROM remote_share WHERE remote_id = ?")
+                .bind(&change.entity_id)
+                .execute(&mut *conn)
+                .await?;
+            Ok(Outcome::Applied)
+        }
+
+        // A newer server talking to an older client. Skip and keep the
+        // cursor moving — this is expected, not a fault.
+        _ => Ok(Outcome::Ignored),
+    }
+}
+
+async fn delete_favorite(
+    conn: &mut SqliteConnection,
+    entity_type: &str,
+    entity_id: &str,
+) -> AppResult<()> {
+    sqlx::query("DELETE FROM remote_favorite WHERE entity_type = ? AND entity_id = ?")
+        .bind(entity_type)
+        .bind(entity_id)
+        .execute(&mut *conn)
+        .await?;
+    Ok(())
+}
+
+/// Playlist upsert, field by field.
+///
+/// The insert plants a row with defaults if none exists; each `UPDATE`
+/// afterwards fires only for a key the payload actually carries. That is
+/// what keeps `create_playlist` — which sends neither `comment` nor
+/// `public` — from blanking values a later `update_playlist` had set.
+async fn apply_playlist_upsert(
+    conn: &mut SqliteConnection,
+    change: &SyncChange,
+) -> AppResult<Outcome> {
+    let id = payload_str(&change.payload, "id")
+        .unwrap_or(&change.entity_id)
+        .to_string();
+
+    sqlx::query(
+        "INSERT INTO remote_playlist (remote_id, name, is_public, created_at, updated_at)
+         VALUES (?, ?, 0, ?, ?)
+         ON CONFLICT(remote_id) DO NOTHING",
+    )
+    .bind(&id)
+    .bind(payload_str(&change.payload, "name").unwrap_or_default())
+    .bind(change.changed_at)
+    .bind(change.changed_at)
+    .execute(&mut *conn)
+    .await?;
+
+    if let Some(name) = payload_str(&change.payload, "name") {
+        sqlx::query("UPDATE remote_playlist SET name = ? WHERE remote_id = ?")
+            .bind(name)
+            .bind(&id)
+            .execute(&mut *conn)
+            .await?;
+    }
+    // Present-and-null is a real clear, so this branch keys on the key
+    // existing, not on the value being a string.
+    if change.payload.get("comment").is_some() {
+        sqlx::query("UPDATE remote_playlist SET comment = ? WHERE remote_id = ?")
+            .bind(payload_str(&change.payload, "comment"))
+            .bind(&id)
+            .execute(&mut *conn)
+            .await?;
+    }
+    if let Some(public) = change.payload.get("public").and_then(Value::as_bool) {
+        sqlx::query("UPDATE remote_playlist SET is_public = ? WHERE remote_id = ?")
+            .bind(i64::from(public))
+            .bind(&id)
+            .execute(&mut *conn)
+            .await?;
+    }
+
+    sqlx::query("UPDATE remote_playlist SET updated_at = ? WHERE remote_id = ?")
+        .bind(change.changed_at)
+        .bind(&id)
+        .execute(&mut *conn)
+        .await?;
+
+    if let Some(ids) = payload_ids(&change.payload, "track_ids") {
+        sqlx::query("DELETE FROM remote_playlist_track WHERE playlist_remote_id = ?")
+            .bind(&id)
+            .execute(&mut *conn)
+            .await?;
+        for (position, track_id) in ids.iter().enumerate() {
+            sqlx::query(
+                "INSERT INTO remote_playlist_track
+                    (playlist_remote_id, position, track_remote_id)
+                 VALUES (?, ?, ?)",
+            )
+            .bind(&id)
+            .bind(position as i64)
+            .bind(track_id)
+            .execute(&mut *conn)
+            .await?;
+        }
+    }
+
+    Ok(Outcome::Applied)
+}
+
+/// Share upsert. Same discipline as the playlist, and it matters here
+/// for one specific reason: updating a share's description emits a
+/// payload with **no** `track_ids`, so writing them unconditionally
+/// would empty the share.
+async fn apply_share_upsert(conn: &mut SqliteConnection, change: &SyncChange) -> AppResult<Outcome> {
+    let id = payload_str(&change.payload, "id")
+        .unwrap_or(&change.entity_id)
+        .to_string();
+
+    sqlx::query(
+        "INSERT INTO remote_share (remote_id, created_at, updated_at)
+         VALUES (?, ?, ?)
+         ON CONFLICT(remote_id) DO NOTHING",
+    )
+    .bind(&id)
+    .bind(change.changed_at)
+    .bind(change.changed_at)
+    .execute(&mut *conn)
+    .await?;
+
+    if change.payload.get("description").is_some() {
+        sqlx::query("UPDATE remote_share SET description = ? WHERE remote_id = ?")
+            .bind(payload_str(&change.payload, "description"))
+            .bind(&id)
+            .execute(&mut *conn)
+            .await?;
+    }
+    if change.payload.get("expires_at").is_some() {
+        sqlx::query("UPDATE remote_share SET expires_at = ? WHERE remote_id = ?")
+            .bind(change.payload.get("expires_at").and_then(Value::as_i64))
+            .bind(&id)
+            .execute(&mut *conn)
+            .await?;
+    }
+    sqlx::query("UPDATE remote_share SET updated_at = ? WHERE remote_id = ?")
+        .bind(change.changed_at)
+        .bind(&id)
+        .execute(&mut *conn)
+        .await?;
+
+    if let Some(ids) = payload_ids(&change.payload, "track_ids") {
+        replace_share_tracks(conn, &id, &ids).await?;
+    }
+
+    Ok(Outcome::Applied)
+}
+
+async fn replace_share_tracks(
+    conn: &mut SqliteConnection,
+    share_id: &str,
+    track_ids: &[String],
+) -> AppResult<()> {
+    sqlx::query("DELETE FROM remote_share_track WHERE share_remote_id = ?")
+        .bind(share_id)
+        .execute(&mut *conn)
+        .await?;
+    for (position, track_id) in track_ids.iter().enumerate() {
+        sqlx::query(
+            "INSERT INTO remote_share_track (share_remote_id, position, track_remote_id)
+             VALUES (?, ?, ?)",
+        )
+        .bind(share_id)
+        .bind(position as i64)
+        .bind(track_id)
+        .execute(&mut *conn)
+        .await?;
+    }
+    Ok(())
+}
+
+/// Read a string field. `None` covers both "absent" and "null" — every
+/// caller that needs to tell them apart checks `payload.get(key)` first.
+fn payload_str<'a>(payload: &'a Value, key: &str) -> Option<&'a str> {
+    payload.get(key).and_then(Value::as_str)
+}
+
+/// Read an ordered list of identifiers, or `None` when the key is
+/// absent. An empty array is a real emptying and comes back as
+/// `Some(vec![])`.
+fn payload_ids(payload: &Value, key: &str) -> Option<Vec<String>> {
+    let array = payload.get(key)?.as_array()?;
+    Some(
+        array
+            .iter()
+            .filter_map(|value| value.as_str().map(str::to_owned))
+            .collect(),
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::remote::dto::SyncPage;
+    use sqlx::sqlite::SqlitePoolOptions;
+    use sqlx::{Row, SqlitePool};
+
+    async fn pool() -> SqlitePool {
+        let pool = SqlitePoolOptions::new()
+            .max_connections(1)
+            .connect(":memory:")
+            .await
+            .unwrap();
+        for migration in [
+            include_str!(
+                "../../../../migrations/profile/20260810120000_remote_source_projection.sql"
+            ),
+            include_str!("../../../../migrations/profile/20260810140000_remote_track_cache.sql"),
+        ] {
+            sqlx::raw_sql(migration).execute(&pool).await.unwrap();
+        }
+        pool
+    }
+
+    fn change(entity_type: &str, action: &str, entity_id: &str, payload: Value) -> SyncChange {
+        SyncChange {
+            cursor: 1,
+            entity_type: entity_type.into(),
+            entity_id: entity_id.into(),
+            action: action.into(),
+            payload,
+            origin_device_id: None,
+            changed_at: 1_000,
+        }
+    }
+
+    async fn playlist_row(conn: &mut SqliteConnection, id: &str) -> (String, Option<String>, i64) {
+        let row = sqlx::query("SELECT name, comment, is_public FROM remote_playlist WHERE remote_id = ?")
+            .bind(id)
+            .fetch_one(&mut *conn)
+            .await
+            .unwrap();
+        (
+            row.try_get("name").unwrap(),
+            row.try_get("comment").unwrap(),
+            row.try_get("is_public").unwrap(),
+        )
+    }
+
+    #[tokio::test]
+    async fn creating_a_playlist_after_an_update_does_not_blank_what_the_update_set() {
+        // The bug this guards: `create_playlist` emits neither `comment`
+        // nor `public`, so an apply that wrote every field would erase
+        // both every time a playlist is re-created or replayed.
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+
+        apply_change(
+            &mut conn,
+            &change(
+                "playlist",
+                "upsert",
+                "p1",
+                serde_json::json!({
+                    "id": "p1", "name": "Mix", "comment": "notes",
+                    "public": true, "track_ids": ["t1"]
+                }),
+            ),
+        )
+        .await
+        .unwrap();
+
+        // Now the create-shaped payload: three keys only.
+        apply_change(
+            &mut conn,
+            &change(
+                "playlist",
+                "upsert",
+                "p1",
+                serde_json::json!({"id": "p1", "name": "Mix renamed", "track_ids": ["t1", "t2"]}),
+            ),
+        )
+        .await
+        .unwrap();
+
+        let (name, comment, public) = playlist_row(&mut conn, "p1").await;
+        assert_eq!(name, "Mix renamed");
+        assert_eq!(comment.as_deref(), Some("notes"), "comment was blanked");
+        assert_eq!(public, 1, "public was reset");
+    }
+
+    #[tokio::test]
+    async fn a_null_comment_is_a_real_clear() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        apply_change(
+            &mut conn,
+            &change(
+                "playlist",
+                "upsert",
+                "p1",
+                serde_json::json!({"id": "p1", "name": "Mix", "comment": "notes"}),
+            ),
+        )
+        .await
+        .unwrap();
+        apply_change(
+            &mut conn,
+            &change(
+                "playlist",
+                "upsert",
+                "p1",
+                serde_json::json!({"id": "p1", "name": "Mix", "comment": null}),
+            ),
+        )
+        .await
+        .unwrap();
+
+        let (_, comment, _) = playlist_row(&mut conn, "p1").await;
+        assert_eq!(comment, None, "an explicit null must clear, not be ignored");
+    }
+
+    #[tokio::test]
+    async fn a_playlist_keeps_a_track_that_appears_twice() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        apply_change(
+            &mut conn,
+            &change(
+                "playlist",
+                "upsert",
+                "p1",
+                serde_json::json!({"id": "p1", "name": "M", "track_ids": ["t1", "t1", "t2"]}),
+            ),
+        )
+        .await
+        .unwrap();
+
+        let ids: Vec<String> = sqlx::query_scalar(
+            "SELECT track_remote_id FROM remote_playlist_track
+              WHERE playlist_remote_id = 'p1' ORDER BY position",
+        )
+        .fetch_all(&mut *conn)
+        .await
+        .unwrap();
+        assert_eq!(ids, vec!["t1", "t1", "t2"]);
+    }
+
+    #[tokio::test]
+    async fn updating_a_share_description_does_not_empty_it() {
+        // `update_share` emits `{id, description, expires_at}` and no
+        // track list. Writing tracks unconditionally would drop them.
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        apply_change(
+            &mut conn,
+            &change(
+                "share",
+                "upsert",
+                "s1",
+                serde_json::json!({"id": "s1", "track_ids": ["t1", "t2"], "description": "a"}),
+            ),
+        )
+        .await
+        .unwrap();
+        apply_change(
+            &mut conn,
+            &change(
+                "share",
+                "upsert",
+                "s1",
+                serde_json::json!({"id": "s1", "description": "b", "expires_at": null}),
+            ),
+        )
+        .await
+        .unwrap();
+
+        let count: i64 =
+            sqlx::query_scalar("SELECT count(*) FROM remote_share_track WHERE share_remote_id='s1'")
+                .fetch_one(&mut *conn)
+                .await
+                .unwrap();
+        assert_eq!(count, 2, "the share lost its tracks on a description edit");
+    }
+
+    #[tokio::test]
+    async fn a_zero_rating_clears_instead_of_storing_zero() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        apply_change(
+            &mut conn,
+            &change(
+                "rating",
+                "upsert",
+                "t1",
+                serde_json::json!({"entity_type": "track", "entity_id": "t1", "rating": 4}),
+            ),
+        )
+        .await
+        .unwrap();
+        apply_change(
+            &mut conn,
+            &change(
+                "rating",
+                "delete",
+                "t1",
+                serde_json::json!({"entity_type": "track", "entity_id": "t1", "rating": 0}),
+            ),
+        )
+        .await
+        .unwrap();
+
+        let count: i64 = sqlx::query_scalar("SELECT count(*) FROM remote_rating")
+            .fetch_one(&mut *conn)
+            .await
+            .unwrap();
+        assert_eq!(count, 0);
+    }
+
+    #[tokio::test]
+    async fn an_out_of_range_rating_is_clamped_rather_than_aborting() {
+        // Aborting would force a fresh snapshot whose replay hits the
+        // same row — an unbreakable loop over one bad field.
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        apply_change(
+            &mut conn,
+            &change(
+                "rating",
+                "upsert",
+                "t1",
+                serde_json::json!({"entity_type": "track", "entity_id": "t1", "rating": 99}),
+            ),
+        )
+        .await
+        .unwrap();
+
+        let rating: i64 = sqlx::query_scalar("SELECT rating FROM remote_rating")
+            .fetch_one(&mut *conn)
+            .await
+            .unwrap();
+        assert_eq!(rating, 5);
+    }
+
+    #[tokio::test]
+    async fn an_unstarred_favorite_upsert_removes_the_row() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        apply_change(
+            &mut conn,
+            &change(
+                "favorite",
+                "upsert",
+                "t1",
+                serde_json::json!({"entity_type": "track", "entity_id": "t1", "starred": true}),
+            ),
+        )
+        .await
+        .unwrap();
+        apply_change(
+            &mut conn,
+            &change(
+                "favorite",
+                "upsert",
+                "t1",
+                serde_json::json!({"entity_type": "track", "entity_id": "t1", "starred": false}),
+            ),
+        )
+        .await
+        .unwrap();
+
+        let count: i64 = sqlx::query_scalar("SELECT count(*) FROM remote_favorite")
+            .fetch_one(&mut *conn)
+            .await
+            .unwrap();
+        assert_eq!(count, 0);
+    }
+
+    #[tokio::test]
+    async fn two_plays_of_one_track_are_distinct_but_a_replay_is_not() {
+        // There is no scrobble identifier in the protocol; the natural
+        // key is the only thing that separates two plays.
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        for played_at in [1_000, 2_000, 1_000] {
+            apply_change(
+                &mut conn,
+                &change(
+                    "scrobble",
+                    "append",
+                    "t1",
+                    serde_json::json!({"track_id": "t1", "submission": true, "played_at": played_at}),
+                ),
+            )
+            .await
+            .unwrap();
+        }
+
+        let count: i64 = sqlx::query_scalar("SELECT count(*) FROM remote_history")
+            .fetch_one(&mut *conn)
+            .await
+            .unwrap();
+        assert_eq!(count, 2);
+    }
+
+    #[tokio::test]
+    async fn an_unknown_entity_is_skipped_not_failed() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        let outcome = apply_change(
+            &mut conn,
+            &change("something_new", "upsert", "x", serde_json::json!({})),
+        )
+        .await
+        .unwrap();
+        assert_eq!(outcome, Outcome::Ignored);
+
+        let outcome = apply_change(
+            &mut conn,
+            &change("playlist", "reorder_v2", "p1", serde_json::json!({})),
+        )
+        .await
+        .unwrap();
+        assert_eq!(outcome, Outcome::Ignored);
+    }
+
+    #[tokio::test]
+    async fn a_snapshot_replaces_everything_and_caches_its_songs() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+
+        // Something stale to be swept away.
+        apply_change(
+            &mut conn,
+            &change(
+                "playlist",
+                "upsert",
+                "old",
+                serde_json::json!({"id": "old", "name": "Stale", "track_ids": ["z"]}),
+            ),
+        )
+        .await
+        .unwrap();
+
+        let snapshot: SyncSnapshot = serde_json::from_value(serde_json::json!({
+            "cursor": 12,
+            "playlists": [{
+                "id": "p1", "name": "Mix", "public": false, "created_at": 1, "updated_at": 2,
+                "songs": [{"id": "t1", "title": "Song", "artist": "A", "duration_ms": 1000}]
+            }],
+            "favorites": [{"entity_type": "track", "entity_id": "t1", "starred_at": 5}],
+            "ratings": [{"entity_type": "track", "entity_id": "t1", "rating": 3, "updated_at": 5}],
+            "history": [{"track_id": "t1", "submission": true, "played_at": 9}],
+            "queue": {"songs": [{"id": "t1", "title": "Song"}], "current": "t1",
+                      "position_ms": 4200, "updated_at": 7},
+            "shares": [{"id": "s1", "track_ids": ["t1"], "visit_count": 2}]
+        }))
+        .unwrap();
+
+        apply_snapshot(&mut conn, &snapshot).await.unwrap();
+
+        let stale: i64 =
+            sqlx::query_scalar("SELECT count(*) FROM remote_playlist WHERE remote_id = 'old'")
+                .fetch_one(&mut *conn)
+                .await
+                .unwrap();
+        assert_eq!(stale, 0, "the snapshot did not replace the old projection");
+
+        let title: String =
+            sqlx::query_scalar("SELECT title FROM remote_track WHERE remote_id = 't1'")
+                .fetch_one(&mut *conn)
+                .await
+                .unwrap();
+        assert_eq!(title, "Song", "the snapshot's song metadata was not cached");
+
+        // Nothing is missing: the snapshot carried every song it
+        // referenced.
+        assert!(missing_track_ids(&mut conn).await.unwrap().is_empty());
+    }
+
+    #[tokio::test]
+    async fn identifiers_from_a_change_event_show_up_as_missing_metadata() {
+        // A change carries bare identifiers, so this is the gap the
+        // orchestrator has to close by fetching.
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        apply_change(
+            &mut conn,
+            &change(
+                "playlist",
+                "upsert",
+                "p1",
+                serde_json::json!({"id": "p1", "name": "M", "track_ids": ["t9"]}),
+            ),
+        )
+        .await
+        .unwrap();
+
+        assert_eq!(missing_track_ids(&mut conn).await.unwrap(), vec!["t9"]);
+    }
+
+    /// Captured verbatim from a running server (2026-08-10) by creating
+    /// a playlist, renaming it with a comment and making it public,
+    /// then creating and deleting a second one. Bytes from the server
+    /// itself, not a shape we imagined — which is the only kind of
+    /// fixture that can catch us having imagined the wrong one.
+    const REAL_SNAPSHOT: &str = include_str!("testdata/snapshot.json");
+    const REAL_CHANGES: &str = include_str!("testdata/changes.json");
+
+    #[tokio::test]
+    async fn the_servers_own_snapshot_applies() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        let snapshot: SyncSnapshot = serde_json::from_str(REAL_SNAPSHOT).unwrap();
+        assert_eq!(snapshot.cursor, 4);
+
+        apply_snapshot(&mut conn, &snapshot).await.unwrap();
+
+        let (name, comment, public) =
+            playlist_row(&mut conn, "31be1c98-3984-40ff-8352-73fc6e2c29b5").await;
+        assert_eq!(name, "Mix renommee");
+        assert_eq!(comment.as_deref(), Some("des notes"));
+        assert_eq!(public, 1);
+    }
+
+    #[tokio::test]
+    async fn replaying_the_servers_own_journal_reaches_the_snapshot_state() {
+        // The real sequence is create -> update -> create -> delete, and
+        // the create events carry only three keys. Replaying it must
+        // land on exactly what the snapshot says, or the two feeds
+        // disagree and the projection depends on which one ran.
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+
+        let page: SyncPage = serde_json::from_str(REAL_CHANGES).unwrap();
+        assert_eq!(page.changes.len(), 4);
+        for change in &page.changes {
+            apply_change(&mut conn, change).await.unwrap();
+        }
+
+        let snapshot: SyncSnapshot = serde_json::from_str(REAL_SNAPSHOT).unwrap();
+        let expected = &snapshot.playlists[0];
+        let (name, comment, public) = playlist_row(&mut conn, &expected.id).await;
+        assert_eq!(name, expected.name);
+        assert_eq!(
+            comment, expected.comment,
+            "the third event is create-shaped and blanked the comment the second one set"
+        );
+        assert_eq!(public, i64::from(expected.public));
+
+        // The fourth event deletes the second playlist, so exactly one
+        // survives — the same one the snapshot lists.
+        let total: i64 = sqlx::query_scalar("SELECT count(*) FROM remote_playlist")
+            .fetch_one(&mut *conn)
+            .await
+            .unwrap();
+        assert_eq!(total, snapshot.playlists.len() as i64);
+    }
+
+    #[tokio::test]
+    async fn a_sparser_sighting_does_not_blank_richer_metadata() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        let rich: SongItem = serde_json::from_value(serde_json::json!({
+            "id": "t1", "title": "Song", "artist": "A", "album": "B", "duration_ms": 1234
+        }))
+        .unwrap();
+        let sparse: SongItem =
+            serde_json::from_value(serde_json::json!({"id": "t1", "title": "Song"})).unwrap();
+
+        cache_song(&mut conn, &rich).await.unwrap();
+        cache_song(&mut conn, &sparse).await.unwrap();
+
+        let row = sqlx::query("SELECT artist, duration_ms FROM remote_track WHERE remote_id='t1'")
+            .fetch_one(&mut *conn)
+            .await
+            .unwrap();
+        assert_eq!(row.try_get::<Option<String>, _>("artist").unwrap().as_deref(), Some("A"));
+        assert_eq!(row.try_get::<i64, _>("duration_ms").unwrap(), 1234);
+    }
+}
diff --git a/src-tauri/crates/app/src/remote/sync.rs b/src-tauri/crates/app/src/remote/sync.rs
new file mode 100644
index 00000000..1df9f3ba
--- /dev/null
+++ b/src-tauri/crates/app/src/remote/sync.rs
@@ -0,0 +1,316 @@
+//! Bootstrap and incremental reads against the journal.
+//!
+//! ```text
+//! BOOTSTRAP  GET /sync/snapshot ──▶ atomic replace ──▶ cursor ──▶ ACK
+//! CATCH UP   GET /sync/changes?after=cursor&limit=… ──▶ apply ──▶ cursor ──▶ ACK
+//!            while has_more, immediately ask for the next page
+//! ```
+//!
+//! ## Everything here is driven by the durable cursor
+//!
+//! Not by what arrives, and not by the socket. A page is applied and the
+//! cursor advanced **in one transaction**, so a crash between the two is
+//! impossible: either the page landed and the position moved, or neither
+//! did and the same page is fetched again. Applying a page twice is
+//! harmless — every write in [`super::projection`] is an upsert or a
+//! delete keyed by identity.
+//!
+//! ## Recovery is a snapshot, never a repair
+//!
+//! An event this build does not understand is skipped and the cursor
+//! keeps moving. A **known** event that fails to apply means the
+//! projection no longer reflects the journal, and the only sound answer
+//! is to throw it away and take a fresh snapshot. [`catch_up`] does that
+//! once; if the snapshot itself cannot be applied, the error is real and
+//! propagates.
+//!
+//! ## The acknowledgement never blocks anything
+//!
+//! It feeds observability and future retention, not read authorization.
+//! A failing ACK is logged and forgotten — treating it as fatal would
+//! stall synchronization over a signal the protocol explicitly says is
+//! not a prerequisite.
+
+use crate::{
+    error::{AppError, AppResult},
+    remote::{
+        binding::{self, RemoteBinding},
+        client::RemoteClient,
+        dto::{SongItem, SyncPage, SyncSnapshot},
+        projection::{self, Outcome},
+    },
+    state::AppState,
+};
+
+/// Page size for `/sync/changes`. The server caps it at 500; asking for
+/// the maximum keeps a long catch-up to as few round-trips as possible,
+/// and a page is applied in one transaction either way.
+const PAGE_LIMIT: i64 = 500;
+
+/// How many pages a single catch-up will walk before yielding.
+///
+/// Not a correctness bound — the loop stops on `has_more` — but a
+/// runaway guard: a server that always answered `has_more` with the same
+/// cursor would otherwise spin forever holding a lease. Hitting it is
+/// logged, never silent.
+const MAX_PAGES: usize = 10_000;
+
+/// How many missing tracks to fetch after a catch-up. Metadata is a
+/// display concern, so it is filled opportunistically rather than
+/// blocking the cursor.
+const TRACK_BACKFILL_LIMIT: usize = 200;
+
+/// What a synchronization pass did, for the UI and the logs.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub struct SyncReport {
+    pub applied: usize,
+    pub ignored: usize,
+    pub pages: usize,
+    pub cursor: i64,
+    /// Whether the pass had to fall back to a fresh snapshot.
+    pub resnapshotted: bool,
+}
+
+/// Bring the projection up to date, bootstrapping first if it has never
+/// been.
+///
+/// The entry point for every trigger: sign-in, app start, the socket
+/// wake-up and the periodic pass all call this.
+pub async fn sync_now(state: &AppState) -> AppResult<SyncReport> {
+    let Some(client) = RemoteClient::try_build(state).await? else {
+        // Not bound, signed out, or bound to a server with no journal.
+        // All three are ordinary states, not failures.
+        return Ok(SyncReport::default());
+    };
+
+    let profile_id = state.require_profile_id().await?;
+    let binding = read_binding(state, profile_id).await?;
+
+    match binding.bootstrapped_at {
+        None => {
+            let cursor = bootstrap(state, profile_id, &client).await?;
+            Ok(SyncReport {
+                cursor,
+                resnapshotted: true,
+                ..Default::default()
+            })
+        }
+        Some(_) => catch_up(state, profile_id, &client, binding.identity.cursor().unwrap_or(0)).await,
+    }
+}
+
+async fn read_binding(state: &AppState, profile_id: i64) -> AppResult<RemoteBinding> {
+    let pool = state.require_profile_pool_for(Some(profile_id)).await?;
+    let mut conn = pool.acquire().await?;
+    binding::read(&mut conn)
+        .await?
+        .ok_or_else(|| AppError::Other("this profile is not bound to a server".into()))
+}
+
+/// Replace the whole projection with one writer-consistent snapshot.
+///
+/// The fetch happens outside the transaction and the write inside it, so
+/// a slow download never holds the database open, and the projection is
+/// never observable half-replaced.
+pub async fn bootstrap(
+    state: &AppState,
+    profile_id: i64,
+    client: &RemoteClient,
+) -> AppResult<i64> {
+    let snapshot: SyncSnapshot = client
+        .send_json(client.get("/api/v2/sync/snapshot"))
+        .await
+        .map_err(|failure| AppError::Other(format!("could not fetch the snapshot: {failure}")))?;
+
+    let cursor = snapshot.cursor;
+    {
+        let pool = state.require_profile_pool_for(Some(profile_id)).await?;
+        let mut tx = pool.begin().await?;
+        projection::apply_snapshot(&mut tx, &snapshot).await?;
+        // Pinned, not `MAX`-ed: a snapshot is authoritative even when its
+        // cursor is lower than a position reached before the projection
+        // was discarded — which is exactly the recovery case.
+        binding::mark_bootstrapped(&mut tx, cursor).await?;
+        tx.commit().await?;
+    }
+
+    acknowledge(state, profile_id, client, cursor).await;
+    Ok(cursor)
+}
+
+/// Walk the journal from `after` to its end.
+pub async fn catch_up(
+    state: &AppState,
+    profile_id: i64,
+    client: &RemoteClient,
+    after: i64,
+) -> AppResult<SyncReport> {
+    let mut report = SyncReport {
+        cursor: after,
+        ..Default::default()
+    };
+
+    loop {
+        if report.pages >= MAX_PAGES {
+            tracing::warn!(
+                cursor = report.cursor,
+                pages = report.pages,
+                "stopping a catch-up that never reported the end of the journal"
+            );
+            break;
+        }
+
+        let page: SyncPage = client
+            .send_json(client.get(&format!(
+                "/api/v2/sync/changes?after={}&limit={PAGE_LIMIT}",
+                report.cursor
+            )))
+            .await
+            .map_err(|failure| AppError::Other(format!("could not fetch changes: {failure}")))?;
+
+        report.pages += 1;
+        let has_more = page.has_more;
+        let next_cursor = page.next_cursor;
+
+        let pool = state.require_profile_pool_for(Some(profile_id)).await?;
+        let mut tx = pool.begin().await?;
+
+        let mut failed = false;
+        for change in &page.changes {
+            match projection::apply_change(&mut tx, change).await {
+                Ok(Outcome::Applied) => report.applied += 1,
+                Ok(Outcome::Ignored) => report.ignored += 1,
+                Err(error) => {
+                    // A known event we could not apply. The projection can
+                    // no longer be trusted, so nothing from this page is
+                    // kept and the cursor does not move.
+                    tracing::warn!(
+                        cursor = change.cursor,
+                        entity = %change.entity_type,
+                        action = %change.action,
+                        error = %error,
+                        "a known event could not be applied; taking a fresh snapshot"
+                    );
+                    failed = true;
+                    break;
+                }
+            }
+        }
+
+        if failed {
+            tx.rollback().await?;
+            let cursor = bootstrap(state, profile_id, client).await?;
+            return Ok(SyncReport {
+                cursor,
+                resnapshotted: true,
+                pages: report.pages,
+                ..Default::default()
+            });
+        }
+
+        // The page and the cursor commit together. A crash here either
+        // keeps both or loses both, so the same page is simply fetched
+        // again — and re-applying it is harmless.
+        binding::advance_cursor(&mut tx, next_cursor).await?;
+        tx.commit().await?;
+        report.cursor = next_cursor;
+
+        if !has_more {
+            break;
+        }
+    }
+
+    acknowledge(state, profile_id, client, report.cursor).await;
+    backfill_missing_tracks(state, profile_id, client).await;
+    Ok(report)
+}
+
+/// Tell the server how far this device has got.
+///
+/// Deliberately infallible from the caller's point of view: a failed ACK
+/// is an observability gap, never a reason to stop synchronizing.
+async fn acknowledge(state: &AppState, profile_id: i64, client: &RemoteClient, cursor: i64) {
+    let Ok(binding) = read_binding(state, profile_id).await else {
+        return;
+    };
+    let Some(device_id) = binding.identity.device_id() else {
+        return;
+    };
+
+    // A plain request, not a `mutate`: the acknowledgement is not a
+    // journalled mutation, so it carries no operation identifier. Minting
+    // a fresh one on every pass would be worse than useless — it would
+    // suggest an idempotency the endpoint does not implement.
+    let outcome = client
+        .send_ok(
+            client
+                .request(reqwest::Method::PUT, "/api/v2/sync/ack")
+                .json(&serde_json::json!({ "device_id": device_id, "cursor": cursor })),
+        )
+        .await;
+
+    if let Err(failure) = outcome {
+        tracing::debug!(%failure, cursor, "acknowledgement failed; continuing anyway");
+    }
+}
+
+/// Fetch metadata for identifiers the journal referenced but never
+/// described.
+///
+/// Best-effort by design. The projection is already correct without it —
+/// ordering and identity are stored — and a failure here costs a
+/// placeholder row, not a wrong one.
+async fn backfill_missing_tracks(state: &AppState, profile_id: i64, client: &RemoteClient) {
+    let missing = {
+        let Ok(pool) = state.require_profile_pool_for(Some(profile_id)).await else {
+            return;
+        };
+        let Ok(mut conn) = pool.acquire().await else {
+            return;
+        };
+        match projection::missing_track_ids(&mut conn).await {
+            Ok(ids) => ids,
+            Err(error) => {
+                tracing::debug!(%error, "could not list tracks awaiting metadata");
+                return;
+            }
+        }
+    };
+    if missing.is_empty() {
+        return;
+    }
+
+    let total = missing.len();
+    let mut fetched = Vec::new();
+    for id in missing.into_iter().take(TRACK_BACKFILL_LIMIT) {
+        match client
+            .send_json::<SongItem>(client.get(&format!("/api/v2/tracks/{id}")))
+            .await
+        {
+            Ok(song) => fetched.push(song),
+            // A track the account can no longer see is not an error: it
+            // stays a placeholder, which is the honest rendering.
+            Err(failure) => tracing::debug!(%failure, track = %id, "track metadata unavailable"),
+        }
+    }
+
+    if total > TRACK_BACKFILL_LIMIT {
+        tracing::info!(
+            total,
+            fetched = fetched.len(),
+            "more tracks await metadata than one pass fetches; the rest follow next pass"
+        );
+    }
+
+    let Ok(pool) = state.require_profile_pool_for(Some(profile_id)).await else {
+        return;
+    };
+    let Ok(mut tx) = pool.begin().await else { return };
+    for song in &fetched {
+        if let Err(error) = projection::cache_song(&mut tx, song).await {
+            tracing::debug!(%error, "could not cache track metadata");
+            return;
+        }
+    }
+    let _ = tx.commit().await;
+}
diff --git a/src-tauri/crates/app/src/remote/testdata/changes.json b/src-tauri/crates/app/src/remote/testdata/changes.json
new file mode 100644
index 00000000..2fbc0993
--- /dev/null
+++ b/src-tauri/crates/app/src/remote/testdata/changes.json
@@ -0,0 +1,64 @@
+{
+  "changes": [
+    {
+      "cursor": 1,
+      "event_id": "338d2144-baaa-4877-99e5-77dceadf7de7",
+      "operation_id": "7fdf499f-89b3-42f2-a633-55e8eed01dd3",
+      "origin_device_id": null,
+      "entity_type": "playlist",
+      "entity_id": "31be1c98-3984-40ff-8352-73fc6e2c29b5",
+      "action": "upsert",
+      "payload": {
+        "id": "31be1c98-3984-40ff-8352-73fc6e2c29b5",
+        "name": "Mix",
+        "track_ids": []
+      },
+      "changed_at": 1786369482470
+    },
+    {
+      "cursor": 2,
+      "event_id": "cd9e2db4-bb47-436a-aeed-b1766f98fc30",
+      "operation_id": "b2f6bbfd-b59f-4170-83c4-28fcdc0d4240",
+      "origin_device_id": null,
+      "entity_type": "playlist",
+      "entity_id": "31be1c98-3984-40ff-8352-73fc6e2c29b5",
+      "action": "upsert",
+      "payload": {
+        "comment": "des notes",
+        "id": "31be1c98-3984-40ff-8352-73fc6e2c29b5",
+        "name": "Mix renommee",
+        "public": true,
+        "track_ids": []
+      },
+      "changed_at": 1786369482481
+    },
+    {
+      "cursor": 3,
+      "event_id": "1cc5f4f5-dabe-40ca-85fc-78aa9b49c8c8",
+      "operation_id": "bb155f83-35a1-488d-bbc3-fb26c2f1eeb1",
+      "origin_device_id": null,
+      "entity_type": "playlist",
+      "entity_id": "170c2731-487e-495e-a97a-4281f961c9f1",
+      "action": "upsert",
+      "payload": {
+        "id": "170c2731-487e-495e-a97a-4281f961c9f1",
+        "name": "A supprimer",
+        "track_ids": []
+      },
+      "changed_at": 1786369482485
+    },
+    {
+      "cursor": 4,
+      "event_id": "65cdcaae-a894-48ec-b387-0fcb4e998a7a",
+      "operation_id": "4e3e9ec2-da99-45f1-a6f6-5ef04c682bbf",
+      "origin_device_id": null,
+      "entity_type": "playlist",
+      "entity_id": "170c2731-487e-495e-a97a-4281f961c9f1",
+      "action": "delete",
+      "payload": {},
+      "changed_at": 1786369482488
+    }
+  ],
+  "next_cursor": 4,
+  "has_more": false
+}
\ No newline at end of file
diff --git a/src-tauri/crates/app/src/remote/testdata/snapshot.json b/src-tauri/crates/app/src/remote/testdata/snapshot.json
new file mode 100644
index 00000000..bc61030d
--- /dev/null
+++ b/src-tauri/crates/app/src/remote/testdata/snapshot.json
@@ -0,0 +1,19 @@
+{
+  "cursor": 4,
+  "playlists": [
+    {
+      "id": "31be1c98-3984-40ff-8352-73fc6e2c29b5",
+      "name": "Mix renommee",
+      "comment": "des notes",
+      "public": true,
+      "created_at": 1786369482469,
+      "updated_at": 1786369482481,
+      "songs": []
+    }
+  ],
+  "favorites": [],
+  "ratings": [],
+  "queue": null,
+  "history": [],
+  "shares": []
+}
\ No newline at end of file
diff --git a/src-tauri/migrations/profile/20260810140000_remote_track_cache.sql b/src-tauri/migrations/profile/20260810140000_remote_track_cache.sql
new file mode 100644
index 00000000..faaa0597
--- /dev/null
+++ b/src-tauri/migrations/profile/20260810140000_remote_track_cache.sql
@@ -0,0 +1,47 @@
+-- Cached metadata for the server's tracks. RFC-005.
+--
+-- The projection references tracks by remote identifier, and the two
+-- feeds that populate it are asymmetric:
+--
+--   * `GET /api/v2/sync/snapshot` returns playlists and the queue with
+--     FULL song objects — title, artist, album, duration, artwork.
+--   * `GET /api/v2/sync/changes` carries a playlist upsert as an ordered
+--     list of `track_ids` and nothing else.
+--
+-- So a playlist edited after the bootstrap would arrive as identifiers
+-- with no way to render them. This table keeps what the snapshot handed
+-- us for free, and the apply path fetches `GET /api/v2/tracks/{id}` only
+-- for identifiers it has never seen.
+--
+-- Purely a cache: it is derived from the server and can be dropped and
+-- refilled at any time. It deliberately does NOT reference `track` —
+-- these rows describe content that exists only on the server, and
+-- matching them to local files is out of scope (RFC-005 §Decision 1).
+--
+-- Nullable almost everywhere because a third-party server fills in far
+-- less than ours does, and a NOT NULL here would turn a sparse catalogue
+-- into a failed sync. `title` and `duration_ms` are the two the UI
+-- cannot render without.
+
+CREATE TABLE remote_track (
+    remote_id    TEXT    PRIMARY KEY,
+    title        TEXT    NOT NULL,
+    artist       TEXT,
+    album        TEXT,
+    album_id     TEXT,
+    duration_ms  INTEGER NOT NULL DEFAULT 0 CHECK (duration_ms >= 0),
+    track_no     INTEGER,
+    disc_no      INTEGER,
+    year         INTEGER,
+    genre        TEXT,
+    suffix       TEXT,
+    bitrate      INTEGER,
+    size         INTEGER,
+    artwork_hash TEXT,
+    library_id   TEXT,
+    -- When we last refreshed this row from the server. Lets a future
+    -- pass expire stale entries without having to re-fetch everything.
+    cached_at    INTEGER NOT NULL
+);
+
+CREATE INDEX idx_remote_track_album ON remote_track (album_id);
diff --git a/src/lib/tauri/remoteServer.ts b/src/lib/tauri/remoteServer.ts
index 39582801..6d3c4df5 100644
--- a/src/lib/tauri/remoteServer.ts
+++ b/src/lib/tauri/remoteServer.ts
@@ -98,3 +98,31 @@ export function remoteSignOut(): Promise<RemoteStatus> {
 export function remoteForgetServer(): Promise<RemoteStatus> {
   return invoke<RemoteStatus>("remote_forget_server");
 }
+
+export interface RemoteSyncReport {
+  applied: number;
+  /**
+   * Events this build did not understand and skipped. Non-zero is not a
+   * fault — it means the server is newer than this client.
+   */
+  ignored: number;
+  pages: number;
+  cursor: number;
+  /**
+   * The pass fell back to a full snapshot, either because it was the
+   * first one or because an event could not be applied.
+   */
+  resnapshotted: boolean;
+}
+
+/**
+ * Bring the cached remote library up to date, bootstrapping if it never
+ * has been.
+ *
+ * Resolves to an all-zero report when the profile is unbound, signed
+ * out, or bound to a server without a journal — all ordinary states, not
+ * errors.
+ */
+export function remoteSyncNow(): Promise<RemoteSyncReport> {
+  return invoke<RemoteSyncReport>("remote_sync_now");
+}

From e5e65cd003e44ab87e2fd2aff78122a61c069e2b Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Mon, 10 Aug 2026 16:00:07 +0200
Subject: [PATCH 05/14] feat(remote): wake up on the journal socket instead of
 only polling

Subscribes to GET /sync/socket and asks the journal on every notice.
The frame's cursor is deliberately not compared against ours before
fetching: it is a hint, an empty page is cheap, and trusting the hint
enough to skip the fetch would lose an event to a stale or reordered
frame. Reconnecting triggers the same fetch, since whatever happened
while we were away arrived through no frame at all.

That makes the whole module an optimisation rather than a mechanism.
Removed, a periodic pass still converges; what it buys is that an edit
made on another device shows up in seconds.

The UI event only fires when something actually changed, so an idle
account does not re-render the library on a timer. Plain ws:// to a
non-loopback host warns once per session -- self-hosted LAN is
legitimate, but the access token rides in the upgrade headers.

The rustls provider is installed here too rather than leaning on the v1
block: the two features are independent, and a sync_v2-only build would
otherwise panic on its first wss:// upgrade.

Claude-Session: https://claude.ai/code/session_01N9WXrurarkoiT2jgimvyj1
---
 src-tauri/crates/app/src/lib.rs           |  21 ++
 src-tauri/crates/app/src/remote/mod.rs    |   6 +
 src-tauri/crates/app/src/remote/socket.rs | 311 ++++++++++++++++++++++
 3 files changed, 338 insertions(+)
 create mode 100644 src-tauri/crates/app/src/remote/socket.rs

diff --git a/src-tauri/crates/app/src/lib.rs b/src-tauri/crates/app/src/lib.rs
index 41fe2c35..5d86aebc 100644
--- a/src-tauri/crates/app/src/lib.rs
+++ b/src-tauri/crates/app/src/lib.rs
@@ -245,6 +245,27 @@ pub fn run() {
                 sync::ws::spawn(app.handle().clone());
             }
 
+            // Remote source wake-up socket (RFC-005). Independent of the
+            // v1 block above and gated separately, so a build can carry
+            // either protocol, both, or neither.
+            #[cfg(feature = "sync_v2")]
+            {
+                // rustls 0.23 needs a process-wide CryptoProvider before
+                // the first TLS handshake, and `connect_async` is what
+                // trips it (reqwest configures its own per-connector).
+                // Installing it here too rather than relying on the v1
+                // block: the two features are independent, and a
+                // `sync_v2`-only build would otherwise panic on the
+                // first wss:// upgrade. A second call returns Err, which
+                // is harmless.
+                let _ = rustls::crypto::ring::default_provider().install_default();
+
+                // The subscriber owns its own gates — unbound profile,
+                // signed out, offline, no journal — so spawning it
+                // unconditionally costs an idle loop and nothing else.
+                remote::socket::spawn(app.handle().clone());
+            }
+
             // Audio engine lives alongside AppState. `new` spawns the cpal
             // output thread (silence callback) and the decoder thread, both
             // receiving a clone of the AppHandle so they can emit Tauri
diff --git a/src-tauri/crates/app/src/remote/mod.rs b/src-tauri/crates/app/src/remote/mod.rs
index 84f6250b..41400a9e 100644
--- a/src-tauri/crates/app/src/remote/mod.rs
+++ b/src-tauri/crates/app/src/remote/mod.rs
@@ -44,6 +44,11 @@
 //!   journal, acknowledge, and recover by re-snapshotting when a known
 //!   event cannot be applied.
 //!
+//! - [`socket`] — the wake-up channel. Pure latency: it carries notice
+//!   that a newer cursor may exist, never state, so removing it would
+//!   leave the projection correct and merely slower to notice another
+//!   device's edits.
+//!
 //! - [`probe`] — server flavour detection. Decides whether the optional
 //!   [`SyncProvider`](#capabilities) surface exists at all.
 //!
@@ -69,5 +74,6 @@ pub mod client;
 pub mod dto;
 pub mod probe;
 pub mod projection;
+pub mod socket;
 pub mod sync;
 pub mod tokens;
diff --git a/src-tauri/crates/app/src/remote/socket.rs b/src-tauri/crates/app/src/remote/socket.rs
new file mode 100644
index 00000000..44ca0095
--- /dev/null
+++ b/src-tauri/crates/app/src/remote/socket.rs
@@ -0,0 +1,311 @@
+//! The wake-up socket.
+//!
+//! `GET /api/v2/sync/socket?after=<cursor>` upgrades to a WebSocket that
+//! sends `{"cursor": 43}` when the account's journal grows.
+//!
+//! ## It carries notice, never state
+//!
+//! The frames are a hint that a newer cursor may exist. Everything the
+//! client actually applies comes from `/sync/changes`, and the durable
+//! cursor — not socket delivery — is the guarantee. That is why a
+//! reconnect, a timeout or a frame we cannot parse all lead to the same
+//! place as a notice: ask the journal. A dropped frame therefore costs
+//! latency, never correctness.
+//!
+//! Which also means this whole module is an optimisation. With it
+//! removed, [`super::sync::sync_now`] on a timer still converges; what
+//! the socket buys is that an edit made on a phone shows up in seconds
+//! instead of at the next poll.
+//!
+//! ## Reconnection
+//!
+//! Exponential backoff, reset after a session that actually delivered
+//! something. An unbound profile, a signed-out one and offline mode are
+//! not failures — the loop idles at the base interval instead of
+//! escalating, because escalating would delay the reconnect that follows
+//! the user signing back in.
+
+use std::time::Duration;
+
+use futures::StreamExt;
+use tauri::{AppHandle, Emitter, Manager};
+use tokio_tungstenite::tungstenite::Message;
+
+use crate::{
+    error::{AppError, AppResult},
+    offline,
+    remote::{binding, client::RemoteClient, sync},
+    state::AppState,
+};
+
+/// Event the frontend listens on to refresh what it shows.
+const SYNCED_EVENT: &str = "remote:synced";
+
+/// Wait between reconnection attempts, and the idle interval when there
+/// is nothing to connect to.
+const BASE_BACKOFF: Duration = Duration::from_secs(5);
+/// Ceiling for the backoff. Five minutes keeps a long outage from
+/// hammering a server that is down, while still recovering promptly once
+/// it returns.
+const MAX_BACKOFF: Duration = Duration::from_secs(300);
+
+/// Start the subscriber. Returns immediately; the loop runs for the
+/// lifetime of the app.
+pub fn spawn(handle: AppHandle) {
+    tauri::async_runtime::spawn(async move {
+        let mut backoff = BASE_BACKOFF;
+        loop {
+            let state = handle.state::<AppState>();
+            match run_session(&handle, state.inner()).await {
+                Ok(delivered) => {
+                    // A session that did some work proves the path is
+                    // healthy; one that returned straight away (no
+                    // binding, offline) proves nothing, so it must not
+                    // reset an escalating backoff either.
+                    backoff = if delivered { BASE_BACKOFF } else { backoff };
+                }
+                Err(error) => {
+                    tracing::debug!(%error, "sync socket session ended");
+                    backoff = (backoff * 2).min(MAX_BACKOFF);
+                }
+            }
+            tokio::time::sleep(backoff).await;
+        }
+    });
+}
+
+/// One connection, from upgrade to close.
+///
+/// `Ok(true)` when the session actually delivered a notice, which is
+/// what tells the caller the path is healthy.
+async fn run_session(handle: &AppHandle, state: &AppState) -> AppResult<bool> {
+    if offline::is_offline() {
+        return Ok(false);
+    }
+    let Some(client) = RemoteClient::try_build(state).await? else {
+        // Unbound, signed out, or a server with no journal.
+        return Ok(false);
+    };
+
+    let cursor = {
+        let profile_id = state.require_profile_id().await?;
+        let pool = state.require_profile_pool_for(Some(profile_id)).await?;
+        let mut conn = pool.acquire().await?;
+        binding::read(&mut conn)
+            .await?
+            .and_then(|b| b.identity.cursor())
+            .unwrap_or(0)
+    };
+
+    let url = ws_url(client.base_url(), cursor)?;
+    if is_cleartext_to_a_remote_host(&url) {
+        // Self-hosted LAN and localhost are legitimate, so this is a
+        // warning rather than a refusal — but the access token rides in
+        // the upgrade headers, so a public host over plain ws:// is
+        // worth saying out loud once per session.
+        tracing::warn!(
+            "sync socket is connecting in cleartext to a non-loopback host; \
+             the access token rides in the upgrade headers unencrypted"
+        );
+    }
+
+    let request = build_request(&url, client.access_token())?;
+    let (stream, _response) = tokio_tungstenite::connect_async(request)
+        .await
+        .map_err(|err| AppError::Other(format!("sync socket upgrade failed: {err}")))?;
+    let (_writer, mut reader) = stream.split();
+
+    // Reconnecting is itself a reason to ask: anything that happened
+    // while we were away arrived through no frame at all.
+    catch_up_and_notify(handle, state).await;
+
+    let mut delivered = false;
+    while let Some(message) = reader.next().await {
+        match message {
+            Ok(Message::Text(text)) => {
+                // The cursor in the frame is deliberately not compared
+                // against ours. It is a hint, and `/sync/changes` is
+                // cheap when there is nothing new: one request answering
+                // an empty page. Trusting the hint enough to skip the
+                // fetch would make a stale or reordered frame lose an
+                // event.
+                let _ = notice_cursor(&text);
+                delivered = true;
+                catch_up_and_notify(handle, state).await;
+            }
+            Ok(Message::Close(_)) => break,
+            // Ping and Pong are handled by the library; anything else is
+            // not part of this protocol and is ignored rather than
+            // treated as an error.
+            Ok(_) => {}
+            Err(error) => {
+                return Err(AppError::Other(format!("sync socket read failed: {error}")));
+            }
+        }
+    }
+
+    Ok(delivered)
+}
+
+async fn catch_up_and_notify(handle: &AppHandle, state: &AppState) {
+    match sync::sync_now(state).await {
+        Ok(report) => {
+            // Only wake the UI when something actually changed. Emitting
+            // on every empty page would re-render the library on a timer
+            // for no reason.
+            if report.applied > 0 || report.resnapshotted {
+                let _ = handle.emit(SYNCED_EVENT, report.cursor);
+            }
+        }
+        Err(error) => tracing::debug!(%error, "catch-up after a socket notice failed"),
+    }
+}
+
+/// Read the cursor out of a notice frame.
+///
+/// A frame we cannot parse is not fatal — the caller fetches regardless
+/// — so this returns `None` rather than an error.
+fn notice_cursor(text: &str) -> Option<i64> {
+    serde_json::from_str::<serde_json::Value>(text)
+        .ok()?
+        .get("cursor")?
+        .as_i64()
+}
+
+/// `http(s)://host` → `ws(s)://host/api/v2/sync/socket?after=N`.
+///
+/// Built by string surgery on the scheme rather than through `Url`,
+/// which is what the v1 subscriber settled on: re-parsing risks
+/// re-encoding a proxy path, and the host's original case must survive
+/// for a case-sensitive proxy.
+fn ws_url(base: &str, after: i64) -> AppResult<String> {
+    let trimmed = base.trim_end_matches('/');
+    let lowered = trimmed.to_ascii_lowercase();
+    let body = if let Some(rest) = lowered.strip_prefix("https://") {
+        format!("wss://{}", &trimmed[8..8 + rest.len()])
+    } else if let Some(rest) = lowered.strip_prefix("http://") {
+        // nosemgrep: detect-insecure-websocket -- plain ws:// is
+        // intentional for self-hosted LAN and localhost; a non-loopback
+        // host is warned about at connect time.
+        format!("ws://{}", &trimmed[7..7 + rest.len()])
+    } else {
+        return Err(AppError::Other(format!(
+            "server URL must start with http:// or https:// (got '{base}')"
+        )));
+    };
+    Ok(format!("{body}/api/v2/sync/socket?after={after}"))
+}
+
+/// Whether this is plain `ws://` to something other than this machine.
+///
+/// An unparseable URL counts as remote: warning once about an odd value
+/// beats silently treating it as safe.
+fn is_cleartext_to_a_remote_host(ws_url: &str) -> bool {
+    if !ws_url.starts_with("ws://") {
+        return false;
+    }
+    let Ok(parsed) = url::Url::parse(ws_url) else {
+        return true;
+    };
+    match parsed.host() {
+        Some(url::Host::Domain(host)) => !host.eq_ignore_ascii_case("localhost"),
+        Some(url::Host::Ipv4(addr)) => !addr.is_loopback(),
+        Some(url::Host::Ipv6(addr)) => !addr.is_loopback(),
+        None => true,
+    }
+}
+
+/// The upgrade request, with the access token attached.
+///
+/// The server authenticates the upgrade with the same Bearer header as
+/// REST, and its middleware reads it before routing — so the token has
+/// to ride on the upgrade itself. There is no in-band hello frame.
+fn build_request(
+    ws_url: &str,
+    access_token: &str,
+) -> AppResult<tokio_tungstenite::tungstenite::handshake::client::Request> {
+    use tokio_tungstenite::tungstenite::client::IntoClientRequest;
+    let mut request = ws_url
+        .into_client_request()
+        .map_err(|err| AppError::Other(format!("sync socket request build: {err}")))?;
+    let value = format!("Bearer {access_token}");
+    request.headers_mut().insert(
+        "Authorization",
+        value
+            .parse()
+            .map_err(|err| AppError::Other(format!("invalid bearer header: {err}")))?,
+    );
+    Ok(request)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn https_upgrades_to_wss_and_http_to_ws() {
+        assert_eq!(
+            ws_url("https://music.example", 12).unwrap(),
+            "wss://music.example/api/v2/sync/socket?after=12"
+        );
+        assert_eq!(
+            ws_url("http://localhost:4533", 0).unwrap(),
+            "ws://localhost:4533/api/v2/sync/socket?after=0"
+        );
+    }
+
+    #[test]
+    fn a_trailing_slash_does_not_double_up_the_path() {
+        assert_eq!(
+            ws_url("https://music.example/", 1).unwrap(),
+            "wss://music.example/api/v2/sync/socket?after=1"
+        );
+    }
+
+    #[test]
+    fn the_hosts_case_survives_for_a_case_sensitive_proxy() {
+        assert!(ws_url("https://Music.Example/Path", 1)
+            .unwrap()
+            .starts_with("wss://Music.Example/Path"));
+    }
+
+    #[test]
+    fn a_scheme_we_cannot_upgrade_is_an_error() {
+        assert!(ws_url("ftp://music.example", 0).is_err());
+        assert!(ws_url("music.example", 0).is_err());
+    }
+
+    #[test]
+    fn cleartext_is_only_flagged_when_it_leaves_the_machine() {
+        assert!(!is_cleartext_to_a_remote_host(
+            "ws://localhost:4533/api/v2/sync/socket?after=0"
+        ));
+        assert!(!is_cleartext_to_a_remote_host(
+            "ws://127.0.0.1:4533/api/v2/sync/socket?after=0"
+        ));
+        assert!(!is_cleartext_to_a_remote_host("ws://[::1]:4533/x"));
+        assert!(is_cleartext_to_a_remote_host("ws://nas.lan/x"));
+        assert!(is_cleartext_to_a_remote_host("ws://198.51.100.7/x"));
+        // Encrypted is never flagged, wherever it points.
+        assert!(!is_cleartext_to_a_remote_host("wss://music.example/x"));
+    }
+
+    #[test]
+    fn an_unparseable_url_is_treated_as_remote() {
+        assert!(is_cleartext_to_a_remote_host("ws://"));
+    }
+
+    #[test]
+    fn a_notice_frame_yields_its_cursor() {
+        assert_eq!(notice_cursor(r#"{"cursor": 43}"#), Some(43));
+    }
+
+    #[test]
+    fn a_frame_we_cannot_read_is_not_fatal() {
+        // The caller fetches regardless, so an unreadable frame costs
+        // nothing but the parse attempt.
+        assert_eq!(notice_cursor("not json"), None);
+        assert_eq!(notice_cursor(r#"{"other": 1}"#), None);
+        assert_eq!(notice_cursor(r#"{"cursor": "43"}"#), None);
+    }
+}

From e03756e575015bc9d5c5d68ac6272de0c8fc4b55 Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Mon, 10 Aug 2026 16:17:04 +0200
Subject: [PATCH 06/14] feat(remote): queue local changes and push them back as
 replayable calls

The write half. Each queued entry is a business call the drain re-issues
verbatim under its operation identifier, so a lost response can be sent
again without applying the change twice.

Order is the constraint that shapes it. Strict FIFO, and the first
retryable failure ends the pass so nothing overtakes what it depends on.
A permanent failure is the exception -- it can never succeed, so that
entry is marked and the drain continues rather than deadlocking every
later change behind one bad request.

A playlist created offline has no server identifier, so it gets a
local: placeholder the projection uses as a real key, and it is visible
and editable immediately. Resolving it taught two things the tests now
pin. The row has to be copied, re-pointed and dropped rather than
renamed: a primary key cannot be updated out from under the rows
referencing it, so renaming first orphans the tracks and re-pointing
first names a parent that does not exist. That was a real foreign-key
failure, caught only because the test database has the constraint on.
And a snapshot must not delete a placeholder playlist -- the server has
never heard of it, so its snapshot is no evidence that it was deleted,
and wiping it would destroy something the user made offline.

Rewriting a queued payload is the one exception to entry immutability
and it is sound for a narrow reason: FIFO guarantees an entry sitting
behind an unlanded creation has never been presented, so there is no
fingerprint for it to conflict with.

Clearing a playlist comment is not expressible. The server coalesces a
null onto the current value, so "leave it" and "empty it" are the same
request; the mutation type says so instead of pretending otherwise.

Claude-Session: https://claude.ai/code/session_01N9WXrurarkoiT2jgimvyj1
---
 .../rfcs/RFC-005-remote-source-and-sync-v2.md |  32 +
 src-tauri/crates/app/src/remote/drain.rs      | 289 ++++++++
 src-tauri/crates/app/src/remote/mod.rs        |   9 +
 src-tauri/crates/app/src/remote/mutation.rs   | 640 ++++++++++++++++++
 src-tauri/crates/app/src/remote/projection.rs |  59 +-
 src-tauri/crates/app/src/remote/sync.rs       |  11 +
 6 files changed, 1038 insertions(+), 2 deletions(-)
 create mode 100644 src-tauri/crates/app/src/remote/drain.rs
 create mode 100644 src-tauri/crates/app/src/remote/mutation.rs

diff --git a/docs/rfcs/RFC-005-remote-source-and-sync-v2.md b/docs/rfcs/RFC-005-remote-source-and-sync-v2.md
index 07bfc6b4..140ea498 100644
--- a/docs/rfcs/RFC-005-remote-source-and-sync-v2.md
+++ b/docs/rfcs/RFC-005-remote-source-and-sync-v2.md
@@ -193,6 +193,38 @@ Both are permanent: a retry cannot change the outcome. The queue marks such an
 entry as failed and surfaces it, instead of retrying forever. Only 5xx, 429 and
 transport errors are retried.
 
+**Order is load-bearing.** Strict FIFO, and the first retryable failure ends the
+pass so nothing overtakes what it depends on. A permanent failure is the
+exception: it can never succeed, so that entry is marked and the drain moves on
+rather than deadlocking every later change behind it.
+
+**Creating something the server has not named yet.** A playlist created offline
+has no server identifier, so it gets a local placeholder — `local:<uuid>` —
+which the projection uses as a real key, making it visible and editable
+immediately. When the creation lands, the placeholder is resolved in three
+places: the projection row, its ordered tracks, and any mutation still queued
+behind it.
+
+Two consequences that are easy to get wrong:
+
+- The row is **copied, re-pointed, then dropped**, never renamed in place. A
+  primary key cannot be updated out from under the rows referencing it —
+  renaming first orphans the tracks, re-pointing first names a parent that does
+  not exist. Either order violates the foreign key.
+- A snapshot **must not delete a placeholder playlist**. The server has never
+  heard of it, so its snapshot cannot be evidence that it was deleted; wiping it
+  would destroy a playlist the user made offline while its creation sat queued.
+
+Rewriting those queued payloads is the single exception to entry immutability,
+and it is sound for a specific reason: FIFO guarantees an entry behind an
+unlanded creation has never been presented to the server, so no fingerprint
+exists for it to conflict with.
+
+**What the API cannot express.** Clearing a playlist comment. The server applies
+`COALESCE(?, comment)`, so a null comment keeps the current one — "leave it
+alone" and "empty it" are the same request. The mutation type reflects that
+rather than pretending otherwise.
+
 ## Decision 8 — v2 lands beside v1, not on top of it
 
 The v1 surface (~12 400 lines across `sync/`, `commands/sync.rs`,
diff --git a/src-tauri/crates/app/src/remote/drain.rs b/src-tauri/crates/app/src/remote/drain.rs
new file mode 100644
index 00000000..69665a6f
--- /dev/null
+++ b/src-tauri/crates/app/src/remote/drain.rs
@@ -0,0 +1,289 @@
+//! Pushing the outbound queue to the server.
+//!
+//! Walks [`super::mutation`] entries in order and turns each into the
+//! business call it stands for, stamped with its operation identifier so
+//! a lost response can be re-sent without applying the change twice.
+//!
+//! ## Why the pass stops on a transient failure
+//!
+//! Order is load-bearing: an edit must never overtake the creation it
+//! depends on. So the first entry that might still succeed ends the
+//! pass, and everything behind it waits for the next one. A *permanent*
+//! failure cannot succeed however long we wait, so that entry is marked
+//! and the drain moves on — otherwise one bad request would deadlock
+//! every later change behind it, forever.
+
+use crate::{
+    error::AppResult,
+    offline,
+    remote::{
+        client::{FailureKind, RemoteClient, RemoteFailure},
+        mutation::{self, Mutation, QueuedMutation},
+    },
+    state::AppState,
+};
+
+/// Entries attempted per pass. A bound rather than a policy: the loop
+/// runs again as soon as it finishes, and a cap keeps one pass from
+/// holding a profile lease across thousands of round-trips.
+const BATCH: i64 = 100;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub struct DrainReport {
+    pub sent: usize,
+    /// Entries that can never succeed and were marked as such.
+    pub failed: usize,
+    /// `true` when the pass stopped early on something retryable.
+    pub stopped_early: bool,
+}
+
+/// The reply we care about from a playlist creation: the identifier the
+/// server chose.
+#[derive(Debug, serde::Deserialize)]
+struct CreatedPlaylist {
+    id: String,
+}
+
+/// Push what is queued. Does nothing, successfully, when there is
+/// nothing to push or nowhere to push it.
+pub async fn drain(state: &AppState) -> AppResult<DrainReport> {
+    let mut report = DrainReport::default();
+    if offline::is_offline() {
+        return Ok(report);
+    }
+    let Some(client) = RemoteClient::try_build(state).await? else {
+        return Ok(report);
+    };
+    let profile_id = state.require_profile_id().await?;
+
+    let queued = {
+        let pool = state.require_profile_pool_for(Some(profile_id)).await?;
+        let mut conn = pool.acquire().await?;
+        mutation::pending(&mut conn, BATCH).await?
+    };
+
+    for entry in queued {
+        match send(&client, &entry).await {
+            Ok(created) => {
+                let pool = state.require_profile_pool_for(Some(profile_id)).await?;
+                let mut tx = pool.begin().await?;
+                // The identifier and the entry's removal commit
+                // together. Resolving without removing would re-send a
+                // creation the server has already accepted, under an
+                // identifier whose fingerprint now names a different
+                // playlist — the exact conflict the protocol rejects.
+                if let (
+                    Mutation::CreatePlaylist { local_id, .. },
+                    Some(CreatedPlaylist { id }),
+                ) = (&entry.mutation, &created)
+                {
+                    mutation::resolve_placeholder(&mut tx, local_id, id).await?;
+                }
+                mutation::remove(&mut tx, entry.id).await?;
+                tx.commit().await?;
+                report.sent += 1;
+            }
+            Err(failure) => {
+                let pool = state.require_profile_pool_for(Some(profile_id)).await?;
+                let mut conn = pool.acquire().await?;
+                match failure.kind {
+                    FailureKind::Permanent => {
+                        tracing::warn!(
+                            operation = %entry.operation_id,
+                            kind = entry.mutation.kind(),
+                            %failure,
+                            "a queued change was refused and will not be retried"
+                        );
+                        mutation::mark_failed(&mut conn, entry.id, &failure.to_string()).await?;
+                        report.failed += 1;
+                    }
+                    FailureKind::Transient | FailureKind::Unauthorized => {
+                        mutation::record_attempt(&mut conn, entry.id, &failure.to_string()).await?;
+                        report.stopped_early = true;
+                        return Ok(report);
+                    }
+                }
+            }
+        }
+    }
+
+    Ok(report)
+}
+
+/// Issue one queued change.
+///
+/// Returns the created playlist when the mutation was a creation, since
+/// that is the one case where the server's reply carries something the
+/// caller must keep.
+async fn send(
+    client: &RemoteClient,
+    entry: &QueuedMutation,
+) -> Result<Option<CreatedPlaylist>, RemoteFailure> {
+    let op = &entry.operation_id;
+    match &entry.mutation {
+        Mutation::SetFavorite {
+            entity_type,
+            entity_id,
+            starred,
+        } => {
+            let method = if *starred {
+                reqwest::Method::PUT
+            } else {
+                reqwest::Method::DELETE
+            };
+            let path = format!("/api/v2/favorites/{entity_type}/{entity_id}");
+            client.send_ok(client.mutate(method, &path, op)).await?;
+            Ok(None)
+        }
+
+        Mutation::SetRating {
+            entity_type,
+            entity_id,
+            rating,
+        } => {
+            let path = format!("/api/v2/ratings/{entity_type}/{entity_id}");
+            client
+                .send_ok(
+                    client
+                        .mutate(reqwest::Method::PUT, &path, op)
+                        .json(&serde_json::json!({ "rating": rating })),
+                )
+                .await?;
+            Ok(None)
+        }
+
+        Mutation::ClearRating {
+            entity_type,
+            entity_id,
+        } => {
+            // Clearing is a rating of zero on the same endpoint — the
+            // server turns it into a delete event. There is no DELETE
+            // route for a rating.
+            let path = format!("/api/v2/ratings/{entity_type}/{entity_id}");
+            client
+                .send_ok(
+                    client
+                        .mutate(reqwest::Method::PUT, &path, op)
+                        .json(&serde_json::json!({ "rating": 0 })),
+                )
+                .await?;
+            Ok(None)
+        }
+
+        Mutation::CreatePlaylist {
+            name, track_ids, ..
+        } => {
+            let created: CreatedPlaylist = client
+                .send_json(
+                    client
+                        .mutate(reqwest::Method::POST, "/api/v2/playlists", op)
+                        .json(&serde_json::json!({ "name": name, "track_ids": track_ids })),
+                )
+                .await?;
+            Ok(Some(created))
+        }
+
+        Mutation::UpdatePlaylist {
+            playlist_id,
+            name,
+            comment,
+            public,
+            add,
+            remove_indexes,
+        } => {
+            if mutation::is_placeholder(playlist_id) {
+                // The creation this depends on never landed, so the
+                // server has no such playlist and never will under this
+                // identifier. Permanent, and reported as such rather
+                // than retried against a URL that cannot exist.
+                return Err(RemoteFailure {
+                    kind: FailureKind::Permanent,
+                    status: None,
+                    message: "the playlist this edit belongs to was never created on the server"
+                        .into(),
+                });
+            }
+            let path = format!("/api/v2/playlists/{playlist_id}");
+            let mut body = serde_json::Map::new();
+            // Only the keys that carry an intent. Sending `null` would
+            // mean the same thing to this server — it coalesces — but
+            // omitting them keeps the request honest about what changed.
+            if let Some(name) = name {
+                body.insert("name".into(), serde_json::json!(name));
+            }
+            if let Some(comment) = comment {
+                body.insert("comment".into(), serde_json::json!(comment));
+            }
+            if let Some(public) = public {
+                body.insert("public".into(), serde_json::json!(public));
+            }
+            if !add.is_empty() {
+                body.insert("add".into(), serde_json::json!(add));
+            }
+            if !remove_indexes.is_empty() {
+                body.insert("remove_indexes".into(), serde_json::json!(remove_indexes));
+            }
+            client
+                .send_ok(
+                    client
+                        .mutate(reqwest::Method::PATCH, &path, op)
+                        .json(&serde_json::Value::Object(body)),
+                )
+                .await?;
+            Ok(None)
+        }
+
+        Mutation::DeletePlaylist { playlist_id } => {
+            if mutation::is_placeholder(playlist_id) {
+                // Deleting something the server never received is
+                // already true. Nothing to send, and nothing to retry.
+                return Ok(None);
+            }
+            let path = format!("/api/v2/playlists/{playlist_id}");
+            client
+                .send_ok(client.mutate(reqwest::Method::DELETE, &path, op))
+                .await?;
+            Ok(None)
+        }
+
+        Mutation::Scrobble {
+            track_id,
+            submission,
+            played_at,
+        } => {
+            client
+                .send_ok(
+                    client
+                        .mutate(reqwest::Method::POST, "/api/v2/scrobbles", op)
+                        .json(&serde_json::json!({
+                            "track_id": track_id,
+                            "submission": submission,
+                            "played_at": played_at,
+                        })),
+                )
+                .await?;
+            Ok(None)
+        }
+
+        Mutation::SaveQueue {
+            track_ids,
+            current,
+            position_ms,
+            client: client_name,
+        } => {
+            client
+                .send_ok(
+                    client
+                        .mutate(reqwest::Method::PUT, "/api/v2/queue", op)
+                        .json(&serde_json::json!({
+                            "track_ids": track_ids,
+                            "current": current,
+                            "position_ms": position_ms,
+                            "client": client_name,
+                        })),
+                )
+                .await?;
+            Ok(None)
+        }
+    }
+}
diff --git a/src-tauri/crates/app/src/remote/mod.rs b/src-tauri/crates/app/src/remote/mod.rs
index 41400a9e..03252430 100644
--- a/src-tauri/crates/app/src/remote/mod.rs
+++ b/src-tauri/crates/app/src/remote/mod.rs
@@ -37,6 +37,13 @@
 //! - [`dto`] — the wire shapes, checked against the server's live
 //!   responses rather than against prose.
 //!
+//! - [`mutation`] — the outbound queue. Replayable business calls, each
+//!   pinned to an operation identifier that must never be reused for a
+//!   different intent.
+//!
+//! - [`drain`] — pushes that queue, in order, stopping on anything that
+//!   might still succeed and marking anything that never will.
+//!
 //! - [`projection`] — writing the server's user data into the local
 //!   `remote_*` tables. Pure database work, testable without a network.
 //!
@@ -71,7 +78,9 @@
 pub mod auth;
 pub mod binding;
 pub mod client;
+pub mod drain;
 pub mod dto;
+pub mod mutation;
 pub mod probe;
 pub mod projection;
 pub mod socket;
diff --git a/src-tauri/crates/app/src/remote/mutation.rs b/src-tauri/crates/app/src/remote/mutation.rs
new file mode 100644
index 00000000..03c8ae9e
--- /dev/null
+++ b/src-tauri/crates/app/src/remote/mutation.rs
@@ -0,0 +1,640 @@
+//! The outbound queue: local changes on their way to the server.
+//!
+//! Not generic operations but **replayable business calls**. Each row is
+//! one REST request the drain re-issues verbatim under its
+//! `operation_id`, which the server reads from `X-WaveFlow-Operation-Id`
+//! to recognize a replay instead of applying it twice.
+//!
+//! ## An entry is immutable once queued
+//!
+//! The server fingerprints the action, the target and the normalized
+//! payload behind the operation identifier. Presenting the same
+//! identifier with a different fingerprint is *rejected as a conflict*,
+//! not accepted as a replay. So correcting a gesture before the queue
+//! drains — renaming a playlist that is already queued — means enqueuing
+//! a **second** mutation with a new identifier, or merging the two
+//! before enqueueing and minting a fresh one. Editing `payload` in place
+//! while keeping `operation_id` is the one thing this module must never
+//! do.
+//!
+//! The single exception is [`resolve_placeholder`], and it is safe for a
+//! reason worth stating: it only rewrites entries that reference a
+//! playlist which does not exist on the server yet, and FIFO order
+//! guarantees those have never been sent.
+//!
+//! ## Ordering, and why a transient failure stops the pass
+//!
+//! Strict FIFO. An update must never overtake the creation it depends
+//! on, so the first transient failure ends the pass and everything
+//! behind it waits. A *permanent* failure is different: it can never
+//! succeed, so the row is marked and the drain moves on rather than
+//! deadlocking the queue behind it.
+//!
+//! ## Creating something that has no server identifier yet
+//!
+//! A playlist created offline cannot know its server identifier. It gets
+//! a local placeholder — `local:<uuid>` — which the projection uses as a
+//! real key, so the playlist is visible and editable immediately. When
+//! the creation finally lands, [`resolve_placeholder`] rewrites the
+//! projection and any still-queued mutation that named it.
+
+use serde::{Deserialize, Serialize};
+use sqlx::{Row, SqliteConnection};
+use uuid::Uuid;
+
+use crate::error::AppResult;
+
+/// Prefix marking an identifier this device invented while offline.
+/// Server identifiers are UUIDs, so the two can never collide.
+pub const PLACEHOLDER_PREFIX: &str = "local:";
+
+/// Whether an identifier is still waiting for the server to name it.
+pub fn is_placeholder(id: &str) -> bool {
+    id.starts_with(PLACEHOLDER_PREFIX)
+}
+
+/// Mint an identifier for something the server has not seen yet.
+pub fn new_placeholder() -> String {
+    format!("{PLACEHOLDER_PREFIX}{}", Uuid::new_v4())
+}
+
+/// One replayable change.
+///
+/// `kind` is the serde tag *and* a column, so the diagnostics surface
+/// can group a queue without parsing every payload.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub enum Mutation {
+    SetFavorite {
+        entity_type: String,
+        entity_id: String,
+        starred: bool,
+    },
+    /// `rating` is 1..=5; clearing is [`Mutation::ClearRating`] rather
+    /// than a zero, so an accidental default can never read as "clear".
+    SetRating {
+        entity_type: String,
+        entity_id: String,
+        rating: u8,
+    },
+    ClearRating {
+        entity_type: String,
+        entity_id: String,
+    },
+    CreatePlaylist {
+        /// The `local:` identifier the projection already shows.
+        local_id: String,
+        name: String,
+        track_ids: Vec<String>,
+    },
+    /// A field left `None` is unchanged.
+    ///
+    /// Note what cannot be expressed: the server applies
+    /// `COALESCE(?, comment)`, so a null comment keeps the current one.
+    /// **Clearing a comment is not possible through this API** — sending
+    /// `None` and sending "please empty it" are the same request.
+    UpdatePlaylist {
+        playlist_id: String,
+        name: Option<String>,
+        comment: Option<String>,
+        public: Option<bool>,
+        /// Appended after the removals below, matching the order the
+        /// server applies them in.
+        add: Vec<String>,
+        remove_indexes: Vec<usize>,
+    },
+    DeletePlaylist {
+        playlist_id: String,
+    },
+    Scrobble {
+        track_id: String,
+        submission: bool,
+        played_at: i64,
+    },
+    SaveQueue {
+        track_ids: Vec<String>,
+        current: Option<String>,
+        position_ms: i64,
+        client: Option<String>,
+    },
+}
+
+impl Mutation {
+    /// Stable discriminant for the `kind` column.
+    pub fn kind(&self) -> &'static str {
+        match self {
+            Mutation::SetFavorite { .. } => "set_favorite",
+            Mutation::SetRating { .. } => "set_rating",
+            Mutation::ClearRating { .. } => "clear_rating",
+            Mutation::CreatePlaylist { .. } => "create_playlist",
+            Mutation::UpdatePlaylist { .. } => "update_playlist",
+            Mutation::DeletePlaylist { .. } => "delete_playlist",
+            Mutation::Scrobble { .. } => "scrobble",
+            Mutation::SaveQueue { .. } => "save_queue",
+        }
+    }
+
+    /// The playlist placeholder this mutation depends on, if any. Used
+    /// to find the entries a completed creation has to rewrite.
+    pub fn placeholder_dependency(&self) -> Option<&str> {
+        let id = match self {
+            Mutation::CreatePlaylist { local_id, .. } => local_id,
+            Mutation::UpdatePlaylist { playlist_id, .. } => playlist_id,
+            Mutation::DeletePlaylist { playlist_id } => playlist_id,
+            _ => return None,
+        };
+        is_placeholder(id).then_some(id.as_str())
+    }
+}
+
+/// A queued entry as stored.
+#[derive(Debug, Clone)]
+pub struct QueuedMutation {
+    pub id: i64,
+    pub operation_id: String,
+    pub mutation: Mutation,
+    pub attempt_count: i64,
+}
+
+fn now_ms() -> i64 {
+    chrono::Utc::now().timestamp_millis()
+}
+
+/// Queue a change, returning the operation identifier it will be sent
+/// under.
+///
+/// Call this inside the same transaction as the optimistic local write.
+/// A projection updated without a queued mutation silently drops the
+/// user's change; a mutation queued without the projection update makes
+/// the UI lie until the round-trip completes.
+pub async fn enqueue(conn: &mut SqliteConnection, mutation: &Mutation) -> AppResult<String> {
+    let operation_id = Uuid::new_v4().to_string();
+    sqlx::query(
+        "INSERT INTO remote_mutation (operation_id, kind, payload, created_at)
+         VALUES (?, ?, ?, ?)",
+    )
+    .bind(&operation_id)
+    .bind(mutation.kind())
+    .bind(serde_json::to_string(mutation).map_err(|err| {
+        crate::error::AppError::Other(format!("could not serialize a mutation: {err}"))
+    })?)
+    .bind(now_ms())
+    .execute(&mut *conn)
+    .await?;
+    Ok(operation_id)
+}
+
+/// Pending entries, oldest first. Permanently-failed rows are left out —
+/// they are for the diagnostics surface, not for the drain.
+pub async fn pending(conn: &mut SqliteConnection, limit: i64) -> AppResult<Vec<QueuedMutation>> {
+    let rows = sqlx::query(
+        "SELECT id, operation_id, payload, attempt_count
+           FROM remote_mutation
+          WHERE failed_at IS NULL
+          ORDER BY id
+          LIMIT ?",
+    )
+    .bind(limit)
+    .fetch_all(&mut *conn)
+    .await?;
+
+    let mut queued = Vec::with_capacity(rows.len());
+    for row in rows {
+        let payload: String = row.try_get("payload")?;
+        // A payload this build cannot parse is a row written by a newer
+        // one. Skipping it keeps the queue moving; failing the whole
+        // drain would stall every later entry over one unknown shape.
+        match serde_json::from_str::<Mutation>(&payload) {
+            Ok(mutation) => queued.push(QueuedMutation {
+                id: row.try_get("id")?,
+                operation_id: row.try_get("operation_id")?,
+                mutation,
+                attempt_count: row.try_get("attempt_count")?,
+            }),
+            Err(error) => {
+                tracing::warn!(%error, "skipping a queued mutation this build cannot read");
+            }
+        }
+    }
+    Ok(queued)
+}
+
+/// Drop an entry the server has accepted.
+pub async fn remove(conn: &mut SqliteConnection, id: i64) -> AppResult<()> {
+    sqlx::query("DELETE FROM remote_mutation WHERE id = ?")
+        .bind(id)
+        .execute(&mut *conn)
+        .await?;
+    Ok(())
+}
+
+/// Record an attempt that failed but may still succeed later.
+pub async fn record_attempt(conn: &mut SqliteConnection, id: i64, error: &str) -> AppResult<()> {
+    sqlx::query(
+        "UPDATE remote_mutation
+            SET attempt_count = attempt_count + 1, last_attempt_at = ?, last_error = ?
+          WHERE id = ?",
+    )
+    .bind(now_ms())
+    .bind(error)
+    .bind(id)
+    .execute(&mut *conn)
+    .await?;
+    Ok(())
+}
+
+/// Mark an entry that can never succeed.
+///
+/// The server answers `422` both for a malformed payload and for an
+/// operation identifier reused with a different fingerprint. Neither
+/// changes on retry, so the row stops being attempted and is surfaced
+/// instead of spinning forever.
+pub async fn mark_failed(conn: &mut SqliteConnection, id: i64, error: &str) -> AppResult<()> {
+    sqlx::query(
+        "UPDATE remote_mutation
+            SET failed_at = ?, attempt_count = attempt_count + 1,
+                last_attempt_at = ?, last_error = ?
+          WHERE id = ?",
+    )
+    .bind(now_ms())
+    .bind(now_ms())
+    .bind(error)
+    .bind(id)
+    .execute(&mut *conn)
+    .await?;
+    Ok(())
+}
+
+/// Give a created playlist its real identifier, everywhere it is named.
+///
+/// Three places, and missing any one of them breaks something specific:
+/// the projection row itself, its ordered tracks, and any mutation still
+/// queued behind the creation. That last rewrite is the only time a
+/// queued payload is edited, and it is sound because FIFO order
+/// guarantees those entries have never been presented to the server —
+/// so no fingerprint exists for them to conflict with.
+///
+/// The row is **copied, re-pointed and dropped** rather than renamed in
+/// place. A primary key cannot be updated out from under the rows that
+/// reference it — renaming the playlist first orphans its tracks, and
+/// re-pointing the tracks first has them name a parent that does not
+/// exist yet. Either order violates the foreign key; going through a
+/// second row never does.
+pub async fn resolve_placeholder(
+    conn: &mut SqliteConnection,
+    placeholder: &str,
+    remote_id: &str,
+) -> AppResult<()> {
+    sqlx::query(
+        "INSERT INTO remote_playlist
+            (remote_id, name, comment, is_public, created_at, updated_at)
+         SELECT ?, name, comment, is_public, created_at, updated_at
+           FROM remote_playlist WHERE remote_id = ?",
+    )
+    .bind(remote_id)
+    .bind(placeholder)
+    .execute(&mut *conn)
+    .await?;
+    sqlx::query("UPDATE remote_playlist_track SET playlist_remote_id = ? WHERE playlist_remote_id = ?")
+        .bind(remote_id)
+        .bind(placeholder)
+        .execute(&mut *conn)
+        .await?;
+    sqlx::query("DELETE FROM remote_playlist WHERE remote_id = ?")
+        .bind(placeholder)
+        .execute(&mut *conn)
+        .await?;
+
+    let rows = sqlx::query(
+        "SELECT id, payload FROM remote_mutation WHERE failed_at IS NULL ORDER BY id",
+    )
+    .fetch_all(&mut *conn)
+    .await?;
+    for row in rows {
+        let id: i64 = row.try_get("id")?;
+        let payload: String = row.try_get("payload")?;
+        let Ok(mutation) = serde_json::from_str::<Mutation>(&payload) else {
+            continue;
+        };
+        if mutation.placeholder_dependency() != Some(placeholder) {
+            continue;
+        }
+        let rewritten = match mutation {
+            Mutation::UpdatePlaylist {
+                name,
+                comment,
+                public,
+                add,
+                remove_indexes,
+                ..
+            } => Mutation::UpdatePlaylist {
+                playlist_id: remote_id.to_string(),
+                name,
+                comment,
+                public,
+                add,
+                remove_indexes,
+            },
+            Mutation::DeletePlaylist { .. } => Mutation::DeletePlaylist {
+                playlist_id: remote_id.to_string(),
+            },
+            // The creation itself is the row being resolved; it is
+            // removed by the drain on success, so there is nothing to
+            // rewrite.
+            other => other,
+        };
+        sqlx::query("UPDATE remote_mutation SET payload = ? WHERE id = ?")
+            .bind(serde_json::to_string(&rewritten).map_err(|err| {
+                crate::error::AppError::Other(format!("could not serialize a mutation: {err}"))
+            })?)
+            .bind(id)
+            .execute(&mut *conn)
+            .await?;
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use sqlx::sqlite::SqlitePoolOptions;
+    use sqlx::SqlitePool;
+
+    async fn pool() -> SqlitePool {
+        let pool = SqlitePoolOptions::new()
+            .max_connections(1)
+            .connect(":memory:")
+            .await
+            .unwrap();
+        for migration in [
+            include_str!(
+                "../../../../migrations/profile/20260810120000_remote_source_projection.sql"
+            ),
+            include_str!("../../../../migrations/profile/20260810140000_remote_track_cache.sql"),
+        ] {
+            sqlx::raw_sql(migration).execute(&pool).await.unwrap();
+        }
+        pool
+    }
+
+    fn favorite(starred: bool) -> Mutation {
+        Mutation::SetFavorite {
+            entity_type: "track".into(),
+            entity_id: "t1".into(),
+            starred,
+        }
+    }
+
+    #[tokio::test]
+    async fn every_enqueue_draws_its_own_operation_id() {
+        // Two identical gestures are two mutations. Reusing one
+        // identifier for both would make the server treat the second as
+        // a replay of the first and drop it.
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        let first = enqueue(&mut conn, &favorite(true)).await.unwrap();
+        let second = enqueue(&mut conn, &favorite(true)).await.unwrap();
+        assert_ne!(first, second);
+    }
+
+    #[tokio::test]
+    async fn pending_comes_back_in_the_order_it_was_queued() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        enqueue(&mut conn, &favorite(true)).await.unwrap();
+        enqueue(&mut conn, &favorite(false)).await.unwrap();
+
+        let queued = pending(&mut conn, 10).await.unwrap();
+        assert_eq!(queued.len(), 2);
+        assert_eq!(queued[0].mutation, favorite(true));
+        assert_eq!(queued[1].mutation, favorite(false));
+    }
+
+    #[tokio::test]
+    async fn a_permanently_failed_entry_leaves_the_queue_without_blocking_it() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        enqueue(&mut conn, &favorite(true)).await.unwrap();
+        enqueue(&mut conn, &favorite(false)).await.unwrap();
+
+        let queued = pending(&mut conn, 10).await.unwrap();
+        mark_failed(&mut conn, queued[0].id, "422 conflict")
+            .await
+            .unwrap();
+
+        let still_pending = pending(&mut conn, 10).await.unwrap();
+        assert_eq!(still_pending.len(), 1);
+        assert_eq!(still_pending[0].mutation, favorite(false));
+
+        // Still readable for diagnostics, just not for the drain.
+        let failed: i64 =
+            sqlx::query_scalar("SELECT count(*) FROM remote_mutation WHERE failed_at IS NOT NULL")
+                .fetch_one(&mut *conn)
+                .await
+                .unwrap();
+        assert_eq!(failed, 1);
+    }
+
+    #[tokio::test]
+    async fn a_transient_attempt_keeps_the_entry_and_counts_the_try() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        enqueue(&mut conn, &favorite(true)).await.unwrap();
+        let queued = pending(&mut conn, 10).await.unwrap();
+
+        record_attempt(&mut conn, queued[0].id, "503").await.unwrap();
+        record_attempt(&mut conn, queued[0].id, "503").await.unwrap();
+
+        let again = pending(&mut conn, 10).await.unwrap();
+        assert_eq!(again.len(), 1);
+        assert_eq!(again[0].attempt_count, 2);
+    }
+
+    #[tokio::test]
+    async fn a_payload_this_build_cannot_read_is_skipped_not_fatal() {
+        // A row written by a newer build must not stall every entry
+        // behind it.
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        sqlx::query(
+            "INSERT INTO remote_mutation (operation_id, kind, payload, created_at)
+             VALUES ('op-future', 'teleport', '{\"kind\":\"teleport\"}', 0)",
+        )
+        .execute(&mut *conn)
+        .await
+        .unwrap();
+        enqueue(&mut conn, &favorite(true)).await.unwrap();
+
+        let queued = pending(&mut conn, 10).await.unwrap();
+        assert_eq!(queued.len(), 1);
+        assert_eq!(queued[0].mutation, favorite(true));
+    }
+
+    #[tokio::test]
+    async fn resolving_a_placeholder_rewrites_the_projection_and_the_queue() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+
+        // Pinned: this test only proves anything with the constraint on,
+        // and it caught a real ordering bug precisely because it was.
+        let fk: i64 = sqlx::query_scalar("PRAGMA foreign_keys")
+            .fetch_one(&mut *conn)
+            .await
+            .unwrap();
+        assert_eq!(fk, 1, "foreign keys are off; this test proves nothing");
+
+        let local_id = new_placeholder();
+        assert!(is_placeholder(&local_id));
+
+        // The optimistic projection a user sees immediately.
+        sqlx::query("INSERT INTO remote_playlist (remote_id, name) VALUES (?, 'Offline mix')")
+            .bind(&local_id)
+            .execute(&mut *conn)
+            .await
+            .unwrap();
+        sqlx::query("INSERT INTO remote_playlist_track VALUES (?, 0, 't1')")
+            .bind(&local_id)
+            .execute(&mut *conn)
+            .await
+            .unwrap();
+
+        enqueue(
+            &mut conn,
+            &Mutation::CreatePlaylist {
+                local_id: local_id.clone(),
+                name: "Offline mix".into(),
+                track_ids: vec!["t1".into()],
+            },
+        )
+        .await
+        .unwrap();
+        // An edit made before the creation ever reached the server.
+        enqueue(
+            &mut conn,
+            &Mutation::UpdatePlaylist {
+                playlist_id: local_id.clone(),
+                name: Some("Renamed offline".into()),
+                comment: None,
+                public: None,
+                add: vec![],
+                remove_indexes: vec![],
+            },
+        )
+        .await
+        .unwrap();
+
+        resolve_placeholder(&mut conn, &local_id, "server-uuid")
+            .await
+            .unwrap();
+
+        let name: String =
+            sqlx::query_scalar("SELECT name FROM remote_playlist WHERE remote_id = 'server-uuid'")
+                .fetch_one(&mut *conn)
+                .await
+                .unwrap();
+        assert_eq!(name, "Offline mix");
+
+        let tracks: i64 = sqlx::query_scalar(
+            "SELECT count(*) FROM remote_playlist_track WHERE playlist_remote_id = 'server-uuid'",
+        )
+        .fetch_one(&mut *conn)
+        .await
+        .unwrap();
+        assert_eq!(tracks, 1, "the ordered tracks did not follow the rename");
+
+        let queued = pending(&mut conn, 10).await.unwrap();
+        match &queued[1].mutation {
+            Mutation::UpdatePlaylist { playlist_id, .. } => {
+                assert_eq!(
+                    playlist_id, "server-uuid",
+                    "the queued edit still names a playlist the server has never heard of"
+                );
+            }
+            other => panic!("unexpected mutation: {other:?}"),
+        }
+    }
+
+    #[tokio::test]
+    async fn resolving_leaves_unrelated_entries_alone() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        let mine = new_placeholder();
+        let other = new_placeholder();
+
+        enqueue(
+            &mut conn,
+            &Mutation::DeletePlaylist {
+                playlist_id: other.clone(),
+            },
+        )
+        .await
+        .unwrap();
+
+        resolve_placeholder(&mut conn, &mine, "server-uuid")
+            .await
+            .unwrap();
+
+        let queued = pending(&mut conn, 10).await.unwrap();
+        assert_eq!(
+            queued[0].mutation,
+            Mutation::DeletePlaylist {
+                playlist_id: other
+            }
+        );
+    }
+
+    #[test]
+    fn a_server_identifier_is_never_mistaken_for_a_placeholder() {
+        assert!(!is_placeholder("31be1c98-3984-40ff-8352-73fc6e2c29b5"));
+        assert!(is_placeholder(&new_placeholder()));
+    }
+
+    #[test]
+    fn only_playlist_mutations_carry_a_placeholder_dependency() {
+        assert!(favorite(true).placeholder_dependency().is_none());
+        let id = new_placeholder();
+        assert_eq!(
+            Mutation::DeletePlaylist {
+                playlist_id: id.clone()
+            }
+            .placeholder_dependency(),
+            Some(id.as_str())
+        );
+        // A playlist the server already knows is not a dependency.
+        assert!(Mutation::DeletePlaylist {
+            playlist_id: "real-uuid".into()
+        }
+        .placeholder_dependency()
+        .is_none());
+    }
+
+    #[test]
+    fn the_stored_shape_round_trips() {
+        for mutation in [
+            favorite(true),
+            Mutation::SetRating {
+                entity_type: "album".into(),
+                entity_id: "a1".into(),
+                rating: 4,
+            },
+            Mutation::ClearRating {
+                entity_type: "track".into(),
+                entity_id: "t1".into(),
+            },
+            Mutation::Scrobble {
+                track_id: "t1".into(),
+                submission: true,
+                played_at: 1_000,
+            },
+            Mutation::SaveQueue {
+                track_ids: vec!["t1".into()],
+                current: Some("t1".into()),
+                position_ms: 4200,
+                client: Some("WaveFlow".into()),
+            },
+        ] {
+            let json = serde_json::to_string(&mutation).unwrap();
+            assert_eq!(serde_json::from_str::<Mutation>(&json).unwrap(), mutation);
+        }
+    }
+}
diff --git a/src-tauri/crates/app/src/remote/projection.rs b/src-tauri/crates/app/src/remote/projection.rs
index 370ff6c8..a42e534f 100644
--- a/src-tauri/crates/app/src/remote/projection.rs
+++ b/src-tauri/crates/app/src/remote/projection.rs
@@ -71,10 +71,25 @@ fn clamp_rating(rating: i64) -> i64 {
 /// The pending outbound queue is untouched. It holds writes the server
 /// has not seen, so it is the one thing here that is not
 /// reconstructible.
+///
+/// And for the same reason, a playlist still carrying a `local:`
+/// placeholder **survives** the replacement. It exists only here, the
+/// server has never heard of it, so a snapshot cannot possibly be
+/// evidence that it was deleted — wiping it would silently destroy a
+/// playlist the user created offline while its creation sat in the
+/// queue.
 pub async fn apply_snapshot(conn: &mut SqliteConnection, snapshot: &SyncSnapshot) -> AppResult<()> {
+    let placeholder_pattern = format!("{}%", crate::remote::mutation::PLACEHOLDER_PREFIX);
+    for statement in [
+        "DELETE FROM remote_playlist_track WHERE playlist_remote_id NOT LIKE ?",
+        "DELETE FROM remote_playlist WHERE remote_id NOT LIKE ?",
+    ] {
+        sqlx::query(statement)
+            .bind(&placeholder_pattern)
+            .execute(&mut *conn)
+            .await?;
+    }
     for statement in [
-        "DELETE FROM remote_playlist_track",
-        "DELETE FROM remote_playlist",
         "DELETE FROM remote_favorite",
         "DELETE FROM remote_rating",
         "DELETE FROM remote_history",
@@ -1023,6 +1038,46 @@ mod tests {
         assert!(missing_track_ids(&mut conn).await.unwrap().is_empty());
     }
 
+    #[tokio::test]
+    async fn a_snapshot_does_not_destroy_a_playlist_created_offline() {
+        // The creation is still queued, so the server has never heard of
+        // this playlist and its snapshot cannot be evidence that it was
+        // deleted.
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        let local_id = crate::remote::mutation::new_placeholder();
+
+        sqlx::query("INSERT INTO remote_playlist (remote_id, name) VALUES (?, 'Offline mix')")
+            .bind(&local_id)
+            .execute(&mut *conn)
+            .await
+            .unwrap();
+        sqlx::query("INSERT INTO remote_playlist_track VALUES (?, 0, 't1')")
+            .bind(&local_id)
+            .execute(&mut *conn)
+            .await
+            .unwrap();
+
+        let snapshot: SyncSnapshot = serde_json::from_str(r#"{"cursor": 9}"#).unwrap();
+        apply_snapshot(&mut conn, &snapshot).await.unwrap();
+
+        let survived: i64 =
+            sqlx::query_scalar("SELECT count(*) FROM remote_playlist WHERE remote_id = ?")
+                .bind(&local_id)
+                .fetch_one(&mut *conn)
+                .await
+                .unwrap();
+        assert_eq!(survived, 1, "an unsent offline playlist was destroyed");
+
+        let tracks: i64 =
+            sqlx::query_scalar("SELECT count(*) FROM remote_playlist_track WHERE playlist_remote_id = ?")
+                .bind(&local_id)
+                .fetch_one(&mut *conn)
+                .await
+                .unwrap();
+        assert_eq!(tracks, 1, "its tracks went with it");
+    }
+
     #[tokio::test]
     async fn identifiers_from_a_change_event_show_up_as_missing_metadata() {
         // A change carries bare identifiers, so this is the gap the
diff --git a/src-tauri/crates/app/src/remote/sync.rs b/src-tauri/crates/app/src/remote/sync.rs
index 1df9f3ba..dc26dca2 100644
--- a/src-tauri/crates/app/src/remote/sync.rs
+++ b/src-tauri/crates/app/src/remote/sync.rs
@@ -84,6 +84,17 @@ pub async fn sync_now(state: &AppState) -> AppResult<SyncReport> {
     };
 
     let profile_id = state.require_profile_id().await?;
+
+    // Push before pulling, for two reasons. Our own changes then come
+    // back in the same pass instead of the next one — and, more
+    // importantly, a bootstrap replaces the projection wholesale, so
+    // anything still queued should have had its chance to become server
+    // state first. A failure here is not fatal: the queue keeps its
+    // entries and the read half still runs.
+    if let Err(error) = crate::remote::drain::drain(state).await {
+        tracing::debug!(%error, "could not push the outbound queue before syncing");
+    }
+
     let binding = read_binding(state, profile_id).await?;
 
     match binding.bootstrapped_at {

From d32124825729d2c2c902ea466ee35270d9161549 Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Mon, 10 Aug 2026 16:26:52 +0200
Subject: [PATCH 07/14] feat(remote): shares as queued mutations on the v2
 endpoints

Create, update and delete through the same replayable queue as
everything else. Replaying a creation needs no special handling: the
share token is derived deterministically from the identifier, so
re-sending returns the same URL rather than minting a second share.

Two things specific to shares. Their URL has exactly one moment -- the
journal never carries it and it cannot be derived locally, since the
token is keyed on a server-side secret. The creation response is the
only time this device can learn the link, so a share created on another
device stays link-less here permanently, and capturing it at creation is
the only chance rather than an optimisation.

And a snapshot must spare a placeholder share for the same reason it
spares a placeholder playlist: the server has never heard of it. That
fix also removed a duplicate unconditional delete that would have undone
the preservation two lines later.

Clearing an optional field remains inexpressible, and it is worse here
than for playlists: expires_at is coalesced too, so a share given an
expiry by mistake cannot have it removed through this API.

Claude-Session: https://claude.ai/code/session_01N9WXrurarkoiT2jgimvyj1
---
 .../rfcs/RFC-005-remote-source-and-sync-v2.md |  15 +-
 src-tauri/crates/app/src/remote/drain.rs      | 103 ++++++++++--
 src-tauri/crates/app/src/remote/mutation.rs   | 153 +++++++++++++++++-
 src-tauri/crates/app/src/remote/projection.rs |   4 +-
 4 files changed, 256 insertions(+), 19 deletions(-)

diff --git a/docs/rfcs/RFC-005-remote-source-and-sync-v2.md b/docs/rfcs/RFC-005-remote-source-and-sync-v2.md
index 140ea498..bdda0ad8 100644
--- a/docs/rfcs/RFC-005-remote-source-and-sync-v2.md
+++ b/docs/rfcs/RFC-005-remote-source-and-sync-v2.md
@@ -220,10 +220,17 @@ and it is sound for a specific reason: FIFO guarantees an entry behind an
 unlanded creation has never been presented to the server, so no fingerprint
 exists for it to conflict with.
 
-**What the API cannot express.** Clearing a playlist comment. The server applies
-`COALESCE(?, comment)`, so a null comment keeps the current one — "leave it
-alone" and "empty it" are the same request. The mutation type reflects that
-rather than pretending otherwise.
+**What the API cannot express.** Clearing an optional field. Playlist updates
+apply `COALESCE(?, comment)` and share updates do the same for `description`
+**and `expires_at`** — so "leave it alone" and "empty it" are the same request.
+The consequence is worst for the expiry: a share given one by mistake cannot
+have it removed. The mutation types say so rather than pretending otherwise.
+
+**A share's URL has exactly one moment.** The journal never carries it, and it
+cannot be derived locally — the token is keyed on a server-side instance secret.
+So the creation response is the only time this device can learn the link, and a
+share created on another device stays link-less here permanently. Capturing it
+at creation is not an optimisation; it is the only chance.
 
 ## Decision 8 — v2 lands beside v1, not on top of it
 
diff --git a/src-tauri/crates/app/src/remote/drain.rs b/src-tauri/crates/app/src/remote/drain.rs
index 69665a6f..852f3724 100644
--- a/src-tauri/crates/app/src/remote/drain.rs
+++ b/src-tauri/crates/app/src/remote/drain.rs
@@ -37,11 +37,17 @@ pub struct DrainReport {
     pub stopped_early: bool,
 }
 
-/// The reply we care about from a playlist creation: the identifier the
-/// server chose.
+/// What a creation's reply carries that we must keep.
+///
+/// For a playlist that is only the identifier. For a share it is the
+/// identifier **and the URL**, which the journal never carries and which
+/// cannot be derived locally — the creation response is the only moment
+/// this device can ever learn it.
 #[derive(Debug, serde::Deserialize)]
-struct CreatedPlaylist {
+struct Created {
     id: String,
+    #[serde(default)]
+    url: Option<String>,
 }
 
 /// Push what is queued. Does nothing, successfully, when there is
@@ -72,12 +78,20 @@ pub async fn drain(state: &AppState) -> AppResult<DrainReport> {
                 // creation the server has already accepted, under an
                 // identifier whose fingerprint now names a different
                 // playlist — the exact conflict the protocol rejects.
-                if let (
-                    Mutation::CreatePlaylist { local_id, .. },
-                    Some(CreatedPlaylist { id }),
-                ) = (&entry.mutation, &created)
-                {
-                    mutation::resolve_placeholder(&mut tx, local_id, id).await?;
+                match (&entry.mutation, &created) {
+                    (Mutation::CreatePlaylist { local_id, .. }, Some(created)) => {
+                        mutation::resolve_placeholder(&mut tx, local_id, &created.id).await?;
+                    }
+                    (Mutation::CreateShare { local_id, .. }, Some(created)) => {
+                        mutation::resolve_share_placeholder(
+                            &mut tx,
+                            local_id,
+                            &created.id,
+                            created.url.as_deref(),
+                        )
+                        .await?;
+                    }
+                    _ => {}
                 }
                 mutation::remove(&mut tx, entry.id).await?;
                 tx.commit().await?;
@@ -118,7 +132,7 @@ pub async fn drain(state: &AppState) -> AppResult<DrainReport> {
 async fn send(
     client: &RemoteClient,
     entry: &QueuedMutation,
-) -> Result<Option<CreatedPlaylist>, RemoteFailure> {
+) -> Result<Option<Created>, RemoteFailure> {
     let op = &entry.operation_id;
     match &entry.mutation {
         Mutation::SetFavorite {
@@ -173,7 +187,7 @@ async fn send(
         Mutation::CreatePlaylist {
             name, track_ids, ..
         } => {
-            let created: CreatedPlaylist = client
+            let created: Created = client
                 .send_json(
                     client
                         .mutate(reqwest::Method::POST, "/api/v2/playlists", op)
@@ -285,5 +299,72 @@ async fn send(
                 .await?;
             Ok(None)
         }
+
+        Mutation::CreateShare {
+            track_ids,
+            description,
+            expires_at,
+            ..
+        } => {
+            // No special handling for a replay: the share token is
+            // derived deterministically from the identifier, so
+            // re-sending returns the same URL rather than minting a
+            // second share.
+            let created: Created = client
+                .send_json(
+                    client
+                        .mutate(reqwest::Method::POST, "/api/v2/shares", op)
+                        .json(&serde_json::json!({
+                            "track_ids": track_ids,
+                            "description": description,
+                            "expires_at": expires_at,
+                        })),
+                )
+                .await?;
+            Ok(Some(created))
+        }
+
+        Mutation::UpdateShare {
+            share_id,
+            description,
+            expires_at,
+        } => {
+            if mutation::is_placeholder(share_id) {
+                return Err(RemoteFailure {
+                    kind: FailureKind::Permanent,
+                    status: None,
+                    message: "the share this edit belongs to was never created on the server"
+                        .into(),
+                });
+            }
+            let path = format!("/api/v2/shares/{share_id}");
+            let mut body = serde_json::Map::new();
+            if let Some(description) = description {
+                body.insert("description".into(), serde_json::json!(description));
+            }
+            if let Some(expires_at) = expires_at {
+                body.insert("expires_at".into(), serde_json::json!(expires_at));
+            }
+            client
+                .send_ok(
+                    client
+                        .mutate(reqwest::Method::PATCH, &path, op)
+                        .json(&serde_json::Value::Object(body)),
+                )
+                .await?;
+            Ok(None)
+        }
+
+        Mutation::DeleteShare { share_id } => {
+            if mutation::is_placeholder(share_id) {
+                // Never reached the server, so it is already gone.
+                return Ok(None);
+            }
+            let path = format!("/api/v2/shares/{share_id}");
+            client
+                .send_ok(client.mutate(reqwest::Method::DELETE, &path, op))
+                .await?;
+            Ok(None)
+        }
     }
 }
diff --git a/src-tauri/crates/app/src/remote/mutation.rs b/src-tauri/crates/app/src/remote/mutation.rs
index 03c8ae9e..a2dec793 100644
--- a/src-tauri/crates/app/src/remote/mutation.rs
+++ b/src-tauri/crates/app/src/remote/mutation.rs
@@ -117,6 +117,29 @@ pub enum Mutation {
         position_ms: i64,
         client: Option<String>,
     },
+    /// A share created offline has neither an identifier nor a link
+    /// until the server answers, so it carries a placeholder like a
+    /// playlist does. Replay is safe without any special handling: the
+    /// share token is derived deterministically from the identifier, so
+    /// re-sending a creation yields the same URL rather than a second
+    /// share.
+    CreateShare {
+        local_id: String,
+        track_ids: Vec<String>,
+        description: Option<String>,
+        expires_at: Option<i64>,
+    },
+    /// Same coalescing limitation as [`Mutation::UpdatePlaylist`], and
+    /// it bites harder here: `expires_at` is also `COALESCE`d, so an
+    /// expiry set by mistake **cannot be removed** through this API.
+    UpdateShare {
+        share_id: String,
+        description: Option<String>,
+        expires_at: Option<i64>,
+    },
+    DeleteShare {
+        share_id: String,
+    },
 }
 
 impl Mutation {
@@ -131,16 +154,22 @@ impl Mutation {
             Mutation::DeletePlaylist { .. } => "delete_playlist",
             Mutation::Scrobble { .. } => "scrobble",
             Mutation::SaveQueue { .. } => "save_queue",
+            Mutation::CreateShare { .. } => "create_share",
+            Mutation::UpdateShare { .. } => "update_share",
+            Mutation::DeleteShare { .. } => "delete_share",
         }
     }
 
-    /// The playlist placeholder this mutation depends on, if any. Used
-    /// to find the entries a completed creation has to rewrite.
+    /// The placeholder this mutation depends on, if any. Used to find
+    /// the entries a completed creation has to rewrite.
     pub fn placeholder_dependency(&self) -> Option<&str> {
         let id = match self {
             Mutation::CreatePlaylist { local_id, .. } => local_id,
             Mutation::UpdatePlaylist { playlist_id, .. } => playlist_id,
             Mutation::DeletePlaylist { playlist_id } => playlist_id,
+            Mutation::CreateShare { local_id, .. } => local_id,
+            Mutation::UpdateShare { share_id, .. } => share_id,
+            Mutation::DeleteShare { share_id } => share_id,
             _ => return None,
         };
         is_placeholder(id).then_some(id.as_str())
@@ -305,6 +334,54 @@ pub async fn resolve_placeholder(
         .execute(&mut *conn)
         .await?;
 
+    rewrite_queued_references(conn, placeholder, remote_id).await
+}
+
+/// The share equivalent, plus the one thing only the creator ever learns.
+///
+/// The journal never carries a share's URL, and it cannot be derived
+/// locally — the token is keyed on a server-side instance secret. So the
+/// creation response is the only moment this device can capture the
+/// link, and a share created on another device stays link-less here for
+/// good. Storing it now is not an optimisation; it is the only chance.
+pub async fn resolve_share_placeholder(
+    conn: &mut SqliteConnection,
+    placeholder: &str,
+    remote_id: &str,
+    url: Option<&str>,
+) -> AppResult<()> {
+    // Copied, re-pointed, dropped — for the same foreign-key reason as
+    // the playlist above.
+    sqlx::query(
+        "INSERT INTO remote_share
+            (remote_id, description, expires_at, visit_count, url, created_at, updated_at)
+         SELECT ?, description, expires_at, visit_count, COALESCE(?, url), created_at, updated_at
+           FROM remote_share WHERE remote_id = ?",
+    )
+    .bind(remote_id)
+    .bind(url)
+    .bind(placeholder)
+    .execute(&mut *conn)
+    .await?;
+    sqlx::query("UPDATE remote_share_track SET share_remote_id = ? WHERE share_remote_id = ?")
+        .bind(remote_id)
+        .bind(placeholder)
+        .execute(&mut *conn)
+        .await?;
+    sqlx::query("DELETE FROM remote_share WHERE remote_id = ?")
+        .bind(placeholder)
+        .execute(&mut *conn)
+        .await?;
+
+    rewrite_queued_references(conn, placeholder, remote_id).await
+}
+
+/// Point every still-queued entry at the identifier the server chose.
+async fn rewrite_queued_references(
+    conn: &mut SqliteConnection,
+    placeholder: &str,
+    remote_id: &str,
+) -> AppResult<()> {
     let rows = sqlx::query(
         "SELECT id, payload FROM remote_mutation WHERE failed_at IS NULL ORDER BY id",
     )
@@ -338,6 +415,18 @@ pub async fn resolve_placeholder(
             Mutation::DeletePlaylist { .. } => Mutation::DeletePlaylist {
                 playlist_id: remote_id.to_string(),
             },
+            Mutation::UpdateShare {
+                description,
+                expires_at,
+                ..
+            } => Mutation::UpdateShare {
+                share_id: remote_id.to_string(),
+                description,
+                expires_at,
+            },
+            Mutation::DeleteShare { .. } => Mutation::DeleteShare {
+                share_id: remote_id.to_string(),
+            },
             // The creation itself is the row being resolved; it is
             // removed by the drain on success, so there is nothing to
             // rewrite.
@@ -554,6 +643,66 @@ mod tests {
         }
     }
 
+    #[tokio::test]
+    async fn resolving_a_share_captures_the_url_the_journal_never_carries() {
+        // The token is keyed on a server-side secret, so the creation
+        // response is the only moment this device can learn the link.
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        let local_id = new_placeholder();
+
+        sqlx::query("INSERT INTO remote_share (remote_id) VALUES (?)")
+            .bind(&local_id)
+            .execute(&mut *conn)
+            .await
+            .unwrap();
+        sqlx::query("INSERT INTO remote_share_track VALUES (?, 0, 't1')")
+            .bind(&local_id)
+            .execute(&mut *conn)
+            .await
+            .unwrap();
+        enqueue(
+            &mut conn,
+            &Mutation::DeleteShare {
+                share_id: local_id.clone(),
+            },
+        )
+        .await
+        .unwrap();
+
+        resolve_share_placeholder(
+            &mut conn,
+            &local_id,
+            "share-uuid",
+            Some("https://music.example/share/abc"),
+        )
+        .await
+        .unwrap();
+
+        let url: Option<String> =
+            sqlx::query_scalar("SELECT url FROM remote_share WHERE remote_id = 'share-uuid'")
+                .fetch_one(&mut *conn)
+                .await
+                .unwrap();
+        assert_eq!(url.as_deref(), Some("https://music.example/share/abc"));
+
+        let tracks: i64 = sqlx::query_scalar(
+            "SELECT count(*) FROM remote_share_track WHERE share_remote_id = 'share-uuid'",
+        )
+        .fetch_one(&mut *conn)
+        .await
+        .unwrap();
+        assert_eq!(tracks, 1);
+
+        let queued = pending(&mut conn, 10).await.unwrap();
+        assert_eq!(
+            queued[0].mutation,
+            Mutation::DeleteShare {
+                share_id: "share-uuid".into()
+            }
+        );
+    }
+
     #[tokio::test]
     async fn resolving_leaves_unrelated_entries_alone() {
         let pool = pool().await;
diff --git a/src-tauri/crates/app/src/remote/projection.rs b/src-tauri/crates/app/src/remote/projection.rs
index a42e534f..98289b0b 100644
--- a/src-tauri/crates/app/src/remote/projection.rs
+++ b/src-tauri/crates/app/src/remote/projection.rs
@@ -83,6 +83,8 @@ pub async fn apply_snapshot(conn: &mut SqliteConnection, snapshot: &SyncSnapshot
     for statement in [
         "DELETE FROM remote_playlist_track WHERE playlist_remote_id NOT LIKE ?",
         "DELETE FROM remote_playlist WHERE remote_id NOT LIKE ?",
+        "DELETE FROM remote_share_track WHERE share_remote_id NOT LIKE ?",
+        "DELETE FROM remote_share WHERE remote_id NOT LIKE ?",
     ] {
         sqlx::query(statement)
             .bind(&placeholder_pattern)
@@ -95,8 +97,6 @@ pub async fn apply_snapshot(conn: &mut SqliteConnection, snapshot: &SyncSnapshot
         "DELETE FROM remote_history",
         "DELETE FROM remote_queue_track",
         "DELETE FROM remote_queue",
-        "DELETE FROM remote_share_track",
-        "DELETE FROM remote_share",
     ] {
         sqlx::query(statement).execute(&mut *conn).await?;
     }

From 78e28023c62e9473e6802b612ba5aa62a2715af9 Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Mon, 10 Aug 2026 23:24:42 +0200
Subject: [PATCH 08/14] test(remote): prove the two feeds converge on a real
 seeded library

Re-captured the fixtures against a server seeded with six actual tracks
and driven through every entity the protocol carries: two favourites (a
track and an album), two ratings, two scrobbles, a saved queue, a
playlist created then updated, and a share. The previous capture only
had empty playlists, so favourites, ratings, scrobbles and the queue had
never been observed -- only read out of the server's source.

All ten event shapes match what was implemented. The convergence test now
compares nine projections rather than one: it walks the journal, snapshots
the same database, and asserts the two produce identical state. If they
ever diverge, what a user sees would depend on whether they bootstrapped
or caught up, which is undebuggable from a screenshot.

Two things learned from the server side and applied. A 422 on an
acknowledgement confounds an out-of-range cursor with an unknown or
revoked device, and the second is both likelier and worse -- a revoked
device fails every mutation too -- so the log now names it first. And the
scrobble trade-off is documented precisely: plays are distinguishable in
the journal but not in a snapshot, so walking the journal is the more
faithful history, and the natural key is taken only because it is the one
both feeds carry.

The retention branch stays unwritten. Measured: a cursor beyond the last
event returns an empty page, not an error, and there is no compaction
contract yet -- so coding against an imagined status would be worse than
leaving the path absent.

Claude-Session: https://claude.ai/code/session_01N9WXrurarkoiT2jgimvyj1
---
 .../rfcs/RFC-005-remote-source-and-sync-v2.md |  11 +-
 src-tauri/crates/app/src/remote/dto.rs        |  17 ++
 src-tauri/crates/app/src/remote/projection.rs | 140 +++++++++---
 src-tauri/crates/app/src/remote/sync.rs       |  19 +-
 .../app/src/remote/testdata/changes.json      | 184 ++++++++++++----
 .../app/src/remote/testdata/snapshot.json     | 203 +++++++++++++++++-
 6 files changed, 490 insertions(+), 84 deletions(-)

diff --git a/docs/rfcs/RFC-005-remote-source-and-sync-v2.md b/docs/rfcs/RFC-005-remote-source-and-sync-v2.md
index bdda0ad8..1bffa325 100644
--- a/docs/rfcs/RFC-005-remote-source-and-sync-v2.md
+++ b/docs/rfcs/RFC-005-remote-source-and-sync-v2.md
@@ -330,9 +330,14 @@ keeping them would carry complexity the protocol no longer asks for.
 - **Last-writer-wins backfill** — a conflict is no longer arbitrated locally: a
   reused operation identifier with a different fingerprint is rejected, and a
   client that cannot apply a known event takes a fresh snapshot.
-- **Compaction and `410 Gone`** — the v2.0 journal is append-only, and any
-  future retention is gated on a snapshot floor. This path disappears, but it is
-  **replaced by snapshot recovery**, not removed without a substitute.
+- **Compaction and `410 Gone`** — the v2.0 journal is append-only, so no cursor
+  can be too old: `after=` beyond the last event returns an empty page, not an
+  error (measured). There is **no retention contract yet**, and the server side
+  has deliberately not written one. So this path has no trigger today, and the
+  right move is to leave it unwritten rather than code against an imagined
+  status. Recovery still exists — it is driven by a *known event that fails to
+  apply*, which discards the projection and re-snapshots — but that is a
+  different trigger, not a stand-in for compaction.
 
 ## The RFC-003 naming trap
 
diff --git a/src-tauri/crates/app/src/remote/dto.rs b/src-tauri/crates/app/src/remote/dto.rs
index 78aac407..2e206f10 100644
--- a/src-tauri/crates/app/src/remote/dto.rs
+++ b/src-tauri/crates/app/src/remote/dto.rs
@@ -116,6 +116,23 @@ pub struct QueueItem {
 /// event's `entity_id` is the **track** id, so two plays of the same
 /// track share it. `(track_id, played_at)` is the only pair that tells
 /// them apart, which is why the projection keys on it.
+///
+/// ## What that costs, precisely
+///
+/// The server stores plays in an auto-incrementing table with no
+/// uniqueness constraint: two byte-identical scrobbles both persist
+/// (confirmed server-side). Those two rows are distinguishable in
+/// `/sync/changes` — they carry different cursors and event ids — but
+/// **not** in a snapshot, which describes each play only by track and
+/// timestamp.
+///
+/// So the loss is real but bounded: walking the journal is *more
+/// faithful* to the history than bootstrapping from a snapshot, and the
+/// collision only bites when two plays share a millisecond, which in
+/// practice means a duplicate submission rather than two listens. We
+/// take the natural key because it is the only one both feeds carry;
+/// keying on the event id would make a snapshot unable to populate the
+/// table at all.
 #[derive(Debug, Clone, Deserialize)]
 pub struct HistoryItem {
     pub track_id: String,
diff --git a/src-tauri/crates/app/src/remote/projection.rs b/src-tauri/crates/app/src/remote/projection.rs
index 98289b0b..6ff82638 100644
--- a/src-tauri/crates/app/src/remote/projection.rs
+++ b/src-tauri/crates/app/src/remote/projection.rs
@@ -1099,62 +1099,138 @@ mod tests {
         assert_eq!(missing_track_ids(&mut conn).await.unwrap(), vec!["t9"]);
     }
 
-    /// Captured verbatim from a running server (2026-08-10) by creating
-    /// a playlist, renaming it with a comment and making it public,
-    /// then creating and deleting a second one. Bytes from the server
-    /// itself, not a shape we imagined — which is the only kind of
-    /// fixture that can catch us having imagined the wrong one.
+    /// Captured verbatim from a running server (2026-08-10) seeded with
+    /// a real six-track library, then driven through every entity the
+    /// protocol carries: two favourites (a track and an album), two
+    /// ratings, two scrobbles, a saved queue, a playlist created then
+    /// updated, and a share.
+    ///
+    /// Bytes the server produced, not a shape we imagined — the only
+    /// kind of fixture that can catch us having imagined the wrong one.
     const REAL_SNAPSHOT: &str = include_str!("testdata/snapshot.json");
     const REAL_CHANGES: &str = include_str!("testdata/changes.json");
 
+    /// Everything the projection holds, in a form two feeds can be
+    /// compared on.
+    async fn projected_state(conn: &mut SqliteConnection) -> Vec<(String, String)> {
+        let mut rows = Vec::new();
+        for (label, sql) in [
+            (
+                "playlist",
+                "SELECT remote_id || '|' || name || '|' || COALESCE(comment, '~') || '|' || is_public
+                   FROM remote_playlist ORDER BY remote_id",
+            ),
+            (
+                "playlist_track",
+                "SELECT playlist_remote_id || '|' || position || '|' || track_remote_id
+                   FROM remote_playlist_track ORDER BY playlist_remote_id, position",
+            ),
+            (
+                "favorite",
+                "SELECT entity_type || '|' || entity_id FROM remote_favorite
+                  ORDER BY entity_type, entity_id",
+            ),
+            (
+                "rating",
+                "SELECT entity_type || '|' || entity_id || '|' || rating FROM remote_rating
+                  ORDER BY entity_type, entity_id",
+            ),
+            (
+                "history",
+                "SELECT track_remote_id || '|' || played_at || '|' || submission
+                   FROM remote_history ORDER BY played_at",
+            ),
+            (
+                "queue",
+                "SELECT COALESCE(current_remote_id, '~') || '|' || position_ms FROM remote_queue",
+            ),
+            (
+                "queue_track",
+                "SELECT position || '|' || track_remote_id FROM remote_queue_track ORDER BY position",
+            ),
+            (
+                "share",
+                "SELECT remote_id || '|' || COALESCE(description, '~') FROM remote_share
+                  ORDER BY remote_id",
+            ),
+            (
+                "share_track",
+                "SELECT share_remote_id || '|' || position || '|' || track_remote_id
+                   FROM remote_share_track ORDER BY share_remote_id, position",
+            ),
+        ] {
+            let values: Vec<String> = sqlx::query_scalar(sqlx::AssertSqlSafe(sql.to_string()))
+                .fetch_all(&mut *conn)
+                .await
+                .unwrap();
+            for value in values {
+                rows.push((label.to_string(), value));
+            }
+        }
+        rows
+    }
+
     #[tokio::test]
-    async fn the_servers_own_snapshot_applies() {
+    async fn the_servers_own_snapshot_applies_across_every_entity() {
         let pool = pool().await;
         let mut conn = pool.acquire().await.unwrap();
         let snapshot: SyncSnapshot = serde_json::from_str(REAL_SNAPSHOT).unwrap();
-        assert_eq!(snapshot.cursor, 4);
 
         apply_snapshot(&mut conn, &snapshot).await.unwrap();
 
-        let (name, comment, public) =
-            playlist_row(&mut conn, "31be1c98-3984-40ff-8352-73fc6e2c29b5").await;
-        assert_eq!(name, "Mix renommee");
-        assert_eq!(comment.as_deref(), Some("des notes"));
-        assert_eq!(public, 1);
+        let state = projected_state(&mut conn).await;
+        let count = |label: &str| state.iter().filter(|(l, _)| l == label).count();
+        assert_eq!(count("playlist"), 1);
+        assert_eq!(count("playlist_track"), 3);
+        assert_eq!(count("favorite"), 2, "a track and an album were starred");
+        assert_eq!(count("rating"), 2);
+        assert_eq!(count("history"), 2);
+        assert_eq!(count("queue"), 1);
+        assert_eq!(count("queue_track"), 3);
+        assert_eq!(count("share"), 1);
+        assert_eq!(count("share_track"), 2);
+
+        // The snapshot carries whole song objects, so nothing is left
+        // waiting for metadata.
+        assert!(missing_track_ids(&mut conn).await.unwrap().is_empty());
+        let cached: i64 = sqlx::query_scalar("SELECT count(*) FROM remote_track")
+            .fetch_one(&mut *conn)
+            .await
+            .unwrap();
+        assert!(cached >= 3, "the snapshot's songs were not cached");
     }
 
     #[tokio::test]
     async fn replaying_the_servers_own_journal_reaches_the_snapshot_state() {
-        // The real sequence is create -> update -> create -> delete, and
-        // the create events carry only three keys. Replaying it must
-        // land on exactly what the snapshot says, or the two feeds
-        // disagree and the projection depends on which one ran.
+        // The two feeds must agree. If they do not, what the user sees
+        // depends on whether they bootstrapped or caught up — which is
+        // the kind of divergence nobody can debug from a screenshot.
         let pool = pool().await;
         let mut conn = pool.acquire().await.unwrap();
 
         let page: SyncPage = serde_json::from_str(REAL_CHANGES).unwrap();
-        assert_eq!(page.changes.len(), 4);
+        assert_eq!(page.changes.len(), 10, "the capture lost events");
         for change in &page.changes {
-            apply_change(&mut conn, change).await.unwrap();
+            assert_eq!(
+                apply_change(&mut conn, change).await.unwrap(),
+                Outcome::Applied,
+                "event {} ({}/{}) was not understood",
+                change.cursor,
+                change.entity_type,
+                change.action
+            );
         }
+        let from_journal = projected_state(&mut conn).await;
 
+        // Same database, replaced by the snapshot.
         let snapshot: SyncSnapshot = serde_json::from_str(REAL_SNAPSHOT).unwrap();
-        let expected = &snapshot.playlists[0];
-        let (name, comment, public) = playlist_row(&mut conn, &expected.id).await;
-        assert_eq!(name, expected.name);
+        apply_snapshot(&mut conn, &snapshot).await.unwrap();
+        let from_snapshot = projected_state(&mut conn).await;
+
         assert_eq!(
-            comment, expected.comment,
-            "the third event is create-shaped and blanked the comment the second one set"
+            from_journal, from_snapshot,
+            "walking the journal and taking a snapshot produced different state"
         );
-        assert_eq!(public, i64::from(expected.public));
-
-        // The fourth event deletes the second playlist, so exactly one
-        // survives — the same one the snapshot lists.
-        let total: i64 = sqlx::query_scalar("SELECT count(*) FROM remote_playlist")
-            .fetch_one(&mut *conn)
-            .await
-            .unwrap();
-        assert_eq!(total, snapshot.playlists.len() as i64);
     }
 
     #[tokio::test]
diff --git a/src-tauri/crates/app/src/remote/sync.rs b/src-tauri/crates/app/src/remote/sync.rs
index dc26dca2..51a79e04 100644
--- a/src-tauri/crates/app/src/remote/sync.rs
+++ b/src-tauri/crates/app/src/remote/sync.rs
@@ -261,7 +261,24 @@ async fn acknowledge(state: &AppState, profile_id: i64, client: &RemoteClient, c
         .await;
 
     if let Err(failure) = outcome {
-        tracing::debug!(%failure, cursor, "acknowledgement failed; continuing anyway");
+        // A `422` here confounds two causes: a cursor beyond the user's
+        // latest event, and a device the server does not know or has
+        // revoked. The second is far more likely and far more
+        // consequential — a revoked device fails every *mutation* too —
+        // so the log names it first. (The server side hit this exact
+        // confusion while testing: an empty device id reads as a bad
+        // cursor.)
+        if failure.status == Some(422) {
+            tracing::warn!(
+                %failure,
+                cursor,
+                device_id,
+                "the server refused this acknowledgement; check the device is still \
+                 registered before suspecting the cursor"
+            );
+        } else {
+            tracing::debug!(%failure, cursor, "acknowledgement failed; continuing anyway");
+        }
     }
 }
 
diff --git a/src-tauri/crates/app/src/remote/testdata/changes.json b/src-tauri/crates/app/src/remote/testdata/changes.json
index 2fbc0993..10b339e3 100644
--- a/src-tauri/crates/app/src/remote/testdata/changes.json
+++ b/src-tauri/crates/app/src/remote/testdata/changes.json
@@ -2,63 +2,173 @@
   "changes": [
     {
       "cursor": 1,
-      "event_id": "338d2144-baaa-4877-99e5-77dceadf7de7",
-      "operation_id": "7fdf499f-89b3-42f2-a633-55e8eed01dd3",
-      "origin_device_id": null,
-      "entity_type": "playlist",
-      "entity_id": "31be1c98-3984-40ff-8352-73fc6e2c29b5",
+      "event_id": "0651703f-03a1-42a9-9eab-8a6b16dc91f1",
+      "operation_id": "a4665e29-a76f-4f1b-b59e-673ddcae9d92",
+      "origin_device_id": "ffc3e353-7c8b-4937-8879-cc6f683ba108",
+      "entity_type": "favorite",
+      "entity_id": "3b1c72eb-99f7-4046-b2a0-798897fe62f0",
       "action": "upsert",
       "payload": {
-        "id": "31be1c98-3984-40ff-8352-73fc6e2c29b5",
-        "name": "Mix",
-        "track_ids": []
+        "entity_id": "3b1c72eb-99f7-4046-b2a0-798897fe62f0",
+        "entity_type": "track",
+        "starred": true
       },
-      "changed_at": 1786369482470
+      "changed_at": 1786396570913
     },
     {
       "cursor": 2,
-      "event_id": "cd9e2db4-bb47-436a-aeed-b1766f98fc30",
-      "operation_id": "b2f6bbfd-b59f-4170-83c4-28fcdc0d4240",
-      "origin_device_id": null,
-      "entity_type": "playlist",
-      "entity_id": "31be1c98-3984-40ff-8352-73fc6e2c29b5",
+      "event_id": "4d5001ff-4c37-45cb-bab3-d192355af7c8",
+      "operation_id": "57120140-fb41-40d7-8b32-e94a6cc802f8",
+      "origin_device_id": "62f0bd77-88a6-45b8-8224-d316d8ffb4b5",
+      "entity_type": "favorite",
+      "entity_id": "3015b5d3-d8bb-4c38-8ff9-70e43c926ced",
       "action": "upsert",
       "payload": {
-        "comment": "des notes",
-        "id": "31be1c98-3984-40ff-8352-73fc6e2c29b5",
-        "name": "Mix renommee",
-        "public": true,
-        "track_ids": []
+        "entity_id": "3015b5d3-d8bb-4c38-8ff9-70e43c926ced",
+        "entity_type": "album",
+        "starred": true
       },
-      "changed_at": 1786369482481
+      "changed_at": 1786396600015
     },
     {
       "cursor": 3,
-      "event_id": "1cc5f4f5-dabe-40ca-85fc-78aa9b49c8c8",
-      "operation_id": "bb155f83-35a1-488d-bbc3-fb26c2f1eeb1",
-      "origin_device_id": null,
-      "entity_type": "playlist",
-      "entity_id": "170c2731-487e-495e-a97a-4281f961c9f1",
+      "event_id": "418d27b5-f0aa-42f2-a317-4356aa080cf4",
+      "operation_id": "bc63b78d-debe-40fd-91bf-8f455822862c",
+      "origin_device_id": "62f0bd77-88a6-45b8-8224-d316d8ffb4b5",
+      "entity_type": "rating",
+      "entity_id": "15d63ac0-1428-43bc-ad2e-c7353d51c3b6",
       "action": "upsert",
       "payload": {
-        "id": "170c2731-487e-495e-a97a-4281f961c9f1",
-        "name": "A supprimer",
-        "track_ids": []
+        "entity_id": "15d63ac0-1428-43bc-ad2e-c7353d51c3b6",
+        "entity_type": "track",
+        "rating": 4
       },
-      "changed_at": 1786369482485
+      "changed_at": 1786396600021
     },
     {
       "cursor": 4,
-      "event_id": "65cdcaae-a894-48ec-b387-0fcb4e998a7a",
-      "operation_id": "4e3e9ec2-da99-45f1-a6f6-5ef04c682bbf",
-      "origin_device_id": null,
+      "event_id": "3de99870-de01-418d-8d8f-fc46aae2caf5",
+      "operation_id": "3c88d097-4007-4d5a-94b0-f69512eb80e1",
+      "origin_device_id": "62f0bd77-88a6-45b8-8224-d316d8ffb4b5",
+      "entity_type": "rating",
+      "entity_id": "3015b5d3-d8bb-4c38-8ff9-70e43c926ced",
+      "action": "upsert",
+      "payload": {
+        "entity_id": "3015b5d3-d8bb-4c38-8ff9-70e43c926ced",
+        "entity_type": "album",
+        "rating": 5
+      },
+      "changed_at": 1786396600024
+    },
+    {
+      "cursor": 5,
+      "event_id": "5f3e4f70-fd1c-47e9-bdaa-049020b8df8b",
+      "operation_id": "334fc539-cf06-4570-8da0-0f59e9f60d4c",
+      "origin_device_id": "62f0bd77-88a6-45b8-8224-d316d8ffb4b5",
+      "entity_type": "scrobble",
+      "entity_id": "3b1c72eb-99f7-4046-b2a0-798897fe62f0",
+      "action": "append",
+      "payload": {
+        "played_at": 1786396600027,
+        "submission": true,
+        "track_id": "3b1c72eb-99f7-4046-b2a0-798897fe62f0"
+      },
+      "changed_at": 1786396600028
+    },
+    {
+      "cursor": 6,
+      "event_id": "b91a4746-39ee-4194-97f7-eab0ab8bdbb6",
+      "operation_id": "6192d5a2-e827-4b44-8cb0-7383e6a1154d",
+      "origin_device_id": "62f0bd77-88a6-45b8-8224-d316d8ffb4b5",
+      "entity_type": "scrobble",
+      "entity_id": "d1c03c1e-0b7c-4de6-b7a2-69e0348a5f9c",
+      "action": "append",
+      "payload": {
+        "played_at": 1786396600031,
+        "submission": true,
+        "track_id": "d1c03c1e-0b7c-4de6-b7a2-69e0348a5f9c"
+      },
+      "changed_at": 1786396600032
+    },
+    {
+      "cursor": 7,
+      "event_id": "3fa6074d-ab5c-4c70-bc6e-46c4612bd683",
+      "operation_id": "70745e43-ae6b-4320-82b4-628dbd4a8650",
+      "origin_device_id": "62f0bd77-88a6-45b8-8224-d316d8ffb4b5",
+      "entity_type": "queue",
+      "entity_id": "5dafc44e-dee9-47fc-a3d3-f0ae4108b034",
+      "action": "upsert",
+      "payload": {
+        "client": "WaveFlow",
+        "current": "15d63ac0-1428-43bc-ad2e-c7353d51c3b6",
+        "position_ms": 4200,
+        "track_ids": [
+          "3b1c72eb-99f7-4046-b2a0-798897fe62f0",
+          "15d63ac0-1428-43bc-ad2e-c7353d51c3b6",
+          "d1c03c1e-0b7c-4de6-b7a2-69e0348a5f9c"
+        ]
+      },
+      "changed_at": 1786396600036
+    },
+    {
+      "cursor": 8,
+      "event_id": "5c9a2066-605a-4973-820b-fa9fffd8e624",
+      "operation_id": "596b9632-ba77-4e7a-9fa8-92377b228c38",
+      "origin_device_id": "62f0bd77-88a6-45b8-8224-d316d8ffb4b5",
+      "entity_type": "playlist",
+      "entity_id": "928d8775-194c-4f8a-ac93-b50976b1cf53",
+      "action": "upsert",
+      "payload": {
+        "id": "928d8775-194c-4f8a-ac93-b50976b1cf53",
+        "name": "Mix de test",
+        "track_ids": [
+          "3b1c72eb-99f7-4046-b2a0-798897fe62f0",
+          "15d63ac0-1428-43bc-ad2e-c7353d51c3b6"
+        ]
+      },
+      "changed_at": 1786396600040
+    },
+    {
+      "cursor": 9,
+      "event_id": "7915026f-5825-4d22-aac0-7e84e480162e",
+      "operation_id": "716d4849-08a2-4b17-9300-9a5aa605dd67",
+      "origin_device_id": "62f0bd77-88a6-45b8-8224-d316d8ffb4b5",
       "entity_type": "playlist",
-      "entity_id": "170c2731-487e-495e-a97a-4281f961c9f1",
-      "action": "delete",
-      "payload": {},
-      "changed_at": 1786369482488
+      "entity_id": "928d8775-194c-4f8a-ac93-b50976b1cf53",
+      "action": "upsert",
+      "payload": {
+        "comment": "des notes",
+        "id": "928d8775-194c-4f8a-ac93-b50976b1cf53",
+        "name": "Mix de test",
+        "public": true,
+        "track_ids": [
+          "3b1c72eb-99f7-4046-b2a0-798897fe62f0",
+          "15d63ac0-1428-43bc-ad2e-c7353d51c3b6",
+          "83dbe6de-9b92-4b2d-a834-457d4053db29"
+        ]
+      },
+      "changed_at": 1786396600047
+    },
+    {
+      "cursor": 10,
+      "event_id": "efafd910-8677-4421-9e84-49f081d686ae",
+      "operation_id": "2c883207-bd51-424c-a579-a942110aa8ac",
+      "origin_device_id": "62f0bd77-88a6-45b8-8224-d316d8ffb4b5",
+      "entity_type": "share",
+      "entity_id": "e22316dc-b3e7-4120-82cf-8d7d82c93063",
+      "action": "upsert",
+      "payload": {
+        "description": "un partage",
+        "expires_at": null,
+        "id": "e22316dc-b3e7-4120-82cf-8d7d82c93063",
+        "track_ids": [
+          "3b1c72eb-99f7-4046-b2a0-798897fe62f0",
+          "15d63ac0-1428-43bc-ad2e-c7353d51c3b6"
+        ]
+      },
+      "changed_at": 1786396600052
     }
   ],
-  "next_cursor": 4,
+  "next_cursor": 10,
   "has_more": false
 }
\ No newline at end of file
diff --git a/src-tauri/crates/app/src/remote/testdata/snapshot.json b/src-tauri/crates/app/src/remote/testdata/snapshot.json
index bc61030d..599c6728 100644
--- a/src-tauri/crates/app/src/remote/testdata/snapshot.json
+++ b/src-tauri/crates/app/src/remote/testdata/snapshot.json
@@ -1,19 +1,200 @@
 {
-  "cursor": 4,
+  "cursor": 10,
   "playlists": [
     {
-      "id": "31be1c98-3984-40ff-8352-73fc6e2c29b5",
-      "name": "Mix renommee",
+      "id": "928d8775-194c-4f8a-ac93-b50976b1cf53",
+      "name": "Mix de test",
       "comment": "des notes",
       "public": true,
-      "created_at": 1786369482469,
-      "updated_at": 1786369482481,
-      "songs": []
+      "created_at": 1786396600040,
+      "updated_at": 1786396600046,
+      "songs": [
+        {
+          "id": "3b1c72eb-99f7-4046-b2a0-798897fe62f0",
+          "library_id": "abe37251-64e0-4b7c-a938-ee5d1506a4cc",
+          "album_id": "69c933ed-9787-4b39-bc6b-5d42b3446650",
+          "title": "Ebb",
+          "album": "Tideline",
+          "artist": "Bellweather",
+          "genre": "Test",
+          "year": 2019,
+          "track": 1,
+          "disc": null,
+          "duration_ms": 1045,
+          "bitrate": 65,
+          "codec": "MP3",
+          "suffix": "mp3",
+          "size": 8712,
+          "artwork_hash": null,
+          "created_at": 1786396537170,
+          "starred_at": 1786396570913,
+          "user_rating": null
+        },
+        {
+          "id": "15d63ac0-1428-43bc-ad2e-c7353d51c3b6",
+          "library_id": "abe37251-64e0-4b7c-a938-ee5d1506a4cc",
+          "album_id": "69c933ed-9787-4b39-bc6b-5d42b3446650",
+          "title": "Flow",
+          "album": "Tideline",
+          "artist": "Bellweather",
+          "genre": "Test",
+          "year": 2019,
+          "track": 2,
+          "disc": null,
+          "duration_ms": 1045,
+          "bitrate": 65,
+          "codec": "MP3",
+          "suffix": "mp3",
+          "size": 8713,
+          "artwork_hash": null,
+          "created_at": 1786396537170,
+          "starred_at": null,
+          "user_rating": 4
+        },
+        {
+          "id": "83dbe6de-9b92-4b2d-a834-457d4053db29",
+          "library_id": "abe37251-64e0-4b7c-a938-ee5d1506a4cc",
+          "album_id": "034cd971-83fc-4806-9fd4-761a113f74e2",
+          "title": "Solstice",
+          "album": "Northern Lights",
+          "artist": "Aurora",
+          "genre": "Test",
+          "year": 2021,
+          "track": 2,
+          "disc": null,
+          "duration_ms": 1045,
+          "bitrate": 65,
+          "codec": "MP3",
+          "suffix": "mp3",
+          "size": 8714,
+          "artwork_hash": null,
+          "created_at": 1786396537170,
+          "starred_at": null,
+          "user_rating": null
+        }
+      ]
     }
   ],
-  "favorites": [],
-  "ratings": [],
-  "queue": null,
-  "history": [],
-  "shares": []
+  "favorites": [
+    {
+      "entity_type": "album",
+      "entity_id": "3015b5d3-d8bb-4c38-8ff9-70e43c926ced",
+      "starred_at": 1786396600015
+    },
+    {
+      "entity_type": "track",
+      "entity_id": "3b1c72eb-99f7-4046-b2a0-798897fe62f0",
+      "starred_at": 1786396570913
+    }
+  ],
+  "ratings": [
+    {
+      "entity_type": "album",
+      "entity_id": "3015b5d3-d8bb-4c38-8ff9-70e43c926ced",
+      "rating": 5,
+      "updated_at": 1786396600024
+    },
+    {
+      "entity_type": "track",
+      "entity_id": "15d63ac0-1428-43bc-ad2e-c7353d51c3b6",
+      "rating": 4,
+      "updated_at": 1786396600020
+    }
+  ],
+  "queue": {
+    "current": "15d63ac0-1428-43bc-ad2e-c7353d51c3b6",
+    "position_ms": 4200,
+    "changed_by": "WaveFlow",
+    "updated_at": 1786396600036,
+    "songs": [
+      {
+        "id": "3b1c72eb-99f7-4046-b2a0-798897fe62f0",
+        "library_id": "abe37251-64e0-4b7c-a938-ee5d1506a4cc",
+        "album_id": "69c933ed-9787-4b39-bc6b-5d42b3446650",
+        "title": "Ebb",
+        "album": "Tideline",
+        "artist": "Bellweather",
+        "genre": "Test",
+        "year": 2019,
+        "track": 1,
+        "disc": null,
+        "duration_ms": 1045,
+        "bitrate": 65,
+        "codec": "MP3",
+        "suffix": "mp3",
+        "size": 8712,
+        "artwork_hash": null,
+        "created_at": 1786396537170,
+        "starred_at": 1786396570913,
+        "user_rating": null
+      },
+      {
+        "id": "15d63ac0-1428-43bc-ad2e-c7353d51c3b6",
+        "library_id": "abe37251-64e0-4b7c-a938-ee5d1506a4cc",
+        "album_id": "69c933ed-9787-4b39-bc6b-5d42b3446650",
+        "title": "Flow",
+        "album": "Tideline",
+        "artist": "Bellweather",
+        "genre": "Test",
+        "year": 2019,
+        "track": 2,
+        "disc": null,
+        "duration_ms": 1045,
+        "bitrate": 65,
+        "codec": "MP3",
+        "suffix": "mp3",
+        "size": 8713,
+        "artwork_hash": null,
+        "created_at": 1786396537170,
+        "starred_at": null,
+        "user_rating": 4
+      },
+      {
+        "id": "d1c03c1e-0b7c-4de6-b7a2-69e0348a5f9c",
+        "library_id": "abe37251-64e0-4b7c-a938-ee5d1506a4cc",
+        "album_id": "034cd971-83fc-4806-9fd4-761a113f74e2",
+        "title": "Polar",
+        "album": "Northern Lights",
+        "artist": "Aurora",
+        "genre": "Test",
+        "year": 2021,
+        "track": 1,
+        "disc": null,
+        "duration_ms": 1045,
+        "bitrate": 65,
+        "codec": "MP3",
+        "suffix": "mp3",
+        "size": 8711,
+        "artwork_hash": null,
+        "created_at": 1786396537170,
+        "starred_at": null,
+        "user_rating": null
+      }
+    ]
+  },
+  "history": [
+    {
+      "track_id": "d1c03c1e-0b7c-4de6-b7a2-69e0348a5f9c",
+      "submission": true,
+      "played_at": 1786396600031
+    },
+    {
+      "track_id": "3b1c72eb-99f7-4046-b2a0-798897fe62f0",
+      "submission": true,
+      "played_at": 1786396600027
+    }
+  ],
+  "shares": [
+    {
+      "id": "e22316dc-b3e7-4120-82cf-8d7d82c93063",
+      "description": "un partage",
+      "expires_at": null,
+      "created_at": 1786396600052,
+      "visit_count": 0,
+      "track_ids": [
+        "3b1c72eb-99f7-4046-b2a0-798897fe62f0",
+        "15d63ac0-1428-43bc-ad2e-c7353d51c3b6"
+      ]
+    }
+  ]
 }
\ No newline at end of file

From 7b62858deb8ff5827d8e0be9a8c50ec5507f48d6 Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Wed, 12 Aug 2026 21:15:07 +0200
Subject: [PATCH 09/14] feat(remote): separate the two 409s and express
 clearing a field

Three contract changes landed server-side and are implemented here,
each verified against a rebuilt server rather than read from the source.

Conflicts moved from 422 to 409 with code "conflict", which matters less
for the verdict -- both were already permanent -- than for what shares
that status. A read can answer 409 with code "cursor_expired", meaning
the journal no longer reaches our position, and the two demand opposite
reactions: an expired cursor treated as a conflict abandons a write that
would have succeeded, a conflict treated as an expired cursor throws away
a healthy projection. So the failure type now keeps the server's code as
a structured field, and the catch-up branches on the code, never on the
status. Folding it into the message would have made a destructive
decision rest on a substring match.

Clearing an optional field is now expressible, which closes a real dead
end: a share given an expiry by mistake could not have it removed, and
the owner's only recourse was deleting the share and publishing a
different URL. An unrecognized field name is refused rather than ignored
-- clear=["expiresAt"] answers 422, measured -- so the three accepted
names are spelled in one place instead of inline at each call site.
Setting a field and clearing it are distinct mutations that cannot share
a replay identifier; the queue satisfies that already, since every
enqueue draws a fresh one.

The recovery branch is written even though it cannot fire: the journal is
append-only, so a cursor beyond the last event still returns an empty
page. It is written against a tested contract rather than an imagined
status, which is the difference from the previous position.

The queued payload flags default, so rows written before clearing existed
still deserialize and mean "clear nothing".

Claude-Session: https://claude.ai/code/session_01N9WXrurarkoiT2jgimvyj1
---
 .../rfcs/RFC-005-remote-source-and-sync-v2.md |  50 ++++---
 src-tauri/crates/app/src/remote/client.rs     | 125 +++++++++++++++---
 src-tauri/crates/app/src/remote/drain.rs      |  29 ++++
 src-tauri/crates/app/src/remote/mutation.rs   | 104 ++++++++++++++-
 src-tauri/crates/app/src/remote/sync.rs       |  32 ++++-
 5 files changed, 298 insertions(+), 42 deletions(-)

diff --git a/docs/rfcs/RFC-005-remote-source-and-sync-v2.md b/docs/rfcs/RFC-005-remote-source-and-sync-v2.md
index 1bffa325..2063a7de 100644
--- a/docs/rfcs/RFC-005-remote-source-and-sync-v2.md
+++ b/docs/rfcs/RFC-005-remote-source-and-sync-v2.md
@@ -187,12 +187,20 @@ perfectly ordinary situations:
   retention, not read authorization. A failing ACK must never block
   synchronization.
 
-**Permanent versus transient failure.** The server answers `422
-validation_error` both for a malformed payload and for an operation-id conflict.
-Both are permanent: a retry cannot change the outcome. The queue marks such an
-entry as failed and surfaces it, instead of retrying forever. Only 5xx, 429 and
+**Permanent versus transient failure.** `422 validation_error` (malformed) and
+`409 conflict` (an operation id replayed with a different payload) are both
+permanent: a retry cannot change the outcome, so the entry is marked and
+surfaced rather than spun on. The fixes differ — correct the request versus mint
+a new operation id — which is why the server keeps them apart. Only 5xx, 429 and
 transport errors are retried.
 
+**`409` carries two opposite meanings, so branch on the code.** It is also the
+status for `cursor_expired` on a read, and confusing the two is destructive in
+both directions: an expired cursor treated as a conflict abandons a write that
+would have succeeded, and a conflict treated as an expired cursor throws away a
+healthy projection. The client therefore keeps the server's `code` as a
+structured field and never decides from the status alone.
+
 **Order is load-bearing.** Strict FIFO, and the first retryable failure ends the
 pass so nothing overtakes what it depends on. A permanent failure is the
 exception: it can never succeed, so that entry is marked and the drain moves on
@@ -220,11 +228,19 @@ and it is sound for a specific reason: FIFO guarantees an entry behind an
 unlanded creation has never been presented to the server, so no fingerprint
 exists for it to conflict with.
 
-**What the API cannot express.** Clearing an optional field. Playlist updates
-apply `COALESCE(?, comment)` and share updates do the same for `description`
-**and `expires_at`** — so "leave it alone" and "empty it" are the same request.
-The consequence is worst for the expiry: a share given one by mistake cannot
-have it removed. The mutation types say so rather than pretending otherwise.
+**Emptying a field is its own verb.** An update coalesces, so an absent field
+and an explicit null are indistinguishable — "leave it" and "empty it" would
+otherwise be the same request. Clearing is expressed by naming the field:
+`clear: ["comment"]` on a playlist, `["description", "expires_at"]` on a share.
+Two consequences the client is built around:
+
+- **An unrecognized name is refused, not ignored.** Asking to clear `expiresAt`
+  answers `422` rather than reporting success while nothing moved. That makes
+  those field names load-bearing, so they are spelled in exactly one place
+  instead of inline at each call site.
+- **The clear belongs to the operation fingerprint.** Setting an expiry and
+  removing it are two distinct mutations and cannot share a replay identifier —
+  which the queue satisfies for free, since every enqueue draws a fresh one.
 
 **A share's URL has exactly one moment.** The journal never carries it, and it
 cannot be derived locally — the token is keyed on a server-side instance secret.
@@ -330,14 +346,14 @@ keeping them would carry complexity the protocol no longer asks for.
 - **Last-writer-wins backfill** — a conflict is no longer arbitrated locally: a
   reused operation identifier with a different fingerprint is rejected, and a
   client that cannot apply a known event takes a fresh snapshot.
-- **Compaction and `410 Gone`** — the v2.0 journal is append-only, so no cursor
-  can be too old: `after=` beyond the last event returns an empty page, not an
-  error (measured). There is **no retention contract yet**, and the server side
-  has deliberately not written one. So this path has no trigger today, and the
-  right move is to leave it unwritten rather than code against an imagined
-  status. Recovery still exists — it is driven by a *known event that fails to
-  apply*, which discards the projection and re-snapshots — but that is a
-  different trigger, not a stand-in for compaction.
+- **Compaction and `410 Gone`** — replaced, not dropped. The v2.0 journal is
+  append-only, so no cursor is too old *yet*: a cursor beyond the last event
+  returns an empty page rather than an error. But the contract for when
+  compaction lands is now defined — `/sync/changes` answers `409` with
+  `code: "cursor_expired"` for a cursor below the oldest retained event — and
+  the client implements the recovery against it. Two triggers therefore lead to
+  the same place: a known event that fails to apply, and an expired cursor.
+  Both discard the projection and take a fresh snapshot.
 
 ## The RFC-003 naming trap
 
diff --git a/src-tauri/crates/app/src/remote/client.rs b/src-tauri/crates/app/src/remote/client.rs
index cddda823..2e2de695 100644
--- a/src-tauri/crates/app/src/remote/client.rs
+++ b/src-tauri/crates/app/src/remote/client.rs
@@ -72,10 +72,11 @@ pub enum FailureKind {
     /// Retrying cannot change the outcome. The caller stops and
     /// surfaces the problem.
     ///
-    /// This covers the idempotency conflict: reusing an operation
-    /// identifier with a different fingerprint answers `422`, the same
-    /// status as a malformed payload. The two are indistinguishable on
-    /// the wire and, usefully, call for the same handling.
+    /// Covers both a malformed payload (`422 validation_error`) and an
+    /// idempotency conflict (`409 conflict`). The server separates the
+    /// two on purpose — the fixes differ, one is "correct the request"
+    /// and the other "mint a new operation id" — but neither is helped
+    /// by sending the same bytes again.
     Permanent,
     /// The condition may clear on its own — congestion, a restart, a
     /// flaky link. Worth retrying with backoff.
@@ -85,10 +86,26 @@ pub enum FailureKind {
     Unauthorized,
 }
 
+/// Error code for a cursor that precedes the oldest retained event.
+///
+/// Shares its `409` with [`CODE_CONFLICT`], and the two demand **opposite**
+/// reactions — which is precisely why the code, not the status, is what
+/// gets tested. See [`RemoteFailure::is_cursor_expired`].
+pub const CODE_CURSOR_EXPIRED: &str = "cursor_expired";
+
+/// Error code for a request that collides with existing state — an
+/// operation id replayed with a different payload, most of all.
+pub const CODE_CONFLICT: &str = "conflict";
+
 /// Classify an HTTP status.
 ///
 /// `408` and `429` sit with the 5xx range rather than with the other
 /// 4xx: they describe a moment, not a malformed request.
+///
+/// `409` is permanent **as a status**, which is right for a conflict:
+/// replaying it can never succeed. It is not the whole story for a read,
+/// where the same status may carry `cursor_expired` and mean "recover" —
+/// so callers branch on the code rather than on this alone.
 pub fn classify_status(status: u16) -> Option<FailureKind> {
     match status {
         200..=299 => None,
@@ -105,14 +122,24 @@ pub fn classify_status(status: u16) -> Option<FailureKind> {
 pub struct RemoteFailure {
     pub kind: FailureKind,
     pub status: Option<u16>,
+    /// The server's machine-readable code, kept **structured** rather
+    /// than folded into the message.
+    ///
+    /// It has to be: `409` covers both `conflict` and `cursor_expired`,
+    /// and reacting to one as the other is destructive in both
+    /// directions — treating an expired cursor as a conflict abandons a
+    /// write that would have succeeded, and treating a conflict as an
+    /// expired cursor throws away a perfectly healthy projection.
+    pub code: Option<String>,
     pub message: String,
 }
 
 impl std::fmt::Display for RemoteFailure {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        match self.status {
-            Some(status) => write!(f, "{status}: {}", self.message),
-            None => write!(f, "{}", self.message),
+        match (self.status, &self.code) {
+            (Some(status), Some(code)) => write!(f, "{status} {code}: {}", self.message),
+            (Some(status), None) => write!(f, "{status}: {}", self.message),
+            (None, _) => write!(f, "{}", self.message),
         }
     }
 }
@@ -124,9 +151,22 @@ impl RemoteFailure {
             // about the request's validity — always worth retrying.
             kind: FailureKind::Transient,
             status: None,
+            code: None,
             message: error.to_string(),
         }
     }
+
+    /// The journal no longer reaches back this far: discard the
+    /// projection and take a fresh snapshot.
+    pub fn is_cursor_expired(&self) -> bool {
+        self.code.as_deref() == Some(CODE_CURSOR_EXPIRED)
+    }
+
+    /// The request collides with existing state. Permanent, and the fix
+    /// is a new operation id — never a retry of this one.
+    pub fn is_conflict(&self) -> bool {
+        self.code.as_deref() == Some(CODE_CONFLICT)
+    }
 }
 
 /// The server's error body. Both fields are always present.
@@ -293,6 +333,7 @@ impl RemoteClient {
             // promises. Retrying re-fetches the same bytes.
             kind: FailureKind::Permanent,
             status: None,
+            code: None,
             message: format!("malformed response body: {err}"),
         })
     }
@@ -311,6 +352,7 @@ impl RemoteClient {
             return Err(RemoteFailure {
                 kind: FailureKind::Transient,
                 status: None,
+                code: None,
                 message: "offline mode is on".into(),
             });
         }
@@ -320,15 +362,18 @@ impl RemoteClient {
         match classify_status(status) {
             None => Ok(response),
             Some(kind) => {
-                // Read the structured body while we still can — it names
-                // the failure far better than the status alone.
-                let message = match response.json::<ErrorBody>().await {
-                    Ok(body) => format!("{} ({})", body.message, body.code),
-                    Err(_) => "no error body".to_string(),
+                // Read the structured body while we still can. The code
+                // is kept as a field, not formatted away: callers have to
+                // branch on it, and a substring match on a message would
+                // be a fragile way to make a destructive decision.
+                let (code, message) = match response.json::<ErrorBody>().await {
+                    Ok(body) => (Some(body.code), body.message),
+                    Err(_) => (None, "no error body".to_string()),
                 };
                 Err(RemoteFailure {
                     kind,
                     status: Some(status),
+                    code,
                     message,
                 })
             }
@@ -457,11 +502,59 @@ mod tests {
     }
 
     #[test]
-    fn an_idempotency_conflict_is_permanent() {
-        // The server answers 422 both for a malformed payload and for a
-        // reused operation id with a different fingerprint. Neither can
-        // succeed on retry, so the queue must stop rather than spin.
+    fn a_malformed_payload_and_a_conflict_are_both_permanent() {
+        // Different codes, different fixes, same verdict for the queue:
+        // sending the same bytes again cannot help.
         assert_eq!(classify_status(422), Some(FailureKind::Permanent));
+        assert_eq!(classify_status(409), Some(FailureKind::Permanent));
+    }
+
+    fn failure(status: u16, code: &str) -> RemoteFailure {
+        RemoteFailure {
+            kind: classify_status(status).unwrap(),
+            status: Some(status),
+            code: Some(code.into()),
+            message: "…".into(),
+        }
+    }
+
+    #[test]
+    fn the_two_meanings_of_409_are_told_apart_by_code_not_status() {
+        // Confusing them is destructive both ways: an expired cursor
+        // read as a conflict abandons a write that would have worked, a
+        // conflict read as an expired cursor throws away a healthy
+        // projection.
+        let expired = failure(409, CODE_CURSOR_EXPIRED);
+        assert!(expired.is_cursor_expired());
+        assert!(!expired.is_conflict());
+
+        let conflict = failure(409, CODE_CONFLICT);
+        assert!(conflict.is_conflict());
+        assert!(!conflict.is_cursor_expired());
+
+        assert_eq!(expired.status, conflict.status, "the status cannot decide");
+    }
+
+    #[test]
+    fn a_failure_without_a_code_claims_neither_meaning() {
+        // A body we could not parse must not be guessed into a
+        // destructive branch.
+        let opaque = RemoteFailure {
+            kind: FailureKind::Permanent,
+            status: Some(409),
+            code: None,
+            message: "no error body".into(),
+        };
+        assert!(!opaque.is_cursor_expired());
+        assert!(!opaque.is_conflict());
+    }
+
+    #[test]
+    fn the_code_shows_up_when_a_failure_is_displayed() {
+        assert_eq!(
+            failure(409, CODE_CURSOR_EXPIRED).to_string(),
+            "409 cursor_expired: …"
+        );
     }
 
     #[test]
diff --git a/src-tauri/crates/app/src/remote/drain.rs b/src-tauri/crates/app/src/remote/drain.rs
index 852f3724..c4fdb4c7 100644
--- a/src-tauri/crates/app/src/remote/drain.rs
+++ b/src-tauri/crates/app/src/remote/drain.rs
@@ -28,6 +28,17 @@ use crate::{
 /// holding a profile lease across thousands of round-trips.
 const BATCH: i64 = 100;
 
+/// Names the `clear` array accepts, spelled once.
+///
+/// A name the server does not recognize is **rejected with 422** rather
+/// than ignored — deliberately, so a client asking to clear `expiresAt`
+/// hears that nothing happened instead of being told all is well. That
+/// makes these three strings load-bearing, and worth having in exactly
+/// one place rather than inline at each call site.
+const FIELD_COMMENT: &str = "comment";
+const FIELD_DESCRIPTION: &str = "description";
+const FIELD_EXPIRES_AT: &str = "expires_at";
+
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
 pub struct DrainReport {
     pub sent: usize,
@@ -204,6 +215,7 @@ async fn send(
             public,
             add,
             remove_indexes,
+            clear_comment,
         } => {
             if mutation::is_placeholder(playlist_id) {
                 // The creation this depends on never landed, so the
@@ -213,6 +225,7 @@ async fn send(
                 return Err(RemoteFailure {
                     kind: FailureKind::Permanent,
                     status: None,
+                    code: None,
                     message: "the playlist this edit belongs to was never created on the server"
                         .into(),
                 });
@@ -237,6 +250,9 @@ async fn send(
             if !remove_indexes.is_empty() {
                 body.insert("remove_indexes".into(), serde_json::json!(remove_indexes));
             }
+            if *clear_comment {
+                body.insert("clear".into(), serde_json::json!([FIELD_COMMENT]));
+            }
             client
                 .send_ok(
                     client
@@ -328,11 +344,14 @@ async fn send(
             share_id,
             description,
             expires_at,
+            clear_description,
+            clear_expires_at,
         } => {
             if mutation::is_placeholder(share_id) {
                 return Err(RemoteFailure {
                     kind: FailureKind::Permanent,
                     status: None,
+                    code: None,
                     message: "the share this edit belongs to was never created on the server"
                         .into(),
                 });
@@ -345,6 +364,16 @@ async fn send(
             if let Some(expires_at) = expires_at {
                 body.insert("expires_at".into(), serde_json::json!(expires_at));
             }
+            let mut clear = Vec::new();
+            if *clear_description {
+                clear.push(FIELD_DESCRIPTION);
+            }
+            if *clear_expires_at {
+                clear.push(FIELD_EXPIRES_AT);
+            }
+            if !clear.is_empty() {
+                body.insert("clear".into(), serde_json::json!(clear));
+            }
             client
                 .send_ok(
                     client
diff --git a/src-tauri/crates/app/src/remote/mutation.rs b/src-tauri/crates/app/src/remote/mutation.rs
index a2dec793..af6ccc04 100644
--- a/src-tauri/crates/app/src/remote/mutation.rs
+++ b/src-tauri/crates/app/src/remote/mutation.rs
@@ -89,10 +89,12 @@ pub enum Mutation {
     },
     /// A field left `None` is unchanged.
     ///
-    /// Note what cannot be expressed: the server applies
-    /// `COALESCE(?, comment)`, so a null comment keeps the current one.
-    /// **Clearing a comment is not possible through this API** — sending
-    /// `None` and sending "please empty it" are the same request.
+    /// Emptying one is a separate verb — see [`clear_comment`] — because
+    /// the server coalesces an absent field and an explicit null
+    /// identically. Naming the field is the only way to say "empty it",
+    /// and it cannot fire by accident on a caller that simply omits it.
+    ///
+    /// [`clear_comment`]: Mutation::UpdatePlaylist::clear_comment
     UpdatePlaylist {
         playlist_id: String,
         name: Option<String>,
@@ -102,6 +104,13 @@ pub enum Mutation {
         /// server applies them in.
         add: Vec<String>,
         remove_indexes: Vec<usize>,
+        /// Blank the comment out. `comment` is the only clearable field
+        /// on a playlist.
+        ///
+        /// `default` on purpose: rows queued by a build that predates
+        /// this field still deserialize, and they mean "clear nothing".
+        #[serde(default)]
+        clear_comment: bool,
     },
     DeletePlaylist {
         playlist_id: String,
@@ -129,13 +138,21 @@ pub enum Mutation {
         description: Option<String>,
         expires_at: Option<i64>,
     },
-    /// Same coalescing limitation as [`Mutation::UpdatePlaylist`], and
-    /// it bites harder here: `expires_at` is also `COALESCE`d, so an
-    /// expiry set by mistake **cannot be removed** through this API.
+    /// Same shape as [`Mutation::UpdatePlaylist`], with two clearable
+    /// fields instead of one.
+    ///
+    /// Clearing the expiry is the one that matters: without it, an
+    /// expiry set by mistake would be permanent, and the owner's only
+    /// recourse would be deleting the share and publishing a different
+    /// URL.
     UpdateShare {
         share_id: String,
         description: Option<String>,
         expires_at: Option<i64>,
+        #[serde(default)]
+        clear_description: bool,
+        #[serde(default)]
+        clear_expires_at: bool,
     },
     DeleteShare {
         share_id: String,
@@ -403,6 +420,7 @@ async fn rewrite_queued_references(
                 public,
                 add,
                 remove_indexes,
+                clear_comment,
                 ..
             } => Mutation::UpdatePlaylist {
                 playlist_id: remote_id.to_string(),
@@ -411,6 +429,7 @@ async fn rewrite_queued_references(
                 public,
                 add,
                 remove_indexes,
+                clear_comment,
             },
             Mutation::DeletePlaylist { .. } => Mutation::DeletePlaylist {
                 playlist_id: remote_id.to_string(),
@@ -418,11 +437,15 @@ async fn rewrite_queued_references(
             Mutation::UpdateShare {
                 description,
                 expires_at,
+                clear_description,
+                clear_expires_at,
                 ..
             } => Mutation::UpdateShare {
                 share_id: remote_id.to_string(),
                 description,
                 expires_at,
+                clear_description,
+                clear_expires_at,
             },
             Mutation::DeleteShare { .. } => Mutation::DeleteShare {
                 share_id: remote_id.to_string(),
@@ -607,6 +630,7 @@ mod tests {
                 public: None,
                 add: vec![],
                 remove_indexes: vec![],
+                clear_comment: false,
             },
         )
         .await
@@ -732,6 +756,72 @@ mod tests {
         );
     }
 
+    #[tokio::test]
+    async fn setting_a_field_and_clearing_it_are_two_operations() {
+        // The clear is part of the server's operation fingerprint, so
+        // "set an expiry" and "remove it" cannot share a replay
+        // identifier — presenting one id with the other's payload is
+        // rejected as a conflict.
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+
+        let set = enqueue(
+            &mut conn,
+            &Mutation::UpdateShare {
+                share_id: "s1".into(),
+                description: None,
+                expires_at: Some(9_999),
+                clear_description: false,
+                clear_expires_at: false,
+            },
+        )
+        .await
+        .unwrap();
+        let cleared = enqueue(
+            &mut conn,
+            &Mutation::UpdateShare {
+                share_id: "s1".into(),
+                description: None,
+                expires_at: None,
+                clear_description: false,
+                clear_expires_at: true,
+            },
+        )
+        .await
+        .unwrap();
+
+        assert_ne!(set, cleared);
+        assert_eq!(pending(&mut conn, 10).await.unwrap().len(), 2);
+    }
+
+    #[tokio::test]
+    async fn a_row_queued_before_clearing_existed_still_reads() {
+        // Backwards compatibility with payloads written by an earlier
+        // build: the absent flags mean "clear nothing".
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        sqlx::query(
+            "INSERT INTO remote_mutation (operation_id, kind, payload, created_at)
+             VALUES ('op-old', 'update_share', ?, 0)",
+        )
+        .bind(r#"{"kind":"update_share","share_id":"s1","description":"a","expires_at":null}"#)
+        .execute(&mut *conn)
+        .await
+        .unwrap();
+
+        let queued = pending(&mut conn, 10).await.unwrap();
+        assert_eq!(
+            queued[0].mutation,
+            Mutation::UpdateShare {
+                share_id: "s1".into(),
+                description: Some("a".into()),
+                expires_at: None,
+                clear_description: false,
+                clear_expires_at: false,
+            }
+        );
+    }
+
     #[test]
     fn a_server_identifier_is_never_mistaken_for_a_placeholder() {
         assert!(!is_placeholder("31be1c98-3984-40ff-8352-73fc6e2c29b5"));
diff --git a/src-tauri/crates/app/src/remote/sync.rs b/src-tauri/crates/app/src/remote/sync.rs
index 51a79e04..08da51a6 100644
--- a/src-tauri/crates/app/src/remote/sync.rs
+++ b/src-tauri/crates/app/src/remote/sync.rs
@@ -171,13 +171,41 @@ pub async fn catch_up(
             break;
         }
 
-        let page: SyncPage = client
+        let page: SyncPage = match client
             .send_json(client.get(&format!(
                 "/api/v2/sync/changes?after={}&limit={PAGE_LIMIT}",
                 report.cursor
             )))
             .await
-            .map_err(|failure| AppError::Other(format!("could not fetch changes: {failure}")))?;
+        {
+            Ok(page) => page,
+            // The journal no longer reaches back this far — a future
+            // compaction dropped the events between our cursor and the
+            // surviving floor. Nothing local can fill that gap, so the
+            // projection is discarded and rebuilt from a snapshot.
+            //
+            // Tested on the *code*, never the status: `409` also carries
+            // `conflict`, and mistaking that for this would throw away a
+            // perfectly healthy projection over a rejected write.
+            Err(failure) if failure.is_cursor_expired() => {
+                tracing::info!(
+                    cursor = report.cursor,
+                    "the journal no longer reaches this cursor; taking a fresh snapshot"
+                );
+                let cursor = bootstrap(state, profile_id, client).await?;
+                return Ok(SyncReport {
+                    cursor,
+                    resnapshotted: true,
+                    pages: report.pages + 1,
+                    ..Default::default()
+                });
+            }
+            Err(failure) => {
+                return Err(AppError::Other(format!(
+                    "could not fetch changes: {failure}"
+                )))
+            }
+        };
 
         report.pages += 1;
         let has_more = page.has_more;

From 94bf6fae9861d11c4329874c130e8189ce89828b Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Wed, 12 Aug 2026 21:25:45 +0200
Subject: [PATCH 10/14] feat(remote): read the projection back out for the
 interface

Commands and typed wrappers over the local tables: a counted overview,
the playlists, one playlist's tracks, the saved queue. Pure queries --
they answer instantly and answer the same whether or not the server is
reachable, which is the point of keeping a projection at all.

Three decisions that shape what a user will see. A track whose metadata
has not been fetched yet keeps its position and comes back with a null
title, because an inner join would drop it and renumber everything after
it, making a playlist look shorter than it is while a backfill is merely
outstanding. A playlist summary sums only the durations it knows, so it
understates rather than refusing to show a number. And a playlist still
carrying a local placeholder is flagged, because it is the one that
exists nowhere else and would vanish if the user forgot this server.

The overview counts pending and permanently-failed changes apart. They
mean different things: one is "not yet", the other is "never, and nobody
will say so unless we do".

No profile active answers empty rather than failing -- onboarding queries
this before one exists.

Claude-Session: https://claude.ai/code/session_01N9WXrurarkoiT2jgimvyj1
---
 .../crates/app/src/commands/remote_auth.rs    |  64 ++++
 src-tauri/crates/app/src/lib.rs               |   8 +
 src-tauri/crates/app/src/remote/mod.rs        |   5 +
 src-tauri/crates/app/src/remote/read.rs       | 326 ++++++++++++++++++
 src/lib/tauri/remoteServer.ts                 |  78 +++++
 5 files changed, 481 insertions(+)
 create mode 100644 src-tauri/crates/app/src/remote/read.rs

diff --git a/src-tauri/crates/app/src/commands/remote_auth.rs b/src-tauri/crates/app/src/commands/remote_auth.rs
index 858cb89c..4fb965e6 100644
--- a/src-tauri/crates/app/src/commands/remote_auth.rs
+++ b/src-tauri/crates/app/src/commands/remote_auth.rs
@@ -151,6 +151,70 @@ pub async fn remote_sync_now(state: tauri::State<'_, AppState>) -> AppResult<Rem
     })
 }
 
+/// Counts for the diagnostics panel. Reads the local projection only —
+/// answers instantly, and answers the same whether or not the server is
+/// reachable.
+#[tauri::command]
+pub async fn remote_get_overview(
+    state: tauri::State<'_, AppState>,
+) -> AppResult<crate::remote::read::RemoteOverview> {
+    let Some(mut conn) = optional_conn(&state).await? else {
+        return Ok(Default::default());
+    };
+    crate::remote::read::overview(&mut conn).await
+}
+
+/// The projected playlists, most recently touched first.
+#[tauri::command]
+pub async fn remote_list_playlists(
+    state: tauri::State<'_, AppState>,
+) -> AppResult<Vec<crate::remote::read::RemotePlaylistSummary>> {
+    let Some(mut conn) = optional_conn(&state).await? else {
+        return Ok(Vec::new());
+    };
+    crate::remote::read::playlists(&mut conn).await
+}
+
+/// One playlist's tracks, in order. Entries whose metadata has not been
+/// fetched yet come back with a null title rather than being skipped —
+/// dropping them would make the playlist look shorter than it is.
+#[tauri::command]
+pub async fn remote_list_playlist_tracks(
+    state: tauri::State<'_, AppState>,
+    playlist_id: String,
+) -> AppResult<Vec<crate::remote::read::RemoteTrack>> {
+    let Some(mut conn) = optional_conn(&state).await? else {
+        return Ok(Vec::new());
+    };
+    crate::remote::read::playlist_tracks(&mut conn, &playlist_id).await
+}
+
+/// The account's saved queue, in order.
+#[tauri::command]
+pub async fn remote_list_queue(
+    state: tauri::State<'_, AppState>,
+) -> AppResult<Vec<crate::remote::read::RemoteTrack>> {
+    let Some(mut conn) = optional_conn(&state).await? else {
+        return Ok(Vec::new());
+    };
+    crate::remote::read::queue_tracks(&mut conn).await
+}
+
+/// A connection to the active profile, or `None` when there is no
+/// active profile.
+///
+/// No profile is an ordinary state for these reads — onboarding queries
+/// them before one exists — so it answers empty rather than failing.
+async fn optional_conn(
+    state: &AppState,
+) -> AppResult<Option<sqlx::pool::PoolConnection<sqlx::Sqlite>>> {
+    match state.require_profile_pool().await {
+        Ok(pool) => Ok(Some(pool.acquire().await?)),
+        Err(AppError::NoActiveProfile) => Ok(None),
+        Err(err) => Err(err),
+    }
+}
+
 async fn status(state: &AppState) -> AppResult<RemoteStatus> {
     // No active profile is a legitimate state here — the onboarding
     // screens can query this before one exists — so it answers "unbound"
diff --git a/src-tauri/crates/app/src/lib.rs b/src-tauri/crates/app/src/lib.rs
index 5d86aebc..43de1d89 100644
--- a/src-tauri/crates/app/src/lib.rs
+++ b/src-tauri/crates/app/src/lib.rs
@@ -786,6 +786,14 @@ pub fn run() {
             commands::remote_auth::remote_forget_server,
             #[cfg(feature = "sync_v2")]
             commands::remote_auth::remote_sync_now,
+            #[cfg(feature = "sync_v2")]
+            commands::remote_auth::remote_get_overview,
+            #[cfg(feature = "sync_v2")]
+            commands::remote_auth::remote_list_playlists,
+            #[cfg(feature = "sync_v2")]
+            commands::remote_auth::remote_list_playlist_tracks,
+            #[cfg(feature = "sync_v2")]
+            commands::remote_auth::remote_list_queue,
             #[cfg(feature = "sync_v1")]
             commands::server_auth::server_get_status,
             #[cfg(feature = "sync_v1")]
diff --git a/src-tauri/crates/app/src/remote/mod.rs b/src-tauri/crates/app/src/remote/mod.rs
index 03252430..1fdba93b 100644
--- a/src-tauri/crates/app/src/remote/mod.rs
+++ b/src-tauri/crates/app/src/remote/mod.rs
@@ -47,6 +47,10 @@
 //! - [`projection`] — writing the server's user data into the local
 //!   `remote_*` tables. Pure database work, testable without a network.
 //!
+//! - [`read`] — reading it back out for the UI. Also pure: what the
+//!   projection holds is already the answer, so nothing here needs the
+//!   server to be reachable.
+//!
 //! - [`sync`] — the orchestrator: bootstrap from a snapshot, walk the
 //!   journal, acknowledge, and recover by re-snapshotting when a known
 //!   event cannot be applied.
@@ -83,6 +87,7 @@ pub mod dto;
 pub mod mutation;
 pub mod probe;
 pub mod projection;
+pub mod read;
 pub mod socket;
 pub mod sync;
 pub mod tokens;
diff --git a/src-tauri/crates/app/src/remote/read.rs b/src-tauri/crates/app/src/remote/read.rs
new file mode 100644
index 00000000..c9aa314d
--- /dev/null
+++ b/src-tauri/crates/app/src/remote/read.rs
@@ -0,0 +1,326 @@
+//! Reading the projection back out, for the UI.
+//!
+//! Pure queries over the `remote_*` tables — no HTTP, no client. What
+//! the projection holds is already the answer; nothing here needs the
+//! server to be reachable, which is the point of keeping a local
+//! projection at all.
+//!
+//! ## Tracks may be identifiers with no metadata yet
+//!
+//! A playlist that arrived through `/sync/changes` carries bare track
+//! identifiers until the backfill fetches them. Rather than hide those
+//! rows or block on a fetch, the queries below return them with
+//! `title: None`, so the caller can render a placeholder in the right
+//! position instead of a playlist that is silently short a few entries.
+
+use serde::Serialize;
+use sqlx::{Row, SqliteConnection};
+
+use crate::error::AppResult;
+
+/// Enough to tell, at a glance, whether synchronization is working.
+#[derive(Debug, Clone, Serialize, Default, PartialEq, Eq)]
+pub struct RemoteOverview {
+    pub playlists: i64,
+    pub favorites: i64,
+    pub ratings: i64,
+    pub history: i64,
+    pub shares: i64,
+    /// Tracks in the saved queue, if the account has one.
+    pub queue_tracks: i64,
+    /// Cached track metadata rows.
+    pub cached_tracks: i64,
+    /// Identifiers the projection references but has no metadata for.
+    /// A non-zero value is normal right after a catch-up and should
+    /// fall back to zero on the next pass.
+    pub tracks_awaiting_metadata: i64,
+    /// Local changes not yet accepted by the server.
+    pub pending_changes: i64,
+    /// Local changes the server refused permanently. These need a
+    /// human: they will never be retried.
+    pub failed_changes: i64,
+}
+
+/// A playlist as the list view needs it.
+#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
+pub struct RemotePlaylistSummary {
+    pub id: String,
+    pub name: String,
+    pub comment: Option<String>,
+    pub is_public: bool,
+    pub track_count: i64,
+    /// Total duration of the tracks we have metadata for. Understates
+    /// while a backfill is outstanding, which is better than refusing
+    /// to show a number at all.
+    pub duration_ms: i64,
+    /// `true` while this playlist exists only here — created offline,
+    /// its creation still queued. It has no server identifier yet.
+    pub pending_creation: bool,
+}
+
+/// One entry of a playlist, in position order.
+#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
+pub struct RemoteTrack {
+    pub id: String,
+    /// `None` when the identifier arrived through a change event and
+    /// the metadata has not been fetched yet.
+    pub title: Option<String>,
+    pub artist: Option<String>,
+    pub album: Option<String>,
+    pub duration_ms: Option<i64>,
+    pub artwork_hash: Option<String>,
+}
+
+/// Count everything worth counting, in one round-trip.
+pub async fn overview(conn: &mut SqliteConnection) -> AppResult<RemoteOverview> {
+    let row = sqlx::query(
+        "SELECT
+            (SELECT count(*) FROM remote_playlist)      AS playlists,
+            (SELECT count(*) FROM remote_favorite)      AS favorites,
+            (SELECT count(*) FROM remote_rating)        AS ratings,
+            (SELECT count(*) FROM remote_history)       AS history,
+            (SELECT count(*) FROM remote_share)         AS shares,
+            (SELECT count(*) FROM remote_queue_track)   AS queue_tracks,
+            (SELECT count(*) FROM remote_track)         AS cached_tracks,
+            (SELECT count(*) FROM remote_mutation WHERE failed_at IS NULL)     AS pending_changes,
+            (SELECT count(*) FROM remote_mutation WHERE failed_at IS NOT NULL) AS failed_changes",
+    )
+    .fetch_one(&mut *conn)
+    .await?;
+
+    Ok(RemoteOverview {
+        playlists: row.try_get("playlists")?,
+        favorites: row.try_get("favorites")?,
+        ratings: row.try_get("ratings")?,
+        history: row.try_get("history")?,
+        shares: row.try_get("shares")?,
+        queue_tracks: row.try_get("queue_tracks")?,
+        cached_tracks: row.try_get("cached_tracks")?,
+        tracks_awaiting_metadata: super::projection::missing_track_ids(&mut *conn)
+            .await?
+            .len() as i64,
+        pending_changes: row.try_get("pending_changes")?,
+        failed_changes: row.try_get("failed_changes")?,
+    })
+}
+
+/// Every projected playlist, newest activity first.
+pub async fn playlists(conn: &mut SqliteConnection) -> AppResult<Vec<RemotePlaylistSummary>> {
+    let rows = sqlx::query(
+        "SELECT p.remote_id, p.name, p.comment, p.is_public,
+                (SELECT count(*) FROM remote_playlist_track t
+                  WHERE t.playlist_remote_id = p.remote_id) AS track_count,
+                COALESCE((SELECT SUM(rt.duration_ms)
+                            FROM remote_playlist_track t
+                            JOIN remote_track rt ON rt.remote_id = t.track_remote_id
+                           WHERE t.playlist_remote_id = p.remote_id), 0) AS duration_ms
+           FROM remote_playlist p
+          ORDER BY COALESCE(p.updated_at, p.created_at, 0) DESC, p.name",
+    )
+    .fetch_all(&mut *conn)
+    .await?;
+
+    rows.into_iter()
+        .map(|row| {
+            let id: String = row.try_get("remote_id")?;
+            Ok(RemotePlaylistSummary {
+                pending_creation: super::mutation::is_placeholder(&id),
+                id,
+                name: row.try_get("name")?,
+                comment: row.try_get("comment")?,
+                is_public: row.try_get::<i64, _>("is_public")? != 0,
+                track_count: row.try_get("track_count")?,
+                duration_ms: row.try_get("duration_ms")?,
+            })
+        })
+        .collect()
+}
+
+/// A playlist's tracks, in position order, placeholders included.
+///
+/// The join is a LEFT JOIN on purpose: an identifier without metadata
+/// still occupies its position. Dropping it would renumber everything
+/// after it and make a playlist look shorter than it is.
+pub async fn playlist_tracks(
+    conn: &mut SqliteConnection,
+    playlist_id: &str,
+) -> AppResult<Vec<RemoteTrack>> {
+    let rows = sqlx::query(
+        "SELECT t.track_remote_id, rt.title, rt.artist, rt.album, rt.duration_ms, rt.artwork_hash
+           FROM remote_playlist_track t
+           LEFT JOIN remote_track rt ON rt.remote_id = t.track_remote_id
+          WHERE t.playlist_remote_id = ?
+          ORDER BY t.position",
+    )
+    .bind(playlist_id)
+    .fetch_all(&mut *conn)
+    .await?;
+
+    rows.into_iter().map(track_from_row).collect()
+}
+
+/// The account's saved queue, in order.
+pub async fn queue_tracks(conn: &mut SqliteConnection) -> AppResult<Vec<RemoteTrack>> {
+    let rows = sqlx::query(
+        "SELECT q.track_remote_id, rt.title, rt.artist, rt.album, rt.duration_ms, rt.artwork_hash
+           FROM remote_queue_track q
+           LEFT JOIN remote_track rt ON rt.remote_id = q.track_remote_id
+          ORDER BY q.position",
+    )
+    .fetch_all(&mut *conn)
+    .await?;
+
+    rows.into_iter().map(track_from_row).collect()
+}
+
+fn track_from_row(row: sqlx::sqlite::SqliteRow) -> AppResult<RemoteTrack> {
+    Ok(RemoteTrack {
+        id: row.try_get("track_remote_id")?,
+        title: row.try_get("title")?,
+        artist: row.try_get("artist")?,
+        album: row.try_get("album")?,
+        duration_ms: row.try_get("duration_ms")?,
+        artwork_hash: row.try_get("artwork_hash")?,
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::remote::dto::SyncSnapshot;
+    use sqlx::sqlite::SqlitePoolOptions;
+    use sqlx::SqlitePool;
+
+    async fn pool() -> SqlitePool {
+        let pool = SqlitePoolOptions::new()
+            .max_connections(1)
+            .connect(":memory:")
+            .await
+            .unwrap();
+        for migration in [
+            include_str!(
+                "../../../../migrations/profile/20260810120000_remote_source_projection.sql"
+            ),
+            include_str!("../../../../migrations/profile/20260810140000_remote_track_cache.sql"),
+        ] {
+            sqlx::raw_sql(migration).execute(&pool).await.unwrap();
+        }
+        pool
+    }
+
+    /// The same capture the projection tests replay: a real server's
+    /// snapshot of a seeded library.
+    const REAL_SNAPSHOT: &str = include_str!("testdata/snapshot.json");
+
+    #[tokio::test]
+    async fn the_overview_counts_a_real_snapshot() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        let snapshot: SyncSnapshot = serde_json::from_str(REAL_SNAPSHOT).unwrap();
+        crate::remote::projection::apply_snapshot(&mut conn, &snapshot)
+            .await
+            .unwrap();
+
+        let overview = overview(&mut conn).await.unwrap();
+        assert_eq!(overview.playlists, 1);
+        assert_eq!(overview.favorites, 2);
+        assert_eq!(overview.ratings, 2);
+        assert_eq!(overview.history, 2);
+        assert_eq!(overview.shares, 1);
+        assert_eq!(overview.queue_tracks, 3);
+        assert_eq!(overview.tracks_awaiting_metadata, 0);
+        assert_eq!(overview.pending_changes, 0);
+    }
+
+    #[tokio::test]
+    async fn an_unbound_profile_reads_as_all_zeroes_rather_than_failing() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        assert_eq!(overview(&mut conn).await.unwrap(), RemoteOverview::default());
+        assert!(playlists(&mut conn).await.unwrap().is_empty());
+    }
+
+    #[tokio::test]
+    async fn a_track_without_metadata_keeps_its_position() {
+        // The bug this guards: an inner join would drop the row and
+        // renumber everything after it, so a playlist would silently
+        // look shorter than it is while a backfill is outstanding.
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        sqlx::raw_sql(
+            "INSERT INTO remote_playlist (remote_id, name) VALUES ('p1', 'Mix');
+             INSERT INTO remote_playlist_track VALUES ('p1', 0, 'known'), ('p1', 1, 'unknown'),
+                                                      ('p1', 2, 'known2');
+             INSERT INTO remote_track (remote_id, title, duration_ms, cached_at)
+                VALUES ('known', 'First', 1000, 0), ('known2', 'Third', 3000, 0);",
+        )
+        .execute(&mut *conn)
+        .await
+        .unwrap();
+
+        let tracks = playlist_tracks(&mut conn, "p1").await.unwrap();
+        assert_eq!(tracks.len(), 3);
+        assert_eq!(tracks[0].title.as_deref(), Some("First"));
+        assert_eq!(tracks[1].title, None, "the placeholder lost its slot");
+        assert_eq!(tracks[1].id, "unknown");
+        assert_eq!(tracks[2].title.as_deref(), Some("Third"));
+    }
+
+    #[tokio::test]
+    async fn a_summary_understates_rather_than_refusing_a_duration() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        sqlx::raw_sql(
+            "INSERT INTO remote_playlist (remote_id, name) VALUES ('p1', 'Mix');
+             INSERT INTO remote_playlist_track VALUES ('p1', 0, 'known'), ('p1', 1, 'unknown');
+             INSERT INTO remote_track (remote_id, title, duration_ms, cached_at)
+                VALUES ('known', 'First', 1000, 0);",
+        )
+        .execute(&mut *conn)
+        .await
+        .unwrap();
+
+        let summaries = playlists(&mut conn).await.unwrap();
+        assert_eq!(summaries[0].track_count, 2, "both entries are counted");
+        assert_eq!(summaries[0].duration_ms, 1000, "only the known one adds up");
+        assert!(!summaries[0].pending_creation);
+    }
+
+    #[tokio::test]
+    async fn a_playlist_created_offline_is_flagged_as_such() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        let local_id = crate::remote::mutation::new_placeholder();
+        sqlx::query("INSERT INTO remote_playlist (remote_id, name) VALUES (?, 'Offline')")
+            .bind(&local_id)
+            .execute(&mut *conn)
+            .await
+            .unwrap();
+
+        let summaries = playlists(&mut conn).await.unwrap();
+        assert!(
+            summaries[0].pending_creation,
+            "the UI cannot tell the user this one has not left the machine"
+        );
+    }
+
+    #[tokio::test]
+    async fn failed_changes_are_counted_apart_from_pending_ones() {
+        // They mean different things to a user: one is "not yet", the
+        // other is "never, and nobody will tell you unless we do".
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        sqlx::raw_sql(
+            "INSERT INTO remote_mutation (operation_id, kind, payload, created_at)
+                VALUES ('a', 'k', '{}', 0), ('b', 'k', '{}', 0);
+             UPDATE remote_mutation SET failed_at = 1 WHERE operation_id = 'b';",
+        )
+        .execute(&mut *conn)
+        .await
+        .unwrap();
+
+        let overview = overview(&mut conn).await.unwrap();
+        assert_eq!(overview.pending_changes, 1);
+        assert_eq!(overview.failed_changes, 1);
+    }
+}
diff --git a/src/lib/tauri/remoteServer.ts b/src/lib/tauri/remoteServer.ts
index 6d3c4df5..0996f611 100644
--- a/src/lib/tauri/remoteServer.ts
+++ b/src/lib/tauri/remoteServer.ts
@@ -126,3 +126,81 @@ export interface RemoteSyncReport {
 export function remoteSyncNow(): Promise<RemoteSyncReport> {
   return invoke<RemoteSyncReport>("remote_sync_now");
 }
+
+export interface RemoteOverview {
+  playlists: number;
+  favorites: number;
+  ratings: number;
+  history: number;
+  shares: number;
+  queue_tracks: number;
+  cached_tracks: number;
+  /**
+   * Identifiers the projection references but has no metadata for.
+   * Normal right after a catch-up; it should fall back to zero on the
+   * next pass.
+   */
+  tracks_awaiting_metadata: number;
+  /** Local changes the server has not accepted yet. */
+  pending_changes: number;
+  /**
+   * Local changes the server refused permanently. These will never be
+   * retried, so surface them — nobody else will say anything.
+   */
+  failed_changes: number;
+}
+
+export interface RemotePlaylistSummary {
+  id: string;
+  name: string;
+  comment: string | null;
+  is_public: boolean;
+  track_count: number;
+  /**
+   * Sums only the tracks whose metadata is cached, so it understates
+   * while a backfill is outstanding. Showing an approximate duration
+   * beats refusing to show one.
+   */
+  duration_ms: number;
+  /**
+   * Created here and never sent: the server has no such playlist yet.
+   * Worth showing, because it is the one that disappears if the user
+   * forgets this server.
+   */
+  pending_creation: boolean;
+}
+
+export interface RemoteTrack {
+  id: string;
+  /** `null` while the metadata has not been fetched yet. */
+  title: string | null;
+  artist: string | null;
+  album: string | null;
+  duration_ms: number | null;
+  artwork_hash: string | null;
+}
+
+/** Counts for the diagnostics panel. Local only — instant, and the same
+ * answer whether or not the server is reachable. */
+export function remoteGetOverview(): Promise<RemoteOverview> {
+  return invoke<RemoteOverview>("remote_get_overview");
+}
+
+export function remoteListPlaylists(): Promise<RemotePlaylistSummary[]> {
+  return invoke<RemotePlaylistSummary[]>("remote_list_playlists");
+}
+
+/**
+ * One playlist's tracks, in order. Entries still awaiting metadata come
+ * back with a null title rather than being skipped — dropping them would
+ * make the playlist look shorter than it is.
+ */
+export function remoteListPlaylistTracks(
+  playlistId: string,
+): Promise<RemoteTrack[]> {
+  return invoke<RemoteTrack[]>("remote_list_playlist_tracks", { playlistId });
+}
+
+export function remoteListQueue(): Promise<RemoteTrack[]> {
+  return invoke<RemoteTrack[]>("remote_list_queue");
+}

From f0e78ef611f19b2232b6c273162126d09aef00fe Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Wed, 12 Aug 2026 21:28:30 +0200
Subject: [PATCH 11/14] feat(remote): a diagnostics card so the protocol can be
 watched by a human

Mounts a Settings panel that identifies a server, signs in through the
browser, synchronizes on demand and shows what the projection holds.
This is the one thing unit tests cannot do for this feature: watch it
run.

Two decisions worth stating. The card is not localized, unlike every
other string in the app -- the sync_v2 feature is off by default, so no
shipped build can render it, and translating copy nobody can reach and
that will still change would put a couple of hundred unreviewed strings
into files that had a native-speaker pass. The keys land when the
feature ships and the wording settles.

And it hides itself rather than trusting a build flag TypeScript cannot
see: it probes for its own backend command and renders nothing when the
command is not registered, which is every build today.

Forgetting a server is styled apart from signing out, because the two
are not the same act -- one drops credentials, the other discards
changes that never left the machine.

Claude-Session: https://claude.ai/code/session_01N9WXrurarkoiT2jgimvyj1
---
 src/components/views/SettingsView.tsx         |   6 +
 .../views/settings/RemoteServerCard.tsx       | 292 ++++++++++++++++++
 2 files changed, 298 insertions(+)
 create mode 100644 src/components/views/settings/RemoteServerCard.tsx

diff --git a/src/components/views/SettingsView.tsx b/src/components/views/SettingsView.tsx
index afa05432..d940d667 100644
--- a/src/components/views/SettingsView.tsx
+++ b/src/components/views/SettingsView.tsx
@@ -48,6 +48,7 @@ import {
   Puzzle,
 } from "lucide-react";
 // import { ServerAccountCard } from "./settings/ServerAccountCard"; // deferred to 1.6.0
+import { RemoteServerCard } from "./settings/RemoteServerCard";
 // import { SyncStatusCard } from "./settings/SyncStatusCard"; // deferred to 1.6.0
 import { PluginStoreCard } from "./settings/PluginStoreCard";
 import { PluginsCard } from "./settings/PluginsCard";
@@ -2400,6 +2401,11 @@ export function SettingsView({ onNavigate }: SettingsViewProps) {
               Uncomment when the 1.6.0 work closes. */}
             {/* <ServerAccountCard /> */}
 
+            {/* Its RFC-005 replacement. Safe to mount unconditionally:
+              the card probes for its own backend and renders nothing
+              when `sync_v2` is off, which is every shipped build today. */}
+            <RemoteServerCard />
+
             <div className="py-5 px-4 rounded-xl hover:bg-zinc-50 dark:hover:bg-zinc-800/30 transition-colors">
               <div className="flex items-start space-x-4">
                 <Radio
diff --git a/src/components/views/settings/RemoteServerCard.tsx b/src/components/views/settings/RemoteServerCard.tsx
new file mode 100644
index 00000000..9c13b667
--- /dev/null
+++ b/src/components/views/settings/RemoteServerCard.tsx
@@ -0,0 +1,292 @@
+import { useCallback, useEffect, useState } from "react";
+import { CloudOff, Loader2, RefreshCw, Server, Unplug } from "lucide-react";
+import {
+  remoteBeginLogin,
+  remoteDetectServer,
+  remoteForgetServer,
+  remoteGetOverview,
+  remoteGetStatus,
+  remoteListPlaylists,
+  remoteSignOut,
+  remoteSyncNow,
+  type RemoteOverview,
+  type RemotePlaylistSummary,
+  type RemoteProbeResult,
+  type RemoteStatus,
+} from "../../../lib/tauri/remoteServer";
+
+/**
+ * Settings → remote server binding (RFC-005).
+ *
+ * ## Deliberately not localized
+ *
+ * Every other string in this app carries a key in all seventeen locale
+ * files. This card does not, and that is a decision rather than an
+ * oversight: the `sync_v2` Cargo feature is off by default, so no
+ * shipped build can render this at all. Translating copy that no user
+ * can reach — and that will still change as the feature grows — would
+ * put ~255 unreviewed strings into files that had a native-speaker
+ * pass. The keys land when the feature ships and the wording settles.
+ *
+ * Until then this is a developer surface: it exists so the protocol can
+ * be exercised and watched by a human, which is the one thing unit
+ * tests cannot do for it.
+ *
+ * ## It hides itself when the feature is absent
+ *
+ * TypeScript cannot see a Cargo feature, so the card probes for its own
+ * backend: if `remote_get_status` is not a registered command, the
+ * whole thing renders nothing rather than showing a broken panel.
+ */
+export function RemoteServerCard() {
+  const [available, setAvailable] = useState<boolean | null>(null);
+  const [status, setStatus] = useState<RemoteStatus | null>(null);
+  const [overview, setOverview] = useState<RemoteOverview | null>(null);
+  const [playlists, setPlaylists] = useState<RemotePlaylistSummary[]>([]);
+  const [urlDraft, setUrlDraft] = useState("");
+  const [probe, setProbe] = useState<RemoteProbeResult | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [busy, setBusy] = useState<null | "probe" | "login" | "sync" | "forget">(
+    null,
+  );
+
+  const refresh = useCallback(async () => {
+    const [next, counts, lists] = await Promise.all([
+      remoteGetStatus(),
+      remoteGetOverview(),
+      remoteListPlaylists(),
+    ]);
+    setStatus(next);
+    setOverview(counts);
+    setPlaylists(lists);
+    if (next.server_url) setUrlDraft(next.server_url);
+  }, []);
+
+  useEffect(() => {
+    let cancelled = false;
+    void (async () => {
+      try {
+        await remoteGetStatus();
+        if (cancelled) return;
+        setAvailable(true);
+        await refresh();
+      } catch {
+        // The command is not registered: this build has sync_v2 off.
+        if (!cancelled) setAvailable(false);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [refresh]);
+
+  const run = useCallback(
+    async (kind: NonNullable<typeof busy>, action: () => Promise<unknown>) => {
+      setBusy(kind);
+      setError(null);
+      try {
+        await action();
+        await refresh();
+      } catch (err) {
+        setError(String(err));
+      } finally {
+        setBusy(null);
+      }
+    },
+    [refresh],
+  );
+
+  if (available !== true) return null;
+
+  const signedIn = status?.signed_in ?? false;
+
+  return (
+    <div className="py-5 px-4 rounded-xl hover:bg-zinc-50 dark:hover:bg-zinc-800/30 transition-colors">
+      <div className="flex items-start space-x-4">
+        <Server size={20} className="text-zinc-400 mt-0.5" aria-hidden="true" />
+        <div className="flex-1 min-w-0 space-y-4">
+          <div>
+            <h3 className="text-sm font-medium text-zinc-900 dark:text-zinc-100">
+              Remote server
+            </h3>
+            <p className="text-xs text-zinc-500 dark:text-zinc-400">
+              Developer surface — not localized while the feature is
+              off by default.
+            </p>
+          </div>
+
+          <div className="flex gap-2">
+            <input
+              type="url"
+              value={urlDraft}
+              onChange={(event) => setUrlDraft(event.target.value)}
+              placeholder="https://music.example"
+              spellCheck={false}
+              disabled={signedIn}
+              className="flex-1 min-w-0 px-3 py-1.5 text-sm rounded-lg border border-zinc-200 dark:border-zinc-700 bg-white dark:bg-zinc-900 disabled:opacity-50"
+              aria-label="Server URL"
+            />
+            <button
+              type="button"
+              onClick={() =>
+                void run("probe", async () =>
+                  setProbe(await remoteDetectServer(urlDraft)),
+                )
+              }
+              disabled={busy !== null || !urlDraft.trim() || signedIn}
+              className="px-3 py-1.5 text-sm rounded-lg border border-zinc-200 dark:border-zinc-700 disabled:opacity-50"
+            >
+              {busy === "probe" ? <Spinner /> : "Identify"}
+            </button>
+          </div>
+
+          {probe && !signedIn && (
+            <p className="text-xs text-zinc-600 dark:text-zinc-300">
+              {probe.server_type ?? "unknown"}
+              {probe.server_version ? ` ${probe.server_version}` : ""} —{" "}
+              {probe.supports_sync
+                ? "native, signs in through the browser"
+                : "Subsonic protocol only; no journal, and no sign-in flow here yet"}
+            </p>
+          )}
+
+          <div className="flex flex-wrap items-center gap-2">
+            {!signedIn ? (
+              <button
+                type="button"
+                onClick={() =>
+                  void run("login", () => remoteBeginLogin(urlDraft))
+                }
+                disabled={
+                  busy !== null || !urlDraft.trim() || probe?.supports_sync === false
+                }
+                className="px-3 py-1.5 text-sm rounded-lg bg-zinc-900 text-white dark:bg-zinc-100 dark:text-zinc-900 disabled:opacity-50"
+              >
+                {busy === "login" ? <Spinner /> : "Sign in with browser"}
+              </button>
+            ) : (
+              <>
+                <span className="text-sm text-zinc-700 dark:text-zinc-200">
+                  {status?.username ?? "signed in"}
+                </span>
+                <button
+                  type="button"
+                  onClick={() => void run("sync", remoteSyncNow)}
+                  disabled={busy !== null}
+                  className="px-3 py-1.5 text-sm rounded-lg border border-zinc-200 dark:border-zinc-700 inline-flex items-center gap-1.5 disabled:opacity-50"
+                >
+                  {busy === "sync" ? (
+                    <Spinner />
+                  ) : (
+                    <RefreshCw size={14} aria-hidden="true" />
+                  )}
+                  Sync now
+                </button>
+                <button
+                  type="button"
+                  onClick={() => void run("login", remoteSignOut)}
+                  disabled={busy !== null}
+                  className="px-3 py-1.5 text-sm rounded-lg border border-zinc-200 dark:border-zinc-700 inline-flex items-center gap-1.5 disabled:opacity-50"
+                >
+                  <Unplug size={14} aria-hidden="true" />
+                  Sign out
+                </button>
+              </>
+            )}
+            {status?.server_url && (
+              <button
+                type="button"
+                onClick={() => void run("forget", remoteForgetServer)}
+                disabled={busy !== null}
+                className="px-3 py-1.5 text-sm rounded-lg text-red-600 dark:text-red-400 border border-red-200 dark:border-red-900/50 inline-flex items-center gap-1.5 disabled:opacity-50"
+                // Destructive in a way signing out is not: this one
+                // discards changes that never reached the server.
+                title="Discards the cached library and any change made offline that never reached the server"
+              >
+                <CloudOff size={14} aria-hidden="true" />
+                Forget server
+              </button>
+            )}
+          </div>
+
+          {status && !status.bootstrapped && signedIn && (
+            <p className="text-xs text-amber-600 dark:text-amber-400">
+              Never synchronized yet — the first pass downloads a full
+              snapshot.
+            </p>
+          )}
+
+          {error && (
+            <p className="text-xs text-red-600 dark:text-red-400 break-words">
+              {error}
+            </p>
+          )}
+
+          {overview && signedIn && <Counts overview={overview} />}
+
+          {playlists.length > 0 && (
+            <ul className="text-xs text-zinc-600 dark:text-zinc-300 space-y-0.5">
+              {playlists.slice(0, 8).map((playlist) => (
+                <li key={playlist.id} className="truncate">
+                  {playlist.name} — {playlist.track_count} tracks
+                  {playlist.pending_creation && " (not sent yet)"}
+                </li>
+              ))}
+            </ul>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function Counts({ overview }: { overview: RemoteOverview }) {
+  const entries: [string, number][] = [
+    ["playlists", overview.playlists],
+    ["favourites", overview.favorites],
+    ["ratings", overview.ratings],
+    ["history", overview.history],
+    ["shares", overview.shares],
+    ["queue", overview.queue_tracks],
+    ["cached tracks", overview.cached_tracks],
+  ];
+  return (
+    <div className="space-y-1">
+      <div className="flex flex-wrap gap-x-4 gap-y-1 text-xs text-zinc-500 dark:text-zinc-400">
+        {entries.map(([label, value]) => (
+          <span key={label}>
+            <span className="tabular-nums text-zinc-700 dark:text-zinc-200">
+              {value}
+            </span>{" "}
+            {label}
+          </span>
+        ))}
+      </div>
+      {/* Awaiting metadata is normal right after a catch-up and clears
+          on the next pass, so it is informational. Pending changes are
+          the same. A permanent failure is neither: nothing will retry
+          it, so it gets the only alarming colour on this card. */}
+      {overview.tracks_awaiting_metadata > 0 && (
+        <p className="text-xs text-zinc-500 dark:text-zinc-400">
+          {overview.tracks_awaiting_metadata} tracks awaiting metadata —
+          clears on the next pass.
+        </p>
+      )}
+      {overview.pending_changes > 0 && (
+        <p className="text-xs text-zinc-500 dark:text-zinc-400">
+          {overview.pending_changes} local changes waiting to be sent.
+        </p>
+      )}
+      {overview.failed_changes > 0 && (
+        <p className="text-xs text-red-600 dark:text-red-400">
+          {overview.failed_changes} local changes were refused and will
+          not be retried.
+        </p>
+      )}
+    </div>
+  );
+}
+
+function Spinner() {
+  return <Loader2 size={14} className="animate-spin" aria-hidden="true" />;
+}

From 74f50630b9ddc2d6e74e25c62fa2c1565225b297 Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Thu, 13 Aug 2026 11:07:15 +0200
Subject: [PATCH 12/14] feat(remote): capture the server's content fingerprint,
 unread

The server now publishes full_hash on its tracks: BLAKE3, non-keyed,
hex, over the whole file, pinned as part of its contract. The projection
stores it and nothing reads it, which is deliberate -- matching a local
file to a server track is out of scope -- but the value arrives free with
every snapshot, and the alternative is re-downloading the catalogue on
the day matching is designed.

Checking whether it lines up with what we already have turned up the
thing worth recording. It does not match track.file_hash, and the names
invite exactly that assumption. The local digest is

  blake3( file_length_le_bytes || head_1MiB || tail_1MiB )

above 2 MiB, and length-prefixed whole content below it. The prefix
alone means it can never equal a plain full-file digest at any size.
That partial form is deliberate: full hashing was the scan's dominant
cost, reading roughly 9 GB for 900 tracks.

The comparable local value is hash_file_full, a plain whole-file BLAKE3
in hex -- equal to the server's on identical bytes. It is computed today
only to confirm duplicates before a destructive delete, and stored
nowhere. So matching on content means reading local files in full, which
is the cost the scan exists to avoid. Both sides already expose size,
which narrows candidates before anything is read.

Recorded in the RFC as input to the matching design rather than as a
design, since that remains someone else's RFC.

Claude-Session: https://claude.ai/code/session_01N9WXrurarkoiT2jgimvyj1
---
 .../rfcs/RFC-005-remote-source-and-sync-v2.md | 42 ++++++++++++++-
 src-tauri/crates/app/src/remote/dto.rs        | 11 ++++
 src-tauri/crates/app/src/remote/mutation.rs   |  1 +
 src-tauri/crates/app/src/remote/projection.rs |  7 ++-
 src-tauri/crates/app/src/remote/read.rs       |  1 +
 .../20260813090000_remote_track_full_hash.sql | 51 +++++++++++++++++++
 6 files changed, 110 insertions(+), 3 deletions(-)
 create mode 100644 src-tauri/migrations/profile/20260813090000_remote_track_full_hash.sql

diff --git a/docs/rfcs/RFC-005-remote-source-and-sync-v2.md b/docs/rfcs/RFC-005-remote-source-and-sync-v2.md
index 2063a7de..0f5851ed 100644
--- a/docs/rfcs/RFC-005-remote-source-and-sync-v2.md
+++ b/docs/rfcs/RFC-005-remote-source-and-sync-v2.md
@@ -364,9 +364,49 @@ Any instruction mentioning "RFC-003" must name the repository, or it will be
 read as the wrong document. This RFC exists partly to end that ambiguity: on the
 desktop side, the accepted design is **RFC-005**.
 
+## A note for whoever designs the matching layer
+
+Still out of scope, but one constraint is now known and worth recording before
+someone plans around an assumption that does not hold.
+
+The server publishes `full_hash` on its tracks: BLAKE3, non-keyed, hexadecimal,
+over the **whole file**, pinned as part of its contract. The projection captures
+it — unread — because it arrives free with every snapshot, and the alternative
+is re-downloading the catalogue on the day matching is designed.
+
+**It is not comparable to the local `track.file_hash`.** The names invite the
+assumption and the assumption is wrong. `scanner::extract::hash_file` computes
+
+```text
+blake3( file_length_le_bytes || head_1MiB || tail_1MiB )
+```
+
+for anything above 2 MiB, and `blake3(length || whole_content)` below it. The
+length prefix alone means it can never equal a plain full-file digest, at any
+size. That partial form is deliberate: full hashing was the scanner's dominant
+cost, reading roughly 9 GB to scan 900 tracks.
+
+The comparable local value is `scanner::extract::hash_file_full` — a plain
+whole-file BLAKE3 in hex, therefore directly equal to `full_hash` on identical
+bytes. It exists today only to confirm duplicates before a destructive delete,
+and is stored nowhere.
+
+So matching on content means reading local files in full, which is exactly the
+cost the scan avoids. A cheap pre-filter exists: both sides already expose
+`size`, so only the handful of candidates that agree on length ever need to be
+read. That turns "hash the whole library" into "hash the few files that could
+possibly match".
+
+The scope rule is unchanged: automatic linking on a **unique** exact match only,
+a MusicBrainz identifier as a suggestion the user confirms, and never a fuzzy
+match on title, artist or duration. Note also what the fingerprint is — the
+file, not the decoded audio — so two copies of the same recording with different
+tags will not meet.
+
 ## Out of scope
 
-- Matching local files to server tracks (own RFC, needs the exact-hash rule).
+- Matching local files to server tracks (own RFC; the note above is input to it,
+  not a design).
 - Full third-party Subsonic implementation: the seam is defined here and
   `WaveflowSource` implements it; the other branch is its own slice.
 - Retention and compaction of the server journal.
diff --git a/src-tauri/crates/app/src/remote/dto.rs b/src-tauri/crates/app/src/remote/dto.rs
index 2e206f10..a785fb86 100644
--- a/src-tauri/crates/app/src/remote/dto.rs
+++ b/src-tauri/crates/app/src/remote/dto.rs
@@ -79,6 +79,17 @@ pub struct SongItem {
     pub artwork_hash: Option<String>,
     #[serde(default)]
     pub library_id: Option<String>,
+    /// BLAKE3 of the whole file, non-keyed, hex — the server's content
+    /// fingerprint, pinned as part of its contract.
+    ///
+    /// Captured but unread: matching a local file to a server track is
+    /// out of scope. It is stored because it arrives free with every
+    /// snapshot, and the alternative is re-downloading the catalogue on
+    /// the day matching is designed. It is **not** comparable to the
+    /// local `track.file_hash`, which is a length-prefixed head+tail
+    /// digest — see the migration for why.
+    #[serde(default)]
+    pub full_hash: Option<String>,
 }
 
 #[derive(Debug, Clone, Deserialize)]
diff --git a/src-tauri/crates/app/src/remote/mutation.rs b/src-tauri/crates/app/src/remote/mutation.rs
index af6ccc04..bf5f7462 100644
--- a/src-tauri/crates/app/src/remote/mutation.rs
+++ b/src-tauri/crates/app/src/remote/mutation.rs
@@ -483,6 +483,7 @@ mod tests {
                 "../../../../migrations/profile/20260810120000_remote_source_projection.sql"
             ),
             include_str!("../../../../migrations/profile/20260810140000_remote_track_cache.sql"),
+            include_str!("../../../../migrations/profile/20260813090000_remote_track_full_hash.sql"),
         ] {
             sqlx::raw_sql(migration).execute(&pool).await.unwrap();
         }
diff --git a/src-tauri/crates/app/src/remote/projection.rs b/src-tauri/crates/app/src/remote/projection.rs
index 6ff82638..ee0c9ad1 100644
--- a/src-tauri/crates/app/src/remote/projection.rs
+++ b/src-tauri/crates/app/src/remote/projection.rs
@@ -233,8 +233,8 @@ pub async fn cache_song(conn: &mut SqliteConnection, song: &SongItem) -> AppResu
     sqlx::query(
         "INSERT INTO remote_track
             (remote_id, title, artist, album, album_id, duration_ms, track_no, disc_no,
-             year, genre, suffix, bitrate, size, artwork_hash, library_id, cached_at)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+             year, genre, suffix, bitrate, size, artwork_hash, library_id, full_hash, cached_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
          ON CONFLICT(remote_id) DO UPDATE SET
             title        = excluded.title,
             artist       = COALESCE(excluded.artist, artist),
@@ -250,6 +250,7 @@ pub async fn cache_song(conn: &mut SqliteConnection, song: &SongItem) -> AppResu
             size         = COALESCE(excluded.size, size),
             artwork_hash = COALESCE(excluded.artwork_hash, artwork_hash),
             library_id   = COALESCE(excluded.library_id, library_id),
+            full_hash    = COALESCE(excluded.full_hash, full_hash),
             cached_at    = excluded.cached_at",
     )
     .bind(&song.id)
@@ -269,6 +270,7 @@ pub async fn cache_song(conn: &mut SqliteConnection, song: &SongItem) -> AppResu
     .bind(song.size)
     .bind(song.artwork_hash.as_deref())
     .bind(song.library_id.as_deref())
+    .bind(song.full_hash.as_deref())
     .bind(chrono::Utc::now().timestamp_millis())
     .execute(&mut *conn)
     .await?;
@@ -676,6 +678,7 @@ mod tests {
                 "../../../../migrations/profile/20260810120000_remote_source_projection.sql"
             ),
             include_str!("../../../../migrations/profile/20260810140000_remote_track_cache.sql"),
+            include_str!("../../../../migrations/profile/20260813090000_remote_track_full_hash.sql"),
         ] {
             sqlx::raw_sql(migration).execute(&pool).await.unwrap();
         }
diff --git a/src-tauri/crates/app/src/remote/read.rs b/src-tauri/crates/app/src/remote/read.rs
index c9aa314d..eaa8dacf 100644
--- a/src-tauri/crates/app/src/remote/read.rs
+++ b/src-tauri/crates/app/src/remote/read.rs
@@ -202,6 +202,7 @@ mod tests {
                 "../../../../migrations/profile/20260810120000_remote_source_projection.sql"
             ),
             include_str!("../../../../migrations/profile/20260810140000_remote_track_cache.sql"),
+            include_str!("../../../../migrations/profile/20260813090000_remote_track_full_hash.sql"),
         ] {
             sqlx::raw_sql(migration).execute(&pool).await.unwrap();
         }
diff --git a/src-tauri/migrations/profile/20260813090000_remote_track_full_hash.sql b/src-tauri/migrations/profile/20260813090000_remote_track_full_hash.sql
new file mode 100644
index 00000000..84f06da6
--- /dev/null
+++ b/src-tauri/migrations/profile/20260813090000_remote_track_full_hash.sql
@@ -0,0 +1,51 @@
+-- The server's content fingerprint for a remote track. RFC-005.
+--
+-- BLAKE3, non-keyed, hexadecimal, 64 characters, over the **whole
+-- file** — the server pins that algorithm as part of its contract: a
+-- change would arrive as a different field, never as different bytes
+-- under this name.
+--
+-- ## Nothing reads this yet, and that is deliberate
+--
+-- Matching a local file to a server track is out of scope (RFC-005
+-- §Decision 1) and needs its own RFC. This column exists because the
+-- value arrives free with every snapshot, and because the alternative
+-- is worse: without it, the day matching is designed, the first step
+-- would be re-downloading the entire catalogue to collect a field we
+-- had already been handed and thrown away.
+--
+-- ## It does NOT match `track.file_hash`
+--
+-- Worth stating here, because the names invite the assumption. The
+-- local `track.file_hash` comes from `scanner::extract::hash_file`,
+-- which is a different function on purpose:
+--
+--   blake3( file_length_le_bytes || head_1MiB || tail_1MiB )
+--
+-- for anything over 2 MiB, and `blake3(length || whole_content)` below
+-- that. The length prefix alone means it can never equal a plain
+-- full-file digest, at any size. That partial form is an I/O
+-- optimisation the scanner depends on — full hashing read roughly 9 GB
+-- to scan 900 tracks.
+--
+-- The comparable local value is `scanner::extract::hash_file_full`,
+-- which is a plain whole-file BLAKE3 in hex and therefore directly
+-- equal to this column when the bytes are identical. It is computed
+-- today only to confirm duplicates before a destructive delete, and is
+-- not stored anywhere.
+--
+-- So whoever designs the matching layer inherits a real constraint:
+-- comparing on content means reading local files in full, which is
+-- exactly the cost the scanner avoids. `remote_track.size` and the
+-- local `track.size` are both already present and make a cheap
+-- pre-filter — a full read then only has to happen for the handful of
+-- candidates that could possibly match.
+
+ALTER TABLE remote_track ADD COLUMN full_hash TEXT;
+
+-- Lookups will be "find the remote track with this content", so the
+-- index goes on the hash. Partial, because the column stays NULL for
+-- every row cached from a server that predates the field or from a
+-- third-party server that has no equivalent.
+CREATE INDEX idx_remote_track_full_hash
+    ON remote_track (full_hash) WHERE full_hash IS NOT NULL;

From f9fdd2551dd7c93198354873abe0351ac611306e Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Thu, 13 Aug 2026 11:18:49 +0200
Subject: [PATCH 13/14] feat(remote): wire user gestures to the queue

Closes the gap that has been open since the queue landed: nothing called
enqueue. Starring, rating, and creating, renaming or deleting a playlist
now each write the projection and queue the mutation in one transaction,
and the command layer kicks the drain without making the caller wait --
the change is already durable, so there is nothing for the user to watch.

The pairing is the point, and it is now tested rather than asserted in a
comment. Splitting it fails in two directions: a projection updated
without a queued mutation silently discards the change the next time a
snapshot lands, and a mutation queued without the projection update makes
the interface lie backwards, showing the old value while the new one is
already travelling. One test rolls a transaction back and checks that
neither half survives; another sweeps every gesture and counts both
sides, so a future gesture that forgets one of them fails there.

Each gesture is split into an in-tx half and a wrapper that owns the
transaction and the profile lease. That is what makes it testable at all,
since an AppState cannot be built in a unit test -- and it moved the
rating range check somewhere every caller inherits it.

Two behaviours worth naming. Deleting a playlist that never reached the
server drops its queued creation instead of sending a create and a delete
for something that existed for nobody. And asking to both set and clear a
comment resolves to the clear: it is the more explicit intent, and
sending the value alongside would let the server coalesce it straight
back in.

The diagnostics card grew a create field and per-playlist delete, so the
whole loop can be watched: a playlist appears at once marked as unsent,
travels on the next drain, and returns named by the server.

Claude-Session: https://claude.ai/code/session_01N9WXrurarkoiT2jgimvyj1
---
 .../crates/app/src/commands/remote_auth.rs    |  89 +++
 src-tauri/crates/app/src/lib.rs               |  10 +
 src-tauri/crates/app/src/remote/drain.rs      |  16 +
 src-tauri/crates/app/src/remote/mod.rs        |   5 +
 src-tauri/crates/app/src/remote/mutation.rs   |  31 +
 src-tauri/crates/app/src/remote/write.rs      | 610 ++++++++++++++++++
 .../views/settings/RemoteServerCard.tsx       |  57 +-
 src/lib/tauri/remoteServer.ts                 |  78 +++
 8 files changed, 890 insertions(+), 6 deletions(-)
 create mode 100644 src-tauri/crates/app/src/remote/write.rs

diff --git a/src-tauri/crates/app/src/commands/remote_auth.rs b/src-tauri/crates/app/src/commands/remote_auth.rs
index 4fb965e6..e0fe73e6 100644
--- a/src-tauri/crates/app/src/commands/remote_auth.rs
+++ b/src-tauri/crates/app/src/commands/remote_auth.rs
@@ -200,6 +200,95 @@ pub async fn remote_list_queue(
     crate::remote::read::queue_tracks(&mut conn).await
 }
 
+/// Star or unstar a remote entity.
+///
+/// Answers as soon as the change is durable locally; the server hears
+/// about it on the drain pass this kicks off. Offline, the entry simply
+/// waits — which is the point of having a queue.
+#[tauri::command]
+pub async fn remote_set_favorite(
+    app: tauri::AppHandle,
+    state: tauri::State<'_, AppState>,
+    entity_type: String,
+    entity_id: String,
+    starred: bool,
+) -> AppResult<()> {
+    crate::remote::write::set_favorite(&state, &entity_type, &entity_id, starred).await?;
+    crate::remote::drain::spawn(app);
+    Ok(())
+}
+
+/// Rate a remote entity from 1 to 5, or clear it with `0`.
+#[tauri::command]
+pub async fn remote_set_rating(
+    app: tauri::AppHandle,
+    state: tauri::State<'_, AppState>,
+    entity_type: String,
+    entity_id: String,
+    rating: u8,
+) -> AppResult<()> {
+    crate::remote::write::set_rating(&state, &entity_type, &entity_id, rating).await?;
+    crate::remote::drain::spawn(app);
+    Ok(())
+}
+
+/// Create a playlist on the remote account.
+///
+/// Returns the identifier it is known by locally. That is a `local:`
+/// placeholder until the creation reaches the server, so a caller
+/// holding it should re-read rather than assume it stays valid.
+#[tauri::command]
+pub async fn remote_create_playlist(
+    app: tauri::AppHandle,
+    state: tauri::State<'_, AppState>,
+    name: String,
+    track_ids: Vec<String>,
+) -> AppResult<String> {
+    let id = crate::remote::write::create_playlist(&state, &name, &track_ids).await?;
+    crate::remote::drain::spawn(app);
+    Ok(id)
+}
+
+/// Rename a playlist, set or empty its comment, change its visibility.
+///
+/// `clearComment` is what empties the comment: omitting the field leaves
+/// it untouched, because the server coalesces an absent value onto the
+/// current one.
+#[tauri::command]
+pub async fn remote_update_playlist(
+    app: tauri::AppHandle,
+    state: tauri::State<'_, AppState>,
+    playlist_id: String,
+    name: Option<String>,
+    comment: Option<String>,
+    public: Option<bool>,
+    clear_comment: Option<bool>,
+) -> AppResult<()> {
+    crate::remote::write::update_playlist(
+        &state,
+        &playlist_id,
+        name,
+        comment,
+        public,
+        clear_comment.unwrap_or(false),
+    )
+    .await?;
+    crate::remote::drain::spawn(app);
+    Ok(())
+}
+
+/// Delete a remote playlist.
+#[tauri::command]
+pub async fn remote_delete_playlist(
+    app: tauri::AppHandle,
+    state: tauri::State<'_, AppState>,
+    playlist_id: String,
+) -> AppResult<()> {
+    crate::remote::write::delete_playlist(&state, &playlist_id).await?;
+    crate::remote::drain::spawn(app);
+    Ok(())
+}
+
 /// A connection to the active profile, or `None` when there is no
 /// active profile.
 ///
diff --git a/src-tauri/crates/app/src/lib.rs b/src-tauri/crates/app/src/lib.rs
index 43de1d89..8cff141c 100644
--- a/src-tauri/crates/app/src/lib.rs
+++ b/src-tauri/crates/app/src/lib.rs
@@ -794,6 +794,16 @@ pub fn run() {
             commands::remote_auth::remote_list_playlist_tracks,
             #[cfg(feature = "sync_v2")]
             commands::remote_auth::remote_list_queue,
+            #[cfg(feature = "sync_v2")]
+            commands::remote_auth::remote_set_favorite,
+            #[cfg(feature = "sync_v2")]
+            commands::remote_auth::remote_set_rating,
+            #[cfg(feature = "sync_v2")]
+            commands::remote_auth::remote_create_playlist,
+            #[cfg(feature = "sync_v2")]
+            commands::remote_auth::remote_update_playlist,
+            #[cfg(feature = "sync_v2")]
+            commands::remote_auth::remote_delete_playlist,
             #[cfg(feature = "sync_v1")]
             commands::server_auth::server_get_status,
             #[cfg(feature = "sync_v1")]
diff --git a/src-tauri/crates/app/src/remote/drain.rs b/src-tauri/crates/app/src/remote/drain.rs
index c4fdb4c7..0deba599 100644
--- a/src-tauri/crates/app/src/remote/drain.rs
+++ b/src-tauri/crates/app/src/remote/drain.rs
@@ -61,6 +61,22 @@ struct Created {
     url: Option<String>,
 }
 
+/// Kick a pass without waiting for it.
+///
+/// Edge-triggered: called after a local change commits. The change is
+/// already durable in the projection and the queue, so the user has
+/// nothing to wait for, and a failure here costs a delay rather than a
+/// loss — the entry stays queued for the next pass.
+pub fn spawn(handle: tauri::AppHandle) {
+    tauri::async_runtime::spawn(async move {
+        use tauri::Manager;
+        let state = handle.state::<AppState>();
+        if let Err(error) = drain(state.inner()).await {
+            tracing::debug!(%error, "could not push the queue after a local change");
+        }
+    });
+}
+
 /// Push what is queued. Does nothing, successfully, when there is
 /// nothing to push or nowhere to push it.
 pub async fn drain(state: &AppState) -> AppResult<DrainReport> {
diff --git a/src-tauri/crates/app/src/remote/mod.rs b/src-tauri/crates/app/src/remote/mod.rs
index 1fdba93b..598dcd52 100644
--- a/src-tauri/crates/app/src/remote/mod.rs
+++ b/src-tauri/crates/app/src/remote/mod.rs
@@ -41,6 +41,10 @@
 //!   pinned to an operation identifier that must never be reused for a
 //!   different intent.
 //!
+//! - [`write`] — local gestures on remote data. Applies the change to
+//!   the projection and queues the mutation in **one** transaction;
+//!   splitting them either loses the change or makes the interface lie.
+//!
 //! - [`drain`] — pushes that queue, in order, stopping on anything that
 //!   might still succeed and marking anything that never will.
 //!
@@ -91,3 +95,4 @@ pub mod read;
 pub mod socket;
 pub mod sync;
 pub mod tokens;
+pub mod write;
diff --git a/src-tauri/crates/app/src/remote/mutation.rs b/src-tauri/crates/app/src/remote/mutation.rs
index bf5f7462..5902cdf0 100644
--- a/src-tauri/crates/app/src/remote/mutation.rs
+++ b/src-tauri/crates/app/src/remote/mutation.rs
@@ -393,6 +393,37 @@ pub async fn resolve_share_placeholder(
     rewrite_queued_references(conn, placeholder, remote_id).await
 }
 
+/// Drop every queued entry that names a placeholder the server will
+/// never be told about.
+///
+/// Used when the user deletes something they created offline before it
+/// was ever sent. Sending the creation and then a delete would be two
+/// pointless round-trips describing something that briefly existed for
+/// nobody; dropping both is the same outcome with none of the noise.
+///
+/// Safe for the same reason [`resolve_placeholder`] is: FIFO guarantees
+/// that entries behind an unlanded creation have never been presented,
+/// so the server holds no fingerprint for them.
+pub async fn discard_for_placeholder(
+    conn: &mut SqliteConnection,
+    placeholder: &str,
+) -> AppResult<()> {
+    let rows = sqlx::query("SELECT id, payload FROM remote_mutation WHERE failed_at IS NULL")
+        .fetch_all(&mut *conn)
+        .await?;
+    for row in rows {
+        let id: i64 = row.try_get("id")?;
+        let payload: String = row.try_get("payload")?;
+        let Ok(mutation) = serde_json::from_str::<Mutation>(&payload) else {
+            continue;
+        };
+        if mutation.placeholder_dependency() == Some(placeholder) {
+            remove(&mut *conn, id).await?;
+        }
+    }
+    Ok(())
+}
+
 /// Point every still-queued entry at the identifier the server chose.
 async fn rewrite_queued_references(
     conn: &mut SqliteConnection,
diff --git a/src-tauri/crates/app/src/remote/write.rs b/src-tauri/crates/app/src/remote/write.rs
new file mode 100644
index 00000000..51fd1841
--- /dev/null
+++ b/src-tauri/crates/app/src/remote/write.rs
@@ -0,0 +1,610 @@
+//! Local gestures on remote data: write here, then send.
+//!
+//! Every gesture below does the same two things in **one transaction**,
+//! and that pairing is the whole point of the module:
+//!
+//! 1. apply the change to the projection, so the interface reflects it
+//!    immediately, offline included;
+//! 2. queue the matching mutation, so the server hears about it.
+//!
+//! Splitting them is the failure this module exists to prevent. A
+//! projection updated without a queued mutation silently discards the
+//! user's change the next time a snapshot lands. A mutation queued
+//! without the projection update makes the interface lie until the
+//! round-trip completes — and lie *backwards*, showing the old value
+//! while the new one is already on its way.
+//!
+//! Each gesture is split in two: a `*_in_tx` half that does the real
+//! work against a connection, and a public wrapper that owns the
+//! transaction and the profile lease. The split is not ceremony — it is
+//! what lets the pairing be tested, since an `AppState` cannot be built
+//! in a unit test.
+//!
+//! ## The drain is kicked by the caller, not waited on
+//!
+//! These functions commit and return; the command layer then wakes the
+//! drain through [`super::drain::spawn`] and answers immediately. The
+//! change is already durable, so the round-trip is not something the
+//! user should be made to watch. Offline, the wake is a no-op and the
+//! entry simply waits.
+//!
+//! ## What comes back through `/changes` is not a problem
+//!
+//! The server echoes every one of these as a journal event, and applying
+//! our own change a second time is harmless: every write in
+//! [`super::projection`] is an upsert or a delete keyed by identity, so
+//! the second application is the same as the first.
+
+use sqlx::SqliteConnection;
+
+use crate::{
+    error::{AppError, AppResult},
+    remote::mutation::{self, Mutation},
+    state::AppState,
+};
+
+fn now_ms() -> i64 {
+    chrono::Utc::now().timestamp_millis()
+}
+
+/// Star or unstar a remote track, album or artist.
+pub async fn set_favorite(
+    state: &AppState,
+    entity_type: &str,
+    entity_id: &str,
+    starred: bool,
+) -> AppResult<()> {
+    let (pool, profile_id) = lease(state).await?;
+    let _ = profile_id;
+    let mut tx = pool.begin().await?;
+    set_favorite_in_tx(&mut tx, entity_type, entity_id, starred).await?;
+    tx.commit().await?;
+    Ok(())
+}
+
+pub async fn set_favorite_in_tx(
+    conn: &mut SqliteConnection,
+    entity_type: &str,
+    entity_id: &str,
+    starred: bool,
+) -> AppResult<()> {
+    if starred {
+        sqlx::query(
+            "INSERT INTO remote_favorite (entity_type, entity_id, starred_at)
+             VALUES (?, ?, ?)
+             ON CONFLICT(entity_type, entity_id) DO UPDATE
+                SET starred_at = excluded.starred_at",
+        )
+        .bind(entity_type)
+        .bind(entity_id)
+        .bind(now_ms())
+        .execute(&mut *conn)
+        .await?;
+    } else {
+        sqlx::query("DELETE FROM remote_favorite WHERE entity_type = ? AND entity_id = ?")
+            .bind(entity_type)
+            .bind(entity_id)
+            .execute(&mut *conn)
+            .await?;
+    }
+    mutation::enqueue(
+        conn,
+        &Mutation::SetFavorite {
+            entity_type: entity_type.to_string(),
+            entity_id: entity_id.to_string(),
+            starred,
+        },
+    )
+    .await?;
+    Ok(())
+}
+
+/// Rate a remote entity, or clear its rating with `0`.
+pub async fn set_rating(
+    state: &AppState,
+    entity_type: &str,
+    entity_id: &str,
+    rating: u8,
+) -> AppResult<()> {
+    let (pool, _) = lease(state).await?;
+    let mut tx = pool.begin().await?;
+    set_rating_in_tx(&mut tx, entity_type, entity_id, rating).await?;
+    tx.commit().await?;
+    Ok(())
+}
+
+/// `0` clears. It becomes a distinct mutation rather than a stored
+/// value, because a stored zero would mean "rated nothing", which is not
+/// a rating.
+///
+/// The range is checked here rather than in the wrapper so every caller
+/// inherits it — and so it can be tested, which the wrapper cannot be.
+pub async fn set_rating_in_tx(
+    conn: &mut SqliteConnection,
+    entity_type: &str,
+    entity_id: &str,
+    rating: u8,
+) -> AppResult<()> {
+    if rating > 5 {
+        return Err(AppError::Other("a rating is 0 to 5 stars".into()));
+    }
+    let mutation = if rating == 0 {
+        sqlx::query("DELETE FROM remote_rating WHERE entity_type = ? AND entity_id = ?")
+            .bind(entity_type)
+            .bind(entity_id)
+            .execute(&mut *conn)
+            .await?;
+        Mutation::ClearRating {
+            entity_type: entity_type.to_string(),
+            entity_id: entity_id.to_string(),
+        }
+    } else {
+        sqlx::query(
+            "INSERT INTO remote_rating (entity_type, entity_id, rating, updated_at)
+             VALUES (?, ?, ?, ?)
+             ON CONFLICT(entity_type, entity_id) DO UPDATE
+                SET rating = excluded.rating, updated_at = excluded.updated_at",
+        )
+        .bind(entity_type)
+        .bind(entity_id)
+        .bind(i64::from(rating))
+        .bind(now_ms())
+        .execute(&mut *conn)
+        .await?;
+        Mutation::SetRating {
+            entity_type: entity_type.to_string(),
+            entity_id: entity_id.to_string(),
+            rating,
+        }
+    };
+    mutation::enqueue(conn, &mutation).await?;
+    Ok(())
+}
+
+/// Create a playlist the server has never heard of.
+///
+/// It gets a `local:` identifier so the projection can key on it like
+/// any other, which is what makes it visible and editable straight away.
+/// Returns that identifier — a caller holding it should re-read rather
+/// than assume it survives, since the server's replaces it.
+pub async fn create_playlist(
+    state: &AppState,
+    name: &str,
+    track_ids: &[String],
+) -> AppResult<String> {
+    let (pool, _) = lease(state).await?;
+    let mut tx = pool.begin().await?;
+    let id = create_playlist_in_tx(&mut tx, name, track_ids).await?;
+    tx.commit().await?;
+    Ok(id)
+}
+
+pub async fn create_playlist_in_tx(
+    conn: &mut SqliteConnection,
+    name: &str,
+    track_ids: &[String],
+) -> AppResult<String> {
+    let name = name.trim();
+    if name.is_empty() {
+        return Err(AppError::Other("a playlist needs a name".into()));
+    }
+    let local_id = mutation::new_placeholder();
+    let now = now_ms();
+
+    sqlx::query(
+        "INSERT INTO remote_playlist (remote_id, name, is_public, created_at, updated_at)
+         VALUES (?, ?, 0, ?, ?)",
+    )
+    .bind(&local_id)
+    .bind(name)
+    .bind(now)
+    .bind(now)
+    .execute(&mut *conn)
+    .await?;
+
+    for (position, track_id) in track_ids.iter().enumerate() {
+        sqlx::query(
+            "INSERT INTO remote_playlist_track (playlist_remote_id, position, track_remote_id)
+             VALUES (?, ?, ?)",
+        )
+        .bind(&local_id)
+        .bind(position as i64)
+        .bind(track_id)
+        .execute(&mut *conn)
+        .await?;
+    }
+
+    mutation::enqueue(
+        conn,
+        &Mutation::CreatePlaylist {
+            local_id: local_id.clone(),
+            name: name.to_string(),
+            track_ids: track_ids.to_vec(),
+        },
+    )
+    .await?;
+    Ok(local_id)
+}
+
+/// Rename a playlist, set or empty its comment, change its visibility.
+pub async fn update_playlist(
+    state: &AppState,
+    playlist_id: &str,
+    name: Option<String>,
+    comment: Option<String>,
+    public: Option<bool>,
+    clear_comment: bool,
+) -> AppResult<()> {
+    let (pool, _) = lease(state).await?;
+    let mut tx = pool.begin().await?;
+    update_playlist_in_tx(&mut tx, playlist_id, name, comment, public, clear_comment).await?;
+    tx.commit().await?;
+    Ok(())
+}
+
+/// `clear_comment` empties the comment, which omitting it cannot do —
+/// the server coalesces an absent field onto the current value, so
+/// naming the field is the only way to say "empty".
+pub async fn update_playlist_in_tx(
+    conn: &mut SqliteConnection,
+    playlist_id: &str,
+    name: Option<String>,
+    comment: Option<String>,
+    public: Option<bool>,
+    clear_comment: bool,
+) -> AppResult<()> {
+    if let Some(name) = &name {
+        sqlx::query("UPDATE remote_playlist SET name = ? WHERE remote_id = ?")
+            .bind(name)
+            .bind(playlist_id)
+            .execute(&mut *conn)
+            .await?;
+    }
+    // The clear wins over a value: asking for both is contradictory, and
+    // emptying is the more explicit of the two intents.
+    if clear_comment {
+        sqlx::query("UPDATE remote_playlist SET comment = NULL WHERE remote_id = ?")
+            .bind(playlist_id)
+            .execute(&mut *conn)
+            .await?;
+    } else if let Some(comment) = &comment {
+        sqlx::query("UPDATE remote_playlist SET comment = ? WHERE remote_id = ?")
+            .bind(comment)
+            .bind(playlist_id)
+            .execute(&mut *conn)
+            .await?;
+    }
+    if let Some(public) = public {
+        sqlx::query("UPDATE remote_playlist SET is_public = ? WHERE remote_id = ?")
+            .bind(i64::from(public))
+            .bind(playlist_id)
+            .execute(&mut *conn)
+            .await?;
+    }
+    sqlx::query("UPDATE remote_playlist SET updated_at = ? WHERE remote_id = ?")
+        .bind(now_ms())
+        .bind(playlist_id)
+        .execute(&mut *conn)
+        .await?;
+
+    mutation::enqueue(
+        conn,
+        &Mutation::UpdatePlaylist {
+            playlist_id: playlist_id.to_string(),
+            name,
+            comment: if clear_comment { None } else { comment },
+            public,
+            add: Vec::new(),
+            remove_indexes: Vec::new(),
+            clear_comment,
+        },
+    )
+    .await?;
+    Ok(())
+}
+
+/// Delete a playlist.
+pub async fn delete_playlist(state: &AppState, playlist_id: &str) -> AppResult<()> {
+    let (pool, _) = lease(state).await?;
+    let mut tx = pool.begin().await?;
+    delete_playlist_in_tx(&mut tx, playlist_id).await?;
+    tx.commit().await?;
+    Ok(())
+}
+
+/// A playlist still carrying a placeholder never reached the server, so
+/// its queued creation is **dropped** rather than sent and immediately
+/// undone. Two round-trips describing something that briefly existed for
+/// nobody is the same outcome with more noise.
+pub async fn delete_playlist_in_tx(
+    conn: &mut SqliteConnection,
+    playlist_id: &str,
+) -> AppResult<()> {
+    sqlx::query("DELETE FROM remote_playlist_track WHERE playlist_remote_id = ?")
+        .bind(playlist_id)
+        .execute(&mut *conn)
+        .await?;
+    sqlx::query("DELETE FROM remote_playlist WHERE remote_id = ?")
+        .bind(playlist_id)
+        .execute(&mut *conn)
+        .await?;
+
+    if mutation::is_placeholder(playlist_id) {
+        mutation::discard_for_placeholder(&mut *conn, playlist_id).await?;
+        return Ok(());
+    }
+
+    mutation::enqueue(
+        conn,
+        &Mutation::DeletePlaylist {
+            playlist_id: playlist_id.to_string(),
+        },
+    )
+    .await?;
+    Ok(())
+}
+
+/// The active profile's pool, pinned to the profile it was resolved
+/// from, so a switch landing mid-write fails the call instead of
+/// applying one profile's gesture to another's data.
+async fn lease(state: &AppState) -> AppResult<(crate::state::ProfilePool, i64)> {
+    let profile_id = state.require_profile_id().await?;
+    let pool = state.require_profile_pool_for(Some(profile_id)).await?;
+    Ok((pool, profile_id))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::remote::mutation::pending;
+    use sqlx::sqlite::SqlitePoolOptions;
+    use sqlx::{Row, SqlitePool};
+
+    async fn pool() -> SqlitePool {
+        let pool = SqlitePoolOptions::new()
+            .max_connections(1)
+            .connect(":memory:")
+            .await
+            .unwrap();
+        for migration in [
+            include_str!(
+                "../../../../migrations/profile/20260810120000_remote_source_projection.sql"
+            ),
+            include_str!("../../../../migrations/profile/20260810140000_remote_track_cache.sql"),
+            include_str!("../../../../migrations/profile/20260813090000_remote_track_full_hash.sql"),
+        ] {
+            sqlx::raw_sql(migration).execute(&pool).await.unwrap();
+        }
+        pool
+    }
+
+    async fn count(conn: &mut SqliteConnection, sql: &str) -> i64 {
+        sqlx::query_scalar(sqlx::AssertSqlSafe(sql.to_string()))
+            .fetch_one(&mut *conn)
+            .await
+            .unwrap()
+    }
+
+    #[tokio::test]
+    async fn starring_writes_the_projection_and_queues_the_mutation() {
+        // The pairing is the module's reason to exist: one without the
+        // other either loses the change or shows the wrong value.
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+
+        set_favorite_in_tx(&mut conn, "track", "t1", true)
+            .await
+            .unwrap();
+
+        assert_eq!(count(&mut conn, "SELECT count(*) FROM remote_favorite").await, 1);
+        let queued = pending(&mut conn, 10).await.unwrap();
+        assert_eq!(
+            queued[0].mutation,
+            Mutation::SetFavorite {
+                entity_type: "track".into(),
+                entity_id: "t1".into(),
+                starred: true
+            }
+        );
+    }
+
+    #[tokio::test]
+    async fn unstarring_removes_the_row_and_still_queues() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        set_favorite_in_tx(&mut conn, "track", "t1", true).await.unwrap();
+        set_favorite_in_tx(&mut conn, "track", "t1", false).await.unwrap();
+
+        assert_eq!(count(&mut conn, "SELECT count(*) FROM remote_favorite").await, 0);
+        assert_eq!(
+            pending(&mut conn, 10).await.unwrap().len(),
+            2,
+            "the removal has to travel too"
+        );
+    }
+
+    #[tokio::test]
+    async fn a_zero_rating_clears_locally_and_queues_a_clear() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        set_rating_in_tx(&mut conn, "track", "t1", 4).await.unwrap();
+        set_rating_in_tx(&mut conn, "track", "t1", 0).await.unwrap();
+
+        assert_eq!(count(&mut conn, "SELECT count(*) FROM remote_rating").await, 0);
+        let queued = pending(&mut conn, 10).await.unwrap();
+        assert_eq!(
+            queued[1].mutation,
+            Mutation::ClearRating {
+                entity_type: "track".into(),
+                entity_id: "t1".into()
+            },
+            "a zero must not travel as a rating of zero"
+        );
+    }
+
+    #[tokio::test]
+    async fn a_rating_above_five_is_refused_before_anything_is_written() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+
+        assert!(set_rating_in_tx(&mut conn, "track", "t1", 6).await.is_err());
+
+        assert_eq!(count(&mut conn, "SELECT count(*) FROM remote_rating").await, 0);
+        assert_eq!(
+            count(&mut conn, "SELECT count(*) FROM remote_mutation").await,
+            0,
+            "a refused gesture must not leave a queued mutation behind"
+        );
+    }
+
+    #[tokio::test]
+    async fn a_new_playlist_is_visible_immediately_and_queued() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+
+        let id = create_playlist_in_tx(&mut conn, "  Offline mix  ", &["t1".into(), "t2".into()])
+            .await
+            .unwrap();
+
+        assert!(mutation::is_placeholder(&id));
+        let name: String =
+            sqlx::query_scalar("SELECT name FROM remote_playlist WHERE remote_id = ?")
+                .bind(&id)
+                .fetch_one(&mut *conn)
+                .await
+                .unwrap();
+        assert_eq!(name, "Offline mix", "the name was not trimmed");
+        assert_eq!(
+            count(&mut conn, "SELECT count(*) FROM remote_playlist_track").await,
+            2
+        );
+        assert_eq!(pending(&mut conn, 10).await.unwrap().len(), 1);
+    }
+
+    #[tokio::test]
+    async fn a_nameless_playlist_is_refused() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        assert!(create_playlist_in_tx(&mut conn, "   ", &[]).await.is_err());
+    }
+
+    #[tokio::test]
+    async fn clearing_a_comment_wins_over_setting_one() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        let id = create_playlist_in_tx(&mut conn, "Mix", &[]).await.unwrap();
+        update_playlist_in_tx(&mut conn, &id, None, Some("notes".into()), None, false)
+            .await
+            .unwrap();
+
+        // Contradictory input: a value and a clear. The clear is the
+        // more explicit intent and must not silently lose.
+        update_playlist_in_tx(&mut conn, &id, None, Some("ignored".into()), None, true)
+            .await
+            .unwrap();
+
+        let comment: Option<String> =
+            sqlx::query_scalar("SELECT comment FROM remote_playlist WHERE remote_id = ?")
+                .bind(&id)
+                .fetch_one(&mut *conn)
+                .await
+                .unwrap();
+        assert_eq!(comment, None);
+
+        let queued = pending(&mut conn, 10).await.unwrap();
+        match &queued.last().unwrap().mutation {
+            Mutation::UpdatePlaylist {
+                comment,
+                clear_comment,
+                ..
+            } => {
+                assert!(clear_comment);
+                assert_eq!(
+                    comment, &None,
+                    "sending both would let the server coalesce the value back in"
+                );
+            }
+            other => panic!("unexpected mutation: {other:?}"),
+        }
+    }
+
+    #[tokio::test]
+    async fn deleting_an_unsent_playlist_drops_its_queued_creation() {
+        // Sending a creation and then a delete describes something that
+        // existed for nobody. Both are dropped instead.
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        let id = create_playlist_in_tx(&mut conn, "Offline", &["t1".into()])
+            .await
+            .unwrap();
+        assert_eq!(pending(&mut conn, 10).await.unwrap().len(), 1);
+
+        delete_playlist_in_tx(&mut conn, &id).await.unwrap();
+
+        assert_eq!(count(&mut conn, "SELECT count(*) FROM remote_playlist").await, 0);
+        assert_eq!(
+            count(&mut conn, "SELECT count(*) FROM remote_playlist_track").await,
+            0
+        );
+        assert!(
+            pending(&mut conn, 10).await.unwrap().is_empty(),
+            "the creation should not travel for something already deleted"
+        );
+    }
+
+    #[tokio::test]
+    async fn deleting_a_playlist_the_server_knows_queues_the_delete() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        sqlx::query("INSERT INTO remote_playlist (remote_id, name) VALUES ('server-id', 'Mix')")
+            .execute(&mut *conn)
+            .await
+            .unwrap();
+
+        delete_playlist_in_tx(&mut conn, "server-id").await.unwrap();
+
+        let queued = pending(&mut conn, 10).await.unwrap();
+        assert_eq!(
+            queued[0].mutation,
+            Mutation::DeletePlaylist {
+                playlist_id: "server-id".into()
+            }
+        );
+    }
+
+    #[tokio::test]
+    async fn a_failed_write_leaves_neither_half_behind() {
+        // The transaction is what guarantees this. Rolling back after a
+        // projection write must take the queued mutation with it.
+        let pool = pool().await;
+        let mut tx = pool.begin().await.unwrap();
+        set_favorite_in_tx(&mut tx, "track", "t1", true).await.unwrap();
+        tx.rollback().await.unwrap();
+
+        let mut conn = pool.acquire().await.unwrap();
+        assert_eq!(count(&mut conn, "SELECT count(*) FROM remote_favorite").await, 0);
+        assert_eq!(count(&mut conn, "SELECT count(*) FROM remote_mutation").await, 0);
+    }
+
+    #[tokio::test]
+    async fn every_gesture_leaves_the_projection_and_the_queue_in_step() {
+        // A sweep rather than a per-gesture assertion: any future
+        // gesture that writes one half and forgets the other fails here.
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+
+        set_favorite_in_tx(&mut conn, "track", "t1", true).await.unwrap();
+        set_rating_in_tx(&mut conn, "track", "t1", 3).await.unwrap();
+        let id = create_playlist_in_tx(&mut conn, "Mix", &[]).await.unwrap();
+        update_playlist_in_tx(&mut conn, &id, Some("Renamed".into()), None, None, false)
+            .await
+            .unwrap();
+
+        let queued = pending(&mut conn, 20).await.unwrap();
+        assert_eq!(queued.len(), 4, "a gesture wrote without queuing");
+        let rows = count(&mut conn, "SELECT count(*) FROM remote_favorite").await
+            + count(&mut conn, "SELECT count(*) FROM remote_rating").await
+            + count(&mut conn, "SELECT count(*) FROM remote_playlist").await;
+        assert_eq!(rows, 3, "a gesture queued without writing");
+    }
+}
diff --git a/src/components/views/settings/RemoteServerCard.tsx b/src/components/views/settings/RemoteServerCard.tsx
index 9c13b667..e8f94669 100644
--- a/src/components/views/settings/RemoteServerCard.tsx
+++ b/src/components/views/settings/RemoteServerCard.tsx
@@ -2,6 +2,8 @@ import { useCallback, useEffect, useState } from "react";
 import { CloudOff, Loader2, RefreshCw, Server, Unplug } from "lucide-react";
 import {
   remoteBeginLogin,
+  remoteCreatePlaylist,
+  remoteDeletePlaylist,
   remoteDetectServer,
   remoteForgetServer,
   remoteGetOverview,
@@ -46,9 +48,10 @@ export function RemoteServerCard() {
   const [urlDraft, setUrlDraft] = useState("");
   const [probe, setProbe] = useState<RemoteProbeResult | null>(null);
   const [error, setError] = useState<string | null>(null);
-  const [busy, setBusy] = useState<null | "probe" | "login" | "sync" | "forget">(
-    null,
-  );
+  const [newPlaylist, setNewPlaylist] = useState("");
+  const [busy, setBusy] = useState<
+    null | "probe" | "login" | "sync" | "forget" | "write"
+  >(null);
 
   const refresh = useCallback(async () => {
     const [next, counts, lists] = await Promise.all([
@@ -224,12 +227,54 @@ export function RemoteServerCard() {
 
           {overview && signedIn && <Counts overview={overview} />}
 
+          {signedIn && (
+            <div className="flex gap-2">
+              {/* Exercises the write path end to end: the playlist
+                  appears at once with a local identifier, travels on the
+                  next drain, and comes back named by the server. */}
+              <input
+                type="text"
+                value={newPlaylist}
+                onChange={(event) => setNewPlaylist(event.target.value)}
+                placeholder="New playlist name"
+                className="flex-1 min-w-0 px-3 py-1.5 text-sm rounded-lg border border-zinc-200 dark:border-zinc-700 bg-white dark:bg-zinc-900"
+                aria-label="New playlist name"
+              />
+              <button
+                type="button"
+                onClick={() =>
+                  void run("write", async () => {
+                    await remoteCreatePlaylist(newPlaylist);
+                    setNewPlaylist("");
+                  })
+                }
+                disabled={busy !== null || !newPlaylist.trim()}
+                className="px-3 py-1.5 text-sm rounded-lg border border-zinc-200 dark:border-zinc-700 disabled:opacity-50"
+              >
+                {busy === "write" ? <Spinner /> : "Create"}
+              </button>
+            </div>
+          )}
+
           {playlists.length > 0 && (
             <ul className="text-xs text-zinc-600 dark:text-zinc-300 space-y-0.5">
               {playlists.slice(0, 8).map((playlist) => (
-                <li key={playlist.id} className="truncate">
-                  {playlist.name} — {playlist.track_count} tracks
-                  {playlist.pending_creation && " (not sent yet)"}
+                <li key={playlist.id} className="flex items-center gap-2">
+                  <span className="truncate flex-1">
+                    {playlist.name} — {playlist.track_count} tracks
+                    {playlist.pending_creation && " (not sent yet)"}
+                  </span>
+                  <button
+                    type="button"
+                    onClick={() =>
+                      void run("write", () => remoteDeletePlaylist(playlist.id))
+                    }
+                    disabled={busy !== null}
+                    className="text-zinc-400 hover:text-red-600 dark:hover:text-red-400 disabled:opacity-50"
+                    aria-label={`Delete ${playlist.name}`}
+                  >
+                    ×
+                  </button>
                 </li>
               ))}
             </ul>
diff --git a/src/lib/tauri/remoteServer.ts b/src/lib/tauri/remoteServer.ts
index 0996f611..7790eead 100644
--- a/src/lib/tauri/remoteServer.ts
+++ b/src/lib/tauri/remoteServer.ts
@@ -204,3 +204,81 @@ export function remoteListPlaylistTracks(
 export function remoteListQueue(): Promise<RemoteTrack[]> {
   return invoke<RemoteTrack[]>("remote_list_queue");
 }
+
+/**
+ * Local gestures on remote data.
+ *
+ * Each resolves as soon as the change is durable **locally** — it is
+ * written to the cached library and queued for the server in one
+ * transaction — not when the server has acknowledged it. That is
+ * deliberate: the change is not at risk, so there is nothing for the
+ * user to wait on, and the same call works offline.
+ *
+ * The server echoes each one back through the journal, which is
+ * harmless: applying our own change twice lands on the same state.
+ */
+
+/** Star or unstar a remote track, album or artist. */
+export function remoteSetFavorite(
+  entityType: string,
+  entityId: string,
+  starred: boolean,
+): Promise<void> {
+  return invoke<void>("remote_set_favorite", {
+    entityType,
+    entityId,
+    starred,
+  });
+}
+
+/** Rate from 1 to 5, or pass `0` to clear the rating. */
+export function remoteSetRating(
+  entityType: string,
+  entityId: string,
+  rating: number,
+): Promise<void> {
+  return invoke<void>("remote_set_rating", { entityType, entityId, rating });
+}
+
+/**
+ * Create a remote playlist.
+ *
+ * Resolves to the identifier it is known by locally — a temporary one
+ * until the creation reaches the server, which then replaces it. Re-read
+ * rather than holding on to it.
+ */
+export function remoteCreatePlaylist(
+  name: string,
+  trackIds: string[] = [],
+): Promise<string> {
+  return invoke<string>("remote_create_playlist", { name, trackIds });
+}
+
+/**
+ * Rename a playlist, set or empty its comment, change its visibility.
+ *
+ * Omitting a field leaves it untouched. Emptying the comment needs
+ * `clearComment` — the server treats an absent value and an explicit
+ * null identically, so naming the field is the only way to say "empty".
+ */
+export function remoteUpdatePlaylist(
+  playlistId: string,
+  changes: {
+    name?: string;
+    comment?: string;
+    public?: boolean;
+    clearComment?: boolean;
+  },
+): Promise<void> {
+  return invoke<void>("remote_update_playlist", {
+    playlistId,
+    name: changes.name ?? null,
+    comment: changes.comment ?? null,
+    public: changes.public ?? null,
+    clearComment: changes.clearComment ?? false,
+  });
+}
+
+export function remoteDeletePlaylist(playlistId: string): Promise<void> {
+  return invoke<void>("remote_delete_playlist", { playlistId });
+}

From 9b1157eef1d2e0ac06ee1022b3b4bfbe7f62c3d5 Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Thu, 13 Aug 2026 11:28:06 +0200
Subject: [PATCH 14/14] feat(remote): complete the write surface with
 scrobbles, queue and shares

Shares now have commands, and so do scrobbles and the play queue. Every
gesture keeps the same shape as the others: the projection write and the
queued mutation commit together, and the drain is kicked without making
the caller wait.

What is deliberately absent is the wiring to playback. The local queue
holds file paths and local row ids, and the scrobbler joins the local
track table; the server validates identifiers and would reject every one
of them. Hooking the player today would not ship an incomplete feature,
it would ship a defect -- a steady stream of permanently-failed mutations
piling up in a queue the user then has to be told about. The dependency
is remote playback, which does not exist yet; until it does, these are
the surface for a caller that already holds server identifiers.

Two behaviours the tests pin. A "now playing" ping travels but does not
enter the local history, because it is a transient state rather than a
play and writing it would show a listen that never happened. And a share
created offline is visible at once but carries no link: the token comes
from a server-side secret, so it cannot exist before the creation lands.

The sweep that checks every gesture writes both halves now covers all
seven, so anything added later that forgets one of them fails there.

Claude-Session: https://claude.ai/code/session_01N9WXrurarkoiT2jgimvyj1
---
 .../rfcs/RFC-005-remote-source-and-sync-v2.md |  16 +
 .../crates/app/src/commands/remote_auth.rs    |  96 ++++
 src-tauri/crates/app/src/lib.rs               |  10 +
 src-tauri/crates/app/src/remote/write.rs      | 463 +++++++++++++++++-
 src/lib/tauri/remoteServer.ts                 |  88 ++++
 5 files changed, 668 insertions(+), 5 deletions(-)

diff --git a/docs/rfcs/RFC-005-remote-source-and-sync-v2.md b/docs/rfcs/RFC-005-remote-source-and-sync-v2.md
index 0f5851ed..c4efb77a 100644
--- a/docs/rfcs/RFC-005-remote-source-and-sync-v2.md
+++ b/docs/rfcs/RFC-005-remote-source-and-sync-v2.md
@@ -403,6 +403,22 @@ match on title, artist or duration. Note also what the fingerprint is — the
 file, not the decoded audio — so two copies of the same recording with different
 tags will not meet.
 
+## Scrobbles and the queue wait on remote playback
+
+Their mutations, commands and projection writes all exist, and nothing
+drives them from the player — deliberately.
+
+The local queue holds file paths and local row ids, and the scrobbler joins the
+local `track` table. Those identifiers mean nothing to the server, which
+validates them: every such mutation would come back `404`, be marked
+permanently failed, and accumulate in the queue as garbage the user would then
+have to be told about. Wiring them today would not be an incomplete feature, it
+would be a defect.
+
+The dependency is remote playback (§Decision 6 defines the transport; nothing
+implements it). Until then the commands are the surface for a caller that
+already holds genuine remote identifiers.
+
 ## Out of scope
 
 - Matching local files to server tracks (own RFC; the note above is input to it,
diff --git a/src-tauri/crates/app/src/commands/remote_auth.rs b/src-tauri/crates/app/src/commands/remote_auth.rs
index e0fe73e6..0629ba0f 100644
--- a/src-tauri/crates/app/src/commands/remote_auth.rs
+++ b/src-tauri/crates/app/src/commands/remote_auth.rs
@@ -289,6 +289,102 @@ pub async fn remote_delete_playlist(
     Ok(())
 }
 
+/// Record a play against the remote account.
+///
+/// `submission: false` is a "now playing" ping; only a completed listen
+/// enters the local history.
+///
+/// **The identifier must be the server's.** Nothing calls this from
+/// playback, and it should not until remote playback exists: the local
+/// player deals in file paths and local row ids, which the server
+/// validates and rejects.
+#[tauri::command]
+pub async fn remote_scrobble(
+    app: tauri::AppHandle,
+    state: tauri::State<'_, AppState>,
+    track_id: String,
+    submission: bool,
+    played_at: Option<i64>,
+) -> AppResult<()> {
+    crate::remote::write::scrobble(&state, &track_id, submission, played_at).await?;
+    crate::remote::drain::spawn(app);
+    Ok(())
+}
+
+/// Save the account's play queue. Same identifier caveat as
+/// [`remote_scrobble`].
+#[tauri::command]
+pub async fn remote_save_queue(
+    app: tauri::AppHandle,
+    state: tauri::State<'_, AppState>,
+    track_ids: Vec<String>,
+    current: Option<String>,
+    position_ms: i64,
+    client: Option<String>,
+) -> AppResult<()> {
+    crate::remote::write::save_queue(&state, &track_ids, current, position_ms, client).await?;
+    crate::remote::drain::spawn(app);
+    Ok(())
+}
+
+/// Publish a share of remote tracks.
+///
+/// Returns the local identifier. The public link is not known until the
+/// creation reaches the server — the token is derived from a server-side
+/// secret — so a share made offline has no link to copy yet.
+#[tauri::command]
+pub async fn remote_create_share(
+    app: tauri::AppHandle,
+    state: tauri::State<'_, AppState>,
+    track_ids: Vec<String>,
+    description: Option<String>,
+    expires_at: Option<i64>,
+) -> AppResult<String> {
+    let id = crate::remote::write::create_share(&state, &track_ids, description, expires_at).await?;
+    crate::remote::drain::spawn(app);
+    Ok(id)
+}
+
+/// Change a share's description or expiry, or empty either.
+///
+/// The two `clear*` flags are the only way to empty a field: omitting it
+/// leaves it in place, so an expiry set by mistake would otherwise be
+/// permanent.
+#[tauri::command]
+pub async fn remote_update_share(
+    app: tauri::AppHandle,
+    state: tauri::State<'_, AppState>,
+    share_id: String,
+    description: Option<String>,
+    expires_at: Option<i64>,
+    clear_description: Option<bool>,
+    clear_expires_at: Option<bool>,
+) -> AppResult<()> {
+    crate::remote::write::update_share(
+        &state,
+        &share_id,
+        description,
+        expires_at,
+        clear_description.unwrap_or(false),
+        clear_expires_at.unwrap_or(false),
+    )
+    .await?;
+    crate::remote::drain::spawn(app);
+    Ok(())
+}
+
+/// Withdraw a share.
+#[tauri::command]
+pub async fn remote_delete_share(
+    app: tauri::AppHandle,
+    state: tauri::State<'_, AppState>,
+    share_id: String,
+) -> AppResult<()> {
+    crate::remote::write::delete_share(&state, &share_id).await?;
+    crate::remote::drain::spawn(app);
+    Ok(())
+}
+
 /// A connection to the active profile, or `None` when there is no
 /// active profile.
 ///
diff --git a/src-tauri/crates/app/src/lib.rs b/src-tauri/crates/app/src/lib.rs
index 8cff141c..14b9980d 100644
--- a/src-tauri/crates/app/src/lib.rs
+++ b/src-tauri/crates/app/src/lib.rs
@@ -804,6 +804,16 @@ pub fn run() {
             commands::remote_auth::remote_update_playlist,
             #[cfg(feature = "sync_v2")]
             commands::remote_auth::remote_delete_playlist,
+            #[cfg(feature = "sync_v2")]
+            commands::remote_auth::remote_scrobble,
+            #[cfg(feature = "sync_v2")]
+            commands::remote_auth::remote_save_queue,
+            #[cfg(feature = "sync_v2")]
+            commands::remote_auth::remote_create_share,
+            #[cfg(feature = "sync_v2")]
+            commands::remote_auth::remote_update_share,
+            #[cfg(feature = "sync_v2")]
+            commands::remote_auth::remote_delete_share,
             #[cfg(feature = "sync_v1")]
             commands::server_auth::server_get_status,
             #[cfg(feature = "sync_v1")]
diff --git a/src-tauri/crates/app/src/remote/write.rs b/src-tauri/crates/app/src/remote/write.rs
index 51fd1841..5755fb85 100644
--- a/src-tauri/crates/app/src/remote/write.rs
+++ b/src-tauri/crates/app/src/remote/write.rs
@@ -344,6 +344,319 @@ pub async fn delete_playlist_in_tx(
     Ok(())
 }
 
+/// Record a play against the remote account.
+///
+/// `submission: false` is a "now playing" ping, `true` a completed
+/// listen.
+///
+/// ## Not hooked to the player, and why
+///
+/// Nothing calls this from playback yet, and wiring it there today
+/// would be a bug rather than a feature: the local queue holds file
+/// paths and local row ids, and the scrobbler joins the local `track`
+/// table. Those identifiers mean nothing to the server, which validates
+/// them — every such mutation would come back `404`, be marked
+/// permanently failed, and pile up in the queue as garbage a user would
+/// have to be told about.
+///
+/// The dependency is remote playback, which does not exist. Until it
+/// does, this is the surface a caller holding a genuine remote track
+/// identifier uses.
+pub async fn scrobble(
+    state: &AppState,
+    track_id: &str,
+    submission: bool,
+    played_at: Option<i64>,
+) -> AppResult<()> {
+    let (pool, _) = lease(state).await?;
+    let mut tx = pool.begin().await?;
+    scrobble_in_tx(&mut tx, track_id, submission, played_at).await?;
+    tx.commit().await?;
+    Ok(())
+}
+
+pub async fn scrobble_in_tx(
+    conn: &mut SqliteConnection,
+    track_id: &str,
+    submission: bool,
+    played_at: Option<i64>,
+) -> AppResult<()> {
+    let played_at = played_at.unwrap_or_else(now_ms);
+    // Only a completed listen belongs in the history. A "now playing"
+    // ping is a transient state the server tracks separately, and
+    // writing it here would show a play that never happened.
+    if submission {
+        sqlx::query(
+            "INSERT OR REPLACE INTO remote_history (track_remote_id, played_at, submission)
+             VALUES (?, ?, 1)",
+        )
+        .bind(track_id)
+        .bind(played_at)
+        .execute(&mut *conn)
+        .await?;
+    }
+    mutation::enqueue(
+        conn,
+        &Mutation::Scrobble {
+            track_id: track_id.to_string(),
+            submission,
+            played_at,
+        },
+    )
+    .await?;
+    Ok(())
+}
+
+/// Save the account's play queue.
+///
+/// Same dependency as [`scrobble`]: the identifiers have to be the
+/// server's, so nothing drives this from the local player yet.
+pub async fn save_queue(
+    state: &AppState,
+    track_ids: &[String],
+    current: Option<String>,
+    position_ms: i64,
+    client: Option<String>,
+) -> AppResult<()> {
+    let (pool, _) = lease(state).await?;
+    let mut tx = pool.begin().await?;
+    save_queue_in_tx(&mut tx, track_ids, current, position_ms, client).await?;
+    tx.commit().await?;
+    Ok(())
+}
+
+pub async fn save_queue_in_tx(
+    conn: &mut SqliteConnection,
+    track_ids: &[String],
+    current: Option<String>,
+    position_ms: i64,
+    client: Option<String>,
+) -> AppResult<()> {
+    let position_ms = position_ms.max(0);
+    sqlx::query(
+        "INSERT INTO remote_queue (id, current_remote_id, position_ms, changed_by, updated_at)
+         VALUES (1, ?, ?, ?, ?)
+         ON CONFLICT(id) DO UPDATE SET
+            current_remote_id = excluded.current_remote_id,
+            position_ms       = excluded.position_ms,
+            changed_by        = excluded.changed_by,
+            updated_at        = excluded.updated_at",
+    )
+    .bind(current.as_deref())
+    .bind(position_ms)
+    .bind(client.as_deref())
+    .bind(now_ms())
+    .execute(&mut *conn)
+    .await?;
+
+    sqlx::query("DELETE FROM remote_queue_track")
+        .execute(&mut *conn)
+        .await?;
+    for (position, track_id) in track_ids.iter().enumerate() {
+        sqlx::query("INSERT INTO remote_queue_track (position, track_remote_id) VALUES (?, ?)")
+            .bind(position as i64)
+            .bind(track_id)
+            .execute(&mut *conn)
+            .await?;
+    }
+
+    mutation::enqueue(
+        conn,
+        &Mutation::SaveQueue {
+            track_ids: track_ids.to_vec(),
+            current,
+            position_ms,
+            client,
+        },
+    )
+    .await?;
+    Ok(())
+}
+
+/// Publish a share of remote tracks.
+///
+/// Returns the local identifier. The public link is **not** known yet —
+/// it only comes back with the server's response, because the token is
+/// derived from a server-side secret. A share created offline therefore
+/// has no link until it lands.
+pub async fn create_share(
+    state: &AppState,
+    track_ids: &[String],
+    description: Option<String>,
+    expires_at: Option<i64>,
+) -> AppResult<String> {
+    let (pool, _) = lease(state).await?;
+    let mut tx = pool.begin().await?;
+    let id = create_share_in_tx(&mut tx, track_ids, description, expires_at).await?;
+    tx.commit().await?;
+    Ok(id)
+}
+
+pub async fn create_share_in_tx(
+    conn: &mut SqliteConnection,
+    track_ids: &[String],
+    description: Option<String>,
+    expires_at: Option<i64>,
+) -> AppResult<String> {
+    if track_ids.is_empty() {
+        return Err(AppError::Other("a share needs at least one track".into()));
+    }
+    let local_id = mutation::new_placeholder();
+    let now = now_ms();
+
+    sqlx::query(
+        "INSERT INTO remote_share (remote_id, description, expires_at, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?)",
+    )
+    .bind(&local_id)
+    .bind(description.as_deref())
+    .bind(expires_at)
+    .bind(now)
+    .bind(now)
+    .execute(&mut *conn)
+    .await?;
+    for (position, track_id) in track_ids.iter().enumerate() {
+        sqlx::query(
+            "INSERT INTO remote_share_track (share_remote_id, position, track_remote_id)
+             VALUES (?, ?, ?)",
+        )
+        .bind(&local_id)
+        .bind(position as i64)
+        .bind(track_id)
+        .execute(&mut *conn)
+        .await?;
+    }
+
+    mutation::enqueue(
+        conn,
+        &Mutation::CreateShare {
+            local_id: local_id.clone(),
+            track_ids: track_ids.to_vec(),
+            description,
+            expires_at,
+        },
+    )
+    .await?;
+    Ok(local_id)
+}
+
+/// Change a share's description or expiry, or empty either.
+pub async fn update_share(
+    state: &AppState,
+    share_id: &str,
+    description: Option<String>,
+    expires_at: Option<i64>,
+    clear_description: bool,
+    clear_expires_at: bool,
+) -> AppResult<()> {
+    let (pool, _) = lease(state).await?;
+    let mut tx = pool.begin().await?;
+    update_share_in_tx(
+        &mut tx,
+        share_id,
+        description,
+        expires_at,
+        clear_description,
+        clear_expires_at,
+    )
+    .await?;
+    tx.commit().await?;
+    Ok(())
+}
+
+/// The clears are what make an expiry removable at all — omitting the
+/// field leaves it in place, so a share given one by mistake would
+/// otherwise be stuck with it for good.
+pub async fn update_share_in_tx(
+    conn: &mut SqliteConnection,
+    share_id: &str,
+    description: Option<String>,
+    expires_at: Option<i64>,
+    clear_description: bool,
+    clear_expires_at: bool,
+) -> AppResult<()> {
+    if clear_description {
+        sqlx::query("UPDATE remote_share SET description = NULL WHERE remote_id = ?")
+            .bind(share_id)
+            .execute(&mut *conn)
+            .await?;
+    } else if let Some(description) = &description {
+        sqlx::query("UPDATE remote_share SET description = ? WHERE remote_id = ?")
+            .bind(description)
+            .bind(share_id)
+            .execute(&mut *conn)
+            .await?;
+    }
+    if clear_expires_at {
+        sqlx::query("UPDATE remote_share SET expires_at = NULL WHERE remote_id = ?")
+            .bind(share_id)
+            .execute(&mut *conn)
+            .await?;
+    } else if let Some(expires_at) = expires_at {
+        sqlx::query("UPDATE remote_share SET expires_at = ? WHERE remote_id = ?")
+            .bind(expires_at)
+            .bind(share_id)
+            .execute(&mut *conn)
+            .await?;
+    }
+    sqlx::query("UPDATE remote_share SET updated_at = ? WHERE remote_id = ?")
+        .bind(now_ms())
+        .bind(share_id)
+        .execute(&mut *conn)
+        .await?;
+
+    mutation::enqueue(
+        conn,
+        &Mutation::UpdateShare {
+            share_id: share_id.to_string(),
+            description: if clear_description { None } else { description },
+            expires_at: if clear_expires_at { None } else { expires_at },
+            clear_description,
+            clear_expires_at,
+        },
+    )
+    .await?;
+    Ok(())
+}
+
+/// Withdraw a share. Same placeholder handling as a playlist: one that
+/// never reached the server takes its queued creation with it.
+pub async fn delete_share(state: &AppState, share_id: &str) -> AppResult<()> {
+    let (pool, _) = lease(state).await?;
+    let mut tx = pool.begin().await?;
+    delete_share_in_tx(&mut tx, share_id).await?;
+    tx.commit().await?;
+    Ok(())
+}
+
+pub async fn delete_share_in_tx(
+    conn: &mut SqliteConnection,
+    share_id: &str,
+) -> AppResult<()> {
+    sqlx::query("DELETE FROM remote_share_track WHERE share_remote_id = ?")
+        .bind(share_id)
+        .execute(&mut *conn)
+        .await?;
+    sqlx::query("DELETE FROM remote_share WHERE remote_id = ?")
+        .bind(share_id)
+        .execute(&mut *conn)
+        .await?;
+
+    if mutation::is_placeholder(share_id) {
+        mutation::discard_for_placeholder(&mut *conn, share_id).await?;
+        return Ok(());
+    }
+
+    mutation::enqueue(
+        conn,
+        &Mutation::DeleteShare {
+            share_id: share_id.to_string(),
+        },
+    )
+    .await?;
+    Ok(())
+}
+
 /// The active profile's pool, pinned to the profile it was resolved
 /// from, so a switch landing mid-write fails the call instead of
 /// applying one profile's gesture to another's data.
@@ -586,6 +899,136 @@ mod tests {
         assert_eq!(count(&mut conn, "SELECT count(*) FROM remote_mutation").await, 0);
     }
 
+    #[tokio::test]
+    async fn a_now_playing_ping_travels_without_entering_the_history() {
+        // It is a transient state, not a play. Writing it locally would
+        // show a listen that never happened.
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+
+        scrobble_in_tx(&mut conn, "t1", false, Some(1_000)).await.unwrap();
+        assert_eq!(count(&mut conn, "SELECT count(*) FROM remote_history").await, 0);
+        assert_eq!(pending(&mut conn, 10).await.unwrap().len(), 1);
+
+        scrobble_in_tx(&mut conn, "t1", true, Some(2_000)).await.unwrap();
+        assert_eq!(count(&mut conn, "SELECT count(*) FROM remote_history").await, 1);
+    }
+
+    #[tokio::test]
+    async fn saving_the_queue_replaces_it_rather_than_appending() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+
+        save_queue_in_tx(&mut conn, &["a".into(), "b".into()], Some("a".into()), 0, None)
+            .await
+            .unwrap();
+        save_queue_in_tx(&mut conn, &["c".into()], Some("c".into()), 4200, None)
+            .await
+            .unwrap();
+
+        let ids: Vec<String> =
+            sqlx::query_scalar("SELECT track_remote_id FROM remote_queue_track ORDER BY position")
+                .fetch_all(&mut *conn)
+                .await
+                .unwrap();
+        assert_eq!(ids, vec!["c"]);
+        assert_eq!(count(&mut conn, "SELECT count(*) FROM remote_queue").await, 1);
+    }
+
+    #[tokio::test]
+    async fn a_negative_position_never_reaches_storage() {
+        // The column has a CHECK, so a stray negative would abort the
+        // whole gesture rather than degrade.
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        save_queue_in_tx(&mut conn, &["a".into()], None, -5, None)
+            .await
+            .unwrap();
+        let position: i64 = sqlx::query_scalar("SELECT position_ms FROM remote_queue")
+            .fetch_one(&mut *conn)
+            .await
+            .unwrap();
+        assert_eq!(position, 0);
+    }
+
+    #[tokio::test]
+    async fn a_share_is_visible_at_once_but_has_no_link_yet() {
+        // The token is derived from a server-side secret, so the link
+        // cannot exist before the creation lands.
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+
+        let id = create_share_in_tx(&mut conn, &["t1".into()], Some("notes".into()), None)
+            .await
+            .unwrap();
+
+        assert!(mutation::is_placeholder(&id));
+        let url: Option<String> =
+            sqlx::query_scalar("SELECT url FROM remote_share WHERE remote_id = ?")
+                .bind(&id)
+                .fetch_one(&mut *conn)
+                .await
+                .unwrap();
+        assert_eq!(url, None);
+        assert_eq!(pending(&mut conn, 10).await.unwrap().len(), 1);
+    }
+
+    #[tokio::test]
+    async fn an_empty_share_is_refused() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        assert!(create_share_in_tx(&mut conn, &[], None, None).await.is_err());
+    }
+
+    #[tokio::test]
+    async fn clearing_an_expiry_empties_it_locally_and_says_so_upstream() {
+        // The case that motivated the whole clear verb: without it an
+        // expiry set by mistake is permanent.
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        let id = create_share_in_tx(&mut conn, &["t1".into()], None, Some(9_999))
+            .await
+            .unwrap();
+
+        update_share_in_tx(&mut conn, &id, None, None, false, true)
+            .await
+            .unwrap();
+
+        let expires: Option<i64> =
+            sqlx::query_scalar("SELECT expires_at FROM remote_share WHERE remote_id = ?")
+                .bind(&id)
+                .fetch_one(&mut *conn)
+                .await
+                .unwrap();
+        assert_eq!(expires, None);
+
+        match &pending(&mut conn, 10).await.unwrap().last().unwrap().mutation {
+            Mutation::UpdateShare {
+                clear_expires_at,
+                expires_at,
+                ..
+            } => {
+                assert!(clear_expires_at);
+                assert_eq!(expires_at, &None, "sending both would coalesce it back");
+            }
+            other => panic!("unexpected mutation: {other:?}"),
+        }
+    }
+
+    #[tokio::test]
+    async fn deleting_an_unsent_share_drops_its_queued_creation() {
+        let pool = pool().await;
+        let mut conn = pool.acquire().await.unwrap();
+        let id = create_share_in_tx(&mut conn, &["t1".into()], None, None)
+            .await
+            .unwrap();
+
+        delete_share_in_tx(&mut conn, &id).await.unwrap();
+
+        assert_eq!(count(&mut conn, "SELECT count(*) FROM remote_share").await, 0);
+        assert!(pending(&mut conn, 10).await.unwrap().is_empty());
+    }
+
     #[tokio::test]
     async fn every_gesture_leaves_the_projection_and_the_queue_in_step() {
         // A sweep rather than a per-gesture assertion: any future
@@ -595,16 +1038,26 @@ mod tests {
 
         set_favorite_in_tx(&mut conn, "track", "t1", true).await.unwrap();
         set_rating_in_tx(&mut conn, "track", "t1", 3).await.unwrap();
-        let id = create_playlist_in_tx(&mut conn, "Mix", &[]).await.unwrap();
-        update_playlist_in_tx(&mut conn, &id, Some("Renamed".into()), None, None, false)
+        let playlist = create_playlist_in_tx(&mut conn, "Mix", &[]).await.unwrap();
+        update_playlist_in_tx(&mut conn, &playlist, Some("Renamed".into()), None, None, false)
+            .await
+            .unwrap();
+        scrobble_in_tx(&mut conn, "t1", true, Some(1_000)).await.unwrap();
+        save_queue_in_tx(&mut conn, &["t1".into()], None, 0, None)
+            .await
+            .unwrap();
+        create_share_in_tx(&mut conn, &["t1".into()], None, None)
             .await
             .unwrap();
 
         let queued = pending(&mut conn, 20).await.unwrap();
-        assert_eq!(queued.len(), 4, "a gesture wrote without queuing");
+        assert_eq!(queued.len(), 7, "a gesture wrote without queuing");
         let rows = count(&mut conn, "SELECT count(*) FROM remote_favorite").await
             + count(&mut conn, "SELECT count(*) FROM remote_rating").await
-            + count(&mut conn, "SELECT count(*) FROM remote_playlist").await;
-        assert_eq!(rows, 3, "a gesture queued without writing");
+            + count(&mut conn, "SELECT count(*) FROM remote_playlist").await
+            + count(&mut conn, "SELECT count(*) FROM remote_history").await
+            + count(&mut conn, "SELECT count(*) FROM remote_queue").await
+            + count(&mut conn, "SELECT count(*) FROM remote_share").await;
+        assert_eq!(rows, 6, "a gesture queued without writing");
     }
 }
diff --git a/src/lib/tauri/remoteServer.ts b/src/lib/tauri/remoteServer.ts
index 7790eead..1e55aa60 100644
--- a/src/lib/tauri/remoteServer.ts
+++ b/src/lib/tauri/remoteServer.ts
@@ -282,3 +282,91 @@ export function remoteUpdatePlaylist(
 export function remoteDeletePlaylist(playlistId: string): Promise<void> {
   return invoke<void>("remote_delete_playlist", { playlistId });
 }
+
+/**
+ * Record a play against the remote account. `submission: false` is a
+ * "now playing" ping; only a completed listen enters the history.
+ *
+ * **`trackId` must be a server identifier.** Nothing calls this from
+ * playback, and nothing should until remote playback exists: the local
+ * player deals in file paths and local row ids, which the server
+ * validates and rejects — every such call would fail permanently and
+ * pile up in the outbound queue.
+ */
+export function remoteScrobble(
+  trackId: string,
+  submission: boolean,
+  playedAt?: number,
+): Promise<void> {
+  return invoke<void>("remote_scrobble", {
+    trackId,
+    submission,
+    playedAt: playedAt ?? null,
+  });
+}
+
+/** Save the account's play queue. Same identifier caveat as
+ * {@link remoteScrobble}. */
+export function remoteSaveQueue(
+  trackIds: string[],
+  current: string | null,
+  positionMs: number,
+  client?: string,
+): Promise<void> {
+  return invoke<void>("remote_save_queue", {
+    trackIds,
+    current,
+    positionMs,
+    client: client ?? null,
+  });
+}
+
+/**
+ * Publish a share of remote tracks.
+ *
+ * Resolves to the local identifier. The public link is **not** available
+ * yet — the token is derived from a server-side secret, so it only
+ * arrives with the server's response. A share created offline has no
+ * link to copy until it lands.
+ */
+export function remoteCreateShare(
+  trackIds: string[],
+  description?: string,
+  expiresAt?: number,
+): Promise<string> {
+  return invoke<string>("remote_create_share", {
+    trackIds,
+    description: description ?? null,
+    expiresAt: expiresAt ?? null,
+  });
+}
+
+/**
+ * Change a share's description or expiry, or empty either.
+ *
+ * The `clear*` flags are the only way to empty a field: omitting it
+ * leaves it in place, so an expiry set by mistake would otherwise be
+ * permanent — the owner's only recourse being to withdraw the share and
+ * publish a different link.
+ */
+export function remoteUpdateShare(
+  shareId: string,
+  changes: {
+    description?: string;
+    expiresAt?: number;
+    clearDescription?: boolean;
+    clearExpiresAt?: boolean;
+  },
+): Promise<void> {
+  return invoke<void>("remote_update_share", {
+    shareId,
+    description: changes.description ?? null,
+    expiresAt: changes.expiresAt ?? null,
+    clearDescription: changes.clearDescription ?? false,
+    clearExpiresAt: changes.clearExpiresAt ?? false,
+  });
+}
+
+export function remoteDeleteShare(shareId: string): Promise<void> {
+  return invoke<void>("remote_delete_share", { shareId });
+}