Bring script headers onto the template and close safeguard gaps

Headers claimed protections the code never had, and several destructive paths had no guard against a collapsed config value.
2026-08-01 20:37:59 -04:00
parent cdce877601
commit e8b114094a
78 changed files with 3301 additions and 277 deletions
@@ -29,6 +29,28 @@
 # Emby's config path is detected from the Docker mount — no hardcoded paths.
 #
 # ==============================================================================================
+# DESIGN PRINCIPLES
+# ==============================================================================================
+#
+# Diagnose, Never Repair
+#   The script reports which databases fail integrity_check and stops there. SQLite
+#   "repair" means dumping and rebuilding, which silently discards whatever rows were
+#   corrupt — an outcome nobody should get without deciding to. The remediation steps
+#   are printed instead, for a human to run against a backup.
+#
+# Stop Emby Before Reading
+#   integrity_check against a live database gives unreliable answers and can itself
+#   contend with Emby's writes. Emby is stopped for the duration and restarted after,
+#   so the check runs against a quiescent file.
+#
+# Always Restart, Even on Failure
+#   Emby is brought back up regardless of what the check found, and an EXIT trap armed
+#   before it is stopped restores it even if this script dies partway through. It is
+#   disarmed only once the normal restart has run. Leaving the media server down because
+#   a diagnostic reported a problem turns an investigation into an outage — and the
+#   original running state is honoured, so an Emby that was already stopped stays stopped.
+#
+# ==============================================================================================
 # OPERATIONAL SAFEGUARDS
 # ==============================================================================================
 #