aede_core/

user.rs

//! What the user writes: favourites, ratings, notes, tags, listening history.
//!
//! This is the only data in the program that cannot be recovered. Lose the
//! catalog and a scan rebuilds it in a minute; lose this and it is gone. Two
//! consequences run through the whole module.
//!
//! **It lives in its own file**, never in the catalog. The catalog is derived
//! from the disk and written whole; a rating that changes on a keystroke has no
//! business rewriting a library.
//!
//! **It is never keyed by a catalog identifier.** Those are positions in a
//! vector that every scan renumbers — the lesson the imported analyses already
//! taught, at the cost of a rewrite. A [`EntityRef`] names a thing the way the
//! thing names itself, and an annotation whose target is missing is **kept
//! waiting, never dropped**: a folder renamed between two scans must not cost
//! anybody a note they wrote.
//!
//! Favourites, ratings, notes and tags look like four features and are one:
//! something a person said about an entity. One record per target, so copying
//! everything said about one album onto another is a record copy rather than a
//! loop over four kinds.

use std::collections::{BTreeMap, BTreeSet};

use crate::model::{Catalog, EntityKind, Id};
use crate::text;

#[path = "user_history.rs"]
mod history;
#[path = "user_identity.rs"]
mod identity;
#[path = "user_preferences.rs"]
mod preferences;
pub use preferences::{ClientPreference, valid_preference};
#[path = "user_playback.rs"]
mod playback;
#[path = "user_playlists.rs"]
mod playlists;
#[path = "user_relink.rs"]
mod relink;
pub use identity::{Attachment, TrackIdentity, reconcile};
pub use playback::{
    PLAYBACK_ENTRY_LIMIT, PLAYBACK_PROFILE_LIMIT, PLAYBACK_STATE_LIMIT, PlaybackEntry,
    PlaybackSettings, PlaybackSource, PlaybackState, valid_playback_profile,
};
pub use playlists::{
    PLAYLIST_LIMIT, PLAYLIST_OWNER_LIMIT, PLAYLIST_TRACK_LIMIT, Playlist, Scrobble,
};
pub use relink::{Relink, RelinkSummary};

/// Version of the user file on disk, independent of the catalog's.
///
/// The two change for different reasons and at different times, so they are
/// counted separately. Reading a newer file must fail loudly rather than lose
/// what it did not understand.
pub const USER_FORMAT_VERSION: u32 = 2;

/// Name of the user file inside the data folder.
pub const USER_FILE: &str = "user.json";

/// Whose opinion it is.
///
/// Every personal table is scoped by a stable owner from its first version.
/// Account sessions use immutable account IDs; the CLI and first administrator
/// retain [`LOCAL_USER`]. A mutable login name is never a personal owner.
pub type UserRef = String;

/// The owner of a library nobody has named yet.
pub const LOCAL_USER: &str = aede_accounts::LOCAL_OWNER;

/// What separates the three parts of a release key.
pub const RELEASE_KEY_SEPARATOR: char = '|';

/// A stable way to name an entity, independent of any scan.
///
/// The key is what the thing calls itself rather than where it currently sits:
/// a path for a track, the release key for an album, the normalized name for
/// name-based entities. Recordings, works and release groups use an explicit
/// MusicBrainz identifier when the catalog has one. Source-only artists and
/// canonical credit exclusions may also use `mbid:<identifier>`.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
pub struct EntityRef {
    /// Which kind of thing is named.
    pub kind: EntityKind,
    /// Its stable key, in the spelling [`EntityRef`] builds.
    pub key: String,
}

impl EntityRef {
    /// Builds a reference by hand, for a key already in the right shape.
    pub fn new(kind: EntityKind, key: impl Into<String>) -> EntityRef {
        EntityRef {
            kind,
            key: key.into(),
        }
    }

    /// How the reference is written in one token: `track:/music/a.flac`.
    ///
    /// The kind comes first and the key may itself contain colons — a path
    /// does — so the split is on the **first** one only.
    pub fn to_token(&self) -> String {
        format!("{}:{}", self.kind.as_str(), self.key)
    }

    /// Reads back what [`EntityRef::to_token`] wrote.
    pub fn parse_token(text: &str) -> Option<EntityRef> {
        let (kind, key) = text.split_once(':')?;
        Some(EntityRef {
            kind: EntityKind::parse_kind(kind)?,
            key: key.to_string(),
        })
    }

    /// The reference naming an entity of a catalog, if that entity exists.
    pub fn of(catalog: &Catalog, kind: EntityKind, id: Id) -> Option<EntityRef> {
        let key = match kind {
            // The path is what the file calls itself, and it survives every
            // rescan that leaves the file where it is.
            EntityKind::Track => catalog
                .track(id)
                .and_then(|t| catalog.file(t.file_id))
                .map(|f| f.path.clone())?,
            // The same three parts the release is built on, so a release
            // recognised as itself by a scan is recognised here too.
            EntityKind::Release => {
                let release = catalog.release(id)?;
                let artist = release
                    .album_artist_id
                    .and_then(|a| catalog.artist(a))
                    .map(|a| a.key.clone())
                    .unwrap_or_default();
                let folder = &release.folder;
                format!(
                    "{artist}{RELEASE_KEY_SEPARATOR}{}{RELEASE_KEY_SEPARATOR}{folder}",
                    text::normalize(&release.title)
                )
            }
            EntityKind::Artist => catalog.artist(id).map(|a| a.key.clone())?,
            EntityKind::Recording => {
                let recording = catalog.recording(id)?;
                recording.mbid.clone().or_else(|| {
                    recording
                        .track_ids
                        .first()
                        .and_then(|track| catalog.track(*track))
                        .and_then(|track| catalog.file(track.file_id))
                        .map(|file| format!("local:{}", file.path))
                })?
            }
            EntityKind::Work => catalog.work(id).map(|w| w.mbid.clone())?,
            EntityKind::ReleaseGroup => catalog.release_group(id).map(|g| g.mbid.clone())?,
            EntityKind::Label => catalog.label(id).map(|l| l.key.clone())?,
            EntityKind::Genre => catalog.genres.get(id as usize).map(|g| g.key.clone())?,
        };
        Some(EntityRef { kind, key })
    }

