@kromatv/sdk 0.1.40-canary.0

package/rust/kroma-db/src/schema/migrations.rs

@@ -0,0 +1,261 @@
+//! Idempotent upgrades applied after the schema on every open.
+
+// Idempotent column additions for databases created before a column existed.
+// `ALTER TABLE … ADD COLUMN` errors with "duplicate column name" once the
+// column is present, which we ignore.
+pub(crate) const MIGRATIONS: &[&str] = &[
+    // The downloads ledger predates its move into this schema; a database
+    // that already carries it is missing the columns added since.
+    "ALTER TABLE downloads ADD COLUMN upgrade INTEGER NOT NULL DEFAULT 0",
+    "ALTER TABLE items ADD COLUMN metadata TEXT",
+    "ALTER TABLE shows ADD COLUMN metadata TEXT",
+    // Per-user permissions for accounts created before they existed.
+    "ALTER TABLE users ADD COLUMN permissions TEXT NOT NULL DEFAULT '[\"playback\"]'",
+    // Full per-file audio-track list (was a single representative track).
+    "ALTER TABLE files ADD COLUMN audio_tracks TEXT NOT NULL DEFAULT '[]'",
+    // Last-seen timestamp for the admin "Membres & partage" activity column.
+    "ALTER TABLE users ADD COLUMN last_seen TEXT",
+    // Per-account preferred UI locale ("fr" | "en"), synced across devices.
+    "ALTER TABLE users ADD COLUMN language TEXT",
+    // Optional profile-lock PIN (PBKDF2 hash, own salt). NULL = no PIN.
+    "ALTER TABLE users ADD COLUMN pin_hash TEXT",
+    // Per-account playback language preferences, synced across devices.
+    // audio_language: preferred audio ISO code (NULL = no preference).
+    // subtitle_language: preferred subtitle ISO code, or "off" (NULL = none).
+    "ALTER TABLE users ADD COLUMN audio_language TEXT",
+    "ALTER TABLE users ADD COLUMN subtitle_language TEXT",
+    // Backstop the app-level username-uniqueness check against a check-then-
+    // write race. Best-effort: on a legacy DB that already holds duplicate
+    // usernames the index creation errors and is ignored (the app check still
+    // covers the common case); fresh/clean DBs gain the hard guarantee.
+    "CREATE UNIQUE INDEX IF NOT EXISTS idx_users_username ON users(username)",
+    // `season_meta` shipped briefly with a `cast` column a reserved SQLite
+    // keyword that breaks unquoted SELECT/INSERT. Rename to `casts`. Errors
+    // ("no such column") once renamed / on fresh DBs, which we ignore.
+    "ALTER TABLE season_meta RENAME COLUMN \"cast\" TO casts",
+    // Keyframe-derived HLS segment tables (infra::hls). `CREATE TABLE IF NOT
+    // EXISTS` is idempotent for DBs created before the table existed.
+    "CREATE TABLE IF NOT EXISTS file_segments (\
+        file_id TEXT PRIMARY KEY REFERENCES files(id) ON DELETE CASCADE,\
+        mtime INTEGER, size INTEGER, version INTEGER NOT NULL,\
+        duration_us INTEGER NOT NULL, v_codec TEXT,\
+        segments TEXT NOT NULL, updated_at INTEGER NOT NULL)",
+    // One-time migration for DBs created before the language-agnostic cache.
+    // Each statement is idempotent, and must run in this order: the backfills
+    // (1, 2) need the old columns/indexes still present to read from.
+    //
+    // 1) Seed `metadata_core.tmdb_id` (+ the other invariant fields) from the
+    //    existing single-language `metadata` blobs, so availability matching can
+    //    move off the json_extract indexes without re-enriching the catalog.
+    "INSERT OR IGNORE INTO metadata_core \
+        (subject_kind,subject_id,tmdb_id,imdb_id,release_date,rating,poster_url,backdrop_url,logo_url,updated_at) \
+     SELECT 'item', id, json_extract(metadata,'$.tmdbId'), json_extract(metadata,'$.imdbId'), \
+        json_extract(metadata,'$.releaseDate'), json_extract(metadata,'$.rating'), \
+        json_extract(metadata,'$.posterUrl'), json_extract(metadata,'$.backdropUrl'), \
+        json_extract(metadata,'$.logoUrl'), CAST(strftime('%s','now') AS INTEGER)*1000 \
+     FROM items WHERE metadata IS NOT NULL AND kind IN ('movie','video')",
+    "INSERT OR IGNORE INTO metadata_core \
+        (subject_kind,subject_id,tmdb_id,imdb_id,release_date,rating,poster_url,backdrop_url,logo_url,updated_at) \
+     SELECT 'show', id, json_extract(metadata,'$.tmdbId'), json_extract(metadata,'$.imdbId'), \
+        json_extract(metadata,'$.releaseDate'), json_extract(metadata,'$.rating'), \
+        json_extract(metadata,'$.posterUrl'), json_extract(metadata,'$.backdropUrl'), \
+        json_extract(metadata,'$.logoUrl'), CAST(strftime('%s','now') AS INTEGER)*1000 \
+     FROM shows WHERE metadata IS NOT NULL",
+    // 2) Backfill the old per-language curated / suggestion columns into the
+    //    generic translation cache BEFORE dropping those columns.
+    "INSERT OR IGNORE INTO translations (subject_kind,subject_id,lang,source,data,updated_at) \
+     SELECT 'curated', key, 'fr', 'llm', json_object('title',title_fr,'reason',reason_fr), \
+        CAST(strftime('%s','now') AS INTEGER)*1000 \
+     FROM curated_sections WHERE title_fr IS NOT NULL OR reason_fr IS NOT NULL",
+    "INSERT OR IGNORE INTO translations (subject_kind,subject_id,lang,source,data,updated_at) \
+     SELECT 'curated', key, 'en', 'llm', json_object('title',title_en,'reason',reason_en), \
+        CAST(strftime('%s','now') AS INTEGER)*1000 \
+     FROM curated_sections WHERE title_en IS NOT NULL OR reason_en IS NOT NULL",
+    "INSERT OR IGNORE INTO translations (subject_kind,subject_id,lang,source,data,updated_at) \
+     SELECT 'suggestion', item_id, 'fr', 'llm', json_object('reason',reason_fr), \
+        CAST(strftime('%s','now') AS INTEGER)*1000 \
+     FROM item_suggestions WHERE reason_fr IS NOT NULL",
+    "INSERT OR IGNORE INTO translations (subject_kind,subject_id,lang,source,data,updated_at) \
+     SELECT 'suggestion', item_id, 'en', 'llm', json_object('reason',reason_en), \
+        CAST(strftime('%s','now') AS INTEGER)*1000 \
+     FROM item_suggestions WHERE reason_en IS NOT NULL",
+    // 3) Retire the json_extract availability indexes (now on metadata_core).
+    "DROP INDEX IF EXISTS idx_items_tmdb",
+    "DROP INDEX IF EXISTS idx_shows_tmdb",
+    // 4) Drop the now-migrated per-language columns (SQLite >= 3.35).
+    "ALTER TABLE curated_sections DROP COLUMN title_fr",
+    "ALTER TABLE curated_sections DROP COLUMN title_en",
+    "ALTER TABLE curated_sections DROP COLUMN reason_fr",
+    "ALTER TABLE curated_sections DROP COLUMN reason_en",
+    "ALTER TABLE item_suggestions DROP COLUMN reason_fr",
+    "ALTER TABLE item_suggestions DROP COLUMN reason_en",
+    // The device's User-Agent captured when its access token is minted, so the
+    // account's session list can label each device.
+    "ALTER TABLE access_tokens ADD COLUMN user_agent TEXT",
+    // The parent access token a session was minted from, so the account can
+    // tell which listed device is the one making the current request.
+    "ALTER TABLE sessions ADD COLUMN access_token TEXT",
+    // One row per registered authenticator. `id` is the credential id
+    // (base64url); `credential` is the serialized webauthn-rs `Passkey` (JSON).
+    "CREATE TABLE IF NOT EXISTS passkeys (\
+        id          TEXT PRIMARY KEY,\
+        user_id     TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,\
+        name        TEXT NOT NULL,\
+        credential  TEXT NOT NULL,\
+        created_at  TEXT NOT NULL,\
+        last_used   TEXT)",
+    "CREATE INDEX IF NOT EXISTS idx_passkeys_user ON passkeys(user_id)",
+    // Earliest auto-retry time for a failed pipeline task (exponential backoff
+    // between attempts, so a manually re-kicked stage doesn't hammer a flaky
+    // dependency).
+    "ALTER TABLE pipeline_tasks ADD COLUMN next_retry_at INTEGER",
+    // Individual-episode subset for a show request (JSON array of
+    // {season,episode}), unioned with the `seasons` full-season subset.
+    "ALTER TABLE requests ADD COLUMN episodes TEXT",
+    // Airing signals synced from TMDB by the acquisition.refresh job.
+    "ALTER TABLE requests ADD COLUMN air_status TEXT",
+    "ALTER TABLE requests ADD COLUMN next_air_date TEXT",
+    "ALTER TABLE requests ADD COLUMN last_refresh_at INTEGER",
+    // Per-row search backoff: how many fruitless passes this row has cost,
+    // and the epoch-ms before which the next one must not bother. NULL is
+    // "due now", so rows from before the column keep their turn.
+    "ALTER TABLE wanted ADD COLUMN search_attempts INTEGER NOT NULL DEFAULT 0",
+    "ALTER TABLE wanted ADD COLUMN next_search_at INTEGER",
+    // `wanted_searchable` selects on status + next_search_at and orders by
+    // air date; the old (status, last_search_at) index served neither. Both
+    // statements run here, after the column they name exists.
+    "DROP INDEX IF EXISTS idx_wanted_search",
+    "CREATE INDEX IF NOT EXISTS idx_wanted_due ON wanted(status, next_search_at, air_date)",
+    "CREATE TABLE IF NOT EXISTS audio_analysis (\
+        file_id     TEXT NOT NULL REFERENCES files(id) ON DELETE CASCADE,\
+        track_index INTEGER NOT NULL,\
+        lufs_i      REAL NOT NULL,\
+        lra         REAL NOT NULL,\
+        true_peak   REAL NOT NULL,\
+        dialog_lufs REAL,\
+        verdict     TEXT NOT NULL,\
+        updated_at  TEXT NOT NULL,\
+        PRIMARY KEY (file_id, track_index))",
+    // The old `acq_tmdb(logical_id)` keyed the import's known id by a
+    // recomputed logical id that orphaned on a title-parse mismatch; replaced
+    // by `acq_file_tmdb(abs_path)` (created in SCHEMA above).
+    "DROP TABLE IF EXISTS acq_tmdb",
+    // No backfill: the name -> id table lives in @kroma/core, not in SQL, so a
+    // row keeps resolving by name until its next enrichment writes the ids.
+    "ALTER TABLE metadata_core ADD COLUMN tmdb_genre_ids TEXT NOT NULL DEFAULT '[]'",
+    // Fold the old watch_later queue into my_list, then drop it: My list now
+    // covers not-yet-available titles too, so the separate queue is redundant.
+    "INSERT OR IGNORE INTO my_list (user_id, item_id, added_at) SELECT user_id, item_id, added_at FROM watch_later",
+    "DROP INDEX IF EXISTS idx_watch_later_user",
+    "DROP TABLE IF EXISTS watch_later",
+    // Per-download byte counters, so the queue can show a seeding ratio and an
+    // all-time up/down total that outlives the engine session (librqbit's own
+    // counters reset with the process).
+    "ALTER TABLE downloads ADD COLUMN downloaded_bytes INTEGER NOT NULL DEFAULT 0",
+    "ALTER TABLE downloads ADD COLUMN uploaded_bytes INTEGER NOT NULL DEFAULT 0",
+    // How `tmdb_id` was decided: 'auto' from the release name, 'pinned' from a
+    // grab that already named a title, 'none' once the automatic pass has looked
+    // and found nothing. NULL is a row it has not reached yet. A 'pinned' row is
+    // never re-matched.
+    "ALTER TABLE downloads ADD COLUMN match_source TEXT",
+    "UPDATE downloads SET match_source = 'pinned' WHERE match_source = 'manual'",
+    // Paging the queue orders by grabbed_at across every filter, and filtering
+    // by client is a full scan without this.
+    "CREATE INDEX IF NOT EXISTS idx_downloads_grabbed ON downloads(grabbed_at DESC)",
+    "CREATE INDEX IF NOT EXISTS idx_downloads_client ON downloads(client_id, grabbed_at DESC)",
+    // The play log kept who and what and threw away the how: the registry knew
+    // the device, the player, whether the stream was transcoded and which side
+    // of the router it left by, and none of it survived the session. An admin
+    // asking "who watched this, on what, and did the box have to re-encode it"
+    // had nothing to read.
+    "ALTER TABLE play_history ADD COLUMN device TEXT",
+    "ALTER TABLE play_history ADD COLUMN player TEXT",
+    "ALTER TABLE play_history ADD COLUMN mode TEXT",
+    "ALTER TABLE play_history ADD COLUMN network TEXT",
+    "ALTER TABLE play_history ADD COLUMN video_label TEXT",
+    "ALTER TABLE play_history ADD COLUMN audio_label TEXT",
+    "ALTER TABLE play_history ADD COLUMN show_title TEXT",
+    "ALTER TABLE play_history ADD COLUMN season INTEGER",
+    "ALTER TABLE play_history ADD COLUMN episode INTEGER",
+    // The plays query joins items and filters on the library; nothing covered
+    // either, so both were a scan on a log with years in it.
+    "CREATE INDEX IF NOT EXISTS idx_history_library ON play_history(library, ended_at DESC)",
+    "CREATE INDEX IF NOT EXISTS idx_history_item ON play_history(item_id)",
+    // Sixteen thousand rows on one live server were never viewings. A browser
+    // throttles a background tab to about one timer wake-up a minute, so the
+    // heartbeat landed after the 30s session TTL had already reaped and logged
+    // the session, and the next beat opened another the reaper logged a minute
+    // later, around the clock for two months.
+    //
+    // Their signature is exact and nothing else shares it: a run of at least
+    // three rows for one account, each starting exactly 60 seconds after the
+    // last, none lasting longer than the TTL plus one reap interval. Accounts
+    // that never ran a throttled tab match nothing. The server now refuses to
+    // log a session that never played, so no new ones can appear.
+    "DELETE FROM play_history WHERE id IN (
+        WITH gapped AS (
+          SELECT id, watched_ms, started_at,
+                 COALESCE(user_id, username, '?') AS who,
+                 started_at - LAG(started_at) OVER (
+                   PARTITION BY COALESCE(user_id, username, '?') ORDER BY started_at
+                 ) AS prev_gap
+          FROM play_history
+        ),
+        runs AS (
+          SELECT id, watched_ms, who,
+                 SUM(CASE WHEN prev_gap = 60 THEN 0 ELSE 1 END) OVER (
+                   PARTITION BY who ORDER BY started_at
+                 ) AS run
+          FROM gapped
+        )
+        SELECT id FROM runs
+        WHERE (who, run) IN (
+          SELECT who, run FROM runs GROUP BY who, run
+          HAVING COUNT(*) >= 3 AND MAX(watched_ms) <= 45000
+        )
+      )",
+    // The series, the season, the episode number and the library only started
+    // being written with the columns above, so every row logged before them
+    // reads as a bare episode name.
+    "UPDATE play_history AS h \
+        SET show_title = COALESCE(h.show_title, s.title, i.show_title), \
+            season     = COALESCE(h.season, i.season), \
+            episode    = COALESCE(h.episode, i.episode) \
+       FROM items i LEFT JOIN shows s ON s.id = i.show_id \
+      WHERE i.id = h.item_id \
+        AND ((h.show_title IS NULL AND COALESCE(s.title, i.show_title) IS NOT NULL) \
+          OR (h.season IS NULL AND i.season IS NOT NULL) \
+          OR (h.episode IS NULL AND i.episode IS NOT NULL))",
+    "UPDATE play_history AS h SET library = i.library \
+       FROM items i WHERE i.id = h.item_id AND h.library IS NULL",
+    // One row per admin-minted credential reset. The code is stored as a hash
+    // (same PBKDF2 as passwords), never in clear.
+    "CREATE TABLE IF NOT EXISTS credential_resets (\
+        token       TEXT PRIMARY KEY,\
+        user_id     TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,\
+        code_hash   TEXT NOT NULL,\
+        attempts    INTEGER NOT NULL DEFAULT 0,\
+        created_by  TEXT REFERENCES users(id) ON DELETE SET NULL,\
+        created_at  TEXT NOT NULL,\
+        expires_at  INTEGER NOT NULL,\
+        used_at     TEXT)",
+    // The address's proof of ownership: set when a verification link confirms,
+    // cleared whenever the address changes.
+    "ALTER TABLE users ADD COLUMN email_verified_at TEXT",
+    // One row per admin-minted email verification. No code: reaching the
+    // mailbox is itself the proof, so the link alone suffices.
+    "CREATE TABLE IF NOT EXISTS email_verifications (\
+        token       TEXT PRIMARY KEY,\
+        user_id     TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,\
+        email       TEXT NOT NULL,\
+        created_by  TEXT REFERENCES users(id) ON DELETE SET NULL,\
+        created_at  TEXT NOT NULL,\
+        expires_at  INTEGER NOT NULL,\
+        used_at     TEXT)",
+    // One open reset request per account, asked from the sign-in screen and
+    // cleared when the owner mints a reset.
+    "CREATE TABLE IF NOT EXISTS reset_requests (\
+        user_id     TEXT PRIMARY KEY REFERENCES users(id) ON DELETE CASCADE,\
+        created_at  TEXT NOT NULL)",
+    "ALTER TABLE metadata_core ADD COLUMN certification TEXT",
+];

