swarm: tests and docs for the queue-credential revocation

Pins the three properties the revocation rests on and cannot check
against a store: that only `Destroyed` revokes (a revocation on
`Offline` or `Paused` would give an agent that stops and never
restarts), that a 404 is absence while a 403 stays a failure, and that
the delete addresses `secret/metadata/` -- the path that takes every
version, which is the string the grant has to match.

docs/swarm/credentials.md gains the revocation section and its table
cell stops describing the deletion as something an operator does by
hand.

swarm-controller/src/main.rs

@@ -3308,6 +3308,32 @@ mod tests {
         );
     }
 
+    /// `Destroyed` is the one declaration that ends an agent's life, so it is
+    /// the one that revokes. The credential is a bearer secret: left behind,
+    /// anything that recovers it still authenticates as an agent that no
+    /// longer exists.
+    #[test]
+    fn declaring_an_agent_destroyed_revokes_its_queue_credential() {
+        assert!(crate::revokes_queue_credential(
+            swarm_queue_client::wanted::AgentState::Destroyed
+        ));
+    }
+
+    /// The control, and the more expensive half to get wrong: a revocation on
+    /// `Offline` or `Paused` would give an agent that can be stopped and never
+    /// restarted. Every non-terminal state is listed rather than sampled, so
+    /// a state added later shows up here as well as in the match itself.
+    #[test]
+    fn no_state_an_agent_comes_back_from_revokes() {
+        use swarm_queue_client::wanted::AgentState;
+        for state in [AgentState::Up, AgentState::Offline, AgentState::Paused] {
+            assert!(
+                !crate::revokes_queue_credential(state),
+                "{state:?} is a state an agent returns from"
+            );
+        }
+    }
+
     /// The whole point of the node: a freshly created agent is declared
     /// `Paused`, so it does not start driving turns the moment its hive
     /// brings it up. Any other state here is the bug this fixes.