Merge pull request #226 from creator35lwb-web/chore/v0.5.37-version-bump

creator35lwb-web · web-flow · commit fa96e2e07443 · 2026-05-26T00:08:00.000+08:00
feat(rate-limit): v0.5.37 Tier Clarity — branch 429 CTA on uuid_status
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,26 @@ Full version history also available at [verifimind.ysenseai.org/changelog](https
 
 ---
 
+## v0.5.37 - Tier Clarity (May 26, 2026)
+
+Branches the 429 rate-limit CTA so the response fits *why* the caller is anonymous, and surfaces `uuid_status` for diagnosis. Driven by a tier-setup audit (findings T1–T6).
+
+### What changed
+- **429 response body now branches on `uuid_status` (`absent` | `invalid` | `valid`):**
+  - *No UUID header* → acquisition CTA: register a free Scholar UUID (30/60s + BYOK + dashboard), with the Privacy-Doctrine-v1.0 line and a founder/feedback note.
+  - *UUID header present but invalid* → **recovery** hint (`VERIFIMIND_UUID` unset / `your-uuid-here` placeholder → see `/setup`) instead of wrongly pitching registration to someone who already has a UUID.
+- `uuid_status` added to the 429 JSON body and the rate-limit warning log (observability for misconfigured-Scholar detection — AY funnel signal).
+- CTA logic extracted to a pure `_build_rate_limit_cta()` helper with 4 new unit tests.
+- Version bump 0.5.36 → 0.5.37 (both `SERVER_VERSION` surfaces + 9 test files); `server.json` 3.13.0 → 3.14.0.
+
+### Why
+A tier-setup audit — prompted by a Scholar-tier user being rate-limited as Anonymous — found: the rate limiter resolves tier *solely* from the `X-VerifiMind-UUID` header (T1); the downgrade to Anonymous is silent (T2); the tool-response `tier` field (from `tier_gate`, = "not Pioneer") contradicts the rate-limiter tier (T5); and the rate limiter reads an **empty** `ea_registrations` collection for Pioneer quota while real registrations live in `early_adopters` (T6 — Pioneer rate tier effectively dead). v0.5.37 ships the user-facing half (recovery CTA + diagnosis). The deeper reconciliation (T3/T6 — single source of truth for caller tier; fix the collection mismatch) is routed to T (CTO) in a forensic audit report — see PRIVATE `.macp/handoffs/`.
+
+### Evidence
+AY/AZ Report 092 (May 21–24) showed active anonymous builders hitting the IP-tier wall with 0 registrations — the exact cohort the branched CTA targets.
+
+---
+
 ## v0.5.36 - Changelog Endpoint Redirect (May 21, 2026)
 
 Single-sources the changelog to end dual-maintenance drift.
diff --git a/SERVER_STATUS.md b/SERVER_STATUS.md
@@ -1,16 +1,17 @@
 # VerifiMind-PEAS Server Status
 
-**Last Updated:** May 13, 2026
+**Last Updated:** May 26, 2026
 
 ---
 
 ## Current Status: Operational
 
-**v0.5.33 "Changelog Hygiene" — deployed May 13, 2026**
+**v0.5.37 "Tier Clarity" — deployed May 26, 2026**
 
-The VerifiMind MCP server is fully operational. All security gates passed.
+The VerifiMind MCP server is fully operational. All security gates passed. (Per-version public detail now lives in [GitHub Releases](https://github.com/creator35lwb-web/VerifiMind-PEAS/releases) since the `/changelog` redirect in v0.5.36.)
 
 - 13 MCP tools (4 core Trinity + 6 template management + 3 coordination) — **all free for everyone**
+- **Tier Clarity (v0.5.37)**: 429 rate-limit CTA now branches on `uuid_status` — a *misconfigured Scholar* (UUID header present but invalid) gets a recovery hint (`VERIFIMIND_UUID` / `/setup`), while a true anonymous caller gets the register-for-Scholar acquisition CTA (+ BYOK + dashboard, Privacy-Doctrine-v1.0 line, founder/feedback note). `uuid_status` surfaced in the body + warning log. Shipped from a tier-setup audit (T1–T6); the T3/T6 reconciliation (rate-limiter reads empty `ea_registrations` vs real `early_adopters`; single source of truth for caller tier) routed to T (CTO) — May 26, 2026
 - **Changelog Hygiene (v0.5.33)**: Retroactively sanitized public `/changelog` to remove specific blocked-IP addresses from v0.5.30 and v0.5.32 entries; matches v0.5.22 / v0.5.26 disclosure pattern. Full forensics preserved in internal `CHANGELOG.md`, PR bodies, and commit history. Added disclosure-policy header to internal CHANGELOG. PR# links added to public v0.5.30 / v0.5.32 entries — May 13, 2026
 - **Secret Scanner Block + SonarCloud P1 (v0.5.32)**: 7th IP added to application-layer blocklist — credential/secret enumeration scanner, 788 req single burst on May 12 (probed `.env` variants, `.git/*`, `.terraform.*`, `.stripe/`, `?phpinfo=1`, CI configs). 77% caught by rate limiter; zero leak (4 served 200 = safe root response only). SonarCloud P1 cleanup: extracted `MCP_ENDPOINT_PATH`/`MCP_SERVER_URL`/`MCP_REMOTE_QUICKSTART` constants (removed 13 duplicate literals); refactored `http_exception_handler` cognitive complexity 23 → ≤15; CodeQL `py/empty-except` × 2 resolved; logger.exception() in registration 500 path — May 13, 2026
 - **SonarCloud P0 (v0.5.31)**: Resolved 14 SonarCloud Vulnerabilities + 15 BLOCKER severity items per XV's May 12 audit. Workflow permissions scoped to job level; TLS 1.2 explicit minimum; broken `__all__` in templates/library removed; 8 false-positive suppressions with NOSONAR + justification comments; deprecated `datetime.utcnow()` replaced. Expected impact: Security count 14 → 1, BLOCKER 15 → 0 — May 13, 2026
diff --git a/mcp-server/http_server.py b/mcp-server/http_server.py
@@ -64,7 +64,7 @@
 mcp_app = mcp_server.http_app(path='/', transport='streamable-http')
 
 # Server version
-SERVER_VERSION = "0.5.36"
+SERVER_VERSION = "0.5.37"
 
 # MCP endpoint constants — single source of truth for URL/path strings used in
 # JSON responses, quickstart commands, and HTML setup pages. Extracted in v0.5.32
diff --git a/mcp-server/src/verifimind_mcp/middleware/rate_limiter.py b/mcp-server/src/verifimind_mcp/middleware/rate_limiter.py
@@ -75,6 +75,41 @@ def _resolve_uuid_tier(uuid: str) -> str:
     return tier
 
 
+def _build_rate_limit_cta(tier: str, uuid_status: str) -> Tuple[Optional[str], Optional[str]]:
+    """Build the (upgrade_hint, from_the_builder) pair for a 429 body.
+
+    Branches on why the caller is anonymous so the copy fits the situation
+    (tier-audit findings T4/T5, v0.5.37):
+      - tier != "anonymous"       → (None, None)        no pitch to registered users
+      - anonymous, uuid invalid   → RECOVERY hint       "your UUID isn't valid, fix VERIFIMIND_UUID"
+      - anonymous, uuid absent    → ACQUISITION hint     "register a free Scholar UUID"
+    The founder/feedback line accompanies any anonymous-tier 429.
+    """
+    if tier != "anonymous":
+        return None, None
+    if uuid_status == "invalid":
+        upgrade_hint = (
+            "A VerifiMind UUID was received but is not valid, so this request is on the "
+            "Anonymous tier (10 req/60s per IP). Check that VERIFIMIND_UUID is set to your "
+            "real UUID (not the 'your-uuid-here' placeholder) in your MCP config. "
+            "Setup help: https://verifimind.ysenseai.org/setup"
+        )
+    else:  # absent — no UUID header at all
+        upgrade_hint = (
+            "Anonymous tier limit reached (10 req/60s per IP). Register a free Scholar UUID "
+            "for 30 req/60s + BYOK + a usage dashboard: https://verifimind.ysenseai.org/register "
+            "— your UUID is only a quota key; BYOK keys are never logged and registration adds "
+            "no public identification (Privacy Doctrine v1.0). "
+            "MCP config: https://verifimind.ysenseai.org/setup"
+        )
+    from_the_builder = (
+        "VerifiMind is built by a solo dev keeping the lights on. "
+        "Features & feedback welcome → "
+        "https://github.com/creator35lwb-web/VerifiMind-PEAS/discussions"
+    )
+    return upgrade_hint, from_the_builder
+
+
 class RateLimitStore:
     """In-memory rate limit tracking with automatic cleanup. Sliding window."""
 
@@ -215,19 +250,25 @@ async def dispatch(self, request: Request, call_next):
 
         client_ip = get_client_ip(request)
 
-        # Resolve tier from X-VerifiMind-UUID header
+        # Resolve tier from X-VerifiMind-UUID header.
+        # Track WHY a request is anonymous (uuid_status) so the 429 body can tell a
+        # misconfigured Scholar (header present but invalid) apart from a true
+        # anonymous caller (no header) — tier-audit findings T1/T2/T5, v0.5.37.
         uuid_header = request.headers.get("x-verifimind-uuid", "").strip()
         tier = "anonymous"
         active_limit = TIER_LIMITS["anonymous"]
+        uuid_status = "absent"  # absent | invalid | valid
 
         if uuid_header:
+            uuid_status = "invalid"  # present until proven valid
             try:
                 from verifimind_mcp.utils.uuid_tracer import is_valid_uuid
                 if is_valid_uuid(uuid_header):
                     tier = _resolve_uuid_tier(uuid_header)
                     active_limit = TIER_LIMITS[tier]
+                    uuid_status = "valid"
             except Exception:
-                pass  # invalid header → fall back to anonymous
+                pass  # invalid header → fall back to anonymous (uuid_status="invalid")
 
         if tier == "anonymous":
             allowed, retry_after, limit_type = _rate_limit_store.check_and_record(client_ip)
@@ -238,23 +279,26 @@ async def dispatch(self, request: Request, call_next):
 
         if not allowed:
             logger.warning(
-                "Rate limited: tier=%s key=%s type=%s path=%s retry_after=%ss",
-                tier, (uuid_header[:8] if uuid_header else client_ip), limit_type,
-                request.url.path, retry_after,
+                "Rate limited: tier=%s uuid_status=%s key=%s type=%s path=%s retry_after=%ss",
+                tier, uuid_status, (uuid_header[:8] if uuid_header else client_ip),
+                limit_type, request.url.path, retry_after,
             )
+            # Branch the CTA so a misconfigured Scholar (UUID present but invalid) gets a
+            # RECOVERY hint, while a true anonymous caller gets the acquisition pitch —
+            # tier-audit findings T4/T5, v0.5.37.
+            upgrade_hint, from_the_builder = _build_rate_limit_cta(tier, uuid_status)
             return JSONResponse(
                 status_code=429,
                 content={
                     "error": "rate_limit_exceeded",
                     "message": f"Too many requests. Please try again in {retry_after} seconds.",
                     "tier": tier,
+                    "uuid_status": uuid_status,
                     "limit": active_limit,
                     "limit_type": limit_type,
                     "retry_after": retry_after,
-                    "upgrade_hint": (
-                        "Register at verifimind.ysenseai.org/register for Scholar tier (30 req/60s). "
-                        "Pioneer tier: 100 req/60s."
-                    ) if tier == "anonymous" else None,
+                    "upgrade_hint": upgrade_hint,
+                    "from_the_builder": from_the_builder,
                     "documentation": "https://github.com/creator35lwb-web/VerifiMind-PEAS#rate-limits",
                 },
                 headers={
diff --git a/mcp-server/src/verifimind_mcp/server.py b/mcp-server/src/verifimind_mcp/server.py
@@ -40,7 +40,7 @@
 
 # v0.4.3 — System Notice: broadcast messages to all MCP users via env var
 _RAW_SYSTEM_NOTICE = os.environ.get("SYSTEM_NOTICE", "")
-SERVER_VERSION = "0.5.36"
+SERVER_VERSION = "0.5.37"
 
 # Mock mode transparency — shown in every tool response when no real inference is available
 MOCK_MODE_WARNING = (
diff --git a/mcp-server/tests/unit/test_p0_tool_manifest_audit.py b/mcp-server/tests/unit/test_p0_tool_manifest_audit.py
@@ -279,4 +279,4 @@ class TestServerVersion:
 
     def test_server_version_is_0522(self):
         import http_server
-        assert http_server.SERVER_VERSION == "0.5.36"
+        assert http_server.SERVER_VERSION == "0.5.37"
diff --git a/mcp-server/tests/unit/test_v050_foundation.py b/mcp-server/tests/unit/test_v050_foundation.py
@@ -67,8 +67,8 @@ def test_no_smithery_decorator_in_server_py(self):
     def test_server_version_is_0513(self):
         """SERVER_VERSION must be bumped to 0.5.16 (Scholar Incentives — P1-A/P1-C)."""
         from verifimind_mcp.server import SERVER_VERSION
-        assert SERVER_VERSION == "0.5.36", (
-            f"Expected 0.5.36, got {SERVER_VERSION}"
+        assert SERVER_VERSION == "0.5.37", (
+            f"Expected 0.5.37, got {SERVER_VERSION}"
         )
 
 
diff --git a/mcp-server/tests/unit/test_v0511_coordination.py b/mcp-server/tests/unit/test_v0511_coordination.py
@@ -588,7 +588,7 @@ class TestFreeToolRegression:
 
     def test_server_version_is_0513(self):
         from verifimind_mcp.server import SERVER_VERSION
-        assert SERVER_VERSION == "0.5.36"
+        assert SERVER_VERSION == "0.5.37"
 
     def test_wrap_response_still_works(self):
         from verifimind_mcp.server import wrap_response
diff --git a/mcp-server/tests/unit/test_v0512_polar.py b/mcp-server/tests/unit/test_v0512_polar.py
@@ -549,4 +549,4 @@ def test_no_stripe_in_tier_gate(self):
 class TestServerVersion:
     def test_server_version_is_0513(self):
         from verifimind_mcp.server import SERVER_VERSION
-        assert SERVER_VERSION == "0.5.36"
+        assert SERVER_VERSION == "0.5.37"
diff --git a/mcp-server/tests/unit/test_v0516_trinity_history.py b/mcp-server/tests/unit/test_v0516_trinity_history.py
@@ -159,4 +159,4 @@ def test_run_full_trinity_calls_persist(self):
 
     def test_server_version_is_0516(self):
         from verifimind_mcp.server import SERVER_VERSION
-        assert SERVER_VERSION == "0.5.36", f"Expected 0.5.36, got {SERVER_VERSION}"
+        assert SERVER_VERSION == "0.5.37", f"Expected 0.5.37, got {SERVER_VERSION}"
diff --git a/mcp-server/tests/unit/test_v0517_mcp_config_header.py b/mcp-server/tests/unit/test_v0517_mcp_config_header.py
@@ -72,4 +72,4 @@ class TestServerVersion:
 
     def test_server_version_is_0517(self):
         from verifimind_mcp.server import SERVER_VERSION
-        assert SERVER_VERSION == "0.5.36", f"Expected 0.5.36, got {SERVER_VERSION}"
+        assert SERVER_VERSION == "0.5.37", f"Expected 0.5.37, got {SERVER_VERSION}"
diff --git a/mcp-server/tests/unit/test_v0519_uuid_rate_limiter.py b/mcp-server/tests/unit/test_v0519_uuid_rate_limiter.py
@@ -21,6 +21,7 @@
     _resolve_uuid_tier,
     _uuid_tier_cache,
     UUID_TIER_CACHE_TTL,
+    _build_rate_limit_cta,
 )
 
 VALID_UUID = "019d40d6-9e84-7738-9c0c-fa85b2930600"
@@ -169,6 +170,42 @@ def test_expired_cache_triggers_fresh_lookup(self):
         _uuid_tier_cache.pop(test_uuid, None)
 
 
+# ---------------------------------------------------------------------------
+# v0.5.37 — 429 CTA branching (tier-audit T4/T5)
+# ---------------------------------------------------------------------------
+
+class TestBuildRateLimitCta:
+
+    def test_non_anonymous_gets_no_pitch(self):
+        # Registered users (scholar/pioneer) must never be told to "register"
+        assert _build_rate_limit_cta("scholar", "valid") == (None, None)
+        assert _build_rate_limit_cta("pioneer", "valid") == (None, None)
+
+    def test_anonymous_absent_is_acquisition_cta(self):
+        hint, builder = _build_rate_limit_cta("anonymous", "absent")
+        assert hint is not None
+        # acquisition: invites registration + states the unlock + privacy doctrine
+        assert "/register" in hint
+        assert "BYOK" in hint
+        assert "Privacy Doctrine v1.0" in hint
+        assert builder is not None and "feedback" in builder.lower()
+
+    def test_anonymous_invalid_is_recovery_not_acquisition(self):
+        hint, builder = _build_rate_limit_cta("anonymous", "invalid")
+        assert hint is not None
+        # recovery: points at the misconfig, does NOT pitch a fresh registration
+        assert "VERIFIMIND_UUID" in hint
+        assert "/setup" in hint
+        assert "Register a free Scholar UUID" not in hint
+        assert builder is not None
+
+    def test_builder_line_present_for_all_anonymous(self):
+        _, b_absent = _build_rate_limit_cta("anonymous", "absent")
+        _, b_invalid = _build_rate_limit_cta("anonymous", "invalid")
+        assert b_absent == b_invalid  # same founder voice regardless of cause
+        assert b_absent is not None
+
+
 # ---------------------------------------------------------------------------
 # Server version
 # ---------------------------------------------------------------------------
@@ -177,4 +214,4 @@ class TestServerVersion:
 
     def test_server_version_is_0519(self):
         from verifimind_mcp.server import SERVER_VERSION
-        assert SERVER_VERSION == "0.5.36", f"Expected 0.5.36, got {SERVER_VERSION}"
+        assert SERVER_VERSION == "0.5.37", f"Expected 0.5.37, got {SERVER_VERSION}"
diff --git a/mcp-server/tests/unit/test_v0525_inference_mode.py b/mcp-server/tests/unit/test_v0525_inference_mode.py
@@ -82,4 +82,4 @@ class TestServerVersion:
 
     def test_server_version_is_0525(self):
         import http_server
-        assert http_server.SERVER_VERSION == "0.5.36"
+        assert http_server.SERVER_VERSION == "0.5.37"
diff --git a/mcp-server/tests/unit/test_v0526_scanner_block_head.py b/mcp-server/tests/unit/test_v0526_scanner_block_head.py
@@ -90,4 +90,4 @@ class TestServerVersion:
 
     def test_server_version_is_0526(self):
         import http_server
-        assert http_server.SERVER_VERSION == "0.5.36"
+        assert http_server.SERVER_VERSION == "0.5.37"
diff --git a/server.json b/server.json
@@ -2,8 +2,8 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.creator35lwb-web/verifimind-genesis",
   "title": "VerifiMind PEAS - RefleXion Trinity",
-  "description": "Multi-Agent AI Validation: X-Z-CS Trinity. 13 tools FREE. Growth-first. v0.5.36",
-  "version": "3.13.0",
+  "description": "Multi-Agent AI Validation: X-Z-CS Trinity. 13 tools FREE. Growth-first. v0.5.37",
+  "version": "3.14.0",
   "repository": {
     "url": "https://github.com/creator35lwb-web/VerifiMind-PEAS",
     "source": "github"

Original file line number	Diff line number	Diff line change
`@@ -67,8 +67,8 @@ def test_no_smithery_decorator_in_server_py(self):`
`67`	`67`	`def test_server_version_is_0513(self):`
`68`	`68`	`"""SERVER_VERSION must be bumped to 0.5.16 (Scholar Incentives — P1-A/P1-C)."""`
`69`	`69`	`from verifimind_mcp.server import SERVER_VERSION`
`70`		`- assert SERVER_VERSION == "0.5.36", (`
`71`		`- f"Expected 0.5.36, got {SERVER_VERSION}"`
	`70`	`+ assert SERVER_VERSION == "0.5.37", (`
	`71`	`+ f"Expected 0.5.37, got {SERVER_VERSION}"`
`72`	`72`	`)`
`73`	`73`
`74`	`74`