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/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";