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
@@ -45,6 +45,36 @@
 #   Format: DATE|RAMDISK_USED_GB|FLIP_COUNT|RAM_SESSION_COUNT|SSD_SESSION_COUNT|FILES_CLEANED
 #
 # ==============================================================================================
+# DESIGN PRINCIPLES
+# ==============================================================================================
+#
+# Flip the Destination, Never Move the Sessions
+#   Switching targets only repoints the symlink so NEW sessions land elsewhere. Existing
+#   transcodes keep writing to the path they opened and drain naturally. Moving files
+#   mid-transcode would break every stream currently playing, which is the opposite of
+#   what pressure relief is for.
+#
+# Asymmetric Thresholds
+#   Flipping away happens at RAMDISK_WARN_GB, flipping back at RAMDISK_LOW_GB — two
+#   separate values, not one. A single threshold would flip on every fluctuation around
+#   it; the gap between them is what makes the decision stable under load.
+#
+# Safety Checks Are Unconditional
+#   Symlink, ramdisk presence, SSD presence, transcoding-temp and permissions are all
+#   verified on every run in every mode, including the fixed ramdisk/ssd modes. Mode
+#   controls where transcodes go, not whether the plumbing gets checked.
+#
+# Degrade Toward the Fallback
+#   Every failure path resolves toward SSD, never toward an unusable target. A vanished
+#   ramdisk flips to SSD immediately rather than leaving sessions pointed at nothing —
+#   transcoding slower is recoverable, transcoding nowhere is not.
+#
+# Observe Without Emby
+#   With Emby down, threshold logic is skipped but the symlink is still verified. There
+#   is no session pressure to react to, and acting on stale usage would flip the target
+#   for sessions that no longer exist.
+#
+# ==============================================================================================
 # OPERATIONAL SAFEGUARDS
 # ==============================================================================================
 #
@@ -55,9 +85,6 @@
 # Docker Timeout
 #   DOCKER_TIMEOUT caps all docker calls against a hung daemon.
 #
-# Notification Validated
-#   platform_require_cmd confirms the notify script is present before use.
-#
 # Silent by Default
 #   Runs every 7 minutes — only speaks when something changes or needs attention.
 #