    /// The entity a reference names in this catalog, if it holds one.
    pub fn resolve(&self, catalog: &Catalog) -> Option<Id> {
        match self.kind {
            EntityKind::Track => catalog
                .tracks
                .iter()
                .find(|t| catalog.file(t.file_id).is_some_and(|f| f.path == self.key))
                .map(|t| t.id),
            EntityKind::Release => identity::resolve_release(self, catalog),
            EntityKind::Artist => catalog
                .artists
                .iter()
                .find(|a| a.key == self.key)
                .or_else(|| {
                    let mbid = self.key.strip_prefix("mbid:")?;
                    let mut matched = catalog
                        .artists
                        .iter()
                        .filter(|artist| artist.mbid.as_deref() == Some(mbid));
                    let artist = matched.next()?;
                    matched.next().is_none().then_some(artist)
                })
                .map(|a| a.id),
            EntityKind::Recording => catalog
                .recordings
                .iter()
                .find(|recording| {
                    recording.mbid.as_deref() == Some(&self.key)
                        || self.key.strip_prefix("local:").is_some_and(|path| {
                            recording.track_ids.iter().any(|track| {
                                catalog
                                    .track(*track)
                                    .and_then(|track| catalog.file(track.file_id))
                                    .is_some_and(|file| file.path == path)
                            })
                        })
                })
                .map(|recording| recording.id),
            EntityKind::Work => catalog
                .works
                .iter()
                .find(|work| work.mbid == self.key)
                .map(|work| work.id),
            EntityKind::ReleaseGroup => catalog
                .release_groups
                .iter()
                .find(|group| group.mbid == self.key)
                .map(|group| group.id),
            EntityKind::Label => catalog
                .labels
                .iter()
                .find(|l| l.key == self.key)
                .map(|l| l.id),
            EntityKind::Genre => catalog
                .genres
                .iter()
                .find(|g| g.key == self.key)
                .map(|g| g.id),
        }
    }

    /// How the thing is called on screen, or the key when it is gone.
    pub fn display_name(&self, catalog: &Catalog) -> String {
        let named = self.resolve(catalog).and_then(|id| match self.kind {
            EntityKind::Track => catalog.track(id).map(|t| t.title.clone()),
            EntityKind::Release => catalog.release(id).map(|r| r.title.clone()),
            EntityKind::Artist => catalog.artist(id).map(|a| a.name.clone()),
            EntityKind::Recording => catalog.recording(id).map(|r| r.title.clone()),
            EntityKind::Work => catalog.work(id).map(|w| w.title.clone()),
            EntityKind::ReleaseGroup => catalog.release_group(id).map(|g| g.title.clone()),
            EntityKind::Label => catalog.label(id).map(|l| l.name.clone()),
            EntityKind::Genre => catalog.genres.get(id as usize).map(|g| g.name.clone()),
        });
        named.unwrap_or_else(|| match self.kind {
            // A path is unreadable in a column; its file name is not.
            EntityKind::Track => text::file_name(&self.key).to_string(),
            _ => self.key.clone(),
        })
    }
}

enum RelationAnnotationMatch {
    Absent,
    Unique(usize),
    Ambiguous,
}

pub(crate) fn same_annotation_relation(
    catalog: &Catalog,
    held: &crate::graph::RelationRef,
    current: &crate::graph::RelationRef,
) -> bool {
    held == current
        || (current.kind.starts_with("credit:")
            && crate::graph::same_credit_relation(catalog, held, current))
}

/// Everything one person said about one entity.
///
/// One record per target rather than one per fact: a favourite, a rating, a
/// note and a set of tags are four ways of having an opinion, not four
/// features, and keeping them together is what makes copying what was said
/// about an album onto another album a single operation.
#[derive(Debug, Clone, Default, PartialEq)]
pub struct Annotation {
    /// Whose opinion it is.
    pub owner: UserRef,
    /// What it is about.
    pub target: EntityRef,
    /// A favourite.
    pub loved: bool,
    /// One to five stars, or nothing said.
    pub rating: Option<u8>,
    /// Free text, as long as the user cares to make it.
    pub note: Option<String>,
    /// Free labels: "to rip again", "vinyl", "for the car".
    pub tags: BTreeSet<String>,
    /// When it was first written (Unix epoch, seconds).
    pub created_at: u64,
    /// When it was last touched.
    pub updated_at: u64,
}

impl Default for EntityRef {
    fn default() -> EntityRef {
        EntityRef {
            kind: EntityKind::Track,
            key: String::new(),
        }
    }
}

impl Annotation {
    /// `true` when the record says nothing at all and can be dropped.
    ///
    /// Removing the last thing said about an album must remove the record, not
    /// leave an empty one that a listing would then have to filter out — and
    /// that an export would carry for ever.
    pub fn is_empty(&self) -> bool {
        // A note of `Some("")` says nothing, the same as `None` — the
        // difference between the two is an implementation detail (typed
        // empty text, an empty `--file`, a round trip through export and
        // import) that nobody looking at this record should have to know
        // about. Treating it as content would keep a record alive, and
        // therefore visible, for having said nothing at all.
        !self.loved
            && self.rating.is_none()
            && self.note.as_deref().is_none_or(|n| n.trim().is_empty())
            && self.tags.is_empty()
    }
}

/// A personal note and free-form labels attached to one relationship.
///
/// Relations are not entities: the opinion belongs to the edge itself, not to
/// either endpoint. Keeping it in the user layer also preserves the invariant
/// that the shared catalog contains facts while each person's notes remain
/// private.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RelationAnnotation {
    /// Whose opinion it is.
    pub owner: UserRef,
    /// Stable relationship being described.
    pub relation: crate::graph::RelationRef,
    /// Free text about this exact relationship.
    pub note: Option<String>,
    /// Personal labels such as `dubious`, `favourite collaboration`…
    pub tags: BTreeSet<String>,
    /// When the annotation was first written.
    pub created_at: u64,
    /// When it was last changed.
    pub updated_at: u64,
}

impl RelationAnnotation {
    /// Whether the annotation says nothing and can be removed.
    pub fn is_empty(&self) -> bool {
        self.note
            .as_deref()
            .is_none_or(|note| note.trim().is_empty())
            && self.tags.is_empty()
    }
}

/// One listening event.
///
/// An annotation is a statement; a play is an event, and events accumulate.
#[derive(Debug, Clone, PartialEq)]
pub struct Play {
    /// Who listened.
    pub owner: UserRef,
    /// What was played.
    pub track: EntityRef,
    /// When it started (Unix epoch, seconds).
    pub at: u64,
    /// How much of it was actually heard.
    pub ms_played: u64,
    /// Whether it played to the end.
    ///
    /// A track skipped after eight seconds is evidence *against* it, and a
    /// history that cannot tell a skip from a listen measures the wrong thing.
    pub completed: bool,
}

/// How often one person played one track, for as long as the library lasts.
///
/// Deliberately not derived from the log: the log is bounded so that the file
/// stays small, and "what have I never heard" cannot be answered from a
/// truncated one. The bounded events and all-time totals answer different
/// questions without implying a history-weighted shuffle policy.
#[derive(Debug, Clone, Default, PartialEq)]
pub struct PlayCount {
    /// Whose count it is.
    pub owner: UserRef,
    /// Which track.
    pub track: EntityRef,
    /// All-time native listens and client-declared scrobbles combined.
    pub count: u32,
    /// All-time completed Play events; duration-less scrobbles never increment this.
    pub completed_count: u32,
    /// When it was last played.
    pub last_played: u64,
}

