03-DESIGN/01-to-be/13-credentials-and-their-rotation.md

@@ -5,7 +5,7 @@ code:
   - mesh-control internal/inventory/secrets.go
   - mesh-control cmd/mesh-control/rotate.go
   - mesh-control examples/postgres-provisioner
-updated: 2026-08-31
+updated: 2026-09-01
 decisions:
   - 02-DECISIONS/0001-mesh-brokers-nodes-host-agents-think.md
   - 02-DECISIONS/0009-modules-and-the-graph.md
@@ -35,9 +35,21 @@ Three separate faults, and it is worth naming them apart because they have diffe
 ## What replaces it
 
 **Every pair has its own credential.** A provision between one consumer and one provider is one
-password, made once and kept. So rotating a machine's credential touches one role and leaves every
-other consumer alone — and *who holds this* is a query rather than an assumption. That alone
-removes the first fault: there is no shared secret to fan out.
+password, made once and kept. So rotating a credential touches one role and leaves every other
+consumer alone — and *who holds this* is a query rather than an assumption. That alone removes the
+first fault: there is no shared secret to fan out.
+
+**A consumer is a module on a machine, not a machine.** This was written as though a pair were two
+machines, and built that way, and it was wrong in a way that only shows on a real node
+([`022`](../../04-ISSUES/022-one-credential-per-node-per-provision-not-per-module/00-report.md)):
+a machine running several services against one database server had one credential between them.
+The provider refused to plan at all, and the consuming node did not refuse — it gave the first
+module a credential and the rest nothing.
+
+Two modules on one node are as separate as two on different nodes. They are different containers,
+with different data, and one login opening both is the thing this page exists to prevent. It is
+also what makes withdrawal possible: one role per machine cannot express *this module no longer
+has a login and the others still do*.
 
 **The change and the delivery are one command.** `rotate` discards the credential and sends both
 ends, and it does the sending itself. Leaving that to whoever remembers is the second fault