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

musefs_common/__init__.py

@@ -13,6 +13,7 @@ from .scan import run_scan
 from .store import (
     check_schema_version,
     connect,
+    merge_tags,
     prune_missing,
     replace_tags,
     replace_track_art,
@@ -22,7 +23,7 @@ from .store import (
 )
 from .sync import ArtImage, Record, SyncStats, sync_files, sync_one
 
-__version__ = "0.1.0"
+__version__ = "1.0.0"
 
 __all__ = [
     "EXPECTED_USER_VERSION",
@@ -36,6 +37,7 @@ __all__ = [
     "check_schema_version",
     "track_id_for_path",
     "prune_missing",
+    "merge_tags",
     "replace_tags",
     "upsert_art",
     "replace_track_art",

musefs_common/schema.py

@@ -5,146 +5,21 @@
 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
-);
-
-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)
-);
-
-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
-);
-
-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)
-);
-
-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)
-    WHERE id = NEW.track_id;
-END;
-CREATE TRIGGER tags_au AFTER UPDATE ON tags 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 tags_ad AFTER DELETE ON tags 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 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;
-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);
-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;
-
--- Self-pruning ring: writers maintain it; the mount's read-only connections
--- never need to. Deletes only from the old end, so retained seqs stay contiguous.
-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;
-
-DROP TABLE track_art;
-DROP TABLE tags;
-DROP TABLE art;
-DROP TABLE tracks;
-
-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 >= 0),
+    CHECK (backing_mtime_ns >= 0),
     CHECK (content_version >= 0),
     CHECK (updated_at >= 0),
     CHECK (audio_offset + audio_length <= backing_size)
@@ -158,7 +33,12 @@ 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(value) <= 262144),
+    CHECK (value_blob IS NULL OR length(value_blob) <= 16711680)
 );
 
 CREATE TABLE art (
@@ -172,7 +52,9 @@ CREATE TABLE art (
     CHECK (byte_len = length(data)),
     CHECK (length(sha256) = 64),
     CHECK (width IS NULL OR width >= 0),
-    CHECK (height IS NULL OR height >= 0)
+    CHECK (height IS NULL OR height >= 0),
+    CHECK (length(mime) <= 255),
+    CHECK (byte_len <= 16711680)
 );
 
 CREATE TABLE track_art (
@@ -183,18 +65,35 @@ CREATE TABLE track_art (
     ordinal      INTEGER NOT NULL DEFAULT 0,
     PRIMARY KEY (track_id, ordinal),
     CHECK (picture_type BETWEEN 0 AND 20),
-    CHECK (ordinal >= 0)
+    CHECK (ordinal >= 0),
+    CHECK (length(description) <= 1024)
 );
 
-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;
+-- 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
+);
 
-DROP TABLE _m4_track_art;
-DROP TABLE _m4_tags;
-DROP TABLE _m4_art;
-DROP TABLE _m4_tracks;
+-- 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,
@@ -237,7 +136,70 @@ 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;
+
+-- Self-pruning ring: writers maintain it; the mount's read-only connections
+-- never need to. Deletes only from the old end, so retained seqs stay contiguous.
+CREATE TRIGGER track_changes_prune AFTER INSERT ON track_changes BEGIN
+    DELETE FROM track_changes WHERE seq <= NEW.seq - 8192;
+END;
+
+-- 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;
+
+-- 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;
+
+-- 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;
+
+-- 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;
 """
 
-USER_VERSION = 4
+USER_VERSION = 1

musefs_common/store.py

@@ -1,3 +1,4 @@
+import contextlib
 import hashlib
 import os
 import sqlite3
@@ -5,6 +6,64 @@ import sqlite3
 from .constants import EXPECTED_USER_VERSION
 from .errors import SchemaMismatch
 
+# 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."""
@@ -54,20 +113,58 @@ 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)
+
+        for key in set(by_key) | set(delete_keys or ()):
+            conn.execute(
+                "DELETE FROM tags WHERE track_id = ? AND key = ? 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 +204,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

@@ -3,7 +3,14 @@ from __future__ import annotations
 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 +33,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
@@ -42,10 +50,12 @@ class SyncStats:
         )
 
 