/// A query saved under a name: a smart collection.
///
/// It holds the expression rather than the result, so it answers with what the
/// library holds *now* — which is the whole difference between a smart
/// collection and a playlist. And since running one produces a selection, and a
/// selection is what `--csv`, `--m3u` and M3's queue consume, a saved query is
/// playable the day it is written, with nothing built for it.
#[derive(Debug, Clone, PartialEq)]
pub struct Collection {
    /// Whose collection it is.
    pub owner: UserRef,
    /// What it is called, as typed.
    pub name: String,
    /// The expression, kept as written rather than as parsed: a grammar that
    /// gains a field must not silently change what an old collection means.
    pub expression: String,
    /// When it was first saved.
    pub created_at: u64,
    /// When it was last changed.
    pub updated_at: u64,
}

/// Events kept per owner in each native-play or scrobble journal before that
/// owner's oldest events are forgotten.
///
/// The log answers "what did I listen to last night"; the counters answer
/// everything that needs all of history. Bounding the first keeps the file
/// small without costing the second anything.
pub const HISTORY_LIMIT: usize = 500;
/// Global journal capacity, independent of per-owner retention. Publication
/// refuses this bound rather than evicting another owner's records.
pub const HISTORY_STORE_LIMIT: usize = HISTORY_LIMIT * aede_accounts::MAX_ACCOUNTS;
/// Maximum UTF-8 bytes read from or published to the personal store.
pub const USER_MAX_BYTES: usize = 64 * 1024 * 1024;

/// A record the user has taken off a report, and why that is allowed.
///
/// **The one thing in this file that is not keyed on an entity of the
/// catalog.** Everything else here describes something the library holds; this
/// describes something it deliberately does *not*. `aede missing` lists albums a
/// source credits to an artist and the shelf lacks, and sometimes the source is
/// simply wrong about what an album is — a demo, a compilation and a single all
/// arrive typed `Album` until somebody says otherwise on MusicBrainz.
///
/// Aède will not overrule a source: the whole attributed layer exists so that
/// what somebody else said stays what they said, correctable only by them. But
/// it will record that **you** disagree, which is what this file has always
/// been for, and stop putting the record in front of you.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SetAside {
    /// Whose decision it is.
    pub owner: UserRef,
    /// The MusicBrainz release-group identifier, which is the key.
    ///
    /// Globally unique, so no artist is needed to tell two apart, and stable
    /// across a re-fetch and a rescan — where a title is neither.
    pub release_group: String,
    /// The title as it read when it was set aside.
    ///
    /// Kept so a listing can show something a person recognises. Without it the
    /// list is a column of identifiers, and a decision nobody can read is one
    /// nobody can undo.
    pub title: String,
    /// When it was set aside.
    pub created_at: u64,
}

/// Two spellings the owner of the disk says are one musician.
///
/// The second half of artist identity, and the half no authority can settle.
/// `MUSICBRAINZ_ARTISTID` answers for the files that met Picard; for an old
/// rip, a download, a friend's drive, **nobody on earth knows that a particular
/// `O. Osbourne` is Ozzy except the person whose shelf it is**. Comparing the
/// strings cannot stand in for them — a fragment match merges Angus Young with
/// Neil Young — so the program asks instead of guessing, and keeps the answer
/// here, with everything else that was said rather than derived.
///
/// **Both keys are normalised**, because that is the form the merge is decided
/// on everywhere else in the program: a statement about `Ozzy  Osbourne` must
/// still be about `ozzy osbourne` on the next scan. They are readable as they
/// stand — unlike a [`SetAside`], whose key is an identifier and which
/// therefore has to carry a title beside it.
///
/// Nothing in an audio file changes, ever. This is a statement about how the
/// shelf is *read*, and `aede merge --forget` takes it back.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SameArtist {
    /// Whose statement it is.
    pub owner: UserRef,
    /// The spelling that gives way, normalised.
    pub spelling: String,
    /// The spelling it is filed under, normalised.
    pub filed_as: String,
    /// When it was said.
    pub created_at: u64,
}

/// Everything the user wrote, as it sits on disk.
#[derive(Debug, Clone, Default)]
pub struct UserData {
    /// Optional owner-private application preferences; retained across scans and exports.
    pub client_preferences: Vec<ClientPreference>,
    /// One record per owner and target.
    pub annotations: Vec<Annotation>,
    /// Notes and labels attached to graph relationships.
    pub relation_annotations: Vec<RelationAnnotation>,
    /// The most recent plays, oldest first, bounded by [`HISTORY_LIMIT`].
    pub plays: Vec<Play>,
    /// All-time counts, which never forget.
    pub counts: Vec<PlayCount>,
    /// Saved queries, by name.
    pub collections: Vec<Collection>,
    /// Private, ordered static playlists, including repeated/missing tracks.
    pub playlists: Vec<Playlist>,
    /// Client-declared listens with unknown duration/completion, oldest first.
    pub scrobbles: Vec<Scrobble>,
    /// Optional named native-player checkpoints, private to their immutable owner.
    pub playback_states: Vec<PlaybackState>,
    /// Records taken off the `missing` report — see [`SetAside`].
    pub set_aside: Vec<SetAside>,
    /// Spellings the owner says are one artist — see [`SameArtist`].
    pub same_artist: Vec<SameArtist>,
    /// Last observed evidence for referenced files, used for safe relocation.
    pub track_identities: Vec<TrackIdentity>,
    /// Explicit owner-scoped reattachments, retained for conflict-safe undo.
    pub relinks: Vec<Relink>,
}

impl UserData {
    /// The record for one owner and target, if there is one.
    pub fn find(&self, owner: &str, target: &EntityRef) -> Option<&Annotation> {
        self.annotations
            .iter()
            .find(|a| a.owner == owner && &a.target == target)
    }

    /// The record for one owner and target, opening one if needed.
    ///
    /// `now` stamps a record that did not exist; an existing one keeps its
    /// creation date and has its `updated_at` moved by the caller.
    pub fn entry(&mut self, owner: &str, target: &EntityRef, now: u64) -> &mut Annotation {
        let found = self
            .annotations
            .iter()
            .position(|a| a.owner == owner && &a.target == target);
        let at = match found {
            Some(at) => at,
            None => {
                self.annotations.push(Annotation {
                    owner: owner.to_string(),
                    target: target.clone(),
                    created_at: now,
                    updated_at: now,
                    ..Default::default()
                });
                self.annotations.len() - 1
            }
        };
        &mut self.annotations[at]
    }

