From e7a5e93bbcc7a2ff84978060aad4a36b24c6db66 Mon Sep 17 00:00:00 2001
From: atlas <atlas@hyperhive.local>
Date: Mon, 17 Aug 2026 19:45:06 +0200
Subject: [PATCH] docs: trim the trustBundle comment under the 30-line lint

Keeps the three constraints a reader cannot derive; the reasoning behind
them lives in the PR.
---
 nix/host-modules/lib/hive-ca-trust.nix | 53 ++++++++------------------
 1 file changed, 16 insertions(+), 37 deletions(-)

diff --git a/nix/host-modules/lib/hive-ca-trust.nix b/nix/host-modules/lib/hive-ca-trust.nix
index 9b8cd95a..5e46e878 100644
--- a/nix/host-modules/lib/hive-ca-trust.nix
+++ b/nix/host-modules/lib/hive-ca-trust.nix
@@ -63,46 +63,25 @@ in
     requires = [ "hive-tls-ca.service" ];
   };
 
-  # Assemble system CAs + the hive CA into one bundle, for runtimes whose
-  # trust variable *replaces* the default store (Go's `SSL_CERT_FILE`,
-  # rustls-native-certs) rather than adding to it — pointing those at
-  # `caContainerPath` alone would drop every public anchor.
+  # System CAs + hive CA in one bundle, with `SSL_CERT_FILE` set on each
+  # consumer — for runtimes whose trust variable *replaces* the store (Go,
+  # rustls-native-certs). An additive one (Node's `NODE_EXTRA_CA_CERTS`,
+  # hive-ci) needs no bundle and should not use this.
   #
-  # The header above says consumption stays at the call site, and the *env
-  # var* still does. The assembly does not: four containers were each
-  # hand-rolling this concat, which is how they came to share one defect —
-  # `wantedBy` + `before` express ordering but not success, so a failed
-  # assembly let the consumer start against a missing file and end up
-  # trusting **nothing**, which fails every outbound TLS call while the unit
-  # looks healthy.
+  #   imports = [ (caTrust.trustBundle { inherit pkgs; name = "swarm-nats";
+  #                                      consumers = [ "swarm-nats-auth" ]; }) ];
   #
-  # Two things this does that a hand-rolled version kept getting wrong:
-  #   - `requires` on the CONSUMER, so a failed bundle stops it — and the
-  #     dependency is visible in `systemctl status <consumer>`, where someone
-  #     debugging a TLS failure actually looks.
-  #   - assemble to a temp path, check the result is non-empty and actually
-  #     contains a certificate, and only then move it into place. `cat` of an
-  #     empty bind exits 0, so `set -e` alone does not catch it, and a partial
-  #     bundle must never appear under the final name.
+  # Three constraints, each earned:
+  #   - `requires` on the CONSUMER: `before` orders but does not gate, so a
+  #     failed assembly otherwise leaves it running and trusting *nothing*.
+  #   - assemble to a temp path, verify, then move: `cat` of an empty bind
+  #     exits 0, and a partial bundle must never appear under the final name.
+  #   - `consumers` are BARE unit names — they are `systemd.services` keys
+  #     (no suffix) *and* go in `before`/`requires` (suffixed). Reversed, the
+  #     edge names a unit that does not exist and systemd orders nothing.
   #
-  # Returns a MODULE to import inside the container, not an attrset to splice
-  # in — same shape as `swarm-container-resolver.nix`, and for a concrete
-  # reason: a caller that already writes `systemd.services.<consumer> = …`
-  # cannot also write `systemd.services = …` in the same attrset, so anything
-  # returning bare services forces the call site to be restructured.
-  #
-  #   imports = [ (caTrust.trustBundle { inherit pkgs; name = "swarm-nats"; consumers = [ "swarm-nats-auth" ]; }) ];
-  #
-  # It sets `SSL_CERT_FILE` on each consumer itself. That is the right default
-  # for this helper's audience — runtimes whose trust variable *replaces* the
-  # store. A runtime with an additive variable (Node's `NODE_EXTRA_CA_CERTS`,
-  # hive-ci) needs no bundle at all and should not use this.
-  #
-  # `consumers` are BARE unit names (no `.service`): they are used both as
-  # `systemd.services` attribute keys, which must not carry the suffix, and
-  # inside `before`/`requires`, which must. Getting that backwards produces an
-  # edge to a unit that does not exist — which systemd accepts in silence,
-  # ordering nothing.
+  # Returns a module, not bare services: a caller already writing
+  # `systemd.services.<consumer>` cannot also write `systemd.services`.
   trustBundle =
     {
       name,