aede_core/

store.rs

//! Catalog persistence.
//!
//! The format is a JSON document whose every key is a "table": it is the
//! mirror image of the relational schema described in `schema.sql`. Costly
//! conclusions are saved independently, so a catalog-format change does not
//! require recomputing them. SQLite remains deferred.
//!
//! Writing is atomic (temporary file then rename): an interruption during
//! saving cannot leave a half-written catalog behind.

use std::collections::BTreeMap;
use std::io::{self, Write};
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicU64, Ordering};

use crate::analysis::FileAnalysis;
use crate::audit;
use crate::conclusions;
use crate::json::{self, Json};
use crate::model::{
    self, Artist, AudioFile, Catalog, Credit, EntityKind, Genre, GenreLink, Id, IntegrityRecord,
    Label, Recording, Relation, Release, ReleaseGroup, Track, Work,
};
use crate::tags::AudioProperties;

/// On-disk format version. Every incompatible change increments it.
pub const FORMAT_VERSION: u32 = 1;

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

/// What can go wrong when saving or loading a catalog.
///
/// A missing file is not an error: [`load`] reports it as `Ok(None)`.
#[derive(Debug)]
pub enum StoreError {
    /// The catalog file, its parent folder or the temporary file used for the
    /// atomic rename could not be accessed.
    Io(std::io::Error),
    /// The file exists but is not valid JSON, typically after being edited by
    /// hand or truncated by a full disk.
    Parse(json::ParseError),
    /// The independent conclusions document is not valid JSON.
    ConclusionsParse(json::ParseError),
    /// The file was written by an incompatible version.
    Version {
        /// Version stamped in the file; `0` when the field is missing
        /// altogether, which is how a pre-versioning catalog shows up.
        found: u32,
        /// Version this build understands, that is [`FORMAT_VERSION`].
        expected: u32,
    },
    /// The conclusions store uses a version this build cannot read.
    ConclusionsVersion {
        /// Version stamped in `conclusions.json`.
        found: u32,
        /// Version this build understands.
        expected: u32,
    },
    /// The JSON parsed but the catalog does not hold together: a row without
    /// an identifier, a track pointing at no file, non-contiguous identifiers.
    /// The payload names the specific breach.
    Invalid(&'static str),
    /// A malformed row in the conclusions store.
    ConclusionsInvalid(&'static str),
    /// Private credential document could not be parsed.
    AccountsParse(json::ParseError),
    /// Account metadata or credential policy is inconsistent.
    AccountsInvalid(&'static str),
}

impl std::fmt::Display for StoreError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            StoreError::Io(e) => write!(f, "input/output error: {e}"),
            StoreError::Parse(e) => write!(f, "unreadable catalog: {e}"),
            StoreError::ConclusionsParse(e) => write!(f, "unreadable conclusions: {e}"),
            StoreError::Version { found, expected } => write!(
                f,
                "catalog in version {found}, expected {expected} — run a full scan again"
            ),
            StoreError::Invalid(what) => write!(f, "inconsistent catalog: {what}"),
            StoreError::ConclusionsVersion { found, expected } => {
                write!(f, "conclusions in version {found}, expected {expected}")
            }
            StoreError::ConclusionsInvalid(what) => write!(f, "inconsistent conclusions: {what}"),
            StoreError::AccountsParse(what) => write!(f, "unreadable accounts: {what}"),
            StoreError::AccountsInvalid(what) => write!(f, "inconsistent accounts: {what}"),
        }
    }
}

impl std::error::Error for StoreError {}

impl From<std::io::Error> for StoreError {
    fn from(e: std::io::Error) -> Self {
        StoreError::Io(e)
    }
}

/// Default data location: `~/.local/share/aede`, or `$AEDE_HOME` if the
/// variable is set.
pub fn default_data_dir() -> PathBuf {
    if let Ok(custom) = std::env::var("AEDE_HOME") {
        return PathBuf::from(custom);
    }
    if let Ok(xdg) = std::env::var("XDG_DATA_HOME") {
        return PathBuf::from(xdg).join("aede");
    }
    match std::env::var("HOME") {
        Ok(home) => PathBuf::from(home).join(".local/share/aede"),
        Err(_) => PathBuf::from(".aede"),
    }
}

/// Builds the catalog path inside a data folder.
///
/// Nothing is created or checked here; the folder is only made to exist when
/// [`save`] runs.
pub fn catalog_path(data_dir: &Path) -> PathBuf {
    data_dir.join(CATALOG_FILE)
}

/// Where a picture goes when no single folder on disk can hold it.
///
/// `fetch --portraits` prefers the folder shared by every album of an artist,
/// the same place `cover.jpg` sits relative to a release — nothing here is
/// involved and nothing needs backing up beyond the music library itself. This
/// is the fallback for the artist that has no such folder: credited only on
/// compilations, or with a discography spread across more than one watched
/// root. Inside the data folder rather than beside anything on disk, because
/// there is no "beside" to put it — the same reasoning that puts `sources.json`
/// here and not in the library.
pub const ASSETS_DIR: &str = "assets";

/// The folder pictures without a home on disk are written into.
///
/// Nothing is created or checked here, the same as [`catalog_path`]: it is
/// made to exist only when something is about to be written into it.
pub fn assets_dir(data_dir: &Path) -> PathBuf {
    data_dir.join(ASSETS_DIR)
}

/// Writes a new sidecar through a temporary file, never replacing an existing one.
///
/// An interrupted download may leave a hidden temporary file, but never a
/// truncated image or lyric at its final path. Publication uses a hard link
/// on the same filesystem and fails closed if the filesystem cannot provide
/// it: an existence check followed by rename could replace another writer's file.
pub fn write_new_atomic(path: &Path, bytes: &[u8]) -> io::Result<bool> {
    static NEXT_TEMP: AtomicU64 = AtomicU64::new(1);

    if path.exists() {
        return Ok(false);
    }
    let parent = path.parent().unwrap_or(Path::new("."));
    let name = path
        .file_name()
        .ok_or_else(|| io::Error::new(io::ErrorKind::InvalidInput, "sidecar has no file name"))?;
    let mut temporary_name = std::ffi::OsString::from(".");
    temporary_name.push(name);
    let nonce = std::time::SystemTime::now()
        .duration_since(std::time::SystemTime::UNIX_EPOCH)
        .unwrap_or_default()
        .as_nanos();
    temporary_name.push(format!(
        ".aede-tmp-{}-{nonce}-{}",
        std::process::id(),
        NEXT_TEMP.fetch_add(1, Ordering::Relaxed)
    ));
    let temporary = parent.join(temporary_name);
    let mut file = std::fs::OpenOptions::new()
        .write(true)
        .create_new(true)
        .open(&temporary)?;
    if let Err(error) = file.write_all(bytes) {
        drop(file);
        let _ = std::fs::remove_file(&temporary);
        return Err(error);
    }
    drop(file);
    publish_new(&temporary, path)
}