    /// Drops the records that no longer say anything.
    ///
    /// Called after every change, so that un-loving the one album somebody ever
    /// loved leaves nothing behind.
    pub fn forget_empty(&mut self) {
        self.annotations.retain(|a| !a.is_empty());
        self.relation_annotations.retain(|a| !a.is_empty());
    }

    /// Personal annotation for one relation, if one exists.
    pub fn find_relation(
        &self,
        owner: &str,
        relation: &crate::graph::RelationRef,
    ) -> Option<&RelationAnnotation> {
        self.relation_annotations
            .iter()
            .find(|annotation| annotation.owner == owner && &annotation.relation == relation)
    }

    /// Finds one owner’s credit context across exact catalog identity aliases.
    ///
    /// An exact reference wins. A unique equivalent credit is usable when the
    /// catalog can resolve both endpoints; ambiguous aliases select nothing.
    /// Other relationship kinds retain exact-reference behavior.
    pub fn find_relation_in(
        &self,
        catalog: &Catalog,
        owner: &str,
        relation: &crate::graph::RelationRef,
    ) -> Option<&RelationAnnotation> {
        match self.relation_annotation_match(catalog, owner, relation) {
            RelationAnnotationMatch::Unique(index) => self.relation_annotations.get(index),
            RelationAnnotationMatch::Absent | RelationAnnotationMatch::Ambiguous => None,
        }
    }

    /// Opens existing credit context without combining historical annotations.
    /// A new credit keeps its known artist MBID when local tags later disappear.
    pub fn relation_entry_in(
        &mut self,
        catalog: &Catalog,
        owner: &str,
        relation: &crate::graph::RelationRef,
        now: u64,
    ) -> Result<&mut RelationAnnotation, String> {
        match self.relation_annotation_match(catalog, owner, relation) {
            RelationAnnotationMatch::Unique(index) => Ok(&mut self.relation_annotations[index]),
            RelationAnnotationMatch::Ambiguous => Err(
                "several saved annotations match this credit; use their exact saved references"
                    .into(),
            ),
            RelationAnnotationMatch::Absent => {
                let reference = if relation.kind.starts_with("credit:") {
                    crate::graph::canonical_credit_relation(catalog, relation.clone())
                } else {
                    relation.clone()
                };
                Ok(self.relation_entry(owner, &reference, now))
            }
        }
    }

    /// Removes one exact or uniquely equivalent owner annotation.
    /// Ambiguous history is refused without deleting or merging any row.
    pub fn remove_relation_in(
        &mut self,
        catalog: &Catalog,
        owner: &str,
        relation: &crate::graph::RelationRef,
    ) -> Result<bool, String> {
        match self.relation_annotation_match(catalog, owner, relation) {
            RelationAnnotationMatch::Unique(index) => {
                self.relation_annotations.remove(index);
                Ok(true)
            }
            RelationAnnotationMatch::Absent => Ok(false),
            RelationAnnotationMatch::Ambiguous => Err(
                "several saved annotations match this credit; use their exact saved references"
                    .into(),
            ),
        }
    }

    fn relation_annotation_match(
        &self,
        catalog: &Catalog,
        owner: &str,
        relation: &crate::graph::RelationRef,
    ) -> RelationAnnotationMatch {
        if let Some(index) = self
            .relation_annotations
            .iter()
            .position(|annotation| annotation.owner == owner && &annotation.relation == relation)
        {
            return RelationAnnotationMatch::Unique(index);
        }
        if !relation.kind.starts_with("credit:") {
            return RelationAnnotationMatch::Absent;
        }
        let mut matching =
            self.relation_annotations
                .iter()
                .enumerate()
                .filter(|(_, annotation)| {
                    annotation.owner == owner
                        && same_annotation_relation(catalog, &annotation.relation, relation)
                });
        match (matching.next(), matching.next()) {
            (None, _) => RelationAnnotationMatch::Absent,
            (Some((index, _)), None) => RelationAnnotationMatch::Unique(index),
            (Some(_), Some(_)) => RelationAnnotationMatch::Ambiguous,
        }
    }

    /// Opens the personal annotation for one relation.
    pub fn relation_entry(
        &mut self,
        owner: &str,
        relation: &crate::graph::RelationRef,
        now: u64,
    ) -> &mut RelationAnnotation {
        let found = self
            .relation_annotations
            .iter()
            .position(|annotation| annotation.owner == owner && &annotation.relation == relation);
        let index = match found {
            Some(index) => index,
            None => {
                self.relation_annotations.push(RelationAnnotation {
                    owner: owner.to_string(),
                    relation: relation.clone(),
                    note: None,
                    tags: BTreeSet::new(),
                    created_at: now,
                    updated_at: now,
                });
                self.relation_annotations.len() - 1
            }
        };
        &mut self.relation_annotations[index]
    }

    /// Copies everything said about one target onto another.
    ///
    /// Returns `false` when there was nothing to copy — which is worth telling
    /// the user, since a silent success there means they typed the wrong name
    /// and will not find out until they look.
    pub fn copy(&mut self, owner: &str, from: &EntityRef, to: &EntityRef, now: u64) -> bool {
        let Some(source) = self.find(owner, from).cloned() else {
            return false;
        };
        let target = self.entry(owner, to, now);
        target.loved = source.loved;
        target.rating = source.rating;
        target.note = source.note.clone();
        target.tags = source.tags;
        target.updated_at = now;
        true
    }

    /// Takes back the most recent play of a track, log and counter together.
    ///
    /// The counter is not a summary of the log — the log is bounded at
    /// [`HISTORY_LIMIT`] and the counter is not — so a removal that touched one
    /// and not the other would leave a track played "three times" with two
    /// plays behind it, and nothing on screen to say which was right. They are
    /// written together by [`UserData::record_play`] and they are taken back
    /// together here.
    ///
    /// Returns `false` when there was nothing to take back, which the caller
    /// says rather than reporting a removal that did not happen.
    pub fn forget_last_play(&mut self, owner: &str, track: &EntityRef) -> bool {
        let Some(index) = self
            .plays
            .iter()
            .rposition(|p| p.owner == owner && &p.track == track)
        else {
            // The log may have rolled the play off its front while the counter
            // still holds it. Decrementing on a play nobody can point at would
            // be guessing, so it is refused.
            return false;
        };
        let completed = self.plays.remove(index).completed;
        if let Some(counter) = self
            .counts
            .iter_mut()
            .find(|c| c.owner == owner && &c.track == track)
        {
            counter.count = counter.count.saturating_sub(1);
            counter.completed_count = counter.completed_count.saturating_sub(u32::from(completed));
            // The last-played date now belongs to whatever play is newest of
            // those left, and to nothing at all when none is.
            counter.last_played = self
                .plays
                .iter()
                .filter(|p| p.owner == owner && &p.track == track)
                .map(|p| p.at)
                .chain(
                    self.scrobbles
                        .iter()
                        .filter(|p| p.owner == owner && &p.track == track)
                        .map(|p| p.at_ms / 1000),
                )
                .max()
                .unwrap_or(0);
        }
        self.counts
            .retain(|c| c.count > 0 || c.owner != owner || &c.track != track);
        true
    }

