python-musefs 0.0.1__py3-none-any.whl → 1.1.0__py3-none-any.whl

musefs_common/__init__.py

@@ -11,18 +11,24 @@ from .errors import ScanError, SchemaMismatch
 from .paths import realpath_key
 from .scan import run_scan
 from .store import (
+    TagRow,
     check_schema_version,
     connect,
+    delete_tracks,
+    merge_tags,
     prune_missing,
     replace_tags,
     replace_track_art,
     sniff_mime,
+    tags_for_track,
     track_id_for_path,
+    track_ids_by_tag,
+    track_ids_for_paths,
     upsert_art,
 )
 from .sync import ArtImage, Record, SyncStats, sync_files, sync_one
 
-__version__ = "0.1.0"
+__version__ = "1.1.0"
 
 __all__ = [
     "EXPECTED_USER_VERSION",
@@ -35,7 +41,13 @@ __all__ = [
     "connect",
     "check_schema_version",
     "track_id_for_path",
+    "track_ids_for_paths",
+    "track_ids_by_tag",
+    "tags_for_track",
+    "TagRow",
+    "delete_tracks",
     "prune_missing",
+    "merge_tags",
     "replace_tags",
     "upsert_art",
     "replace_track_art",

musefs_common/scan.py

@@ -4,19 +4,23 @@ import subprocess
 from .errors import ScanError
 
 
-def run_scan(binary, db_path, target, *, timeout=None):
-    """Run ``<binary> scan <target...> --db <db_path>``. ``target`` is a single
-    path or an iterable of paths; all targets precede the ``--db`` flag and are
-    scanned under one process (one DB open). Creates the DB if absent and fills
-    the structural columns a plugin can't compute. Raises ``ScanError`` (with
-    ``kind`` in ``"not_found" | "timeout" | "failed"``) on failure; the caller
-    formats its own user-facing message from the exception attributes."""
+def run_scan(binary, db_path, target, *, revalidate=False, timeout=None):
+    """Run ``<binary> scan <target...> --db <db_path> [--revalidate]``. ``target``
+    is a single path or an iterable of paths; all targets precede the ``--db``
+    flag and are scanned under one process (one DB open). Creates the DB if
+    absent and fills the structural columns a plugin can't compute. With
+    ``revalidate``, the scanner re-checks stamps, prunes rows whose backing file
+    is gone, and GCs orphaned art. Raises ``ScanError`` (with ``kind`` in
+    ``"not_found" | "timeout" | "failed"``) on failure; the caller formats its
+    own user-facing message from the exception attributes."""
     if isinstance(target, (str, os.PathLike)):
         targets = [target]
     else:
         targets = list(target)
     display = str(targets[0]) if len(targets) == 1 else f"{len(targets)} target(s)"
     argv = [binary, "scan", *(str(t) for t in targets), "--db", str(db_path)]
+    if revalidate:
+        argv.append("--revalidate")
     try:
         result = subprocess.run(argv, capture_output=True, timeout=timeout)
     except FileNotFoundError as exc:

musefs_common/schema.py

@@ -5,23 +5,40 @@
 SCHEMA_SQL = """\
 -- ── MIGRATION_V1 ──
 CREATE TABLE tracks (
-    id              INTEGER PRIMARY KEY,
-    backing_path    TEXT NOT NULL UNIQUE,
-    format          TEXT NOT NULL,
-    audio_offset    INTEGER NOT NULL,
-    audio_length    INTEGER NOT NULL,
-    backing_size    INTEGER NOT NULL,
-    backing_mtime   INTEGER NOT NULL,
-    content_version INTEGER NOT NULL DEFAULT 0,
-    updated_at      INTEGER NOT NULL
+    id               INTEGER PRIMARY KEY,
+    backing_path     TEXT NOT NULL UNIQUE,
+    format           TEXT NOT NULL,
+    audio_offset     INTEGER NOT NULL,
+    audio_length     INTEGER NOT NULL,
+    backing_size     INTEGER NOT NULL,
+    backing_mtime_ns INTEGER NOT NULL,
+    content_version  INTEGER NOT NULL DEFAULT 0,
+    updated_at       INTEGER NOT NULL,
+    backing_ctime_ns INTEGER NOT NULL DEFAULT 0 CHECK (backing_ctime_ns >= 0),
+    CHECK (format IN ('flac','mp3','m4a','opus','vorbis','oggflac','wav')),
+    CHECK (audio_offset >= 0),
+    CHECK (audio_length >= 0),
+    CHECK (backing_size >= 0),
+    CHECK (backing_mtime_ns >= 0),
+    CHECK (content_version >= 0),
+    CHECK (updated_at >= 0),
+    CHECK (audio_offset + audio_length <= backing_size)
 );
 
 CREATE TABLE tags (
-    track_id INTEGER NOT NULL REFERENCES tracks(id) ON DELETE CASCADE,
-    key      TEXT NOT NULL,
-    value    TEXT NOT NULL,
-    ordinal  INTEGER NOT NULL DEFAULT 0,
-    PRIMARY KEY (track_id, key, ordinal)
+    track_id   INTEGER NOT NULL REFERENCES tracks(id) ON DELETE CASCADE,
+    key        TEXT NOT NULL,
+    value      TEXT NOT NULL,
+    ordinal    INTEGER NOT NULL DEFAULT 0,
+    value_blob BLOB,
+    PRIMARY KEY (track_id, key, ordinal),
+    CHECK (ordinal >= 0),
+    CHECK (value_blob IS NULL OR value = ''),
+    CHECK (length(key) <= 256),
+    CHECK (length(key) >= 1
+           AND key NOT GLOB '*[' || char(1) || '-' || char(31) || ']*'),
+    CHECK (length(value) <= 262144),
+    CHECK (value_blob IS NULL OR length(value_blob) <= 16711680)
 );
 
 CREATE TABLE art (
@@ -31,7 +48,13 @@ CREATE TABLE art (
     width    INTEGER,
     height   INTEGER,
     byte_len INTEGER NOT NULL,
-    data     BLOB NOT NULL
+    data     BLOB NOT NULL,
+    CHECK (byte_len = length(data)),
+    CHECK (length(sha256) = 64),
+    CHECK (width IS NULL OR width >= 0),
+    CHECK (height IS NULL OR height >= 0),
+    CHECK (length(mime) <= 255),
+    CHECK (byte_len <= 16711680)
 );
 
 CREATE TABLE track_art (
@@ -40,9 +63,38 @@ CREATE TABLE track_art (
     picture_type INTEGER NOT NULL DEFAULT 3,
     description  TEXT NOT NULL DEFAULT '',
     ordinal      INTEGER NOT NULL DEFAULT 0,
-    PRIMARY KEY (track_id, ordinal)
+    PRIMARY KEY (track_id, ordinal),
+    CHECK (picture_type BETWEEN 0 AND 20),
+    CHECK (ordinal >= 0),
+    CHECK (length(description) <= 1024)
 );
 
+-- Read-only, derived-from-file structural metadata (FLAC STREAMINFO/SEEKTABLE).
+-- NOT part of the editable `tags` contract: external tools never touch it.
+CREATE TABLE structural_blocks (
+    track_id INTEGER NOT NULL REFERENCES tracks(id) ON DELETE CASCADE,
+    kind     TEXT NOT NULL,
+    ordinal  INTEGER NOT NULL DEFAULT 0,
+    body     BLOB NOT NULL,
+    PRIMARY KEY (track_id, kind, ordinal),
+    CHECK (kind IN ('STREAMINFO','SEEKTABLE')),
+    CHECK (ordinal >= 0),
+    CHECK (length(body) <= 16777215)
+);
+
+-- Bounded changelog ring for O(changed) refresh. Every metadata edit funnels
+-- through an UPDATE on the tracks row (the tags/track_art triggers), so
+-- triggers on tracks alone capture all writers. Relies on SQLite nested
+-- trigger activation (on by default; distinct from PRAGMA recursive_triggers).
+CREATE TABLE track_changes (
+    seq      INTEGER PRIMARY KEY AUTOINCREMENT,
+    track_id INTEGER NOT NULL
+);
+
+-- Index the reverse art -> track_art edge so bulk orphan-GC and the art delete
+-- trigger below do not scan the whole join table per deleted row.
+CREATE INDEX track_art_art_id_idx ON track_art(art_id);
+
 CREATE TRIGGER tags_ai AFTER INSERT ON tags BEGIN
     UPDATE tracks SET content_version = content_version + 1,
                       updated_at = CAST(strftime('%s','now') AS INTEGER)
@@ -74,33 +126,6 @@ CREATE TRIGGER track_art_ad AFTER DELETE ON track_art BEGIN
                       updated_at = CAST(strftime('%s','now') AS INTEGER)
     WHERE id = OLD.track_id;
 END;
-PRAGMA user_version = 1;
-
--- ── MIGRATION_V2 ──
--- Binary tag payloads live alongside text tags. A row is binary iff
--- value_blob IS NOT NULL; binary rows store '' in value.
-ALTER TABLE tags ADD COLUMN value_blob BLOB;
-
--- Read-only, derived-from-file structural metadata (FLAC STREAMINFO/SEEKTABLE).
--- NOT part of the editable `tags` contract: external tools never touch it.
-CREATE TABLE structural_blocks (
-    track_id INTEGER NOT NULL REFERENCES tracks(id) ON DELETE CASCADE,
-    kind     TEXT NOT NULL,
-    ordinal  INTEGER NOT NULL DEFAULT 0,
-    body     BLOB NOT NULL,
-    PRIMARY KEY (track_id, kind, ordinal)
-);
-PRAGMA user_version = 2;
-
--- ── MIGRATION_V3 ──
--- Bounded changelog ring for O(changed) refresh. Every metadata edit funnels
--- through an UPDATE on the tracks row (the V1 tags/track_art triggers), so
--- triggers on tracks alone capture all writers. Relies on SQLite nested
--- trigger activation (on by default; distinct from PRAGMA recursive_triggers).
-CREATE TABLE track_changes (
-    seq      INTEGER PRIMARY KEY AUTOINCREMENT,
-    track_id INTEGER NOT NULL
-);
 
 CREATE TRIGGER tracks_changelog_ai AFTER INSERT ON tracks BEGIN
     INSERT INTO track_changes (track_id) VALUES (NEW.id);
@@ -117,40 +142,91 @@ END;
 CREATE TRIGGER track_changes_prune AFTER INSERT ON track_changes BEGIN
     DELETE FROM track_changes WHERE seq <= NEW.seq - 8192;
 END;
-PRAGMA user_version = 3;
 
--- ── MIGRATION_V4 ──
-CREATE TEMP TABLE _m4_tracks AS SELECT * FROM tracks;
-CREATE TEMP TABLE _m4_tags AS SELECT * FROM tags;
-CREATE TEMP TABLE _m4_art AS SELECT * FROM art;
-CREATE TEMP TABLE _m4_track_art AS SELECT * FROM track_art;
+-- art rows are content-addressed by sha256: once written, their content
+-- columns are immutable. A writer needing different bytes/metadata inserts a
+-- NEW row and relinks via track_art (which bumps content_version through the
+-- track_art triggers). width/height use IS NOT (NULL-safe) because they are
+-- nullable; the NOT NULL columns use <>.
+CREATE TRIGGER art_reject_content_update
+BEFORE UPDATE ON art
+WHEN NEW.data   <> OLD.data
+  OR NEW.sha256 <> OLD.sha256
+  OR NEW.mime   <> OLD.mime
+  OR NEW.byte_len <> OLD.byte_len
+  OR NEW.width  IS NOT OLD.width
+  OR NEW.height IS NOT OLD.height
+BEGIN
+    SELECT RAISE(ABORT,
+        'art rows are immutable; insert a new content-addressed row and relink via track_art');
+END;
 
-DROP TABLE track_art;
-DROP TABLE tags;
-DROP TABLE art;
-DROP TABLE tracks;
+-- Deleting an art row that still has track_art references (an orphan an
+-- external writer can produce with foreign_keys OFF) bumps every referencing
+-- track, so the mount rebuilds and serves a clean EIO on the orphan rather
+-- than streaming stale bytes from an old cached layout. Inert on the normal
+-- gc_orphan_art path, where the deleted row has no references.
+CREATE TRIGGER art_ad AFTER DELETE ON art BEGIN
+    UPDATE tracks SET content_version = content_version + 1,
+                      updated_at = CAST(strftime('%s','now') AS INTEGER)
+    WHERE id IN (SELECT track_id FROM track_art WHERE art_id = OLD.id);
+END;
 
-CREATE TABLE tracks (
-    id              INTEGER PRIMARY KEY,
-    backing_path    TEXT NOT NULL UNIQUE,
-    format          TEXT NOT NULL,
-    audio_offset    INTEGER NOT NULL,
-    audio_length    INTEGER NOT NULL,
-    backing_size    INTEGER NOT NULL,
-    backing_mtime   INTEGER NOT NULL,
-    content_version INTEGER NOT NULL DEFAULT 0,
-    updated_at      INTEGER NOT NULL,
-    CHECK (format IN ('flac','mp3','m4a','opus','vorbis','oggflac','wav')),
-    CHECK (audio_offset >= 0),
-    CHECK (audio_length >= 0),
-    CHECK (backing_size >= 0),
-    CHECK (backing_mtime >= 0),
-    CHECK (content_version >= 0),
-    CHECK (updated_at >= 0),
-    CHECK (audio_offset + audio_length <= backing_size)
-);
+-- Scanner-owned geometry feeds the synthesized layout, but upsert_track does
+-- not touch content_version. Bump it whenever a geometry column actually
+-- changes, making content_version a true superset of served-byte inputs. The
+-- WHEN guard is false on this trigger's own nested UPDATE (only content_version
+-- changes), so the recursion terminates after exactly one bump.
+CREATE TRIGGER tracks_geometry_au
+AFTER UPDATE ON tracks
+WHEN NEW.format        <> OLD.format
+  OR NEW.audio_offset  <> OLD.audio_offset
+  OR NEW.audio_length  <> OLD.audio_length
+  OR NEW.backing_size  <> OLD.backing_size
+  OR NEW.backing_mtime_ns <> OLD.backing_mtime_ns
+BEGIN
+    UPDATE tracks SET content_version = content_version + 1 WHERE id = NEW.id;
+END;
 
-CREATE TABLE tags (
+-- FLAC structural blocks feed synthesized headers and flip the synthesis path
+-- (legacy front-read fallback vs streamed fast path), so a change must bump.
+-- set_structural_blocks is DELETE-then-INSERT (no UPDATE path exists), so these
+-- fire on every rewrite; the resulting over-bump on a byte-identical re-probe
+-- is harmless monotone churn (content_version is compared only for equality).
+CREATE TRIGGER structural_blocks_ai AFTER INSERT ON structural_blocks BEGIN
+    UPDATE tracks SET content_version = content_version + 1 WHERE id = NEW.track_id;
+END;
+CREATE TRIGGER structural_blocks_ad AFTER DELETE ON structural_blocks BEGIN
+    UPDATE tracks SET content_version = content_version + 1 WHERE id = OLD.track_id;
+END;
+PRAGMA user_version = 1;
+
+-- ── MIGRATION_V2 ──
+-- fingerprint/content_hash are scanner-owned content identities. Neither is
+-- UNIQUE and the index is NON-unique BY DESIGN: duplicate-content tracks (same
+-- album in two places, genuine dupes) legitimately share both values, and a
+-- UNIQUE constraint would abort the scan batch on the second copy. Correctness
+-- comes from the refind logic (unique-missing candidate + confirmation), not
+-- from DB uniqueness. Both columns carry a length(x) = 64 CHECK locking them
+-- to SHA-256 hex (Task E2 benchmark locked the hash to SHA-256: under a
+-- realistic SSD/HDD I/O profile the fingerprint adds ~8.6%; the RAM
+-- microbench's higher ratio is an I/O-elimination artifact — see
+-- the benchmarks docs). Hash function is now fixed, so the CHECK is added here.
+ALTER TABLE tracks ADD COLUMN fingerprint  TEXT
+    CHECK (fingerprint IS NULL OR length(fingerprint) = 64);
+ALTER TABLE tracks ADD COLUMN content_hash TEXT
+    CHECK (content_hash IS NULL OR length(content_hash) = 64);
+CREATE INDEX tracks_fingerprint_idx ON tracks(fingerprint);
+
+-- Rebuild `tags` with a byte-accurate value cap (#505). SQLite's length() on
+-- TEXT counts characters, so the V1 `CHECK (length(value) <= 262144)` was up to
+-- ~4x looser than the documented 256 KiB byte bound; length(CAST(value AS BLOB))
+-- counts bytes. SQLite cannot alter a CHECK in place, so recreate the table
+-- (V2 is unreleased — this is folded in rather than added as a new migration).
+-- Pre-existing over-cap rows (only reachable on an upgraded store) are dropped:
+-- the read-time guard already counts bytes, so they were unreadable anyway, and
+-- carrying them would abort the rebuild on the new CHECK.
+CREATE TABLE tags_new (
     track_id   INTEGER NOT NULL REFERENCES tracks(id) ON DELETE CASCADE,
     key        TEXT NOT NULL,
     value      TEXT NOT NULL,
@@ -158,44 +234,21 @@ CREATE TABLE tags (
     value_blob BLOB,
     PRIMARY KEY (track_id, key, ordinal),
     CHECK (ordinal >= 0),
-    CHECK (value_blob IS NULL OR value = '')
+    CHECK (value_blob IS NULL OR value = ''),
+    CHECK (length(key) <= 256),
+    CHECK (length(key) >= 1
+           AND key NOT GLOB '*[' || char(1) || '-' || char(31) || ']*'),
+    CHECK (length(CAST(value AS BLOB)) <= 262144),
+    CHECK (value_blob IS NULL OR length(value_blob) <= 16711680)
 );
+INSERT INTO tags_new (track_id, key, value, ordinal, value_blob)
+    SELECT track_id, key, value, ordinal, value_blob FROM tags
+    WHERE length(CAST(value AS BLOB)) <= 262144;
+DROP TABLE tags;
+ALTER TABLE tags_new RENAME TO tags;
 
-CREATE TABLE art (
-    id       INTEGER PRIMARY KEY,
-    sha256   TEXT NOT NULL UNIQUE,
-    mime     TEXT NOT NULL,
-    width    INTEGER,
-    height   INTEGER,
-    byte_len INTEGER NOT NULL,
-    data     BLOB NOT NULL,
-    CHECK (byte_len = length(data)),
-    CHECK (length(sha256) = 64),
-    CHECK (width IS NULL OR width >= 0),
-    CHECK (height IS NULL OR height >= 0)
-);
-
-CREATE TABLE track_art (
-    track_id     INTEGER NOT NULL REFERENCES tracks(id) ON DELETE CASCADE,
-    art_id       INTEGER NOT NULL REFERENCES art(id),
-    picture_type INTEGER NOT NULL DEFAULT 3,
-    description  TEXT NOT NULL DEFAULT '',
-    ordinal      INTEGER NOT NULL DEFAULT 0,
-    PRIMARY KEY (track_id, ordinal),
-    CHECK (picture_type BETWEEN 0 AND 20),
-    CHECK (ordinal >= 0)
-);
-
-INSERT INTO tracks SELECT * FROM _m4_tracks;
-INSERT INTO art SELECT * FROM _m4_art;
-INSERT INTO tags SELECT * FROM _m4_tags;
-INSERT INTO track_art SELECT * FROM _m4_track_art;
-
-DROP TABLE _m4_track_art;
-DROP TABLE _m4_tags;
-DROP TABLE _m4_art;
-DROP TABLE _m4_tracks;
-
+-- DROP TABLE tags dropped its INSERT/UPDATE/DELETE triggers; recreate them
+-- verbatim so the content_version/updated_at bump contract is unchanged.
 CREATE TRIGGER tags_ai AFTER INSERT ON tags BEGIN
     UPDATE tracks SET content_version = content_version + 1,
                       updated_at = CAST(strftime('%s','now') AS INTEGER)
@@ -211,33 +264,7 @@ CREATE TRIGGER tags_ad AFTER DELETE ON tags BEGIN
                       updated_at = CAST(strftime('%s','now') AS INTEGER)
     WHERE id = OLD.track_id;
 END;
-
-CREATE TRIGGER track_art_ai AFTER INSERT ON track_art BEGIN
-    UPDATE tracks SET content_version = content_version + 1,
-                      updated_at = CAST(strftime('%s','now') AS INTEGER)
-    WHERE id = NEW.track_id;
-END;
-CREATE TRIGGER track_art_au AFTER UPDATE ON track_art BEGIN
-    UPDATE tracks SET content_version = content_version + 1,
-                      updated_at = CAST(strftime('%s','now') AS INTEGER)
-    WHERE id = NEW.track_id;
-END;
-CREATE TRIGGER track_art_ad AFTER DELETE ON track_art BEGIN
-    UPDATE tracks SET content_version = content_version + 1,
-                      updated_at = CAST(strftime('%s','now') AS INTEGER)
-    WHERE id = OLD.track_id;
-END;
-
-CREATE TRIGGER tracks_changelog_ai AFTER INSERT ON tracks BEGIN
-    INSERT INTO track_changes (track_id) VALUES (NEW.id);
-END;
-CREATE TRIGGER tracks_changelog_au AFTER UPDATE ON tracks BEGIN
-    INSERT INTO track_changes (track_id) VALUES (NEW.id);
-END;
-CREATE TRIGGER tracks_changelog_ad AFTER DELETE ON tracks BEGIN
-    INSERT INTO track_changes (track_id) VALUES (OLD.id);
-END;
-PRAGMA user_version = 4;
+PRAGMA user_version = 2;
 """
 
-USER_VERSION = 4
+USER_VERSION = 2

musefs_common/store.py

@@ -1,10 +1,86 @@
+import contextlib
 import hashlib
 import os
 import sqlite3
+from dataclasses import dataclass
 
 from .constants import EXPECTED_USER_VERSION
 from .errors import SchemaMismatch
 
+# SQLite caps a statement's host parameters (SQLITE_MAX_VARIABLE_NUMBER: 999 on
+# the <3.32 floor). Chunk bulk IN-lists below it so large lookups never trip it.
+_MAX_SQL_VARS = 900
+
+
+@dataclass(frozen=True)
+class TagRow:
+    """One tag row read back from the store: the key, the text value, and the
+    raw ``value_blob``. Plugin-owned text tags have ``value_blob is None``;
+    scanner-written binary tags have ``value == ""`` and ``value_blob`` bytes."""
+
+    key: str
+    value: str
+    value_blob: object = None  # bytes | None
+
+
+# sqlite3.LEGACY_TRANSACTION_CONTROL is 3.12+; it is == -1. Use getattr so this
+# module still imports on the 3.8 floor (where the constant does not exist).
+_LEGACY = getattr(sqlite3, "LEGACY_TRANSACTION_CONTROL", -1)
+
+
+def _is_autocommit(conn):
+    """True if the connection auto-commits each statement (no caller-owned
+    transaction will be committed for us)."""
+    ac = getattr(conn, "autocommit", _LEGACY)  # 3.12+ attribute; _LEGACY on <3.12
+    if ac is True:
+        return True
+    if ac is False:
+        return False
+    return conn.isolation_level is None  # legacy transaction control
+
+
+def _is_legacy(conn):
+    """True if the connection uses legacy transaction control (the <3.12 default
+    and the 3.12+ LEGACY_TRANSACTION_CONTROL mode)."""
+    return getattr(conn, "autocommit", _LEGACY) == _LEGACY
+
+
+@contextlib.contextmanager
+def _savepoint(conn, name):
+    """Make a DELETE+INSERT block atomic regardless of the connection's
+    transaction mode. On a caller-managed connection it nests via SAVEPOINT and
+    never commits the enclosing transaction; on an autocommit connection the
+    outermost call owns a transaction for the block (commit on success, rollback
+    on failure). Nested calls only nest -- they never BEGIN or commit -- so a
+    sync_one savepoint may wrap these per-function savepoints safely.
+
+    ``name`` must be a hardcoded SQL identifier (it is interpolated into the SQL,
+    so never pass caller-controlled text)."""
+    autocommit = _is_autocommit(conn)
+    owns = not conn.in_transaction  # outermost call: it opens & owns the txn
+    # Legacy mode never auto-BEGINs before SAVEPOINT, so a savepoint opened as
+    # the first statement of a batch would become the outermost transaction and
+    # commit durably on RELEASE. Force a nesting BEGIN there. PEP-249 modes
+    # auto-begin before any statement, so they need no nudge.
+    if owns and _is_legacy(conn):
+        conn.execute("BEGIN")
+    conn.execute(f"SAVEPOINT {name}")
+    try:
+        yield
+    except BaseException:
+        try:
+            conn.execute(f"ROLLBACK TO {name}")
+            conn.execute(f"RELEASE {name}")
+            if owns and autocommit:
+                conn.rollback()
+        except sqlite3.Error:
+            pass  # never mask the original exception with a cleanup failure
+        raise
+    else:
+        conn.execute(f"RELEASE {name}")
+        if owns and autocommit:
+            conn.commit()
+
 
 def connect(db_path):
     """Open the musefs DB with a busy timeout and foreign keys enabled."""
@@ -29,6 +105,77 @@ def track_id_for_path(conn, key):
     return row[0] if row else None
 
 
+def track_ids_for_paths(conn, keys):
+    """Resolve many ``backing_path`` keys to track ids in one pass, returning a
+    ``{key: id}`` dict that omits keys with no matching track row. The IN-list is
+    chunked under SQLite's host-parameter cap so arbitrarily large lookups work
+    (the bulk counterpart to ``track_id_for_path``)."""
+    # Deduplicate while preserving first-seen order: a key repeated across chunk
+    # boundaries would re-fetch its row in a later chunk and trip the duplicate
+    # guard below even on a conformant DB.
+    keys = list(dict.fromkeys(keys))
+    out = {}
+    for start in range(0, len(keys), _MAX_SQL_VARS):
+        chunk = keys[start : start + _MAX_SQL_VARS]
+        placeholders = ",".join("?" for _ in chunk)
+        rows = conn.execute(
+            f"SELECT backing_path, id FROM tracks WHERE backing_path IN ({placeholders})",
+            chunk,
+        )
+        for backing_path, track_id in rows:
+            if backing_path in out:
+                # backing_path is UNIQUE in the schema, so a duplicate means a
+                # non-conformant DB; collapsing it would silently hide a track
+                # from prune (#478). Fail loudly instead.
+                raise ValueError(
+                    f"duplicate backing_path {backing_path!r} in tracks "
+                    f"(ids {out[backing_path]} and {track_id})"
+                )
+            out[backing_path] = track_id
+    return out
+
+
+def track_ids_by_tag(conn, key, value):
+    """Return a list of track ids whose plugin-owned text tag ``(key, value)``
+    matches (order unspecified, possibly empty).
+
+    Scoped to text rows (``value_blob IS NULL``); scanner-written binary tags
+    never match. The intent-based counterpart to ``prune_missing``'s
+    existence-based scoping: used to map a source's "I deleted this album/artist"
+    signal back to the rows it tagged.
+    """
+    rows = conn.execute(
+        "SELECT track_id FROM tags WHERE key = ? AND value = ? AND value_blob IS NULL",
+        (key, value),
+    )
+    return [track_id for (track_id,) in rows]
+
+
+def delete_tracks(conn, track_ids):
+    """Unconditionally delete the given track rows; return the count actually
+    deleted (an already-gone id contributes 0).
+
+    The intent-based delete: unlike ``prune_missing`` it does not check on-disk
+    existence. ``tags`` and ``track_art`` rows cascade away via the schema's
+    ``ON DELETE CASCADE`` (``connect`` enables ``foreign_keys = ON``).
+    """
+    deleted = 0
+    for track_id in track_ids:
+        deleted += conn.execute("DELETE FROM tracks WHERE id = ?", (track_id,)).rowcount
+    return deleted
+
+
+def tags_for_track(conn, track_id):
+    """Read back a track's tag rows as an ordered ``list[TagRow]`` (by key, then
+    ordinal). Includes both plugin-owned text tags (``value_blob is None``) and
+    scanner-written binary tags (``value == ""``, ``value_blob`` bytes)."""
+    rows = conn.execute(
+        "SELECT key, value, value_blob FROM tags WHERE track_id = ? ORDER BY key, ordinal",
+        (track_id,),
+    )
+    return [TagRow(key, value, value_blob) for key, value, value_blob in rows]
+
+
 def prune_missing(conn, track_ids=None):
     """Delete track rows whose backing file no longer exists on disk.
 
@@ -54,20 +201,63 @@ def prune_missing(conn, track_ids=None):
 
 def replace_tags(conn, track_id, pairs):
     """Replace all tags for a track. Duplicate keys get incrementing ordinals
-    (mirroring musefs scan ingest)."""
+    (mirroring musefs scan ingest).
+
+    Atomic via an internal savepoint (see ``_savepoint``), so a crash between the
+    DELETE and the INSERT can never leave the track's text tags wiped -- safe
+    even when called on an autocommit connection."""
     # Scope to the plugin-owned text rows: scanner-written binary tags
     # (value_blob NOT NULL) must survive a sync (#82).
-    conn.execute("DELETE FROM tags WHERE track_id = ? AND value_blob IS NULL", (track_id,))
-    ordinals = {}
-    rows = []
-    for key, value in pairs:
-        ordinal = ordinals.get(key, 0)
-        ordinals[key] = ordinal + 1
-        rows.append((track_id, key, value, ordinal))
-    conn.executemany(
-        "INSERT INTO tags (track_id, key, value, ordinal) VALUES (?, ?, ?, ?)",
-        rows,
-    )
+    with _savepoint(conn, "musefs_replace_tags"):
+        conn.execute("DELETE FROM tags WHERE track_id = ? AND value_blob IS NULL", (track_id,))
+        ordinals = {}
+        rows = []
+        for key, value in pairs:
+            ordinal = ordinals.get(key, 0)
+            ordinals[key] = ordinal + 1
+            rows.append((track_id, key, value, ordinal))
+        conn.executemany(
+            "INSERT INTO tags (track_id, key, value, ordinal) VALUES (?, ?, ?, ?)",
+            rows,
+        )
+
+
+def merge_tags(conn, track_id, managed_pairs, delete_keys):
+    """Per-key replace of the plugin-managed text tags, leaving unmanaged text
+    rows (the scan-seeded baseline) intact. ``managed_pairs`` is an ordered list
+    of (key, value); every key it names is cleared and rewritten with contiguous
+    ordinals. ``delete_keys`` names keys to clear without rewriting (tags the
+    plugin previously managed and the user has now removed). Both deletes are
+    scoped to ``value_blob IS NULL`` so scanner-written binary tags survive.
+
+    Atomic via an internal savepoint (see ``_savepoint``): the per-key deletes
+    and the rewrite either all land or none do, even on an autocommit
+    connection."""
+    with _savepoint(conn, "musefs_merge_tags"):
+        by_key = {}
+        for key, value in managed_pairs:
+            by_key.setdefault(key, []).append(value)
+
+        # Case-fold the key match: a scan seeds an unmapped tag in the file's
+        # native case (e.g. Vorbis ``LABEL``) while the plugin canonicalises to
+        # lowercase (``label``). Vorbis keys render case-insensitively, so an
+        # exact-case delete would leave the scan row and render a duplicate (#407).
+        for key in set(by_key) | set(delete_keys or ()):
+            conn.execute(
+                "DELETE FROM tags WHERE track_id = ? AND lower(key) = lower(?) "
+                "AND value_blob IS NULL",
+                (track_id, key),
+            )
+
+        rows = [
+            (track_id, key, value, ordinal)
+            for key, values in by_key.items()
+            for ordinal, value in enumerate(values)
+        ]
+        conn.executemany(
+            "INSERT INTO tags (track_id, key, value, ordinal) VALUES (?, ?, ?, ?)",
+            rows,
+        )
 
 
 _EXT_MIME = {
@@ -107,13 +297,18 @@ def upsert_art(conn, data, mime):
 def replace_track_art(conn, track_id, arts):
     """Replace the track's art rows. ``arts`` is an ordered list of
     ``(art_id, picture_type, description)``; each row's ``ordinal`` is its
-    list index."""
-    conn.execute("DELETE FROM track_art WHERE track_id = ?", (track_id,))
-    conn.executemany(
-        "INSERT INTO track_art (track_id, art_id, picture_type, description, "
-        "ordinal) VALUES (?, ?, ?, ?, ?)",
-        [
-            (track_id, art_id, picture_type, description, i)
-            for i, (art_id, picture_type, description) in enumerate(arts)
-        ],
-    )
+    list index.
+
+    Atomic via an internal savepoint (see ``_savepoint``): the DELETE and the
+    re-insert either both land or neither does, even on an autocommit
+    connection."""
+    with _savepoint(conn, "musefs_replace_track_art"):
+        conn.execute("DELETE FROM track_art WHERE track_id = ?", (track_id,))
+        conn.executemany(
+            "INSERT INTO track_art (track_id, art_id, picture_type, description, "
+            "ordinal) VALUES (?, ?, ?, ?, ?)",
+            [
+                (track_id, art_id, picture_type, description, i)
+                for i, (art_id, picture_type, description) in enumerate(arts)
+            ],
+        )

musefs_common/sync.py

@@ -1,9 +1,17 @@
 from __future__ import annotations
 
+import sqlite3
 from dataclasses import dataclass, field
 
 from .constants import MAX_ART_BYTES
-from .store import replace_tags, replace_track_art, track_id_for_path, upsert_art
+from .store import (
+    _savepoint,
+    merge_tags,
+    replace_tags,
+    replace_track_art,
+    track_id_for_path,
+    upsert_art,
+)
 
 
 @dataclass(frozen=True)
@@ -26,6 +34,7 @@ class Record:
     key: str
     pairs: list = field(default_factory=list)
     art: object = None  # list[ArtImage] | None
+    delete_keys: object = None  # list[str] of keys to clear without rewrite (merge mode)
 
 
 @dataclass
@@ -34,21 +43,32 @@ class SyncStats:
     skipped: int = 0  # path had no matching track row
     art_linked: int = 0
     skipped_art: int = 0  # art over the size cap (or, in the beets adapter, unreadable)
+    skipped_invalid: int = 0  # record violated a store CHECK constraint
+    invalid: list = field(default_factory=list)  # (record key, sqlite error message)
 
     def summary(self):
         return (
             f"synced={self.synced} skipped={self.skipped} "
-            f"art_linked={self.art_linked} skipped_art={self.skipped_art}"
+            f"art_linked={self.art_linked} skipped_art={self.skipped_art} "
+            f"skipped_invalid={self.skipped_invalid}"
         )
 
 
-def sync_one(conn, record, stats, *, dry_run=False):
+def sync_one(conn, record, stats, *, dry_run=False, merge=False):
     """Sync one ``Record`` into the DB, mutating ``stats``. Caller owns the
-    transaction. Tags are always fully replaced (scanner-written binary tags
-    survive — see ``replace_tags``). Art is replaced when at least one image is
+    transaction. With ``merge=False`` (the default) all plugin-owned text tags are
+    replaced; with ``merge=True`` only the keys in ``record.pairs`` and
+    ``record.delete_keys`` are touched (see ``merge_tags``). Either way,
+    scanner-written binary tags survive. Art is replaced when at least one image is
     within ``MAX_ART_BYTES``; each over-cap image bumps ``skipped_art``, and if
     every provided image is over cap any scan-seeded ``track_art`` is left
-    untouched."""
+    untouched.
+
+    A record whose tags or art violate a store CHECK constraint (key/value/mime
+    length, ``picture_type`` range, control chars, ...) is rolled back through its
+    own savepoint and skipped -- it bumps ``skipped_invalid`` and appends
+    ``(record.key, message)`` to ``invalid`` rather than aborting the whole batch
+    with an opaque commit-time ``IntegrityError`` (#420)."""
     track_id = track_id_for_path(conn, record.key)
     if track_id is None:
         stats.skipped += 1
@@ -63,20 +83,29 @@ def sync_one(conn, record, stats, *, dry_run=False):
     will_link_art = bool(kept)
 
     if not dry_run:
-        replace_tags(conn, track_id, record.pairs)
-        if will_link_art:
-            arts = [
-                (upsert_art(conn, img.data, img.mime), img.picture_type, img.description)
-                for img in kept
-            ]
-            replace_track_art(conn, track_id, arts)
+        try:
+            with _savepoint(conn, "musefs_sync_one"):
+                if merge:
+                    merge_tags(conn, track_id, record.pairs, record.delete_keys or [])
+                else:
+                    replace_tags(conn, track_id, record.pairs)
+                if will_link_art:
+                    arts = [
+                        (upsert_art(conn, img.data, img.mime), img.picture_type, img.description)
+                        for img in kept
+                    ]
+                    replace_track_art(conn, track_id, arts)
+        except sqlite3.IntegrityError as err:
+            stats.skipped_invalid += 1
+            stats.invalid.append((record.key, str(err)))
+            return
 
     if will_link_art:
         stats.art_linked += 1
     stats.synced += 1
 
 
-def sync_files(conn, records, *, dry_run=False, stats=None):
+def sync_files(conn, records, *, dry_run=False, stats=None, merge=False):
     """Sync an iterable of ``Record``s, returning the ``SyncStats``. Pass
     ``stats`` to accumulate into a caller-seeded instance (e.g. beets pre-counts
     unreadable art); otherwise a fresh one is created. Caller owns the
@@ -84,5 +113,5 @@ def sync_files(conn, records, *, dry_run=False, stats=None):
     if stats is None:
         stats = SyncStats()
     for record in records:
-        sync_one(conn, record, stats, dry_run=dry_run)
+        sync_one(conn, record, stats, dry_run=dry_run, merge=merge)
     return stats

python_musefs-1.1.0.dist-info/METADATA

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: python-musefs
+Version: 1.1.0
+Summary: Shared musefs SQLite-store contract for the beets and Picard plugins
+Author: Conor Futro
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Sohex/musefs
+Project-URL: Repository, https://github.com/Sohex/musefs
+Project-URL: Issues, https://github.com/Sohex/musefs/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# python-musefs
+
+The full guide now lives in the musefs documentation site:
+
+- **Published:** <https://sohex.github.io/musefs/integrations/python-musefs.html>
+- **In-repo source:** [`docs/src/integrations/python-musefs.md`](../../docs/src/integrations/python-musefs.md)

python_musefs-1.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+musefs_common/__init__.py,sha256=fA6mE93fSYBjObMMeCjDKnOnmETrbc2xt1TrdMKJ5cE,1505
+musefs_common/constants.py,sha256=M0zS6YCnYdE_JjIbvxg-GhbYdfbe30ccKZvbZ1WTZZ8,302
+musefs_common/contract.py,sha256=tUflCxfFiaIzJiTqYL-o-bjKNH_s91EHkC2amk8sKxE,1472
+musefs_common/errors.py,sha256=OUBXzpa4q7TPYvFFiTyoIfRC3SGRRgZcpXlr43RP0jk,1456
+musefs_common/paths.py,sha256=dE3wwop5mRxoJ8RhdYwTIZpX4MPaUUw2LJhjcxApOIA,649
+musefs_common/scan.py,sha256=C20WmDWhGJ3FqjNOssLsoxtx0KgsTg9PPlrGPhOkE2E,1662
+musefs_common/schema.py,sha256=HFo2qG0xtTgBVgxm8hCjVQAjxTeCqaPvYklw08rhOoU,11853
+musefs_common/store.py,sha256=pUNlad1FITJCKwBNy4EH98jQQTmb9Ao5ggLlgo99XwU,12769
+musefs_common/sync.py,sha256=iXlekqpuRfBEoOrjvujnZQYfDgs3afENaPU0n3D59nQ,4200
+python_musefs-1.1.0.dist-info/licenses/LICENSE,sha256=4VbfzhgMpuFrhFjBCtLptGV_bzCj_gML9y_9o2Tr1OQ,1068
+python_musefs-1.1.0.dist-info/METADATA,sha256=R3v-Qu_1-kc0JKc_xPlgIcZPhNuzcjIo6rvuZ8gAjT8,1012
+python_musefs-1.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+python_musefs-1.1.0.dist-info/top_level.txt,sha256=ejWexGk95-s11kZnTFwg1T3iG_dFcaE4vhcLnL3t3Ak,14
+python_musefs-1.1.0.dist-info/RECORD,,

python_musefs-0.0.1.dist-info/METADATA

@@ -1,73 +0,0 @@
-Metadata-Version: 2.4
-Name: python-musefs
-Version: 0.0.1
-Summary: Shared musefs SQLite-store contract for the beets and Picard plugins
-Author: Conor Futro
-License-Expression: MIT
-Project-URL: Homepage, https://github.com/Sohex/musefs
-Project-URL: Repository, https://github.com/Sohex/musefs
-Project-URL: Issues, https://github.com/Sohex/musefs/issues
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: Operating System :: POSIX
-Classifier: Programming Language :: Python :: 3
-Classifier: Topic :: Multimedia :: Sound/Audio
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Provides-Extra: test
-Requires-Dist: pytest>=7; extra == "test"
-Dynamic: license-file
-
-# python-musefs
-
-The shared store-contract library behind the [beets](../beets/README.md),
-[Picard](../picard/README.md), and [Lidarr](../lidarr/README.md) musefs
-plugins. It is the single source of truth for how a plugin writes the musefs
-SQLite store: the schema-version check, the `tags` / `art` / `track_art`
-writes, sha256 art content-addressing, the `realpath_key` path normalization,
-the `musefs scan` shell-out (`run_scan`), and the per-file sync write-loop
-(`Record` / `sync_files`).
-
-Field mapping stays in each plugin — beets expands multi-valued
-`genres`/`composers` into one tag each, Picard takes the first value — so this
-library deliberately does not own it.
-
-## Consumers
-
-- **beets** depends on this package via pip (`contrib/beets/pyproject.toml`).
-- **Picard** cannot pip-install plugin dependencies, so the package is
-  **vendored** into `contrib/picard/musefs/_common/` by
-  `vendor_to_picard.py`. After any change here, re-run:
-
-  ```bash
-  python contrib/python-musefs/vendor_to_picard.py
-  ```
-
-  The Picard test `tests/test_vendor_sync.py` fails if the committed copy drifts.
-- **Lidarr** depends on this package via pip (`contrib/lidarr/pyproject.toml`).
-
-## Schema coupling
-
-`musefs_common/schema.py` (`SCHEMA_SQL`, `USER_VERSION`) is **generated** from
-the Rust migrations in `musefs-db/src/schema.rs` — do not edit it by hand.
-`EXPECTED_USER_VERSION` (in `constants.py`) derives from it. When the Rust
-schema bumps, regenerate and re-vendor:
-
-```bash
-MUSEFS_REGEN_SCHEMA_PY=1 cargo test -p musefs-db schema_py
-python contrib/python-musefs/vendor_to_picard.py
-```
-
-A `musefs-db` unit test fails if the generated file drifts. This is all
-independent of the package's own `__version__` (its release SemVer).
-
-## Tests
-
-```bash
-cd contrib/python-musefs
-python -m venv .venv && source .venv/bin/activate
-pip install -e ".[test]"
-python -m pytest -v
-ruff check . && ruff format --check .
-```

python_musefs-0.0.1.dist-info/RECORD

@@ -1,14 +0,0 @@
-musefs_common/__init__.py,sha256=hV6UKgOJ4n98n-2OR9LVTSE3Yhhz_E4MSRERUzQOpqM,1265
-musefs_common/constants.py,sha256=M0zS6YCnYdE_JjIbvxg-GhbYdfbe30ccKZvbZ1WTZZ8,302
-musefs_common/contract.py,sha256=tUflCxfFiaIzJiTqYL-o-bjKNH_s91EHkC2amk8sKxE,1472
-musefs_common/errors.py,sha256=OUBXzpa4q7TPYvFFiTyoIfRC3SGRRgZcpXlr43RP0jk,1456
-musefs_common/paths.py,sha256=dE3wwop5mRxoJ8RhdYwTIZpX4MPaUUw2LJhjcxApOIA,649
-musefs_common/scan.py,sha256=2rOFQQt0pE1uhF31huSwRtapU0QK3fFDGbscynwLtRE,1453
-musefs_common/schema.py,sha256=Y9zE25PEFX-mVJzULT2aOi5AiS10pYp6_y50oirrrvo,8716
-musefs_common/store.py,sha256=O3HNrq5clPMcWYGDiiKhfbDpBB3u8UNtpvIcqWP6_Gs,4316
-musefs_common/sync.py,sha256=aCK0zacYZ0B5GWlS-MwOdMf4j6XutX7wi62QxZzXqP8,2835
-python_musefs-0.0.1.dist-info/licenses/LICENSE,sha256=4VbfzhgMpuFrhFjBCtLptGV_bzCj_gML9y_9o2Tr1OQ,1068
-python_musefs-0.0.1.dist-info/METADATA,sha256=_n-iNLP2PZQpW-JzfE44FL-y9fwnlu5iuS-5LqUpCk8,2664
-python_musefs-0.0.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-python_musefs-0.0.1.dist-info/top_level.txt,sha256=ejWexGk95-s11kZnTFwg1T3iG_dFcaE4vhcLnL3t3Ak,14
-python_musefs-0.0.1.dist-info/RECORD,,