fn publish_new(temporary: &Path, path: &Path) -> io::Result<bool> {
    let published = std::fs::hard_link(temporary, path);
    let cleanup = std::fs::remove_file(temporary);
    match published {
        Ok(()) => {
            cleanup?;
            Ok(true)
        }
        Err(error) if error.kind() == io::ErrorKind::AlreadyExists => {
            cleanup?;
            Ok(false)
        }
        Err(error) => Err(io::Error::new(
            error.kind(),
            format!(
                "cannot safely publish a new sidecar (filesystem hard links required): {error}"
            ),
        )),
    }
}

/// Saves the catalog atomically, after preserving its independent conclusions.
///
/// The caller must hold the data-directory writer lock for the whole
/// read/modify/save operation. Legacy conclusions are migrated here, not by
/// readers; the legacy catalog stays untouched if the migration fails.
pub fn save(catalog: &Catalog, path: &Path) -> Result<(), StoreError> {
    let conclusions_path = conclusions::conclusions_path(path.parent().unwrap_or(Path::new(".")));
    let existing = conclusions::load(&conclusions_path)?;
    let had_store = existing.is_some();
    let mut gathered = existing.unwrap_or_default();
    if !had_store {
        // Keep conclusions for files absent from the new scan, too. An
        // incompatible catalog remains rebuildable; other read errors must
        // not hide data that this write would otherwise discard.
        match load_catalog_only(path) {
            Ok(Some(legacy)) => {
                gathered.merge_legacy(&legacy);
            }
            Ok(None) | Err(StoreError::Version { .. }) => {}
            Err(error) => return Err(error),
        }
    }
    gathered.update_from_catalog(catalog);
    if had_store
        || !gathered.files.is_empty()
        || !gathered.analyses.is_empty()
        || !gathered.loudness_tracks.is_empty()
        || !gathered.loudness_programmes.is_empty()
    {
        conclusions::save(&gathered, &conclusions_path)?;
    }
    save_catalog_only(catalog, path)
}

/// Writes only the rebuildable catalog, for a restore that handles each store independently.
pub fn save_catalog_only(catalog: &Catalog, path: &Path) -> Result<(), StoreError> {
    crate::atomic_file::write(path, to_json(catalog).to_string_compact().as_bytes())?;
    Ok(())
}

/// Loads a catalog without writing anything, including during legacy migration.
/// Returns `Ok(None)` if the file does not exist yet.
pub fn load(path: &Path) -> Result<Option<Catalog>, StoreError> {
    let Some(mut catalog) = load_catalog_only(path)? else {
        return Ok(None);
    };
    let conclusions_path = conclusions::conclusions_path(path.parent().unwrap_or(Path::new(".")));
    let existing = conclusions::load(&conclusions_path)?;
    let missing = existing.is_none();
    let mut gathered = existing.unwrap_or_default();
    if missing {
        gathered.merge_legacy(&catalog);
    }
    gathered.attach(&mut catalog);
    Ok(Some(catalog))
}

/// Reads the catalog snapshot without loading independent conclusions.
///
/// Backups handle each store separately: an unreadable conclusions document
/// must not hide an otherwise readable catalog. Legacy inline conclusions stay
/// available to the caller for migration. Ordinary catalog consumers should use
/// [`load`] to attach the current independent results.
pub fn load_catalog_only(path: &Path) -> Result<Option<Catalog>, StoreError> {
    let text = match std::fs::read_to_string(path) {
        Ok(text) => text,
        Err(error) if error.kind() == io::ErrorKind::NotFound => return Ok(None),
        Err(error) => return Err(error.into()),
    };
    let value = json::parse(&text).map_err(StoreError::Parse)?;
    from_json(&value).map(Some)
}

// --------------------------------------------------------------------------
// Serialisation
// --------------------------------------------------------------------------

/// Turns a catalog into its JSON document, one array per table.
///
/// Exposed apart from [`save`] so callers can inspect or divert the document
/// without writing it. The result carries the current [`FORMAT_VERSION`], so a
/// round trip through [`from_json`] is always accepted.
pub fn to_json(catalog: &Catalog) -> Json {
    let mut root = Json::obj();
    root.set("format_version", FORMAT_VERSION.into());
    root.set("relation_rules", model::RELATION_RULES.into());
    root.set("scanned_at", catalog.scanned_at.into());
    root.set(
        "excluded",
        Json::Arr(
            catalog
                .excluded
                .iter()
                .map(|f| Json::from(f.as_str()))
                .collect(),
        ),
    );
    root.set(
        "roots",
        Json::Arr(catalog.roots.iter().map(|r| Json::Str(r.clone())).collect()),
    );

    root.set(
        "file",
        Json::Arr(
            catalog
                .files
                .iter()
                .map(|file| {
                    let mut row = file_to_json(file);
                    if let Some(fraction) = catalog.file_mtime_subseconds.get(&file.path) {
                        row.set("mtime_subseconds", (*fraction).into());
                    }
                    if let Some(added) = catalog.file_added_at.get(&file.path) {
                        row.set("added_at", (*added).into());
                    }
                    row
                })
                .collect(),
        ),
    );
    root.set("artist", array(&catalog.artists, artist_to_json));
    root.set("release", array(&catalog.releases, release_to_json));
    root.set(
        "release_group",
        array(&catalog.release_groups, release_group_to_json),
    );
    root.set("track", array(&catalog.tracks, track_to_json));
    root.set("recording", array(&catalog.recordings, recording_to_json));
    root.set("work", array(&catalog.works, work_to_json));
    root.set("label", array(&catalog.labels, label_to_json));
    root.set("genre", array(&catalog.genres, genre_to_json));
    root.set("credit", array(&catalog.credits, credit_to_json));
    root.set("relation", array(&catalog.relations, relation_to_json));
    root.set(
        "genre_link",
        array(&catalog.genre_links, genre_link_to_json),
    );
    root
}

fn array<T>(items: &[T], f: impl Fn(&T) -> Json) -> Json {
    Json::Arr(items.iter().map(f).collect())
}

fn opt_str(value: &Option<String>) -> Json {
    match value {
        Some(s) => Json::Str(s.clone()),
        None => Json::Null,
    }
}

fn opt_num<T: Into<Json> + Copy>(value: &Option<T>) -> Json {
    match value {
        Some(v) => (*v).into(),
        None => Json::Null,
    }
}

