From 04e5ed9ae916bced67f589101a273ca9622985c4 Mon Sep 17 00:00:00 2001
From: npub1jmc9dt2lyvzu3h0kxlwxt5zg4fxp9476awyxw6gwxn72g6cw7exqs64whm
 <96f056ad5f2305c8ddf637dc65d048aa4c12d7daeb8867690e34fca46b0ef64c@sprout-oss.stage.blox.sqprod.co>
Date: Fri, 26 Jun 2026 13:46:15 -0400
Subject: [PATCH] =?UTF-8?q?docs(auth=5Fwire):=20fix=20doc=20drift=20?=
 =?UTF-8?q?=E2=80=94=20tests=20are=20in-module,=20P5=20grep-lint=20not=20y?=
 =?UTF-8?q?et=20shipped?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Eva [11] code-verify catch: two docstrings in auth_wire.rs referenced state
that doesn't exist on this branch.

- AuthErrorWireCategory::message pointed at "tests/auth_error_payload_oracle.rs"
  for the byte-identity property test. The tests are actually in-module
  (#[cfg(test)] mod tests at the bottom of auth_wire.rs); no separate file
  exists. Updated to name the two specific tests that prove the invariant
  (verification_class_all_coalesce, internal_two_communities_byte_identical).

- auth_error_wire's docstring said "the CI grep-lint enforces" — but the
  grep-lint (P5 in the audit note) is a planned follow-up, not yet shipped.
  Replaced with an accurate description of what actually fences regressions
  today: the wildcard-free match arm. Adding any AuthError variant fails to
  compile here until a wire-class decision is made — that catches the cause,
  not just the symptom. P5 grep-lint is correctly described as planned
  belt-and-suspenders, not currently in CI.

Doc-only diff. No behavior change.

Validation:
- cargo fmt -p buzz-relay --check ✅
- cargo test -p buzz-relay --lib auth_wire ✅ (6/6 property tests green)

Co-authored-by: Tyler Longwell <tlongwell@block.xyz>
Signed-off-by: Tyler Longwell <tlongwell@block.xyz>
---
 crates/buzz-relay/src/auth_wire.rs | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/crates/buzz-relay/src/auth_wire.rs b/crates/buzz-relay/src/auth_wire.rs
index ed71149f5..b76a42a5c 100644
--- a/crates/buzz-relay/src/auth_wire.rs
+++ b/crates/buzz-relay/src/auth_wire.rs
@@ -70,8 +70,9 @@ impl AuthErrorWireCategory {
     /// Stable, byte-identical user-visible message for this category.
     ///
     /// Two `AuthError` values that map to the same category MUST produce the
-    /// same bytes here — that's the property-test invariant in
-    /// `tests/auth_error_payload_oracle.rs`.
+    /// same bytes here — that's the property-test invariant proved in the
+    /// in-module `#[cfg(test)] mod tests` below (see
+    /// `verification_class_all_coalesce` and `internal_two_communities_byte_identical`).
     pub fn message(self) -> &'static str {
         match self {
             // Coalesces Nip98Invalid, Nip98Replay, InvalidSignature,
@@ -102,9 +103,13 @@ impl AuthErrorWireCategory {
 /// Map an [`AuthError`] to its wire category.
 ///
 /// **Do not stringify `AuthError` for the wire by any other path.** This
-/// function is the only sanctioned conversion; the CI grep-lint enforces
-/// that no other call site uses `auth_err.to_string()` or `format!("{}", auth_err)`
-/// in a response-construction chain (P5).
+/// function is the only sanctioned conversion. The load-bearing fence is
+/// the wildcard-free match below: adding any new `AuthError` variant fails
+/// to compile here until a wire-class decision is made — that catches the
+/// cause (a new variant lacks a wire class), not just the symptom (raw
+/// stringification). A `scripts/check-no-authror-leak.sh` grep-lint (P5 in
+/// the audit note) is planned as a belt-and-suspenders follow-up but is
+/// not yet wired into CI.
 pub fn auth_error_wire(err: &AuthError) -> AuthErrorWireCategory {
     match err {
         // Verification class — coalesce.