refact(comments): state the mechanism, not the incident

Every comment that invoked a 'law' (50 word-boundary sites across 28
tracked files) now states what is going on and why, in terms that
transfer to any project: gate twins drift until one side greenlights
what the other refuses; a tag re-points while a digest pins; a
restrictive engine behavior belongs to the runtime that imposed it and
must be re-tested, not inherited; a speculative head is tensors in the
file, not a flag; snapshot links dangle where the container resolves
them; exit 0 is a clean stop to systemd, so a self-exiting daemon on
on-failure goes dark reporting success. Event narratives and dates are
gone from these comments; the mechanics carry the argument.

Behavior-identical: bash -n, py_compile, yaml parse, full bats suite
408/408 green. One symbol rename rides along (stack script local
scale_law -> scale_contract, with its log text).
This commit is contained in:
Frank committed 2026-10-14 13:36:40 -07:00
1 parent 65bd5ccea7
commit d4ce76b68b
28 files changed
+195 -164

No files matched your search

+8 -6
View File
@@ -18,11 +18,12 @@ facts written by hand in three config files). They now all read
render pihole-hosts the Pi-hole addn-hosts file
check [NAME...] integrity + drift gates (exit 1 on drift)
Two laws the engine enforces structurally:
Two rules the engine enforces structurally:
* A path selects only services that RUN on the planned target. The old planner
matched paths host-blind and filtered at the end, so a frankbook-pro file
could plan a dankserver service (the stale *arr entries made that reachable).
* A path selects only services that RUN on the planned target. Path
matching that is host-blind (match first, filter later) lets a file on
one host plan a service on another; selection is scoped to the host the
path belongs to.
* The netns family is DERIVED, never declared: a unit file that says
`Network=gluetun.container` rides that tunnel, so a gluetun change selects
every sharer. The unit files are the source of that coupling.
@@ -499,8 +500,9 @@ def check_config(inv: Inventory) -> list[str]:
# --- node-exporter quadlet template (rank 6) --------------------------------
# The two node-exporter units were a MIRROR pair kept in step by a comment.
# The template is now the law; `check` drift-gates both tracked copies.
# Parallel per-host copies kept in step by a comment drift apart; the
# template is the single source, and `check` drift-gates every tracked
# rendering against it.
NODE_EXPORTER_TEMPLATE = """\
# Quadlet unit: node-exporter (rootless, boot-persistent) — RENDERED ARTIFACT.
# Regenerate: python3 scripts/service-map.py render node-exporter-unit --host {host}