fn file_to_json(file: &AudioFile) -> Json {
    let mut o = Json::obj();
    o.set("id", file.id.into());
    o.set("path", file.path.clone().into());
    o.set("size", file.size.into());
    o.set("mtime", file.mtime.into());
    o.set("codec", file.properties.codec.clone().into());
    o.set("container", file.properties.container.clone().into());
    o.set("sample_rate", opt_num(&file.properties.sample_rate));
    o.set(
        "bit_depth",
        opt_num(&file.properties.bit_depth.map(u32::from)),
    );
    o.set(
        "channels",
        opt_num(&file.properties.channels.map(u32::from)),
    );
    o.set("duration_ms", opt_num(&file.properties.duration_ms));
    o.set("bitrate_kbps", opt_num(&file.properties.bitrate_kbps));
    o.set("lossless", file.properties.lossless.into());
    o.set("has_embedded_art", file.has_embedded_art.into());
    o.set("lyrics_path", opt_str(&file.lyrics_path));

    let mut tags = Json::obj();
    for (key, values) in &file.tags {
        tags.set(
            key,
            Json::Arr(values.iter().map(|v| Json::Str(v.clone())).collect()),
        );
    }
    o.set("tags", tags);

    o
}

/// An imported analysis, field for field.
///
/// Absent measurements are written as `null` rather than left out: the reader
/// then distinguishes "not measured" from "measured as zero", which for a peak
/// or a dynamic range is the whole difference.
/// Serializes an attributed analysis without dropping unknown source data.
///
/// Dated rows retain the legacy numeric `result_at_ns` and an additive decimal
/// `result_at_ns_exact` for precision beyond the JSON model's `f64` range.
pub fn analysis_to_json(a: &FileAnalysis) -> Json {
    let mut o = Json::obj();
    o.set("path", a.path.clone().into());
    o.set("source", a.source.clone().into());
    o.set("source_version", a.source_version.into());
    o.set("imported_at", a.imported_at.into());
    o.set("result_at_ns", a.result_at_ns.into());
    if a.result_at_ns != 0 {
        // Keep the legacy numeric field for older readers. Nanosecond dates
        // exceed the JSON model's exact f64 integer range.
        o.set("result_at_ns_exact", a.result_at_ns.to_string().into());
    }
    o.set("size_bytes", a.size_bytes.into());
    o.set("modified_unix", a.modified_unix.into());
    o.set("file_md5", opt_str(&a.file_md5));
    o.set("source_data", a.source_data.clone().unwrap_or(Json::Null));
    o.set("md5_state", opt_str(&a.md5_state));
    o.set("md5_detail", opt_str(&a.md5_detail));
    o.set("real_bit_depth", opt_num(&a.real_bit_depth.map(u32::from)));
    o.set("requant_rate", opt_float(&a.requant_rate));
    o.set("fake_stereo", opt_bool(&a.fake_stereo));
    o.set("ext_mismatch", opt_bool(&a.ext_mismatch));
    o.set("transcoding", opt_str(&a.transcoding));
    o.set("upscaling", opt_bool(&a.upscaling));
    o.set("upsampling", opt_bool(&a.upsampling));
    o.set("summary", opt_str(&a.summary));
    o.set("detail", opt_str(&a.detail));
    o.set("cutoff_hz", opt_float(&a.cutoff_hz));
    o.set("cutoff_ratio", opt_float(&a.cutoff_ratio));
    o.set("dr_db", opt_float(&a.dr_db));
    o.set("peak_dbfs", opt_float(&a.peak_dbfs));
    o.set("true_peak_dbtp", opt_float(&a.true_peak_dbtp));
    o.set("integrated_lufs", opt_float(&a.integrated_lufs));
    o.set("clipped_samples", opt_num(&a.clipped_samples));
    o.set("clip_events", opt_num(&a.clip_events));
    o.set("clipped", opt_bool(&a.clipped));
    o.set("error", opt_str(&a.error));
    o
}

pub(crate) fn analysis_from_json(item: &Json) -> Result<FileAnalysis, StoreError> {
    let path = item
        .field_str("path")
        .filter(|path| !path.is_empty())
        .ok_or(StoreError::Invalid("analysis without path"))?;
    // Missing/null optional measurements are legacy-compatible. A present
    // value of the wrong type must not be lost on the next protected save.
    stored_fields(
        item,
        &[
            "source",
            "file_md5",
            "md5_state",
            "md5_detail",
            "transcoding",
            "summary",
            "detail",
            "error",
        ],
        |value| value.as_str().is_some(),
        "invalid stored analysis field",
    )?;
    stored_fields(
        item,
        &[
            "imported_at",
            "size_bytes",
            "modified_unix",
            "clipped_samples",
            "clip_events",
        ],
        |value| value.as_u64().is_some(),
        "invalid stored analysis field",
    )?;
    stored_fields(
        item,
        &["source_version"],
        |value| value.as_u32().is_some(),
        "invalid stored analysis field",
    )?;
    stored_fields(
        item,
        &["real_bit_depth"],
        |value| {
            value
                .as_u32()
                .is_some_and(|depth| u16::try_from(depth).is_ok())
        },
        "invalid stored analysis field",
    )?;
    stored_fields(
        item,
        &[
            "requant_rate",
            "cutoff_hz",
            "cutoff_ratio",
            "dr_db",
            "peak_dbfs",
            "true_peak_dbtp",
            "integrated_lufs",
        ],
        |value| value.as_f64().is_some_and(f64::is_finite),
        "invalid stored analysis field",
    )?;
    stored_fields(
        item,
        &[
            "fake_stereo",
            "ext_mismatch",
            "upscaling",
            "upsampling",
            "clipped",
        ],
        |value| value.as_bool().is_some(),
        "invalid stored analysis field",
    )?;
    stored_fields(
        item,
        &["source_data"],
        |value| matches!(value, Json::Obj(_)),
        "invalid stored analysis field",
    )?;
    Ok(FileAnalysis {
        path,
        source: item.field_str("source").unwrap_or_default(),
        source_version: item.field_u32("source_version").unwrap_or(0),
        imported_at: item.field_u64("imported_at").unwrap_or(0),
        result_at_ns: analysis_result_date(item)?,
        size_bytes: item.field_u64("size_bytes").unwrap_or(0),
        modified_unix: item.field_u64("modified_unix").unwrap_or(0),
        file_md5: item.field_str("file_md5"),
        source_data: item
            .get("source_data")
            .filter(|value| matches!(value, Json::Obj(_)))
            .cloned(),
        md5_state: item.field_str("md5_state"),
        md5_detail: item.field_str("md5_detail"),
        real_bit_depth: item
            .field_u32("real_bit_depth")
            .and_then(|v| u16::try_from(v).ok()),
        requant_rate: item.field_f64("requant_rate"),
        fake_stereo: item.field_optional_bool("fake_stereo"),
        ext_mismatch: item.field_optional_bool("ext_mismatch"),
        transcoding: item.field_str("transcoding"),
        upscaling: item.field_optional_bool("upscaling"),
        upsampling: item.field_optional_bool("upsampling"),
        summary: item.field_str("summary"),
        detail: item.field_str("detail"),
        cutoff_hz: item.field_f64("cutoff_hz"),
        cutoff_ratio: item.field_f64("cutoff_ratio"),
        dr_db: item.field_f64("dr_db"),
        peak_dbfs: item.field_f64("peak_dbfs"),
        true_peak_dbtp: item.field_f64("true_peak_dbtp"),
        integrated_lufs: item.field_f64("integrated_lufs"),
        clipped_samples: item.field_u64("clipped_samples"),
        clip_events: item.field_u64("clip_events"),
        clipped: item.field_optional_bool("clipped"),
        error: item.field_str("error"),
    })
}

