docs: record the I12 refuse address as 127.0.0.1:1

crates/bugwarden-core/tests/guard_wiremock.rs

@@ -34,13 +34,13 @@ fn client(server: &MockServer) -> BugzillaClient {
 
 /// Connect-time failure that wiremock's 127.0.0.1 pool cannot serve (#115).
 ///
-/// `127.0.0.1:1` is a privileged port: a non-root wiremock listener binds
-/// `127.0.0.1:0` and cannot occupy it. Both Linux and macOS refuse
-/// immediately if nothing is listening (unlike `127.0.0.2`, which is not
-/// aliased on macOS and hangs). A bounded probe refuses to return an
-/// address that accepted or timed out. The URL is built from the probed
-/// socket so the two cannot drift, and the port must stay privileged so
-/// a bind-then-drop of an ephemeral port fails this helper.
+/// The address is `127.0.0.1:1`. Port 1 is privileged: a non-root
+/// wiremock listener binds `127.0.0.1:0` and cannot occupy it, so a
+/// pooled listener from another test cannot answer this request. The
+/// load-bearing assertion is `port() < 1024` — a bind-then-drop of an
+/// ephemeral port fails the helper. A 500 ms TCP probe refuses to
+/// return an address that accepted or timed out; the URL is built from
+/// the probed socket so the two cannot drift.
 fn refused_base_url() -> String {
     let addr = std::net::SocketAddr::from(([127, 0, 0, 1], 1));
     assert!(

crates/bugwarden/tests/common/mod.rs

@@ -2,13 +2,13 @@
 
 /// Connect-time failure that wiremock's 127.0.0.1 pool cannot serve (#115).
 ///
-/// `127.0.0.1:1` is a privileged port: a non-root wiremock listener binds
-/// `127.0.0.1:0` and cannot occupy it. Both Linux and macOS refuse
-/// immediately if nothing is listening (unlike `127.0.0.2`, which is not
-/// aliased on macOS and hangs). A bounded probe refuses to return an
-/// address that accepted or timed out. The URL is built from the probed
-/// socket so the two cannot drift, and the port must stay privileged so
-/// a bind-then-drop of an ephemeral port fails this helper.
+/// The address is `127.0.0.1:1`. Port 1 is privileged: a non-root
+/// wiremock listener binds `127.0.0.1:0` and cannot occupy it, so a
+/// pooled listener from another test cannot answer this request. The
+/// load-bearing assertion is `port() < 1024` — a bind-then-drop of an
+/// ephemeral port fails the helper. A 500 ms TCP probe refuses to
+/// return an address that accepted or timed out; the URL is built from
+/// the probed socket so the two cannot drift.
 pub fn refused_base_url() -> String {
     let addr = std::net::SocketAddr::from(([127, 0, 0, 1], 1));
     assert!(

docs/DESIGN.md

@@ -1997,7 +1997,17 @@ wired, `server.rs` and `main.rs` are the reference.
   id whatever the answer (nonexistent vs withheld cost the same), repeated
   ids fetched once, no batch to poison; per-id
   fallback fail closed; comment privacy; error mapping; API key absent from
-  error text (I12); create_bug and add_attachment endpoint mapping (payload
+  error text (I12) — the I12 transport-error sites connect to
+  `127.0.0.1:1` (a privileged port a non-root wiremock `bind(127.0.0.1:0)`
+  cannot occupy); `assert!(addr.port() < 1024)` is the mutation-kill for a
+  bind-then-drop of an ephemeral port, a 500 ms TCP probe refuses an
+  address that accepted or timed out, the client call is capped at 2 s,
+  and the assertion requires reqwest's `error sending request` so an
+  empty or HTTP-status error cannot pass a bare `!contains(KEY)`
+  (issue #115; known history, issue #127: PR #124 landed as `a0f535f`
+  then `137e552` — the first still describes `127.0.0.2:1` and fails
+  rust-macos; `main` is not rewritten); create_bug and add_attachment
+  endpoint mapping (payload
   travels untouched to POST /rest/bug and /rest/bug/{id}/attachment);
   whoami endpoint mapping (GET /rest/whoami => the `name` login; a missing,
   non-string, or blank — empty/whitespace-only — name is a failure), the