    /// Forgets everything an owner ever played.
    ///
    /// Native events, declared scrobbles and counters are cleared together.
    /// Returns how many events/declarations and how many counters went,
    /// because "your history is cleared" is a claim nobody
    /// can check and a number is.
    pub fn forget_history(&mut self, owner: &str) -> (usize, usize) {
        let plays = self.plays.iter().filter(|p| p.owner == owner).count()
            + self.scrobbles.iter().filter(|p| p.owner == owner).count();
        let counts = self.counts.iter().filter(|c| c.owner == owner).count();
        self.plays.retain(|p| p.owner != owner);
        self.scrobbles.retain(|p| p.owner != owner);
        self.counts.retain(|c| c.owner != owner);
        (plays, counts)
    }

    /// Records one listen: the bounded log and the all-time counter together.
    ///
    /// Both, always — see [`UserData::forget_last_play`] for why the two must
    /// never be written apart.
    pub fn record_play(&mut self, play: Play) {
        match self
            .counts
            .iter_mut()
            .find(|c| c.owner == play.owner && c.track == play.track)
        {
            Some(counter) => {
                counter.count = counter.count.saturating_add(1);
                counter.completed_count = counter
                    .completed_count
                    .saturating_add(u32::from(play.completed));
                counter.last_played = counter.last_played.max(play.at);
            }
            None => self.counts.push(PlayCount {
                owner: play.owner.clone(),
                track: play.track.clone(),
                count: 1,
                completed_count: u32::from(play.completed),
                last_played: play.at,
            }),
        }
        self.plays.push(play);
        // Offline clients can submit older listens after newer ones. Stable
        // ordering keeps equal-time events in arrival order without deduping.
        self.plays.sort_by_key(|play| play.at);
        // Oldest first, so the excess falls off the front.
        history::retain(&mut self.plays, |play| &play.owner);
    }

    /// A saved query by name, compared without regard to case or accents:
    /// somebody typing `aede collection Metal` means the one they saved as
    /// "metal".
    pub fn collection(&self, owner: &str, name: &str) -> Option<&Collection> {
        let wanted = text::normalize(name);
        self.collections
            .iter()
            .find(|c| c.owner == owner && text::normalize(&c.name) == wanted)
    }

    /// Saves a query under a name, replacing one of the same name.
    ///
    /// Returns `true` when a collection was replaced, which the caller says out
    /// loud: overwriting somebody's saved query in silence is how they find out
    /// a week later.
    pub fn save_collection(&mut self, owner: &str, name: &str, expression: &str, now: u64) -> bool {
        let wanted = text::normalize(name);
        if let Some(existing) = self
            .collections
            .iter_mut()
            .find(|c| c.owner == owner && text::normalize(&c.name) == wanted)
        {
            existing.expression = expression.to_string();
            existing.updated_at = now;
            return true;
        }
        self.collections.push(Collection {
            owner: owner.to_string(),
            name: name.to_string(),
            expression: expression.to_string(),
            created_at: now,
            updated_at: now,
        });
        false
    }

    /// Drops a saved query; `false` when there was none by that name.
    pub fn forget_collection(&mut self, owner: &str, name: &str) -> bool {
        let wanted = text::normalize(name);
        let before = self.collections.len();
        self.collections
            .retain(|c| !(c.owner == owner && text::normalize(&c.name) == wanted));
        self.collections.len() != before
    }

    /// How many times one person played a track, all-time.
    pub fn play_count(&self, owner: &str, track: &EntityRef) -> u32 {
        self.counts
            .iter()
            .find(|c| c.owner == owner && &c.track == track)
            .map(|c| c.count)
            .unwrap_or(0)
    }
}

// --------------------------------------------------------------------------
// On disk
// --------------------------------------------------------------------------

/// Where the user file sits inside a data folder.
pub fn user_path(data_dir: &std::path::Path) -> std::path::PathBuf {
    data_dir.join(USER_FILE)
}

/// Saves what the user wrote, atomically.
///
/// Written **pretty**, unlike the catalog. The catalog is machine output that
/// nobody reads; this file is the one a user may want to open, grep, or repair
/// by hand after a bad restore, and it is small enough for that to cost
/// nothing.
/// An exclusive temporary output prevents an existing temporary symlink from
/// being followed; a symlink at the final path is refused.
pub fn save(data: &UserData, path: &std::path::Path) -> Result<(), crate::store::StoreError> {
    preferences::validate(&data.client_preferences)?;
    history::validate(data)?;
    playlists::validate(data)?;
    playback::validate(data)?;
    let text = to_json(data)
        .to_string_pretty_bounded(USER_MAX_BYTES)
        .map_err(|_| crate::store::StoreError::Invalid("personal store byte limit exceeded"))?;
    crate::atomic_file::write(path, text.as_bytes())?;
    Ok(())
}

/// Loads what the user wrote; `Ok(None)` when nothing has been written yet.
pub fn load(path: &std::path::Path) -> Result<Option<UserData>, crate::store::StoreError> {
    use std::io::Read;
    let file = match std::fs::File::open(path) {
        Ok(file) => file,
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(None),
        Err(error) => return Err(error.into()),
    };
    let mut bytes = Vec::new();
    file.take(USER_MAX_BYTES as u64 + 1)
        .read_to_end(&mut bytes)?;
    if bytes.len() > USER_MAX_BYTES {
        return Err(crate::store::StoreError::Invalid(
            "personal store byte limit exceeded",
        ));
    }
    let text = String::from_utf8(bytes).map_err(|failure| {
        std::io::Error::new(std::io::ErrorKind::InvalidData, failure.utf8_error())
    })?;
    let value = crate::json::parse(&text).map_err(crate::store::StoreError::Parse)?;
    from_json(&value).map(Some)
}