fn stored_fields(
    item: &Json,
    fields: &[&str],
    valid: impl Fn(&Json) -> bool,
    message: &'static str,
) -> Result<(), StoreError> {
    if fields.iter().any(|field| {
        item.get(field)
            .is_some_and(|value| *value != Json::Null && !valid(value))
    }) {
        return Err(StoreError::Invalid(message));
    }
    Ok(())
}

fn analysis_result_date(item: &Json) -> Result<u64, StoreError> {
    let invalid = || StoreError::Invalid("invalid analysis result date");
    if let Some(exact) = item.get("result_at_ns_exact") {
        let date = exact
            .as_str()
            .filter(|text| !text.is_empty() && text.bytes().all(|byte| byte.is_ascii_digit()))
            .and_then(|text| text.parse::<u64>().ok())
            .ok_or_else(invalid)?;
        if item.field_f64("result_at_ns") != Some(date as f64) {
            return Err(invalid());
        }
        return Ok(date);
    }
    match item.get("result_at_ns") {
        None | Some(Json::Null) => Ok(0),
        Some(value) => value.as_u64().ok_or_else(invalid),
    }
}

fn opt_bool(value: &Option<bool>) -> Json {
    match value {
        Some(v) => (*v).into(),
        None => Json::Null,
    }
}

fn opt_float(value: &Option<f64>) -> Json {
    match value {
        Some(v) => (*v).into(),
        None => Json::Null,
    }
}

fn artist_to_json(a: &Artist) -> Json {
    let mut o = Json::obj();
    o.set("id", a.id.into());
    o.set("name", a.name.clone().into());
    o.set("sort_name", a.sort_name.clone().into());
    o.set("key", a.key.clone().into());
    o.set("mbid", opt_str(&a.mbid));
    // Written only when there are any: an empty array on every artist of a
    // library that has never been merged is a quarter of a megabyte of `[]`.
    if !a.aliases.is_empty() {
        o.set(
            "aliases",
            Json::Arr(a.aliases.iter().map(|s| s.clone().into()).collect()),
        );
    }
    o
}

fn release_to_json(r: &Release) -> Json {
    let mut o = Json::obj();
    o.set("id", r.id.into());
    o.set("title", r.title.clone().into());
    o.set("key", r.key.clone().into());
    o.set("album_artist_id", opt_num(&r.album_artist_id));
    o.set("date", opt_str(&r.date));
    o.set("year", opt_num(&r.year));
    o.set(
        "label_ids",
        Json::Arr(r.label_ids.iter().map(|&id| Json::Num(id as f64)).collect()),
    );
    o.set("catalog_number", opt_str(&r.catalog_number));
    o.set("barcode", opt_str(&r.barcode));
    o.set("media", opt_str(&r.media));
    o.set("mbid", opt_str(&r.mbid));
    o.set("release_group_mbid", opt_str(&r.release_group_mbid));
    o.set("release_group_id", opt_num(&r.release_group_id));
    o.set("is_compilation", r.is_compilation.into());
    o.set("folder", r.folder.clone().into());
    o.set("cover_path", opt_str(&r.cover_path));
    o.set(
        "track_ids",
        Json::Arr(r.track_ids.iter().map(|&id| Json::Num(id as f64)).collect()),
    );
    o
}

fn work_to_json(work: &Work) -> Json {
    let mut o = Json::obj();
    o.set("id", work.id.into());
    o.set("title", work.title.clone().into());
    o.set("key", work.key.clone().into());
    o.set("mbid", work.mbid.clone().into());
    o.set(
        "recording_ids",
        Json::Arr(
            work.recording_ids
                .iter()
                .map(|&id| Json::Num(id as f64))
                .collect(),
        ),
    );
    o
}

fn release_group_to_json(group: &ReleaseGroup) -> Json {
    let mut o = Json::obj();
    o.set("id", group.id.into());
    o.set("title", group.title.clone().into());
    o.set("key", group.key.clone().into());
    o.set("mbid", group.mbid.clone().into());
    o.set(
        "release_ids",
        Json::Arr(
            group
                .release_ids
                .iter()
                .map(|&id| Json::Num(id as f64))
                .collect(),
        ),
    );
    o
}

fn track_to_json(t: &Track) -> Json {
    let mut o = Json::obj();
    o.set("id", t.id.into());
    o.set("file_id", t.file_id.into());
    o.set("release_id", opt_num(&t.release_id));
    o.set("recording_id", t.recording_id.into());
    o.set("title", t.title.clone().into());
    o.set("disc_no", opt_num(&t.disc_no));
    o.set("track_no", opt_num(&t.track_no));
    o.set("duration_ms", opt_num(&t.duration_ms));
    o.set("isrc", opt_str(&t.isrc));
    o.set("mbid", opt_str(&t.mbid));
    o
}

fn recording_to_json(recording: &Recording) -> Json {
    let mut o = Json::obj();
    o.set("id", recording.id.into());
    o.set("title", recording.title.clone().into());
    o.set("key", recording.key.clone().into());
    o.set("isrc", opt_str(&recording.isrc));
    o.set("mbid", opt_str(&recording.mbid));
    o.set(
        "track_ids",
        Json::Arr(
            recording
                .track_ids
                .iter()
                .map(|&id| Json::Num(id as f64))
                .collect(),
        ),
    );
    o.set(
        "work_ids",
        Json::Arr(
            recording
                .work_ids
                .iter()
                .map(|&id| Json::Num(id as f64))
                .collect(),
        ),
    );
    o
}

fn label_to_json(l: &Label) -> Json {
    let mut o = Json::obj();
    o.set("id", l.id.into());
    o.set("name", l.name.clone().into());
    o.set("key", l.key.clone().into());
    o.set("mbid", opt_str(&l.mbid));
    o
}

fn genre_to_json(g: &Genre) -> Json {
    let mut o = Json::obj();
    o.set("id", g.id.into());
    o.set("name", g.name.clone().into());
    o.set("key", g.key.clone().into());
    o
}

