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/module-eval/agent-matrix.nix

@@ -59,7 +59,7 @@ let
     {
       # A homeserver URL is the whole input: from it the module derives the
       # hive-internal `main` account, and from a non-empty account set the three
-      # things that used to hang off `matrix.enable`.
+      # matrix pieces: daemon unit, path watcher and injected MCP entry.
       name = "an agent with a homeserver gets a main account and the matrix units";
       ok =
         let

nix/module-eval/bao-controller.nix

@@ -101,7 +101,7 @@ let
       ok = refusedWithoutIdentity controllerNoStore && !(refusedWithoutIdentity baoControllerHere);
     }
     {
-      # No hive mints an agent's matrix account any more, so a controller that
+      # No hive mints an agent's matrix account, so a controller that
       # did not know the homeserver would create every agent without one. The
       # default is the swarm's own `chat.` vhost, with no operator setting.
       name = "the controller is told the swarm's homeserver by default";

nix/module-eval/bao-otel-collector.nix

@@ -26,10 +26,10 @@ let
     deploy.bao.enable = true;
     deploy.bao.extraListenAddresses = [ "10.0.0.1" ];
     # Pinned, not incidental: the case counting these listeners is about the
-    # declared API addresses. ⚠️ Since the store got its own collector, this no longer keeps the METRICS
-    # listener out of the count — that one is a function of the store, not of
-    # a collector's placement — so the case below subtracts it by name rather
-    # than by leaving the swarm tier off.
+    # declared API addresses. ⚠️ Leaving the swarm tier off does not keep the
+    # METRICS listener out of the count — that one is a function of the
+    # store, not of a collector's placement — so the case below subtracts it
+    # by name.
     deploy.swarm-otel.enable = false;
   };
 
@@ -156,11 +156,10 @@ let
         && (j.params.format or [ ]) == [ "prometheus" ];
     }
     {
-      # 🎯 This move's deliverable, and it needs BOTH halves or it is not a move:
-      # the job is in the store's own container, and it is no longer declared
-      # to the swarm collector. Only the second half can catch a "move" that
-      # left the original behind — two scrapers of one endpoint, double-counted
-      # and neither obviously wrong.
+      # 🎯 Needs BOTH halves: the job is in the store's own container, and it
+      # is not declared to the swarm collector. Only the second half can catch
+      # a scrape declared in both places — two scrapers of one endpoint,
+      # double-counted and neither obviously wrong.
       name = "the store's metrics are scraped by its own collector, not the swarm's";
       ok = baoScrapeJob baoWithCollector "bao" != null && scrapeJob baoWithCollector "bao" == null;
     }
@@ -206,20 +205,13 @@ let
         j != null && !(j ? metrics_path) && !(j ? params);
     }
     {
-      # 🩸 This case USED to be the absence arm — "a store with no collector
-      # beside it serves no metrics" — and this inverts it deliberately
-      # rather than deleting it, because the condition it asserted is the bug.
-      #
-      # The old reasoning was sound for the old reader: the endpoint is
-      # unauthenticated, so it should not exist where nothing reads it, and
-      # the only reader was a swarm collector that had to be on this host.
-      # What that rendered on every OTHER host was a store whose metrics went
-      # nowhere, indistinguishably from a store nobody had asked to scrape.
-      #
-      # The reader now ships inside the container, so "no collector beside it"
-      # describes no host that exists. The endpoint is still not exposed to
-      # anything new: it is loopback in a netns whose only other occupants are
-      # the store and its collector.
+      # 🩸 The store's metrics endpoint does not depend on where the swarm
+      # collector runs. The endpoint is unauthenticated, so it should not exist
+      # where nothing reads it; the reader ships inside the container, so every
+      # store has one. Gating the endpoint on a collector beside the store
+      # would render a store whose metrics go nowhere, indistinguishable from
+      # a store nobody had asked to scrape. The endpoint is loopback in a
+      # netns whose only other occupants are the store and its collector.
       name = "a store whose swarm collector is elsewhere still serves and scrapes its metrics";
       ok =
         let
@@ -272,12 +264,11 @@ let
         (j.merge or false) == true && j.directory == "/var/log/journal";
     }
     {
-      # The empty-directory trap this receiver used to fall into: `host` mode
-      # bind-mounts a host directory journald never actually writes into, so
-      # `merge`/`directory` above would keep validating and starting while
-      # the receiver reads nothing — silently, same as every other failure
-      # mode here. Guards against re-adding the exact flag this was fixed by
-      # dropping.
+      # The empty-directory trap: `host` mode bind-mounts a host directory
+      # journald never actually writes into, so `merge`/`directory` above
+      # would keep validating and starting while the receiver reads nothing —
+      # silently, same as every other failure mode here. Guards against the
+      # flag that links it.
       name = "the store's container does not link its journal onto the host";
       ok = !(lib.elem "--link-journal=host" (baoWithCollector.containers.swarm-bao.extraFlags or [ ]));
     }