package/rust/kroma-db/src/schema.rs

@@ -0,0 +1,273 @@
+//! Opening a database: the pool, the schema and the migrations that follow it.
+
+use std::path::Path;
+use std::sync::{Arc, Mutex};
+
+use anyhow::{Context, Result};
+use rusqlite::Connection;
+
+use super::{Pool, PoolInner};
+
+mod ddl;
+mod migrations;
+
+pub(crate) use ddl::{FILE_COLS, ITEM_COLS, PRAGMAS, SCHEMA};
+pub(crate) use migrations::MIGRATIONS;
+
+/// A pool over `path` with the pragmas applied and NO schema.
+///
+/// For a database this crate does not own the shape of -- a module's own file,
+/// whose tables come from that module's `migrations()`. [`init`] would stamp the
+/// whole core schema into it, which is forty tables it will never read.
+pub fn open(path: &Path) -> Result<Pool> {
+    pool_at(path, 4, None)
+}
+
+/// The one place a [`Pool`] is built. `scope` is `None` for a database its owner
+/// is not scoped against, and the module grant otherwise.
+///
+/// Opens one connection before returning, so a path that cannot be opened fails
+/// here rather than at whatever query happens to run first.
+pub(crate) fn pool_at(
+    path: &Path,
+    max_idle: usize,
+    scope: Option<crate::grant::Scope>,
+) -> Result<Pool> {
+    if let Some(dir) = path.parent() {
+        std::fs::create_dir_all(dir).ok();
+    }
+    let pool = Arc::new(PoolInner {
+        path: path.to_path_buf(),
+        idle: Mutex::new(Vec::new()),
+        max_idle,
+        scope,
+    });
+    let _ = pool.get()?;
+    Ok(pool)
+}
+
+pub fn init(path: &Path) -> Result<Pool> {
+    let pool = pool_at(path, 8, None)?;
+    let conn = pool.get()?;
+    conn.execute_batch(SCHEMA)
+        .context("failed to apply schema")?;
+    migrate(&conn);
+    Ok(pool)
+}
+
+fn migrate(conn: &Connection) {
+    for sql in MIGRATIONS {
+        let _ = conn.execute(sql, []);
+    }
+}
+
+/// Apply a module's own schema after the core schema at DB init (see
+/// [`kroma_module_host::ServerModule::migrations`], run from the binary). The SQL
+/// is `IF NOT EXISTS` DDL, so it is idempotent across every boot; it runs as one
+/// batch, so a syntax error surfaces instead of being silently swallowed. Kept
+/// here (rather than a raw `execute_batch` at the call site) so a module owns its
+/// tables while the core stays the single place that touches the connection.
+pub fn apply_migrations(conn: &Connection, sql: &str) -> Result<()> {
+    conn.execute_batch(sql)
+        .context("failed to apply module schema")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn a_modules_schema_applies_beside_the_core_one_and_a_broken_batch_names_itself() {
+        let pool = crate::testing::temp_pool("schema-module");
+        let conn = pool.get().unwrap();
+
+        apply_migrations(
+            &conn,
+            "CREATE TABLE IF NOT EXISTS notes (id TEXT PRIMARY KEY, body TEXT NOT NULL);\
+             CREATE INDEX IF NOT EXISTS idx_notes_body ON notes(body);",
+        )
+        .unwrap();
+        conn.execute("INSERT INTO notes (id, body) VALUES ('n1', 'hi')", [])
+            .unwrap();
+
+        apply_migrations(
+            &conn,
+            "CREATE TABLE IF NOT EXISTS notes (id TEXT PRIMARY KEY, body TEXT NOT NULL);",
+        )
+        .unwrap();
+        let rows: i64 = conn
+            .query_row("SELECT COUNT(*) FROM notes", [], |r| r.get(0))
+            .unwrap();
+        assert_eq!(
+            rows, 1,
+            "re-applying the schema must not drop the module's data"
+        );
+
+        let err = apply_migrations(&conn, "CREATE TABL oops (").unwrap_err();
+        assert!(
+            format!("{err:#}").contains("failed to apply module schema"),
+            "{err:#}"
+        );
+    }
+
+    #[test]
+    fn init_opens_a_database_whose_wanted_table_predates_the_backoff_columns() {
+        let dir = kroma_testing::temp_dir("schema-wanted-upgrade");
+        let path = dir.path().join("kroma.db");
+
+        let old = Connection::open(&path).unwrap();
+        old.execute_batch(
+            "CREATE TABLE wanted (\
+                 id             TEXT PRIMARY KEY,\
+                 request_id     TEXT NOT NULL,\
+                 kind           TEXT NOT NULL,\
+                 tmdb_id        INTEGER NOT NULL,\
+                 title          TEXT NOT NULL,\
+                 season         INTEGER,\
+                 episode        INTEGER,\
+                 air_date       TEXT,\
+                 status         TEXT NOT NULL DEFAULT 'wanted',\
+                 last_search_at INTEGER,\
+                 updated_at     INTEGER NOT NULL);\
+             CREATE INDEX idx_wanted_search ON wanted(status, last_search_at);\
+             INSERT INTO wanted (id, request_id, kind, tmdb_id, title, updated_at)\
+                 VALUES ('w1', 'r1', 'episode', 42, 'Show', 0);",
+        )
+        .unwrap();
+        drop(old);
+
+        let pool = init(&path).expect("an existing database must still open");
+        let conn = pool.get().unwrap();
+
+        let due: i64 = conn
+            .query_row(
+                "SELECT COUNT(*) FROM wanted WHERE next_search_at IS NULL",
+                [],
+                |r| r.get(0),
+            )
+            .unwrap();
+        assert_eq!(due, 1, "rows from before the column keep their turn");
+
+        let indexes: Vec<String> = conn
+            .prepare("SELECT name FROM sqlite_master WHERE type = 'index' AND tbl_name = 'wanted'")
+            .unwrap()
+            .query_map([], |r| r.get(0))
+            .unwrap()
+            .collect::<std::result::Result<_, _>>()
+            .unwrap();
+        assert!(indexes.iter().any(|n| n == "idx_wanted_due"), "{indexes:?}");
+        assert!(
+            !indexes.iter().any(|n| n == "idx_wanted_search"),
+            "{indexes:?}"
+        );
+    }
+
+    #[test]
+    fn init_names_the_series_a_play_was_logged_without() {
+        let dir = kroma_testing::temp_dir("schema-history-series");
+        let path = dir.path().join("kroma.db");
+        let old = init(&path).unwrap();
+        old.get()
+            .unwrap()
+            .execute_batch(
+                "INSERT INTO libraries (id,name,kind,path,added_at) \
+                     VALUES ('lib-tv','Series','tv','/media','2026-01-01');\
+                 INSERT INTO shows (id,library,title,added_at) \
+                     VALUES ('hotd','lib-tv','House of the Dragon','2026-01-01');\
+                 INSERT INTO items (id,kind,title,container,library,show_id,season,episode,added_at) \
+                     VALUES ('ep','episode','Salt and Sea, Fire and Blood','mkv','lib-tv','hotd',3,1,'2026-01-01');\
+                 INSERT INTO play_history (id,user_id,username,item_id,kind,title,started_at,ended_at,watched_ms) \
+                     VALUES ('p1','u1','alice','ep','episode','Salt and Sea, Fire and Blood',0,100,1000);",
+            )
+            .unwrap();
+        drop(old);
+
+        let pool = init(&path).unwrap();
+
+        let row: (Option<String>, Option<i64>, Option<i64>, Option<String>) = pool
+            .get()
+            .unwrap()
+            .query_row(
+                "SELECT show_title, season, episode, library FROM play_history WHERE id = 'p1'",
+                [],
+                |r| Ok((r.get(0)?, r.get(1)?, r.get(2)?, r.get(3)?)),
+            )
+            .unwrap();
+        assert_eq!(
+            row,
+            (
+                Some("House of the Dragon".to_string()),
+                Some(3),
+                Some(1),
+                Some("lib-tv".to_string())
+            )
+        );
+    }
+
+    #[test]
+    fn init_leaves_a_play_whose_title_has_left_the_catalog_blank() {
+        let dir = kroma_testing::temp_dir("schema-history-gone");
+        let path = dir.path().join("kroma.db");
+        let old = init(&path).unwrap();
+        old.get()
+            .unwrap()
+            .execute(
+                "INSERT INTO play_history (id,user_id,username,item_id,kind,title,started_at,ended_at,watched_ms) \
+                 VALUES ('p1','u1','alice','deleted','episode','The Dundies',0,100,1000)",
+                [],
+            )
+            .unwrap();
+        drop(old);
+
+        let pool = init(&path).unwrap();
+
+        let row: (Option<String>, Option<i64>, Option<String>) = pool
+            .get()
+            .unwrap()
+            .query_row(
+                "SELECT show_title, season, library FROM play_history WHERE id = 'p1'",
+                [],
+                |r| Ok((r.get(0)?, r.get(1)?, r.get(2)?)),
+            )
+            .unwrap();
+        assert_eq!(row, (None, None, None));
+    }
+
+    #[test]
+    fn init_repins_downloads_a_previous_release_marked_manual() {
+        let dir = kroma_testing::temp_dir("schema-match-source");
+        let path = dir.path().join("kroma.db");
+        let old = init(&path).unwrap();
+        old.get()
+            .unwrap()
+            .execute_batch(
+                "INSERT INTO downloads (id, client_id, client_ref, kind, tmdb_id, release_title, \
+                     magnet_or_url, grabbed_at, match_source) \
+                 VALUES ('d1', 'embedded', '', 'movie', 603, 'R', 'm', 0, 'manual'), \
+                        ('d2', 'embedded', '', 'movie', 0, 'R', 'm', 0, 'none'), \
+                        ('d3', 'embedded', '', 'movie', 42, 'R', 'm', 0, 'auto');",
+            )
+            .unwrap();
+        drop(old);
+
+        let pool = init(&path).unwrap();
+
+        let sources: Vec<Option<String>> = pool
+            .get()
+            .unwrap()
+            .prepare("SELECT match_source FROM downloads ORDER BY id")
+            .unwrap()
+            .query_map([], |r| r.get(0))
+            .unwrap()
+            .collect::<std::result::Result<_, _>>()
+            .unwrap();
+        assert_eq!(
+            sources,
+            [
+                Some("pinned".to_string()),
+                Some("none".to_string()),
+                Some("auto".to_string())
+            ]
+        );
+    }
+}