fn credit_to_json(c: &Credit) -> Json {
    let mut o = Json::obj();
    o.set("artist_id", c.artist_id.into());
    o.set("entity_kind", c.entity_kind.as_str().into());
    o.set("entity_id", c.entity_id.into());
    o.set("role", c.role.clone().into());
    o.set("credited_as", opt_str(&c.credited_as));
    o.set(
        "attributes",
        Json::Arr(
            c.attributes
                .iter()
                .map(|attribute| {
                    let mut row = Json::obj();
                    row.set("id", opt_str(&attribute.id));
                    row.set("name", attribute.name.clone().into());
                    row.set("value", opt_str(&attribute.value));
                    row.set("credited_as", opt_str(&attribute.credited_as));
                    row
                })
                .collect(),
        ),
    );
    o.set("began", opt_str(&c.began));
    o.set("ended", opt_str(&c.ended));
    o.set("order", opt_num(&c.order));
    o.set("source", c.source.clone().into());
    o.set("source_id", opt_str(&c.source_id));
    o
}

fn relation_to_json(r: &Relation) -> Json {
    let mut o = Json::obj();
    o.set("source_kind", r.source_kind.as_str().into());
    o.set("source_id", r.source_id.into());
    o.set("target_kind", r.target_kind.as_str().into());
    o.set("target_id", r.target_id.into());
    o.set("kind", r.kind.clone().into());
    o.set("weight", r.weight.into());
    o.set("source", r.source.clone().into());
    o
}

fn genre_link_to_json(g: &GenreLink) -> Json {
    let mut o = Json::obj();
    o.set("genre_id", g.genre_id.into());
    o.set("entity_kind", g.entity_kind.as_str().into());
    o.set("entity_id", g.entity_id.into());
    o
}

// --------------------------------------------------------------------------
// Deserialisation
// --------------------------------------------------------------------------

