Merge pull request 'fix(media): verify read the library the way the servers write it' (#103) from fix/media-verify-wal-read into main

tests/media_audiobooks.bats

@@ -228,6 +228,51 @@ PY
     [ "$(wc -l < "$BATS_TEST_TMPDIR/exp.tsv")" -eq 1 ]   # header only
 }
 
+# wal_fresh DB ROOT OUT — a row Plex matched during a scan and committed, but
+# has not checkpointed: the normal state of a library being walked. The holder
+# connection stops the WAL folding into the main file when the writer closes,
+# and the census runs as a real subprocess against those same files.
+wal_fresh() {
+    local db="$1" root="$2" out="$3"
+    python3 - "$db" "$root" "$out" "$CENSUS" <<'PY'
+import sqlite3, subprocess, sys
+db, root, out, census = sys.argv[1:5]
+w = sqlite3.connect(db)
+w.execute("pragma journal_mode=wal")
+w.execute("pragma wal_autocheckpoint=0")
+w.commit()
+w.execute("pragma wal_checkpoint(truncate)")     # the rows so far are on disk
+holder = sqlite3.connect(db)                     # last close would checkpoint
+ar = w.execute('insert into metadata_items (parent_id, metadata_type, title,'
+               ' year, "index", deleted_at) VALUES (NULL, 8, ?, NULL, NULL, NULL)',
+               ("Fresh Narrator",)).lastrowid
+al = w.execute('insert into metadata_items (parent_id, metadata_type, title,'
+               ' year, "index", deleted_at) VALUES (?, 9, ?, ?, NULL, NULL)',
+               (ar, "Fresh Book", 2026)).lastrowid
+mi = w.execute('insert into metadata_items (parent_id, metadata_type, title,'
+               ' year, "index", deleted_at) VALUES (?, 10, ?, NULL, ?, NULL)',
+               (al, "Fresh Chapter", 1)).lastrowid
+it = w.execute("insert into media_items (metadata_item_id, deleted_at)"
+               " VALUES (?, NULL)", (mi,)).lastrowid
+w.execute("insert into media_parts (media_item_id, file, deleted_at)"
+          " VALUES (?, ?, NULL)", (it, root + "/Fresh/01.mp3"))
+w.commit()
+sys.exit(subprocess.run([sys.executable, census, "audiobooks", "--root", root,
+                         "--db", db, "--out", out]).returncode)
+PY
+}
+
+@test "the census exports a row the scanner committed but has not checkpointed" {
+    DB="$BATS_TEST_TMPDIR/plex.db"
+    db_with_part "$DB" "$BATS_TEST_TMPDIR/Audiobooks/Old/01.mp3" \
+        "Old Narrator" "Old Book" 1990 1 "Old Chapter"
+    run wal_fresh "$DB" "$BATS_TEST_TMPDIR/Audiobooks" "$BATS_TEST_TMPDIR/exp.tsv"
+    [ "$status" -eq 0 ]
+    [ "$(wc -l < "$BATS_TEST_TMPDIR/exp.tsv")" -eq 3 ]   # header + both rows
+    tail -1 "$BATS_TEST_TMPDIR/exp.tsv" \
+        | grep -q "^$BATS_TEST_TMPDIR/Audiobooks/Fresh/01\.mp3	Fresh Narrator	Fresh Book	2026	1	Fresh Chapter$"
+}
+
 # -------------------------------------------------------------------- the plan
 
 @test "a matched chapter files under its narrator and its book, name untouched" {

tests/media_verify.bats

@@ -195,7 +195,7 @@ setup() {
         --share "$SHARE" --container /data
     [ "$status" -eq 1 ]
     [ "${lines[3]}" = "missing from the DB: 2" ]
-    [ "${lines[4]}" = "missing by extension: .log 1, .mkv 1" ]
+    [[ "$output" == *"missing by extension: .log 1, .mkv 1"* ]]
 }
 
 @test "--ignore-ext keeps a file the server never indexes out of the verdict" {
@@ -208,5 +208,75 @@ setup() {
     [ "$status" -eq 0 ]
     [ "${lines[1]}" = "landed: 1" ]
     [ "${lines[3]}" = "missing from the DB: 0" ]
-    [ "${lines[4]}" = "not indexed (extension ignored): 1" ]
+    [[ "$output" == *"not indexed (extension ignored): 1"* ]]
+}
+
+# wal_case <db> — a Jellyfin database whose NEW row lives only in the
+# write-ahead log: the server has committed the rename but not checkpointed it,
+# which is the normal state of a library a scan is writing. The holder
+# connection keeps the WAL from folding into the main file, and the verifier
+# runs as a real subprocess so it faces the same files Plex and Jellyfin leave.
+wal_case() {
+    python3 - "$JFDB" "$JOURNAL" "$SHARE" "$VERIFY" <<'PY'
+import sqlite3, subprocess, sys
+db, journal, share, verify = sys.argv[1:5]
+w = sqlite3.connect(db)
+w.execute("pragma journal_mode=wal")
+w.execute("pragma wal_autocheckpoint=0")
+w.execute("insert into BaseItems (Path, Type) values ('/data/Movies/Old.mkv', 'x')")
+w.commit()
+w.execute("pragma wal_checkpoint(truncate)")
+holder = sqlite3.connect(db)  # last-connection close would checkpoint
+w.execute("update BaseItems set Path='/data/Movies/Old/Old.mkv'")
+w.commit()
+r = subprocess.run([sys.executable, verify, "--journal", journal,
+                    "--db-kind", "jellyfin", "--db", db,
+                    "--share", share, "--container", "/data"],
+                   capture_output=True, text=True)
+print(r.stdout, end="")
+sys.exit(r.returncode)
+PY
+}
+
+@test "a row the server committed but has not checkpointed is proof, not a miss" {
+    move_row "$SHARE/Movies/Old.mkv" "$SHARE/Movies/Old/Old.mkv"
+    run wal_case
+    [ "$status" -eq 0 ]
+    [ "${lines[1]}" = "landed: 1" ]
+    [ "${lines[3]}" = "missing from the DB: 0" ]
+}
+
+# The DB alone cannot tell a lost file from a sidecar: both are "no row at the
+# destination". The tool therefore stats the two paths and separates the classes
+# the runbook names, so an operator never reads a `.pdf` as a lost film or,
+# worse, reads a real loss as a sidecar.
+@test "a file the database does not name that still sits at src is the pass's own damage" {
+    mkdir -p "$SHARE/Movies"
+    echo film > "$SHARE/Movies/Old.mkv"
+    move_row "$SHARE/Movies/Old.mkv" "$SHARE/Movies/Old/Old.mkv"
+
+    run python3 "$VERIFY" --journal "$JOURNAL" --db-kind jellyfin --db "$JFDB" \
+        --share "$SHARE" --container /data
+    [ "$status" -eq 1 ]
+    [ "${lines[3]}" = "missing from the DB: 1" ]
+    [ "${lines[4]}" = "  on disk at dst, no row names it: 0" ]
+    [ "${lines[5]}" = "  REAL — file still at src: 1" ]
+    [ "${lines[6]}" = "  gone — at neither path: 0" ]
+    [[ "$output" == *"real: $SHARE/Movies/Old.mkv"* ]]
+}
+
+@test "a file at neither path is gone, and a file at dst the server ignores is not a loss" {
+    move_row "$SHARE/Movies/Gone.mkv" "$SHARE/Movies/Gone/Gone.mkv"
+    mkdir -p "$SHARE/Movies/Sidecar"
+    echo cover > "$SHARE/Movies/Sidecar/cover.jpg"
+    move_row "$SHARE/Movies/Album/cover.jpg" "$SHARE/Movies/Sidecar/cover.jpg"
+
+    run python3 "$VERIFY" --journal "$JOURNAL" --db-kind jellyfin --db "$JFDB" \
+        --share "$SHARE" --container /data
+    [ "$status" -eq 1 ]
+    [ "${lines[3]}" = "missing from the DB: 2" ]
+    [ "${lines[4]}" = "  on disk at dst, no row names it: 1" ]
+    [ "${lines[5]}" = "  REAL — file still at src: 0" ]
+    [ "${lines[6]}" = "  gone — at neither path: 1" ]
+    [[ "$output" == *"gone: $SHARE/Movies/Gone/Gone.mkv"* ]]
 }