Complete the header template across Partnership, Kernel, Deployment and Plugin

Finishes the pass: every script now documents its safeguards, and the deliberate absences in the sourced libraries are recorded so they are not "corrected" later.
2026-08-01 22:44:23 -04:00
parent 5c4f8db497
commit c377ddfcca
24 changed files with 1237 additions and 32 deletions
@@ -13,6 +13,58 @@
 # RAM-speed reads and auto-cleared on reboot.
 #
 # ==============================================================================================
+# OPERATIONAL MODEL
+# ==============================================================================================
+#
+# A one-line shim: exec php on api_cache_writer.php in the same directory.
+#
+# All logic lives in the PHP, because the payload builders (vv_monitor_*, vv_arrs_*) are PHP
+# functions shared with the API endpoints. Reimplementing them in bash would mean two
+# implementations of the same payload drifting apart.
+#
+# ==============================================================================================
+# DESIGN PRINCIPLES
+# ==============================================================================================
+#
+# A Shim, Not a Program
+#   This file exists only because the scheduler runs shell scripts and the work is PHP. It
+#   deliberately contains no logic — anything added here would be logic the API endpoints
+#   do not share, which is exactly the drift it exists to prevent.
+#
+# Same Builders as the Live API
+#   The cache is written by the same functions that serve a live request, so a cached
+#   response and a ?live=1 response cannot disagree in shape.
+#
+# ==============================================================================================
+# OPERATIONAL SAFEGUARDS
+# ==============================================================================================
+#
+# No Root, No Lock — Deliberate
+#   Writes only to /tmp/vv_cache as whatever user the scheduler runs as, and a stale cache
+#   is self-correcting on the next minute's run. There is no privileged operation to gate
+#   and no state worth locking: a torn cache file is replaced within 60 seconds, and every
+#   reader already falls back to a live call when the cache is missing or unparseable.
+#
+# Failure Is Non-Fatal by Design
+#   If the PHP fails, the cache simply is not refreshed. Pages fall back to live API calls —
+#   slower, but correct. This script must never be able to take the UI down.
+#
+# ==============================================================================================
+# CONFIGURATION
+# ==============================================================================================
+#
+# None. Cache location and payload contents are owned by api_cache_writer.php and
+# include/config.php (VV_CACHE_DIR). Nothing is configurable from this file.
+#
+# ==============================================================================================
+# RUNTIME MODES
+# ==============================================================================================
+#
+# api_cache_writer.sh
+#     Refresh the monitor and arrs caches once. No flags — the PHP takes no arguments and
+#     there is nothing to preview, since the only effect is replacing a regenerable cache.
+#
+# ==============================================================================================

 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 php "$SCRIPT_DIR/api_cache_writer.php"