/// Rebuilds a catalog from its JSON document.
///
/// The version is checked before anything else, so an old file is rejected
/// rather than half-decoded. Identifiers are then verified to be contiguous:
/// the model indexes entities by position, and a gap would silently shift
/// every relation. Present tables, lists and polymorphic references must be
/// well formed; absent optional legacy fields retain their migration defaults.
/// Optional audio precision/channel counts accept absence or `null`, but
/// present values must be integral `u16` values rather than truncated numbers.
/// Known file scalars and tag tables must have their declared JSON types;
/// malformed values cannot be rewritten as empty/default file metadata.
pub fn from_json(value: &Json) -> Result<Catalog, StoreError> {
    let version = value.field_u32("format_version").unwrap_or(0);
    if version != FORMAT_VERSION {
        return Err(StoreError::Version {
            found: version,
            expected: FORMAT_VERSION,
        });
    }

    for table in [
        "roots",
        "excluded",
        "file",
        "artist",
        "release",
        "release_group",
        "track",
        "recording",
        "work",
        "label",
        "genre",
        "credit",
        "relation",
        "genre_link",
        "analysis",
    ] {
        if value.get(table).is_some_and(|rows| rows.as_arr().is_none()) {
            return Err(StoreError::Invalid("catalog tables must be arrays"));
        }
    }

    let mut catalog = Catalog {
        scanned_at: value.field_u64("scanned_at").unwrap_or(0),
        roots: string_list(value.get("roots"))?,
        // Absent from a file written before exclusions existed, which reads as
        // "nothing excluded" — the behaviour that file was saved with.
        excluded: string_list(value.get("excluded"))?,
        ..Default::default()
    };
    // Relations inferred under older rules are stale, not wrong: they are
    // recomputed below rather than refused, so that upgrading Aède never costs
    // a rescan — nor the integrity verdicts a rescan would keep but a rebuilt
    // catalog would not.
    let stale_relations = value.field_u32("relation_rules").unwrap_or(0) != model::RELATION_RULES;

    for item in rows(value, "file") {
        let file = file_from_json(item)?;
        if let Some(fraction) = item.field_u32("mtime_subseconds") {
            if fraction >= 1_000_000_000 {
                return Err(StoreError::Invalid(
                    "file modification fraction out of range",
                ));
            }
            catalog
                .file_mtime_subseconds
                .insert(file.path.clone(), fraction);
        } else if item.get("mtime_subseconds").is_some() {
            return Err(StoreError::Invalid("invalid file modification fraction"));
        }
        if let Some(added) = item.field_u64("added_at") {
            catalog.file_added_at.insert(file.path.clone(), added);
        } else if item.get("added_at").is_some() {
            return Err(StoreError::Invalid("invalid file catalog date"));
        }
        catalog.files.push(file);
    }
    for item in rows(value, "artist") {
        catalog.artists.push(Artist {
            id: item
                .field_u32("id")
                .ok_or(StoreError::Invalid("artist without identifier"))?,
            name: item.field_str("name").unwrap_or_default(),
            sort_name: item.field_str("sort_name").unwrap_or_default(),
            key: item.field_str("key").unwrap_or_default(),
            mbid: item.field_str("mbid"),
            aliases: string_list(item.get("aliases"))?,
        });
    }
    for item in rows(value, "release") {
        catalog.releases.push(Release {
            id: item
                .field_u32("id")
                .ok_or(StoreError::Invalid("release without identifier"))?,
            title: item.field_str("title").unwrap_or_default(),
            key: item.field_str("key").unwrap_or_default(),
            album_artist_id: item.field_u32("album_artist_id"),
            date: item.field_str("date"),
            year: item.field_u32("year"),
            label_ids: id_list(item.get("label_ids"))?,
            catalog_number: item.field_str("catalog_number"),
            barcode: item.field_str("barcode"),
            media: item.field_str("media"),
            mbid: item.field_str("mbid"),
            release_group_mbid: item.field_str("release_group_mbid"),
            release_group_id: item.field_u32("release_group_id"),
            is_compilation: item.field_bool("is_compilation"),
            folder: item.field_str("folder").unwrap_or_default(),
            cover_path: item.field_str("cover_path"),
            track_ids: id_list(item.get("track_ids"))?,
        });
    }
    for item in rows(value, "release_group") {
        catalog.release_groups.push(ReleaseGroup {
            id: item
                .field_u32("id")
                .ok_or(StoreError::Invalid("release group without identifier"))?,
            title: item.field_str("title").unwrap_or_default(),
            key: item.field_str("key").unwrap_or_default(),
            mbid: item.field_str("mbid").unwrap_or_default(),
            release_ids: id_list(item.get("release_ids"))?,
        });
    }
    if catalog.release_groups.is_empty() {
        rebuild_legacy_release_groups(&mut catalog);
    }
    for item in rows(value, "track") {
        catalog.tracks.push(Track {
            id: item
                .field_u32("id")
                .ok_or(StoreError::Invalid("track without identifier"))?,
            file_id: item
                .field_u32("file_id")
                .ok_or(StoreError::Invalid("track without file"))?,
            release_id: item.field_u32("release_id"),
            // Catalogs written before recordings existed gain their canonical
            // rows below. Their track ids were dense already, so each one is
            // a valid temporary local recording id during that migration.
            recording_id: item
                .field_u32("recording_id")
                .unwrap_or_else(|| item.field_u32("id").unwrap_or(0)),
            title: item.field_str("title").unwrap_or_default(),
            disc_no: item.field_u32("disc_no"),
            track_no: item.field_u32("track_no"),
            duration_ms: item.field_u64("duration_ms"),
            isrc: item.field_str("isrc"),
            mbid: item.field_str("mbid"),
        });
    }
    for item in rows(value, "recording") {
        catalog.recordings.push(Recording {
            id: item
                .field_u32("id")
                .ok_or(StoreError::Invalid("recording without identifier"))?,
            title: item.field_str("title").unwrap_or_default(),
            key: item.field_str("key").unwrap_or_default(),
            isrc: item.field_str("isrc"),
            mbid: item.field_str("mbid"),
            track_ids: id_list(item.get("track_ids"))?,
            work_ids: id_list(item.get("work_ids"))?,
        });
    }
    if catalog.recordings.is_empty() && !catalog.tracks.is_empty() {
        rebuild_legacy_recordings(&mut catalog);
    }
    for item in rows(value, "work") {
        catalog.works.push(Work {
            id: item
                .field_u32("id")
                .ok_or(StoreError::Invalid("work without identifier"))?,
            title: item.field_str("title").unwrap_or_default(),
            key: item.field_str("key").unwrap_or_default(),
            mbid: item
                .field_str("mbid")
                .ok_or(StoreError::Invalid("work without MusicBrainz identifier"))?,
            recording_ids: id_list(item.get("recording_ids"))?,
        });
    }
    for item in rows(value, "label") {
        catalog.labels.push(Label {
            id: item
                .field_u32("id")
                .ok_or(StoreError::Invalid("label without identifier"))?,
            name: item.field_str("name").unwrap_or_default(),
            key: item.field_str("key").unwrap_or_default(),
            mbid: item.field_str("mbid"),
        });
    }
    for item in rows(value, "genre") {
        catalog.genres.push(Genre {
            id: item
                .field_u32("id")
                .ok_or(StoreError::Invalid("genre without identifier"))?,
            name: item.field_str("name").unwrap_or_default(),
            key: item.field_str("key").unwrap_or_default(),
        });
    }
    for item in rows(value, "credit") {
        let kind = item
            .field_str("entity_kind")
            .and_then(|s| EntityKind::parse_kind(&s))
            .ok_or(StoreError::Invalid("credit without a valid entity kind"))?;
        catalog.credits.push(Credit {
            artist_id: item
                .field_u32("artist_id")
                .ok_or(StoreError::Invalid("credit without artist identifier"))?,
            entity_kind: kind,
            entity_id: item
                .field_u32("entity_id")
                .ok_or(StoreError::Invalid("credit without entity identifier"))?,
            role: item.field_str("role").unwrap_or_default(),
            credited_as: item.field_str("credited_as"),
            attributes: item
                .get("attributes")
                .and_then(Json::as_arr)
                .map(|rows| {
                    rows.iter()
                        .filter_map(|row| {
                            Some(model::CreditAttribute {
                                id: row.field_str("id"),
                                name: row.field_str("name")?,
                                value: row.field_str("value"),
                                credited_as: row.field_str("credited_as"),
                            })
                        })
                        .collect()
                })
                .unwrap_or_default(),
            began: item.field_str("began"),
            ended: item.field_str("ended"),
            order: item.field_u32("order"),
            source: item
                .field_str("source")
                .unwrap_or_else(|| "tags".to_string()),
            source_id: item.field_str("source_id"),
        });
    }
    for item in rows(value, "relation") {
        let source_kind = item
            .field_str("source_kind")
            .and_then(|s| EntityKind::parse_kind(&s))
            .ok_or(StoreError::Invalid("relation without a valid source kind"))?;
        let target_kind = item
            .field_str("target_kind")
            .and_then(|s| EntityKind::parse_kind(&s))
            .ok_or(StoreError::Invalid("relation without a valid target kind"))?;
        catalog.relations.push(Relation {
            source_kind,
            source_id: item
                .field_u32("source_id")
                .ok_or(StoreError::Invalid("relation without source identifier"))?,
            target_kind,
            target_id: item
                .field_u32("target_id")
                .ok_or(StoreError::Invalid("relation without target identifier"))?,
            kind: item.field_str("kind").unwrap_or_default(),
            weight: item.field_u32("weight").unwrap_or(1),
            source: item.field_str("source").unwrap_or_default(),
        });
    }
    for item in rows(value, "genre_link") {
        let kind = item
            .field_str("entity_kind")
            .and_then(|s| EntityKind::parse_kind(&s))
            .ok_or(StoreError::Invalid(
                "genre link without a valid entity kind",
            ))?;
        catalog.genre_links.push(GenreLink {
            genre_id: item
                .field_u32("genre_id")
                .ok_or(StoreError::Invalid("genre link without genre identifier"))?,
            entity_kind: kind,
            entity_id: item
                .field_u32("entity_id")
                .ok_or(StoreError::Invalid("genre link without entity identifier"))?,
        });
    }

    for item in rows(value, "analysis") {
        catalog.analyses.push(analysis_from_json(item)?);
    }

    verify_integrity(&catalog)?;
    if stale_relations {
        model::rebuild_relations(&mut catalog);
    }
    for relation in &catalog.relations {
        if !entity_exists(&catalog, relation.source_kind, relation.source_id)
            || !entity_exists(&catalog, relation.target_kind, relation.target_id)
        {
            return Err(StoreError::Invalid("relation attached to a missing entity"));
        }
    }
    Ok(catalog)
}