@@ -291,7 +282,7 @@ let
     {
       # Both ends of the hop, because a mismatch between them is silent in both
       # directions: the exporter retries into a 404 and the receiver never
-      # hears from it. Not "on one host" any more — the far end is the gateway
+      # hears from it. Not "on one host" — the far end is the gateway
       # vhost the swarm collector serves its name on, which is the whole point
       # of addressing it by name rather than by a bridge address.
       name = "the store's forwarder exports to the swarm collector's own route";

nix/module-eval/forge-placement.nix

@@ -4,9 +4,8 @@
 #
 # Where the forge runs. A swarm has one, on the host with
 # `deploy.forgejo.enable`; every other hive is a client of it, and the parts
-# of a split deployment that used to lean on every host running a forge
-# (the OIDC client, the controller's token, the CI runner) still have to
-# hold.
+# of a split deployment that must not assume every host runs a forge
+# (the OIDC client, the controller's token, the CI runner) have to hold.
 {
   pkgs,
   lib,

nix/module-eval/grafana.nix

@@ -70,13 +70,11 @@ let
     deploy.bao.grafanaOidcClientKeyFile = "/etc/pki/bao-grafana-oidc-key.pem";
   };
 
-  # A Grafana host holding no store identity. This used to be the shape the
-  # module went QUIET on — no OIDC block, a warning, and a container whose
-  # login form is off regardless, so no way in and nothing failed. It is kept
-  # rather than deleted because the shape is still reachable by an operator;
-  # what changed is the deliverable, from a warning nothing reads back to a
-  # refusal naming the two options to set. Only the identity is missing, so an
-  # arm below can name which refusal fired.
+  # A Grafana host holding no store identity. The module refuses it with an
+  # assertion naming the two options to set, rather than going QUIET: no OIDC
+  # block can render and the container's login form is off regardless, so
+  # there would be no way in and nothing would fail. Only the identity is
+  # missing, so an arm below can name which refusal fired.
   grafanaNoIdentity = hive {
     deploy.grafana.enable = true;
     deploy.grafana.plugins = [ ];
@@ -104,9 +102,9 @@ let
     ) m.assertions;
   cases = [
     {
-      # This fixture enables grafana and NOT authelia, which is the shape the
-      # login form used to stay enabled in: the toggle read "both services are
-      # on this host" rather than "grafana requires SSO". Grafana ships an
+      # This fixture enables grafana and NOT authelia, so the login-form toggle
+      # has to follow "grafana requires SSO" rather than "both services are on
+      # this host". Grafana ships an
       # `admin`/`admin` account and its vhost is on the public gateway, so a
       # password box there is a way in whatever the topology.
       name = "grafana disables its local login form even where authelia is not on this host";

nix/module-eval/name-guards.nix

@@ -23,8 +23,8 @@ let
 
   # The hive-name guards, with the collector explicitly OFF. That is the whole
   # property: the guards live where `swarm.hives` is declared, so they run in a
-  # deployment that has a secret store and no collector — which used to skip
-  # them entirely, because they were assertions inside swarm-otel's own `mkIf`.
+  # deployment that has a secret store and no collector, rather than being
+  # assertions inside swarm-otel's own `mkIf`.
   #
   # ⚠️ `controllerCommonName` is overridden to a name containing NO reserved
   # fragment. Its default (`swarm-controller`) contains `swarm` and is caught

nix/module-eval/nats-authelia.nix

@@ -44,9 +44,9 @@ let
   # refuses; see ./host-modules/deploy.nix. `package` and `bridgePackage` are
   # ordinary options, so they do carry one. The two arms
   # below have different jobs. `usersFile` tests the rename; the nats one tests
-  # that a reader repointed to the new namespace still renders the derived
-  # path, which is the failure this slice could actually have shipped — seven
-  # of those reads went through an alias a path-shaped grep cannot see.
+  # that a reader pointed at the `deploy` namespace still renders the derived
+  # path — seven of those reads go through an alias a path-shaped grep
+  # cannot see.
   autheliaOldPath = hive {
     deploy.authelia.enable = true;
     deploy.nats.enable = true;
@@ -84,8 +84,8 @@ let
 
   # A hive running NOTHING of the swarm's own services — no IdP here, no
   # `swarm.authelia.url` set by hand. The whole point of the fixture is what it
-  # does *not* say: it is the shape whose IdP address used to be null, and
-  # before that a co-location-derived guess.
+  # does *not* say: no IdP address is given and none is derived from
+  # co-location.
   autheliaNotColocated = hive { };
   # The same swarm's IdP host, for the arm that the two agree.
   autheliaColocated = hive { deploy.authelia.enable = true; };

nix/module-eval/secret-publisher.nix

@@ -36,9 +36,7 @@ let
   # deployment this unit exists for: authelia is the one host the store is
   # guaranteed not to share once either has a machine of its own.
   #
-  # ⚠️ `enable` is deliberately NOT set here. It used to be, with a comment
-  # saying the default asked whether both ran on this host — which documented
-  # the co-location bug instead of catching it. Leaving it unset is what makes
+  # ⚠️ `enable` is deliberately NOT set here: leaving it unset is what makes
   # this fixture exercise the default rather than mask it.
   secretPublisherRemote = hive {
     deploy.authelia.enable = true;
@@ -125,9 +123,9 @@ let
         && !(lib.elem "swarm-grafana" (clients grafanaRemoteAuthelia));
     }
     {
-      # The collector's half of the same defect and the same fix: this used to
-      # be gated on `deploy.swarm-otel.enable`, so a split deployment
-      # registered the client nowhere and authelia minted nothing to publish.
+      # The collector's half of the same property: the client is not gated on
+      # `deploy.swarm-otel.enable`, which would let a split deployment register
+      # it nowhere, so authelia would mint nothing to publish.
       name = "the swarm's collector client is registered wherever authelia runs";
       ok =
         let

nix/module-eval/swarm-otel-core.nix

@@ -112,10 +112,10 @@ let
         && !(lib.hasInfix "secret/swarm/hives/" s);
     }
     {
-      # The defect itself. These exporters used to be gated on the stores'
-      # PER-HOST enables, so a collector that did not share a host with them
-      # rendered none at all and dropped everything it received, from every
-      # hive — silently, because an absent exporter is not an error.
+      # These exporters must not be gated on the stores' PER-HOST enables: a
+      # collector that did not share a host with them would render none at all
+      # and drop everything it received, from every hive — silently, because
+      # an absent exporter is not an error.
       name = "a collector that hosts neither store still exports to both";
       ok =
         let