-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."""
@@ -63,20 +73,24 @@ 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)
+        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)
 
     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 +98,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.0.0.dist-info/METADATA

@@ -0,0 +1,274 @@
+Metadata-Version: 2.4
+Name: python-musefs
+Version: 1.0.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 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.
+
+## Writing a plugin
+
+A plugin turns host metadata (a beets item, a Picard track, a Lidarr release)
+into musefs store writes. This library owns every store-touching step except the
+field mapping: you supply the per-file tag and art values, and it handles the
+schema check, the scan shell-out, content-addressing, and the write loop.
+
+### The write flow
+
+The canonical order is **connect → check_schema_version → run_scan → build
+`Record`s → sync_files → commit → prune_missing**. The caller owns the
+transaction — nothing here commits for you.
+
+```python
+from musefs_common import (
+    SCAN_TIMEOUT_SECONDS,
+    ArtImage,
+    Record,
+    check_schema_version,
+    connect,
+    prune_missing,
+    realpath_key,
+    run_scan,
+    sync_files,
+)
+
+
+def sync(db_path, files, *, musefs_bin="musefs"):
+    # `run_scan` creates the DB if absent and fills the structural columns a
+    # plugin cannot compute (format, audio offset/length, backing size/mtime).
+    # On a brand-new store it must precede `connect`, which has nothing to open
+    # until the scan has created the file.
+    run_scan(musefs_bin, db_path, files, timeout=SCAN_TIMEOUT_SECONDS)
+
+    conn = connect(db_path)
+    try:
+        check_schema_version(conn)  # raises SchemaMismatch on a version skew
+
+        records = [
+            Record(
+                key=realpath_key(path),  # MUST equal the scanned row's backing_path
+                pairs=[("artist", artist), ("title", title)],
+                art=[ArtImage(data=cover, mime="image/jpeg")] if cover else None,
+            )
+            for path, artist, title, cover in host_metadata(files)
+        ]
+
+        stats = sync_files(conn, records)  # full-replace of plugin text tags
+        conn.commit()  # the caller commits
+
+        prune_missing(conn)  # drop rows whose backing file vanished
+        conn.commit()
+        return stats
+    finally:
+        conn.close()
+```
+
+For a dry run, pass `dry_run=True` to `sync_files` and `conn.rollback()` instead
+of committing — `SyncStats` still reports what *would* change.
+
+`run_scan` raises `ScanError` (`kind` ∈ `{"not_found", "timeout", "failed"}`)
+and `check_schema_version` raises `SchemaMismatch`; a host adapter formats its
+own user-facing message from the exception attributes (see the beets plugin's
+`_scan_user_error`).
+
+### The `Record` shape
+
+One `Record` per file is your primary output. Its fields:
+
+| field | type | meaning |
+| ----- | ---- | ------- |
+| `key` | `str` | The file's identity in the store. **Must** be `realpath_key(path)` — the canonicalized absolute path the scanner stored as `backing_path`. A `key` that matches no scanned row is silently counted in `SyncStats.skipped`, not written. |
+| `pairs` | `list[tuple[str, str]]` | Ordered `(tag_key, value)` text tags. Duplicate keys are allowed and get contiguous ordinals (multi-valued tags). |
+| `art` | `list[ArtImage] \| None` | Embedded pictures, already resolved to bytes. `None`/`[]` leaves existing art untouched. |
+| `delete_keys` | `list[str] \| None` | Merge mode only: keys to clear without rewriting (see below). Ignored in replace mode. |
+
+`ArtImage(data, mime, picture_type=3, description="")` is one picture: `data` is
+raw bytes, `picture_type` is the ID3/FLAC type (3 = front cover). Images larger
+than `MAX_ART_BYTES` are dropped and counted in `SyncStats.skipped_art`.
+
+If every record lands in `skipped`, the `key`s and the scan target disagree —
+both must canonicalize the same way, so scan the *real* files (not a symlink
+farm) and build keys with `realpath_key`.
+
+### Merge vs. replace, and sticky deletes
+
+`sync_files(..., merge=False)` (the default) **replaces** every plugin-owned
+text tag on each track: it clears all `value_blob IS NULL` rows and rewrites
+them from `record.pairs`. Scanner-written binary tags always survive.
+
+`sync_files(..., merge=True)` **merges**: only the keys named in `record.pairs`
+and `record.delete_keys` are touched; other scan-seeded text tags stay. Use
+merge when your plugin owns a *subset* of the tags and must not clobber the
+rest. The store does not remember which keys you manage — **you** track your
+managed-key set out of band (the contract is explicit that the store is not the
+place for plugin state).
+
+When the user removes a tag in the host, merge mode needs to delete the
+now-orphaned store row. The beets plugin solves this with an **accumulating
+managed-key set** (the `musefs_managed` pattern), worth copying:
+
+- Persist, per file, the set of keys you have *ever* written (beets uses a
+  flexattr; any per-file host metadata works).
+- On each sync, `delete_keys = previous_managed − keys_written_now`, and the new
+  persisted set is `previous_managed ∪ keys_written_now`.
+- A key you stop writing becomes a tombstone: it keeps getting deleted on every
+  sync until you write it again. Persist the managed set **only after** the store
+  commit succeeds, so a failed sync doesn't lose the record of what you owe.
+
+See `contrib/beets/beetsplug/_core.py` (`build_records` / `persist_managed`) for
+the reference implementation.
+
+### Store invariants you must respect
+
+The full external-writer contract is in
+[ARCHITECTURE.md](../../ARCHITECTURE.md#the-external-writer-contract). The rules
+that bite plugin authors:
+
+- **Write only `tags`, `art`, and `track_art`.** The scanner owns the structural
+  columns of `tracks` and all of `structural_blocks`; never compute them — run
+  `musefs scan` (i.e. `run_scan`). `CHECK` constraints reject malformed
+  structural shapes at commit, so you cannot persist them anyway.
+- **Binary tags survive a sync.** `merge_tags` / `replace_tags` scope their
+  deletes to text rows (`value_blob IS NULL`), so the write loop never wipes
+  scanner-written binary tags. You may write binary tags yourself too — a binary
+  row carries its payload in `value_blob` and must leave `value` empty (the only
+  `CHECK` on the row).
+- **Content-address art** through `upsert_art` (sha256 de-dup) rather than
+  inserting `art` rows by hand; `sync_files` does this for you.
+- **Art rows are immutable.** A trigger rejects in-place updates of an
+  `art` row's content columns (`data`, `sha256`, `mime`, `byte_len`, `width`,
+  `height`). To change a track's art, insert a new content-addressed row via
+  `upsert_art` and relink it via `replace_track_art`.
+- **Path layout is just a tag.** To drive a reorganized mount, write your
+  computed relative path into a custom tag (e.g. `beets_path`) and mount with
+  `--template '$!{beets_path}'`. musefs sanitizes each path segment, so a writer
+  cannot inject traversal.
+
+## API reference
+
+Everything in `__all__`, imported from the top-level `musefs_common` package.
+
+**Connection & schema**
+
+- `connect(db_path)` → `sqlite3.Connection` — open with a 5s busy timeout and
+  `foreign_keys = ON`.
+- `check_schema_version(conn)` — raise `SchemaMismatch` unless the store's
+  `user_version` equals `EXPECTED_USER_VERSION`.
+
+**Scanning**
+
+- `run_scan(binary, db_path, target, *, timeout=None)` — shell out to `musefs
+  scan`; `target` is one path or an iterable, all scanned under one process.
+  Creates the DB if absent. Raises `ScanError`.
+
+**Building records**
+
+- `Record(key, pairs=[], art=None, delete_keys=None)` — one file's sync inputs
+  (see *The `Record` shape*).
+- `ArtImage(data, mime, picture_type=3, description="")` — one embedded picture.
+- `realpath_key(path)` — canonical path string matching the scanner's
+  `backing_path`; accepts `str`/`bytes`, returns `str`.
+
+**Writing**
+
+- `sync_files(conn, records, *, dry_run=False, stats=None, merge=False)` →
+  `SyncStats` — the write loop; caller owns the transaction. Pass `stats` to
+  accumulate into a caller-seeded instance.
+- `sync_one(conn, record, stats, *, dry_run=False, merge=False)` — sync a single
+  record into a caller-supplied `SyncStats`.
+- `SyncStats` — `synced` / `skipped` / `art_linked` / `skipped_art` counters,
+  plus `.summary()`.
+
+**Lower-level store helpers** (called for you by `sync_files`; use directly only
+for a custom write loop)
+
+- `track_id_for_path(conn, key)` → track id or `None`.
+- `merge_tags(conn, track_id, managed_pairs, delete_keys)` — per-key replace of
+  plugin-managed text tags, leaving unmanaged text rows intact.
+- `replace_tags(conn, track_id, pairs)` — replace all plugin-owned text tags.
+- `upsert_art(conn, data, mime)` → art id — content-address `data` by sha256,
+  inserting only if new.
+- `replace_track_art(conn, track_id, arts)` — replace a track's `track_art`
+  rows; `arts` is `[(art_id, picture_type, description), …]`.
+- `sniff_mime(data, path)` — image mime from magic bytes, falling back to file
+  extension.
+- `prune_missing(conn, track_ids=None)` → count — delete tracks whose backing
+  file no longer exists (every track, or just `track_ids`).
+
+**Constants**
+
+- `EXPECTED_USER_VERSION` — schema `user_version` this library targets.
+- `MAX_ART_BYTES` — per-image art cap; larger images are skipped.
+- `SCAN_TIMEOUT_SECONDS` — default wall-clock cap for one `run_scan`.
+
+**Exceptions**
+
+- `SchemaMismatch(found)` — schema-version skew; `.found` is the DB's version.
+- `ScanError(kind, *, binary, target, …)` — a `musefs scan` failure; `.kind` ∈
+  `{"not_found", "timeout", "failed"}`, with context attributes for messaging.
+
+## 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-1.0.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+musefs_common/__init__.py,sha256=e8xfwhe770V9_gnoJEjNqk4lJmpHcqaLgojSo9-MXks,1299
+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=Blab4CIiFIQaaqh5IjMpUR0jD01xU0CFrl4AQQM3yKM,8511
+musefs_common/store.py,sha256=nk34ghVlqMsF__PozYZHCu8Xd0QsoChl9bGTFsrdbwE,8721
+musefs_common/sync.py,sha256=Rh65b69d92FLxNwN4Z939GmfUiZ1Sfw7F_vL31i4VtM,3375
+python_musefs-1.0.0.dist-info/licenses/LICENSE,sha256=4VbfzhgMpuFrhFjBCtLptGV_bzCj_gML9y_9o2Tr1OQ,1068
+python_musefs-1.0.0.dist-info/METADATA,sha256=F2pO6iiY0rn4HLaefxYYo73hc7dbc_KSgWWzvooCXm4,11971
+python_musefs-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+python_musefs-1.0.0.dist-info/top_level.txt,sha256=ejWexGk95-s11kZnTFwg1T3iG_dFcaE4vhcLnL3t3Ak,14
+python_musefs-1.0.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,,