tests use mockall for expectation-style doubles, starting with the builder and hive-priv seams

docs/process/conventions.md

@@ -521,6 +521,27 @@ gate locally: `nix flake check` (shares the build farm, use
 sparingly) or build just the suspect check, for example `nix build
 .#checks.x86_64-linux.hivectl-docs`.
 
+## Testing seams and test doubles
+
+- **A new test seam is a trait, used generically** (`impl Seam` or a type
+  parameter). No `dyn Fn` closure bags: a trait names each question the code
+  asks and gives the test one place to answer it.
+- **A double that only answers and records uses `mockall`** (a
+  dev-dependency): put `#[cfg_attr(test, mockall::automock)]` on the trait,
+  set canned replies with `returning`, and assert calls with `times` and
+  `withf`. The attribute keeps `mockall` out of release builds. Examples:
+  `Probes` in `hive-priv/src/storage.rs`, `Publisher` and `Tokens` in
+  `swarm-builder/src/main.rs`.
+- **`automock` can't mock a trait with a supertrait** such as `Clone`: a mock
+  doesn't implement it. Declare the mock with `mockall::mock!` as a plain
+  struct and implement the trait for `Arc<Mock…>`, as `swarm-builder` does.
+  Better, leave the supertrait off the trait and bound the callers.
+- **Stateful fakes stay hand-written**: in-memory stores whose reads see earlier
+  writes. Real-process stubs such as `ScriptSpawn` also stay, since they run a
+  real `sh` on purpose.
+- **Nothing migrates in one sweep.** Move an existing expectation-style fake
+  to `mockall` when you touch its file for another reason.
+
 ## Best-effort oneshot services
 
 The harness ships a family of one-shot systemd services that