/// The document, one array per table.
pub fn to_json(data: &UserData) -> crate::json::Json {
    use crate::json::Json;
    let mut root = Json::obj();
    root.set("format_version", USER_FORMAT_VERSION.into());

    let annotations: Vec<Json> = data
        .annotations
        .iter()
        .map(|a| {
            let mut o = Json::obj();
            o.set("owner", a.owner.as_str().into());
            o.set("target", a.target.to_token().into());
            if a.loved {
                o.set("loved", Json::Bool(true));
            }
            if let Some(rating) = a.rating {
                o.set("rating", u32::from(rating).into());
            }
            // A blank note — `Some("")`, or whitespace only — says nothing
            // `None` did not already say, and writing the key anyway would
            // hand a reader of this file (or the next `--import` of it) the
            // exact record `forget_empty` exists to drop on the way in.
            if let Some(note) = a.note.as_deref().filter(|n| !n.trim().is_empty()) {
                o.set("note", note.into());
            }
            if !a.tags.is_empty() {
                o.set(
                    "tags",
                    Json::Arr(a.tags.iter().map(|t| t.as_str().into()).collect()),
                );
            }
            o.set("created_at", a.created_at.into());
            o.set("updated_at", a.updated_at.into());
            o
        })
        .collect();
    root.set("annotations", Json::Arr(annotations));

    let relation_annotations: Vec<Json> = data
        .relation_annotations
        .iter()
        .map(|annotation| {
            let mut row = Json::obj();
            row.set("owner", annotation.owner.as_str().into());
            row.set("source", annotation.relation.source.to_token().into());
            row.set("relation", annotation.relation.kind.as_str().into());
            row.set("target", annotation.relation.target.to_token().into());
            row.set("provenance", annotation.relation.provenance.as_str().into());
            if let Some(source_id) = &annotation.relation.source_id {
                row.set("source_id", source_id.as_str().into());
            }
            if let Some(note) = annotation
                .note
                .as_deref()
                .filter(|note| !note.trim().is_empty())
            {
                row.set("note", note.into());
            }
            if !annotation.tags.is_empty() {
                row.set(
                    "tags",
                    Json::Arr(
                        annotation
                            .tags
                            .iter()
                            .map(|tag| tag.as_str().into())
                            .collect(),
                    ),
                );
            }
            row.set("created_at", annotation.created_at.into());
            row.set("updated_at", annotation.updated_at.into());
            row
        })
        .collect();
    root.set("relation_annotations", Json::Arr(relation_annotations));

    let plays: Vec<Json> = data
        .plays
        .iter()
        .map(|p| {
            let mut o = Json::obj();
            o.set("owner", p.owner.as_str().into());
            o.set("track", p.track.to_token().into());
            o.set("at", p.at.into());
            o.set("ms_played", p.ms_played.into());
            o.set("completed", Json::Bool(p.completed));
            o
        })
        .collect();
    root.set("plays", Json::Arr(plays));

    let counts: Vec<Json> = data
        .counts
        .iter()
        .map(|c| {
            let mut o = Json::obj();
            o.set("owner", c.owner.as_str().into());
            o.set("track", c.track.to_token().into());
            o.set("count", c.count.into());
            o.set("completed_count", c.completed_count.into());
            o.set("last_played", c.last_played.into());
            o
        })
        .collect();
    root.set("counts", Json::Arr(counts));

    let collections: Vec<Json> = data
        .collections
        .iter()
        .map(|c| {
            let mut o = Json::obj();
            o.set("owner", c.owner.as_str().into());
            o.set("name", c.name.as_str().into());
            o.set("query", c.expression.as_str().into());
            o.set("created_at", c.created_at.into());
            o.set("updated_at", c.updated_at.into());
            o
        })
        .collect();
    root.set("collections", Json::Arr(collections));
    playlists::write_tables(data, &mut root);
    playback::write_table(data, &mut root);
    preferences::write(data, &mut root);

    let set_aside: Vec<Json> = data
        .set_aside
        .iter()
        .map(|a| {
            let mut o = Json::obj();
            o.set("owner", a.owner.as_str().into());
            o.set("release_group", a.release_group.as_str().into());
            o.set("title", a.title.as_str().into());
            o.set("created_at", a.created_at.into());
            o
        })
        .collect();
    root.set("set_aside", Json::Arr(set_aside));

    let same_artist: Vec<Json> = data
        .same_artist
        .iter()
        .map(|m| {
            let mut o = Json::obj();
            o.set("owner", m.owner.as_str().into());
            o.set("spelling", m.spelling.as_str().into());
            o.set("filed_as", m.filed_as.as_str().into());
            o.set("created_at", m.created_at.into());
            o
        })
        .collect();
    root.set("same_artist", Json::Arr(same_artist));
    root.set(
        "track_identities",
        Json::Arr(
            data.track_identities
                .iter()
                .map(TrackIdentity::to_json)
                .collect(),
        ),
    );
    root.set(
        "relinks",
        Json::Arr(data.relinks.iter().map(Relink::to_json).collect()),
    );
    root
}