/// The `Vec`s are indexed by identifier: we check that the file read back
/// respects that invariant before handing it to the rest of the program.
fn verify_integrity(catalog: &Catalog) -> Result<(), StoreError> {
    // Validated reverse entries prove their forward membership in linear time,
    // including albums or recordings with many placements.
    let mut tracks_in_releases = vec![false; catalog.tracks.len()];
    let mut tracks_in_recordings = vec![false; catalog.tracks.len()];
    let mut releases_in_groups = vec![false; catalog.releases.len()];
    // A frequently performed work can link thousands of recordings. Walking
    // that full list for each reverse reference would make loading quadratic.
    let work_recordings: Vec<std::collections::HashSet<&Id>> = catalog
        .works
        .iter()
        .map(|work| work.recording_ids.iter().collect())
        .collect();
    let mut file_paths = std::collections::HashSet::new();
    for (index, file) in catalog.files.iter().enumerate() {
        if file.id as usize != index {
            return Err(StoreError::Invalid("non-contiguous file identifiers"));
        }
        if !file_paths.insert(file.path.as_str()) {
            return Err(StoreError::Invalid("duplicate file path"));
        }
    }
    for (index, artist) in catalog.artists.iter().enumerate() {
        if artist.id as usize != index {
            return Err(StoreError::Invalid("non-contiguous artist identifiers"));
        }
    }
    for (index, release) in catalog.releases.iter().enumerate() {
        if release.id as usize != index {
            return Err(StoreError::Invalid("non-contiguous release identifiers"));
        }
        if release
            .album_artist_id
            .is_some_and(|id| id as usize >= catalog.artists.len())
        {
            return Err(StoreError::Invalid("release attached to a missing artist"));
        }
        if release
            .label_ids
            .iter()
            .any(|&id| id as usize >= catalog.labels.len())
        {
            return Err(StoreError::Invalid("release attached to a missing label"));
        }
        for &id in &release.track_ids {
            if catalog
                .track(id)
                .is_none_or(|track| track.release_id != Some(release.id))
            {
                return Err(StoreError::Invalid("release attached to a missing track"));
            }
            tracks_in_releases[id as usize] = true;
        }
        if release
            .release_group_id
            .is_some_and(|id| id as usize >= catalog.release_groups.len())
        {
            return Err(StoreError::Invalid(
                "release attached to a missing release group",
            ));
        }
    }
    for (index, group) in catalog.release_groups.iter().enumerate() {
        if group.id as usize != index {
            return Err(StoreError::Invalid(
                "non-contiguous release group identifiers",
            ));
        }
        for &id in &group.release_ids {
            if catalog
                .releases
                .get(id as usize)
                .is_none_or(|release| release.release_group_id != Some(group.id))
            {
                return Err(StoreError::Invalid(
                    "release group attached to a missing release",
                ));
            }
            releases_in_groups[id as usize] = true;
        }
    }
    if catalog
        .releases
        .iter()
        .enumerate()
        .any(|(index, release)| release.release_group_id.is_some() && !releases_in_groups[index])
    {
        return Err(StoreError::Invalid("release absent from its release group"));
    }
    for (index, track) in catalog.tracks.iter().enumerate() {
        if track.id as usize != index {
            return Err(StoreError::Invalid("non-contiguous track identifiers"));
        }
        if track.file_id as usize >= catalog.files.len() {
            return Err(StoreError::Invalid("track attached to a missing file"));
        }
        if track.recording_id as usize >= catalog.recordings.len() {
            return Err(StoreError::Invalid("track attached to a missing recording"));
        }
        if track
            .release_id
            .is_some_and(|id| id as usize >= catalog.releases.len())
        {
            return Err(StoreError::Invalid("track attached to a missing release"));
        }
        if track.release_id.is_some() && !tracks_in_releases[index] {
            return Err(StoreError::Invalid("track absent from its release"));
        }
    }
    for (index, recording) in catalog.recordings.iter().enumerate() {
        if recording.id as usize != index {
            return Err(StoreError::Invalid("non-contiguous recording identifiers"));
        }
        for &id in &recording.track_ids {
            if catalog
                .track(id)
                .is_none_or(|track| track.recording_id != recording.id)
            {
                return Err(StoreError::Invalid("recording attached to a missing track"));
            }
            tracks_in_recordings[id as usize] = true;
        }
        if recording.work_ids.iter().any(|&id| {
            work_recordings
                .get(id as usize)
                .is_none_or(|recordings| !recordings.contains(&recording.id))
        }) {
            return Err(StoreError::Invalid("recording attached to a missing work"));
        }
    }
    if tracks_in_recordings.iter().any(|present| !present) {
        return Err(StoreError::Invalid("track absent from its recording"));
    }
    for (index, work) in catalog.works.iter().enumerate() {
        if work.id as usize != index {
            return Err(StoreError::Invalid("non-contiguous work identifiers"));
        }
        if work.mbid.trim().is_empty() {
            return Err(StoreError::Invalid("work without MusicBrainz identifier"));
        }
        if work.recording_ids.iter().any(|&id| {
            catalog
                .recording(id)
                .is_none_or(|recording| !recording.work_ids.contains(&work.id))
        }) {
            return Err(StoreError::Invalid("work attached to a missing recording"));
        }
    }
    for (index, label) in catalog.labels.iter().enumerate() {
        if label.id as usize != index {
            return Err(StoreError::Invalid("non-contiguous label identifiers"));
        }
    }
    for (index, genre) in catalog.genres.iter().enumerate() {
        if genre.id as usize != index {
            return Err(StoreError::Invalid("non-contiguous genre identifiers"));
        }
    }
    for credit in &catalog.credits {
        if credit.artist_id as usize >= catalog.artists.len()
            || !entity_exists(catalog, credit.entity_kind, credit.entity_id)
        {
            return Err(StoreError::Invalid("credit attached to a missing entity"));
        }
    }
    for link in &catalog.genre_links {
        if link.genre_id as usize >= catalog.genres.len()
            || !entity_exists(catalog, link.entity_kind, link.entity_id)
        {
            return Err(StoreError::Invalid("genre attached to a missing entity"));
        }
    }
    Ok(())
}

fn entity_exists(catalog: &Catalog, kind: EntityKind, id: Id) -> bool {
    let length = match kind {
        EntityKind::Artist => catalog.artists.len(),
        EntityKind::Release => catalog.releases.len(),
        EntityKind::ReleaseGroup => catalog.release_groups.len(),
        EntityKind::Track => catalog.tracks.len(),
        EntityKind::Recording => catalog.recordings.len(),
        EntityKind::Work => catalog.works.len(),
        EntityKind::Label => catalog.labels.len(),
        EntityKind::Genre => catalog.genres.len(),
    };
    (id as usize) < length
}

/// Adds groups to a pre-canonical catalog from explicit release-group MBIDs.
fn rebuild_legacy_release_groups(catalog: &mut Catalog) {
    let mut known: BTreeMap<String, Id> = BTreeMap::new();
    for index in 0..catalog.releases.len() {
        let Some(mbid) = catalog.releases[index].release_group_mbid.clone() else {
            continue;
        };
        if mbid.trim().is_empty() {
            continue;
        }
        let group_id = match known.get(&mbid) {
            Some(&id) => id,
            None => {
                let id = catalog.release_groups.len() as Id;
                let release = &catalog.releases[index];
                catalog.release_groups.push(ReleaseGroup {
                    id,
                    title: release.title.clone(),
                    key: release.key.clone(),
                    mbid: mbid.clone(),
                    release_ids: Vec::new(),
                });
                known.insert(mbid, id);
                id
            }
        };
        let release_id = catalog.releases[index].id;
        catalog.releases[index].release_group_id = Some(group_id);
        catalog.release_groups[group_id as usize]
            .release_ids
            .push(release_id);
    }
}