package/rust/kroma-db/src/suggest.rs

@@ -0,0 +1,129 @@
+//! Persistence for per-item **AI suggestions** ("Suggestions IA" on the detail
+//! page): one cached row per seed item, generated lazily by the LLM connector
+//! (`crate::services::llm::suggest_for`) and served as a plain hydrate. Empty
+//! `item_ids` is a terminal "tried, nothing usable" marker (so the client stops
+//! polling instead of re-triggering generation forever).
+
+use std::collections::HashMap;
+
+use super::translations::{self, TransData};
+use super::*;
+
+use rusqlite::OptionalExtension;
+
+/// A cached AI-suggestion row: resolved member ids + a localized one-line reason
+/// per language (`locale -> reason`, from the `translations` cache).
+#[derive(Debug, Clone, Default)]
+pub struct SuggestionRow {
+    pub item_ids: Vec<String>,
+    pub reasons: HashMap<String, String>,
+}
+
+/// The cached suggestion for one seed item, if generated. `Some` with empty
+/// `item_ids` means generation ran but found nothing a terminal state.
+pub fn get_suggestion(pool: &Pool, item_id: &str) -> Result<Option<SuggestionRow>> {
+    let conn = pool.get()?;
+    let base = conn
+        .query_row(
+            "SELECT item_ids FROM item_suggestions WHERE item_id = ?1",
+            params![item_id],
+            |r| r.get::<_, String>(0),
+        )
+        .optional()?;
+    let Some(ids_json) = base else {
+        return Ok(None);
+    };
+    let mut row = SuggestionRow {
+        item_ids: serde_json::from_str(&ids_json).unwrap_or_default(),
+        reasons: HashMap::new(),
+    };
+    for by_lang in translations::load_all(pool, "suggestion", &[item_id])?.into_values() {
+        for (lang, data) in by_lang {
+            if let Some(reason) = data.reason {
+                row.reasons.insert(lang, reason);
+            }
+        }
+    }
+    Ok(Some(row))
+}
+
+/// Upsert the cached suggestion for one seed item: the base row (ids) plus one
+/// localized reason per language in the `translations` cache. `reasons` is
+/// `locale -> reason` (empty for the terminal "nothing found" marker).
+pub fn set_suggestion(
+    pool: &Pool,
+    item_id: &str,
+    ids: &[String],
+    reasons: &HashMap<String, String>,
+) -> Result<()> {
+    let mut conn = pool.get()?;
+    let tx = conn.transaction()?;
+    let ids_json = serde_json::to_string(ids).unwrap_or_else(|_| "[]".into());
+    tx.execute(
+        "INSERT INTO item_suggestions (item_id, item_ids, updated_at) VALUES (?1, ?2, ?3) \
+         ON CONFLICT(item_id) DO UPDATE SET item_ids=excluded.item_ids, updated_at=excluded.updated_at",
+        params![item_id, ids_json, kroma_primitives::now_ms()],
+    )?;
+    // Replace this seed's reasons wholesale (a fresh generation supersedes them).
+    tx.execute(
+        "DELETE FROM translations WHERE subject_kind='suggestion' AND subject_id=?1",
+        params![item_id],
+    )?;
+    for (lang, reason) in reasons {
+        if reason.trim().is_empty() {
+            continue;
+        }
+        let data = TransData {
+            reason: Some(reason.clone()),
+            ..Default::default()
+        };
+        translations::write(&tx, "suggestion", item_id, lang, translations::LLM, &data)?;
+    }
+    tx.commit()?;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::testing::TempPool;
+    use std::collections::HashMap;
+
+    fn pool() -> TempPool {
+        crate::testing::temp_pool("sug")
+    }
+
+    #[test]
+    fn set_get_and_terminal_marker() {
+        let p = pool();
+        assert!(get_suggestion(&p, "m1").unwrap().is_none());
+
+        let mut reasons = HashMap::new();
+        reasons.insert("fr".to_string(), "parce que".to_string());
+        reasons.insert("en".to_string(), "  ".to_string()); // blank: skipped
+        set_suggestion(&p, "m1", &["a".into(), "b".into()], &reasons).unwrap();
+
+        let row = get_suggestion(&p, "m1").unwrap().unwrap();
+        assert_eq!(row.item_ids, vec!["a".to_string(), "b".to_string()]);
+        assert_eq!(row.reasons.get("fr").map(String::as_str), Some("parce que"));
+        assert!(!row.reasons.contains_key("en"), "blank reason not stored");
+
+        // Regeneration replaces the reasons wholesale.
+        let mut reasons2 = HashMap::new();
+        reasons2.insert("en".to_string(), "now english".to_string());
+        set_suggestion(&p, "m1", &["c".into()], &reasons2).unwrap();
+        let row = get_suggestion(&p, "m1").unwrap().unwrap();
+        assert_eq!(row.item_ids, vec!["c".to_string()]);
+        assert!(!row.reasons.contains_key("fr"), "old fr reason superseded");
+        assert_eq!(
+            row.reasons.get("en").map(String::as_str),
+            Some("now english")
+        );
+
+        // Empty item_ids is a valid terminal "nothing found" marker (Some, not None).
+        set_suggestion(&p, "m1", &[], &HashMap::new()).unwrap();
+        let row = get_suggestion(&p, "m1").unwrap().unwrap();
+        assert!(row.item_ids.is_empty());
+        assert!(row.reasons.is_empty());
+    }
+}