diff --git a/AI/ai_token_sync.sh b/AI/ai_token_sync.sh index 66c3c49..34d5419 100755 --- a/AI/ai_token_sync.sh +++ b/AI/ai_token_sync.sh @@ -30,6 +30,31 @@ # fetches its own data controls its own freshness rather than depending on the partner's cron. # # ============================================================================================== +# DESIGN PRINCIPLES +# ============================================================================================== +# +# A missing file means unknown, never zero. +# The whole point of the tab reporting "not collected here" is that it is a different claim +# from "this partner spent nothing". If a partner is dark, unreachable or has never run a turn, +# there is simply no cache file, and the reader is expected to say so rather than render a 0 +# that looks like a measurement. +# +# The reader pulls; nobody pushes. +# conf_sync.sh pushes as well, because a partner that cannot reach us still needs our +# credentials. Nothing here is needed by anyone else, so a host that wants fleet totals fetches +# them and owns its own freshness instead of depending on someone else's cron having run. +# +# RAM, not flash. +# The cache lands in tmpfs. It is a copy of a file that already exists on the partner and is +# rebuilt on the next pass, so writing it to flash would cost wear for something that is never +# worth surviving a reboot. +# +# Same shape as conf_sync.sh, deliberately. +# Resolve over Tailscale, scp one small file into a tmpfs cache, let a missing file mean +# unknown. A second transport pattern for a second small file would be a second set of +# failure modes to learn. +# +# ============================================================================================== # OPERATIONAL SAFEGUARDS # ============================================================================================== # diff --git a/Plugin/unraid/System_Essentials/pcie_aer_quiet.sh b/Plugin/unraid/System_Essentials/pcie_aer_quiet.sh index 21a203d..50ffe5a 100755 --- a/Plugin/unraid/System_Essentials/pcie_aer_quiet.sh +++ b/Plugin/unraid/System_Essentials/pcie_aer_quiet.sh @@ -24,6 +24,22 @@ # list and reboot. # # ============================================================================================== +# OPERATIONAL MODEL +# ============================================================================================== +# +# One pass over PCIE_QUIET_DEVICES at array start. Each address is looked up under +# /sys/bus/pci/devices, checked against the guards below, and removed through the kernel's own +# per-device remove attribute. Nothing is masked and no kernel parameter is set. +# +# Idempotent, and silent when there is nothing to do. An address that is already gone is not an +# error — that is the normal state on every array start after the first within one boot. +# +# Reapplied every array start rather than once, because a reboot re-enumerates the bus and the +# devices come back. That is also the undo: clear PCIE_QUIET_DEVICES and reboot. +# +# PCIE_QUIET_ENABLED gates the whole run before any device is touched. +# +# ============================================================================================== # DESIGN PRINCIPLES # ============================================================================================== # diff --git a/Rsync/media_seed.sh b/Rsync/media_seed.sh index 26cdd5c..d2eadd0 100755 --- a/Rsync/media_seed.sh +++ b/Rsync/media_seed.sh @@ -35,6 +35,25 @@ # progress in the UI, and lets it be re-run or cancelled without touching onboard. # # ============================================================================================== +# OPERATIONAL MODEL +# ============================================================================================== +# +# One share at a time, in DAILY_SYNC_SHARES order, each handed to Rsync/rsync.sh --seed. The +# transfer itself, its bandwidth cap and its resume behaviour are all rsync.sh's — this script +# decides what to seed and in what order, never how. +# +# Sequential on purpose. The cap that matters is DEFAULT_RSYNC_OPTS' --bwlimit, which is a limit +# per rsync rather than per host; running shares in parallel would multiply it by the number of +# shares and saturate the link the rest of the ecosystem is still using. +# +# Refuses before it starts rather than partway. RSYNC_ENABLED must be true and DAILY_SYNC_SHARES +# must be non-empty, both checked up front — a multi-week transfer is the wrong place to +# discover that the global gate was off. +# +# Nothing waits on this. Phase 3 runs after the partnership is already established, so a seed +# that is still copying weeks later blocks no flag, no status card and no job record. +# +# ============================================================================================== # DESIGN PRINCIPLES # ============================================================================================== #