/// Reads the document back.
///
/// A legacy row whose target cannot be parsed is **skipped rather than fatal**: one
/// corrupted line must not cost the user every note they ever wrote, which is
/// the opposite of the catalog's rule, where a broken row means the graph does
/// not hold together and refusing is the safe answer. Here there is no graph —
/// only statements, each standing alone.
/// Missing optional tables remain compatible with old stores. A present table
/// of the wrong JSON type is refused before a later write can empty it.
/// New static-playlist and scrobble rows are strictly validated: malformed or
/// oversized rows fail the load, preserving the original file for recovery.
pub fn from_json(value: &crate::json::Json) -> Result<UserData, crate::store::StoreError> {
    value
        .check_pretty_size(USER_MAX_BYTES)
        .map_err(|_| crate::store::StoreError::Invalid("personal store byte limit exceeded"))?;
    use crate::store::StoreError;
    let found = value.field_u32("format_version").unwrap_or(0);
    if !matches!(found, 1 | USER_FORMAT_VERSION) {
        return Err(StoreError::Version {
            found,
            expected: USER_FORMAT_VERSION,
        });
    }
    for (table, message) in [
        ("annotations", "user annotations must be an array"),
        (
            "relation_annotations",
            "user relation annotations must be an array",
        ),
        ("plays", "user plays must be an array"),
        ("counts", "user counts must be an array"),
        ("collections", "user collections must be an array"),
        ("playlists", "user playlists must be an array"),
        ("scrobbles", "user scrobbles must be an array"),
        ("playback_states", "user playback states must be an array"),
        ("set_aside", "user set-aside decisions must be an array"),
        ("same_artist", "user artist decisions must be an array"),
        ("track_identities", "user track identities must be an array"),
        ("relinks", "user relink history must be an array"),
    ] {
        if value
            .get(table)
            .is_some_and(|value| value.as_arr().is_none())
        {
            return Err(StoreError::Invalid(message));
        }
    }
    let mut data = UserData {
        client_preferences: preferences::read(value)?,
        playlists: playlists::read_playlists(value)?,
        scrobbles: playlists::read_scrobbles(value)?,
        playback_states: playback::read_states(value)?,
        track_identities: value
            .get("track_identities")
            .and_then(crate::json::Json::as_arr)
            .unwrap_or(&[])
            .iter()
            .filter_map(TrackIdentity::from_json)
            .collect(),
        relinks: value
            .get("relinks")
            .and_then(crate::json::Json::as_arr)
            .unwrap_or(&[])
            .iter()
            .filter_map(Relink::from_json)
            .collect(),
        ..Default::default()
    };

    for row in value
        .get("annotations")
        .and_then(|v| v.as_arr())
        .unwrap_or(&[])
    {
        let Some(target) = row
            .field_str("target")
            .and_then(|t| EntityRef::parse_token(&t))
        else {
            continue;
        };
        data.annotations.push(Annotation {
            owner: row.field_str("owner").unwrap_or_else(|| LOCAL_USER.into()),
            target,
            loved: row.field_bool("loved"),
            rating: row.field_u32("rating").map(|r| r.clamp(1, 5) as u8),
            note: row.field_str("note"),
            tags: row
                .get("tags")
                .and_then(|v| v.as_arr())
                .map(|list| list.iter().filter_map(|t| t.as_string()).collect())
                .unwrap_or_default(),
            created_at: row.field_u64("created_at").unwrap_or(0),
            updated_at: row.field_u64("updated_at").unwrap_or(0),
        });
    }

    for row in value
        .get("relation_annotations")
        .and_then(|value| value.as_arr())
        .unwrap_or(&[])
    {
        let (Some(source), Some(kind), Some(target), Some(provenance)) = (
            row.field_str("source")
                .and_then(|value| EntityRef::parse_token(&value)),
            row.field_str("relation"),
            row.field_str("target")
                .and_then(|value| EntityRef::parse_token(&value)),
            row.field_str("provenance"),
        ) else {
            continue;
        };
        let annotation = RelationAnnotation {
            owner: row.field_str("owner").unwrap_or_else(|| LOCAL_USER.into()),
            relation: crate::graph::RelationRef {
                source,
                kind,
                target,
                provenance,
                source_id: row.field_str("source_id"),
            },
            note: row.field_str("note"),
            tags: row
                .get("tags")
                .and_then(|value| value.as_arr())
                .map(|values| {
                    values
                        .iter()
                        .filter_map(|value| value.as_string())
                        .collect()
                })
                .unwrap_or_default(),
            created_at: row.field_u64("created_at").unwrap_or(0),
            updated_at: row.field_u64("updated_at").unwrap_or(0),
        };
        if !annotation.is_empty() {
            data.relation_annotations.push(annotation);
        }
    }

    for row in value.get("plays").and_then(|v| v.as_arr()).unwrap_or(&[]) {
        let Some(track) = row
            .field_str("track")
            .and_then(|t| EntityRef::parse_token(&t))
        else {
            continue;
        };
        data.plays.push(Play {
            owner: row.field_str("owner").unwrap_or_else(|| LOCAL_USER.into()),
            track,
            at: row.field_u64("at").unwrap_or(0),
            ms_played: row.field_u64("ms_played").unwrap_or(0),
            completed: row.field_bool("completed"),
        });
    }

    // Legacy recent evidence can be recovered, but an evicted unknown visit cannot be guessed.
    let mut legacy_completed = BTreeMap::<(&str, &EntityRef), u32>::new();
    for play in data.plays.iter().filter(|play| play.completed) {
        let count = legacy_completed
            .entry((&play.owner, &play.track))
            .or_default();
        *count = count.saturating_add(1);
    }
    for row in value.get("counts").and_then(|v| v.as_arr()).unwrap_or(&[]) {
        let Some(track) = row
            .field_str("track")
            .and_then(|t| EntityRef::parse_token(&t))
        else {
            continue;
        };
        let owner = row.field_str("owner").unwrap_or_else(|| LOCAL_USER.into());
        let completed_count = match row.get("completed_count") {
            Some(value) => value.as_u32().ok_or(crate::store::StoreError::Invalid(
                "invalid completed listening count",
            ))?,
            None => legacy_completed
                .get(&(owner.as_str(), &track))
                .copied()
                .unwrap_or(0)
                .min(row.field_u32("count").unwrap_or(0)),
        };
        data.counts.push(PlayCount {
            owner,
            track,
            count: row.field_u32("count").unwrap_or(0),
            completed_count,
            last_played: row.field_u64("last_played").unwrap_or(0),
        });
    }
    for row in value
        .get("collections")
        .and_then(|v| v.as_arr())
        .unwrap_or(&[])
    {
        let (Some(name), Some(expression)) = (row.field_str("name"), row.field_str("query")) else {
            continue;
        };
        data.collections.push(Collection {
            owner: row.field_str("owner").unwrap_or_else(|| LOCAL_USER.into()),
            name,
            expression,
            created_at: row.field_u64("created_at").unwrap_or(0),
            updated_at: row.field_u64("updated_at").unwrap_or(0),
        });
    }
    for row in value
        .get("set_aside")
        .and_then(crate::json::Json::as_arr)
        .unwrap_or(&[])
    {
        // No identifier, no decision: the title alone cannot say which record
        // was meant, and a wish list quietly shortened by one is worse than
        // one item too long.
        let Some(release_group) = row.field_str("release_group") else {
            continue;
        };
        data.set_aside.push(SetAside {
            owner: row
                .field_str("owner")
                .unwrap_or_else(|| LOCAL_USER.to_string()),
            release_group,
            title: row.field_str("title").unwrap_or_default(),
            created_at: row.field_u64("created_at").unwrap_or(0),
        });
    }
    for row in value
        .get("same_artist")
        .and_then(crate::json::Json::as_arr)
        .unwrap_or(&[])
    {
        // Half a statement is not a statement: a row naming one spelling says
        // nothing about which artist it gives way to, and filing it under the
        // empty key would collect every broken row in the file under one
        // artist nobody named.
        let (Some(spelling), Some(filed_as)) =
            (row.field_str("spelling"), row.field_str("filed_as"))
        else {
            continue;
        };
        // Normalised on the way in as well as on the way out. A file edited by
        // hand — which is a thing this format invites, being readable — must
        // not be able to state a merge the program can never match.
        let (spelling, filed_as) = (text::normalize(&spelling), text::normalize(&filed_as));
        if spelling.is_empty() || filed_as.is_empty() || spelling == filed_as {
            continue;
        }
        data.same_artist.push(SameArtist {
            owner: row
                .field_str("owner")
                .unwrap_or_else(|| LOCAL_USER.to_string()),
            spelling,
            filed_as,
            created_at: row.field_u64("created_at").unwrap_or(0),
        });
    }
    // Older writers stored arrival order. Normalize in memory so readers and
    // undo operations use event time without changing counts or losing events.
    data.plays.sort_by_key(|play| play.at);
    history::validate(&data)?;
    Ok(data)
}