/// Builds recordings for a pre-canonical catalog without title-based claims.
///
/// A recording MBID is explicit enough to join placements. Without it, one
/// legacy placement becomes one local recording and can be joined later only
/// by sourced evidence.
fn rebuild_legacy_recordings(catalog: &mut Catalog) {
    let mut known: BTreeMap<String, Id> = BTreeMap::new();
    for index in 0..catalog.tracks.len() {
        let track = &catalog.tracks[index];
        let key = track
            .mbid
            .as_ref()
            .map(|mbid| format!("mbid:{mbid}"))
            .unwrap_or_else(|| format!("local:{}", track.file_id));
        let recording_id = match known.get(&key) {
            Some(&id) => id,
            None => {
                let id = catalog.recordings.len() as Id;
                catalog.recordings.push(Recording {
                    id,
                    title: track.title.clone(),
                    key: crate::text::normalize(&track.title),
                    isrc: track.isrc.clone(),
                    mbid: track.mbid.clone(),
                    track_ids: Vec::new(),
                    work_ids: Vec::new(),
                });
                known.insert(key, id);
                id
            }
        };
        let track_id = catalog.tracks[index].id;
        catalog.tracks[index].recording_id = recording_id;
        catalog.recordings[recording_id as usize]
            .track_ids
            .push(track_id);
    }
}

fn file_optional_u16(item: &Json, field: &str) -> Result<Option<u16>, StoreError> {
    match item.get(field) {
        None | Some(Json::Null) => Ok(None),
        Some(value) => value
            .as_u32()
            .and_then(|value| u16::try_from(value).ok())
            .map(Some)
            .ok_or(StoreError::Invalid("invalid stored audio property")),
    }
}

fn file_from_json(item: &Json) -> Result<AudioFile, StoreError> {
    stored_fields(
        item,
        &["codec", "container", "lyrics_path"],
        |value| value.as_str().is_some(),
        "invalid stored file field",
    )?;
    stored_fields(
        item,
        &["size", "mtime", "duration_ms"],
        |value| value.as_u64().is_some(),
        "invalid stored file field",
    )?;
    stored_fields(
        item,
        &["sample_rate", "bitrate_kbps"],
        |value| value.as_u32().is_some(),
        "invalid stored file field",
    )?;
    stored_fields(
        item,
        &["lossless", "has_embedded_art"],
        |value| value.as_bool().is_some(),
        "invalid stored file field",
    )?;
    stored_fields(
        item,
        &["tags"],
        |value| matches!(value, Json::Obj(_)),
        "file tags must be an object",
    )?;
    let mut tags: BTreeMap<String, Vec<String>> = BTreeMap::new();
    if let Some(Json::Obj(map)) = item.get("tags") {
        for (key, values) in map {
            tags.insert(key.clone(), string_list(Some(values))?);
        }
    }
    Ok(AudioFile {
        lyrics_path: item.field_str("lyrics_path"),
        id: item
            .field_u32("id")
            .ok_or(StoreError::Invalid("file without identifier"))?,
        path: item
            .field_str("path")
            .ok_or(StoreError::Invalid("file without path"))?,
        size: item.field_u64("size").unwrap_or(0),
        mtime: item.field_u64("mtime").unwrap_or(0),
        properties: AudioProperties {
            codec: item.field_str("codec").unwrap_or_default(),
            container: item.field_str("container").unwrap_or_default(),
            sample_rate: item.field_u32("sample_rate"),
            bit_depth: file_optional_u16(item, "bit_depth")?,
            channels: file_optional_u16(item, "channels")?,
            duration_ms: item.field_u64("duration_ms"),
            bitrate_kbps: item.field_u32("bitrate_kbps"),
            lossless: item.field_bool("lossless"),
        },
        has_embedded_art: item.field_bool("has_embedded_art"),
        tags,
        integrity: integrity_from_json(item.get("integrity")),
        fingerprint: fingerprint_from_json(item.get("fingerprint")),
    })
}

/// Reads back a stored fingerprint, or nothing.
///
/// A row missing either half is read as no fingerprint at all rather than as
/// half of one: the pair is what a lookup needs, and a fingerprint with no
/// length would be sent out as a duration of zero.
pub(crate) fn fingerprint_from_json(
    value: Option<&Json>,
) -> Option<crate::fingerprint::Fingerprint> {
    let value = value?;
    let data = value.field_str("data").filter(|d| !d.is_empty())?;
    let seconds = value.field_u32("seconds").filter(|s| *s > 0)?;
    Some(crate::fingerprint::Fingerprint { data, seconds })
}

/// Reads back a stored verdict; an unknown state is treated as no verdict at
/// all, so a catalog written by a later version degrades instead of failing.
pub(crate) fn integrity_from_json(value: Option<&Json>) -> Option<IntegrityRecord> {
    let value = value?;
    let verdict = match value.field_str("state")?.as_str() {
        "intact" => audit::integrity::Verdict::Intact,
        "nothing_to_check" => audit::integrity::Verdict::NothingToCheck,
        "damaged" => audit::integrity::Verdict::Damaged {
            detail: value.field_str("detail").unwrap_or_default(),
        },
        _ => return None,
    };
    Some(IntegrityRecord {
        verdict,
        method: value.field_str("method").unwrap_or_default(),
        checked_at: value.field_u64("checked_at").unwrap_or(0),
    })
}

fn rows<'a>(value: &'a Json, key: &str) -> &'a [Json] {
    value.get(key).and_then(|v| v.as_arr()).unwrap_or(&[])
}

fn string_list(value: Option<&Json>) -> Result<Vec<String>, StoreError> {
    let Some(value) = value else {
        return Ok(Vec::new());
    };
    value
        .as_arr()
        .ok_or(StoreError::Invalid("string list must be an array"))?
        .iter()
        .map(|item| {
            item.as_string()
                .ok_or(StoreError::Invalid("string list contains a non-string"))
        })
        .collect()
}

fn id_list(value: Option<&Json>) -> Result<Vec<Id>, StoreError> {
    let Some(value) = value else {
        return Ok(Vec::new());
    };
    value
        .as_arr()
        .ok_or(StoreError::Invalid("identifier list must be an array"))?
        .iter()
        .map(|item| {
            item.as_u32().ok_or(StoreError::Invalid(
                "identifier list contains an invalid identifier",
            ))
        })
        .collect()
}

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