nix: comments state current behaviour, not history

Rewrite comments and option descriptions under nix/ that narrate how the
code got here ("used to", "new name", "sat at the TOP", "no longer",
renamed/moved narration, attributions) to say what the code does now and
why. Comments and description strings only; no logic changes.

Files in open PR #4970's diff are left alone. Refs #3902

nix/host-modules/hive-gateway/default.nix

@@ -55,10 +55,9 @@ let
   # `cfg.useSelfSigned` (options.nix) is the derived single source of truth.
   useSelfSigned = cfg.useSelfSigned;
 
-  # nginx's own state dir. Kept at the historical `/var/lib/hive-gateway`
-  # path rather than renamed with the move: it holds the imported leaf
-  # across reboots, and renaming it would strand every existing hive's
-  # certs for no gain.
+  # nginx's own state dir, fixed at `/var/lib/hive-gateway` independent of
+  # this module's own path: it holds the imported leaf across reboots, and
+  # a different path would strand every existing hive's certs.
   tlsDir = "/var/lib/hive-gateway/tls";
   # TLS cert + key paths.
   # - self-signed (default): the hive leaf the store issues (the
@@ -207,14 +206,12 @@ in
     # before c0re has run, and pin owner + mode rather than leaving it
     # to whoever creates the path first.
     #
-    # ⚠️ There is deliberately NO rule for /var/lib/hyperhive here. One
-    # used to declare it `0755 root root` and could never win:
+    # ⚠️ There is deliberately NO rule for /var/lib/hyperhive here.
     # `hive-c0re.service` sets `StateDirectory = "hyperhive"` with
     # `StateDirectoryMode = "0750"`, which systemd re-applies on every
-    # start. Two mechanisms owning one path, and the loser still read as
-    # a guarantee — it is why the resulting outage was first misdiagnosed
-    # as someone having changed the mode. c0re's own unit owns that dir;
-    # this module no longer has an opinion about it.
+    # start, so a tmpfiles rule for the same path could never win: two
+    # mechanisms owning one path, the loser still reading as a guarantee.
+    # c0re's own unit owns that dir; this module has no opinion about it.
     systemd.tmpfiles.rules = [
       # The gateway's own config dir — NOT under /var/lib/hyperhive. c0re
       # writes here, nginx reads here, and neither needs any access to the
@@ -393,23 +390,15 @@ in
     # ⚠️ NO `SupplementaryGroups = [ "hive-core" ]` on nginx, and its
     # absence is load-bearing rather than an omission.
     #
-    # It used to be here, to let nginx traverse `/var/lib/hyperhive` and
-    # reach the config fragments that lived inside: `hive-c0re.service`
-    # declares `StateDirectory = "hyperhive"` with `StateDirectoryMode =
-    # "0750"` owned by `hive-core`, and systemd re-applies that on every
-    # c0re start — beating this module's own tmpfiles rule for the same
-    # path. Without the group, nginx failed its config test and never
-    # started (`nginx: [emerg] open() ".../agents.conf" failed (13:
-    # Permission denied)`), taking the gateway and every hive domain
-    # behind it down.
-    #
-    # The group fixed the symptom and paid for it: it also gave nginx
-    # read access to everything ELSE group-readable under that dir,
-    # including the broker sqlite — i.e. every message between every
-    # agent, reachable by the process whose entire job is parsing
-    # untrusted network input. Moving the fragments to the gateway's own
-    # dir removes the need and the exposure together. Re-adding this line
-    # would restore both.
+    # `hive-c0re.service` declares `StateDirectory = "hyperhive"` with
+    # `StateDirectoryMode = "0750"` owned by `hive-core`, and systemd
+    # re-applies that on every c0re start. The group would let nginx
+    # traverse that dir, but it also gives nginx read access to everything
+    # ELSE group-readable under it, including the broker sqlite — i.e.
+    # every message between every agent, reachable by the process whose
+    # entire job is parsing untrusted network input. The config fragments
+    # nginx reads live in the gateway's own dir instead, so nginx needs no
+    # access to c0re's tree. Adding this line would reopen that exposure.
 
     networking.firewall = lib.mkIf cfg.openFirewall {
       allowedTCPPorts = [
@@ -424,12 +413,11 @@ in
     # every name a service module contributed. See `docs/networking/gateway.md`
     # ("Local dev").
     #
-    # This used to restate the per-service list a THIRD time (after the
-    # vhosts and the dnsmasq records), with its own copy of each
-    # service's guard. It is the same question — "which names does this
-    # host answer for" — so it reads the same answer; a service added
-    # later lands here with no edit, and cannot land here with a
-    # different condition than it used for DNS.
+    # This does not restate the per-service list (the vhosts and the
+    # dnsmasq records already carry it). It is the same question —
+    # "which names does this host answer for" — so it reads the same
+    # answer; a service added later lands here with no edit, and cannot
+    # land here with a different condition than it used for DNS.
     networking.hosts = lib.mkIf cfg.localHostsEntry {
       "127.0.0.1" = lib.unique ([ hyperhiveDomain ] ++ cfg.localNames);
     };