/// What a merge did, so that an import can say it rather than be trusted.
#[derive(Debug, Clone, Copy, Default, PartialEq)]
pub struct Merge {
    /// Records that did not exist here.
    pub added: usize,
    /// Records replaced because the incoming one was written later.
    pub updated: usize,
    /// Records left alone because what is here is newer.
    pub kept: usize,
    /// Native listening events or client declarations newly added to their logs.
    pub plays: usize,
    /// Saved queries taken in.
    pub collections: usize,
}

/// Folds one set of user data into another.
///
/// **Merging, never replacing.** Someone restoring half a backup wants their
/// two halves, not the older one; and an import that emptied what was already
/// there would be the one operation in this program capable of losing
/// everything at once.
///
/// The rule is the same everywhere: the record written **last** wins, and the
/// one that lost is reported rather than dropped in silence. Play counters take
/// the larger of the two, since a count is a total and neither side ever
/// counted the other's listens.
/// Recent listening events are merged as a multiset of their complete values:
/// simultaneous identical events keep their multiplicity, and reimporting a
/// backup does not append them again. Relink history remains an audit trail;
/// importing it never replays reattachment or undo commands.
/// Native-player profiles are imported only when absent locally: an import
/// never rewinds an existing device checkpoint, even if its timestamp is older.
pub fn merge(into: &mut UserData, incoming: UserData) -> Merge {
    let mut report = Merge::default();
    for entry in incoming.client_preferences {
        if !into
            .client_preferences
            .iter()
            .any(|known| known.owner == entry.owner && known.key == entry.key)
        {
            into.client_preferences.push(entry);
        }
    }
    playlists::merge(into, incoming.playlists, incoming.scrobbles, &mut report);
    playback::merge(into, incoming.playback_states, &mut report);

    // These are evidence and an audit trail, not commands to replay. Preserve
    // local evidence on conflict; imported history never moves current data.
    for identity in incoming.track_identities {
        if !into
            .track_identities
            .iter()
            .any(|known| known.path == identity.path)
        {
            into.track_identities.push(identity);
        }
    }
    for mut event in incoming.relinks {
        let known = into.relinks.iter().any(|known| {
            known.origin_id == event.origin_id
                && known.owner == event.owner
                && known.from == event.from
                && known.to == event.to
                && known.at == event.at
                && known.before.annotations == event.before.annotations
                && known.before.plays == event.before.plays
                && known.before.counts == event.before.counts
                && known.before.relation_annotations == event.before.relation_annotations
                && known.before.playlists == event.before.playlists
                && known.before.scrobbles == event.before.scrobbles
        });
        if known {
            continue;
        }
        if into.relinks.iter().any(|known| known.id == event.id) {
            let Some(next) = into
                .relinks
                .iter()
                .map(|known| known.id)
                .max()
                .unwrap_or(0)
                .checked_add(1)
            else {
                continue;
            };
            event.id = next;
        }
        into.relinks.push(event);
    }

    for annotation in incoming.annotations {
        match into
            .annotations
            .iter_mut()
            .find(|a| a.owner == annotation.owner && a.target == annotation.target)
        {
            Some(existing) if existing.updated_at >= annotation.updated_at => report.kept += 1,
            Some(existing) => {
                *existing = annotation;
                report.updated += 1;
            }
            None => {
                into.annotations.push(annotation);
                report.added += 1;
            }
        }
    }

    for annotation in incoming.relation_annotations {
        match into.relation_annotations.iter_mut().find(|existing| {
            existing.owner == annotation.owner && existing.relation == annotation.relation
        }) {
            Some(existing) if existing.updated_at >= annotation.updated_at => report.kept += 1,
            Some(existing) => {
                *existing = annotation;
                report.updated += 1;
            }
            None => {
                into.relation_annotations.push(annotation);
                report.added += 1;
            }
        }
    }

    // Equal-time listens can be distinct, including repeated identical events.
    // Consume only the multiplicity already present, so restoring a backup
    // keeps every listen while importing that same backup again is idempotent.
    let play_key = |play: &Play| {
        (
            play.owner.clone(),
            play.track.clone(),
            play.at,
            play.ms_played,
            play.completed,
        )
    };
    let mut available = BTreeMap::new();
    for play in &into.plays {
        *available.entry(play_key(play)).or_insert(0usize) += 1;
    }
    for play in incoming.plays {
        let copies = available.entry(play_key(&play)).or_default();
        if *copies > 0 {
            *copies -= 1;
        } else {
            into.plays.push(play);
            report.plays += 1;
        }
    }
    into.plays.sort_by_key(|p| p.at);
    history::retain(&mut into.plays, |play| &play.owner);

    for count in incoming.counts {
        match into
            .counts
            .iter_mut()
            .find(|c| c.owner == count.owner && c.track == count.track)
        {
            Some(existing) => {
                existing.count = existing.count.max(count.count);
                existing.completed_count = existing.completed_count.max(count.completed_count);
                existing.last_played = existing.last_played.max(count.last_played);
            }
            None => into.counts.push(count),
        }
    }

    for collection in incoming.collections {
        let owner = collection.owner.clone();
        match into.collections.iter_mut().find(|c| {
            c.owner == owner && text::normalize(&c.name) == text::normalize(&collection.name)
        }) {
            Some(existing) if existing.updated_at >= collection.updated_at => report.kept += 1,
            Some(existing) => {
                *existing = collection;
                report.collections += 1;
            }
            None => {
                into.collections.push(collection);
                report.collections += 1;
            }
        }
    }
    // A decision has no versions to arbitrate: it was taken or it was not, so
    // importing the same backup twice must not file it twice.
    for aside in incoming.set_aside {
        let known = into
            .set_aside
            .iter()
            .any(|a| a.owner == aside.owner && a.release_group == aside.release_group);
        if !known {
            into.set_aside.push(aside);
            report.added += 1;
        }
    }
    // Same rule, and the same reason: a merge was stated or it was not.
    // Keyed on the spelling that gives way alone, not on the pair — two rows
    // filing `o osbourne` under two different artists is not a statement said
    // twice, it is a contradiction, and the one already on this disk wins
    // because taking it back is one command and finding it is not.
    for same in incoming.same_artist {
        let known = into
            .same_artist
            .iter()
            .any(|m| m.owner == same.owner && m.spelling == same.spelling);
        if !known {
            into.same_artist.push(same);
            report.added += 1;
        }
    }
    report
}

#[cfg(test)]
#[path = "user_test_support.rs"]
mod test_support;

#[cfg(test)]
#[path = "user_tests.rs"]
mod tests;

#[cfg(test)]
#[path = "user_history_tests.rs"]
mod history_tests;