fix: remove jurisdiction_restricted from FIXABLE_DENIAL_REASONS

The API only emits jurisdiction_restricted AFTER KYC is verified — meaning the
user's KYC'd country is in the merchant's blocked list (or absent from the
allowed list). Re-doing KYC won't change the country, so it's permanent. Same
shape as sanctions_flagged / age_insufficient — should surface contact_support,
not bootstrap a doomed verification session.

Also flips empty/None reasons to return False (don't bootstrap on unknown deny —
default to bare denial). Updates the canonical wallet_not_trusted instructions
copy and all six adapter comments to spell out the API-side rationale.

Tests updated: jurisdiction_restricted now in the unfixable bucket alongside
sanctions/age, empty reasons returns False.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: vvillait88

agentscore_commerce/identity/_denial.py

@@ -23,26 +23,35 @@
 
 from agentscore_commerce.identity.types import DenialReason, VerifyWalletSignerResult
 
+# Compliance denial reasons that can be resolved by re-completing KYC. The API emits these
+# when KYC is missing/pending/failed; the user can re-verify and retry.
+#
+# `jurisdiction_restricted` is NOT in this set — the API only emits it AFTER KYC is verified,
+# meaning the user's KYC'd country is in the merchant's blocked list (or absent from the
+# allowed list). Re-doing KYC won't change the country, so it's permanent. Same shape as
+# `sanctions_flagged` and `age_insufficient` — surface contact_support, don't waste a
+# /v1/sessions mint.
 FIXABLE_DENIAL_REASONS: frozenset[str] = frozenset(
     {
         "kyc_required",
         "kyc_pending",
         "kyc_failed",
-        "jurisdiction_restricted",
     }
 )
 
 
 def is_fixable_denial(reasons: Iterable[str] | None) -> bool:
-    """Return True when every reason is fixable (or reasons is empty/None).
+    """Return True when every reason is fixable via KYC re-verification.
 
-    Sanctions and age failures are permanent — any of those in the list returns False.
+    False when any reason is permanent (sanctions, age, jurisdiction_restricted) OR when
+    reasons is empty/None — without a known reason we can't promise a fix, so default to
+    the bare denial path.
     """
     if not reasons:
-        return True
+        return False
     reasons_list = list(reasons)
     if not reasons_list:
-        return True
+        return False
     return all(r in FIXABLE_DENIAL_REASONS for r in reasons_list)
 
 

agentscore_commerce/identity/_response.py

@@ -142,10 +142,13 @@
             ),
             (
                 "Fixable compliance reasons (`kyc_required`, `kyc_pending`, "
-                "`kyc_failed`, `jurisdiction_required` without explicit restriction) "
-                "do NOT land on this code — the gate auto-mints a verification session "
-                "for those and returns `identity_verification_required` with poll "
-                "endpoints, same shape as `missing_identity`."
+                "`kyc_failed`) do NOT land on this code — the gate auto-mints a "
+                "verification session for those and returns "
+                "`identity_verification_required` with poll endpoints, same shape as "
+                "`missing_identity`. `jurisdiction_restricted` IS in the unfixable "
+                "bucket because the API only emits it after KYC is verified (the "
+                "user's KYC'd country is in the blocked list — re-doing KYC won't "
+                "change the country)."
             ),
         ],
         "user_message": (

agentscore_commerce/identity/aiohttp.py

@@ -179,12 +179,14 @@ async def _agentscore_middleware(
                 request["agentscore"] = result.raw
                 return await handler(request)
 
-            # Fixable compliance denials (kyc_required, kyc_pending, kyc_failed,
-            # jurisdiction_required when not explicitly restricted) get the same UX as
-            # missing_identity: the gate mints a fresh verification session, the agent
-            # polls until status=verified, gets a fresh opc_..., and retries with
-            # X-Operator-Token. Unfixable reasons (sanctions, age, jurisdiction_restricted)
-            # keep the bare wallet_not_trusted denial — re-verification won't fix them.
+            # Fixable compliance denials (kyc_required, kyc_pending, kyc_failed) get the
+            # same UX as missing_identity: the gate mints a fresh verification session,
+            # the agent polls until status=verified, gets a fresh opc_..., and retries
+            # with X-Operator-Token. Unfixable reasons (sanctions_flagged, age_insufficient,
+            # jurisdiction_restricted) keep the bare wallet_not_trusted denial.
+            # `jurisdiction_restricted` is unfixable: the API only emits it after KYC is
+            # verified (the user's KYC'd country is in the blocked list — re-doing KYC
+            # won't change the country).
             if is_fixable_denial(result.reasons) and create_session_on_missing is not None:
                 session_reason = await try_create_session_denial_reason(
                     create_session_on_missing,

agentscore_commerce/identity/django.py

@@ -170,12 +170,14 @@ def __call__(self, request: HttpRequest) -> Any:
                 setattr(request, "agentscore", result.raw)  # noqa: B010 — dynamic attribute attach on HttpRequest
                 return self.get_response(request)
 
-            # Fixable compliance denials (kyc_required, kyc_pending, kyc_failed,
-            # jurisdiction_required when not explicitly restricted) get the same UX as
-            # missing_identity: the gate mints a fresh verification session, the agent
-            # polls until status=verified, gets a fresh opc_..., and retries with
-            # X-Operator-Token. Unfixable reasons (sanctions, age, jurisdiction_restricted)
-            # keep the bare wallet_not_trusted denial — re-verification won't fix them.
+            # Fixable compliance denials (kyc_required, kyc_pending, kyc_failed) get the
+            # same UX as missing_identity: the gate mints a fresh verification session,
+            # the agent polls until status=verified, gets a fresh opc_..., and retries
+            # with X-Operator-Token. Unfixable reasons (sanctions_flagged, age_insufficient,
+            # jurisdiction_restricted) keep the bare wallet_not_trusted denial.
+            # `jurisdiction_restricted` is unfixable: the API only emits it after KYC is
+            # verified (the user's KYC'd country is in the blocked list — re-doing KYC
+            # won't change the country).
             if is_fixable_denial(result.reasons) and self._create_session_on_missing is not None:
                 session_reason = try_create_session_denial_reason_sync(
                     self._create_session_on_missing,

agentscore_commerce/identity/fastapi.py

@@ -208,13 +208,14 @@ async def __call__(self, request: Request) -> None:
             setattr(request.state, ASSESS_STATE_KEY, result.raw)
             return
 
-        # Fixable compliance denials (kyc_required, kyc_pending, kyc_failed,
-        # jurisdiction_required when not explicitly restricted) get the same UX as
-        # missing_identity: the gate mints a fresh verification session, the agent
-        # polls until status=verified, gets a fresh opc_..., and retries with
+        # Fixable compliance denials (kyc_required, kyc_pending, kyc_failed) get the
+        # same UX as missing_identity: the gate mints a fresh verification session, the
+        # agent polls until status=verified, gets a fresh opc_..., and retries with
         # X-Operator-Token. No "go to verify_url and tell us when done" gap.
-        # Unfixable reasons (sanctions, age, jurisdiction_restricted) keep the
-        # bare wallet_not_trusted denial — re-verification won't fix them.
+        # Unfixable reasons (sanctions_flagged, age_insufficient, jurisdiction_restricted)
+        # keep the bare wallet_not_trusted denial — re-verification won't fix them.
+        # `jurisdiction_restricted` is unfixable because the API only emits it AFTER KYC
+        # is verified (the user's KYC'd country is in the blocked list).
         if is_fixable_denial(result.reasons) and self._create_session_on_missing is not None:
             session_reason = await try_create_session_denial_reason(
                 self._create_session_on_missing,

agentscore_commerce/identity/flask.py

@@ -184,12 +184,14 @@ def _agentscore_check() -> Response | tuple[Response, int] | None:
                 g.agentscore = result.raw
                 return None
 
-            # Fixable compliance denials (kyc_required, kyc_pending, kyc_failed,
-            # jurisdiction_required when not explicitly restricted) get the same UX as
-            # missing_identity: the gate mints a fresh verification session, the agent
-            # polls until status=verified, gets a fresh opc_..., and retries with
-            # X-Operator-Token. Unfixable reasons (sanctions, age, jurisdiction_restricted)
-            # keep the bare wallet_not_trusted denial — re-verification won't fix them.
+            # Fixable compliance denials (kyc_required, kyc_pending, kyc_failed) get the
+            # same UX as missing_identity: the gate mints a fresh verification session,
+            # the agent polls until status=verified, gets a fresh opc_..., and retries
+            # with X-Operator-Token. Unfixable reasons (sanctions_flagged, age_insufficient,
+            # jurisdiction_restricted) keep the bare wallet_not_trusted denial.
+            # `jurisdiction_restricted` is unfixable: the API only emits it after KYC is
+            # verified (the user's KYC'd country is in the blocked list — re-doing KYC
+            # won't change the country).
             if is_fixable_denial(result.reasons) and create_session_on_missing is not None:
                 session_reason = try_create_session_denial_reason_sync(
                     create_session_on_missing,

agentscore_commerce/identity/middleware.py

@@ -191,12 +191,14 @@ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
                 await self.app(scope, receive, send)
                 return
 
-            # Fixable compliance denials (kyc_required, kyc_pending, kyc_failed,
-            # jurisdiction_required when not explicitly restricted) get the same UX as
-            # missing_identity: the gate mints a fresh verification session, the agent
-            # polls until status=verified, gets a fresh opc_..., and retries with
-            # X-Operator-Token. Unfixable reasons (sanctions, age, jurisdiction_restricted)
-            # keep the bare wallet_not_trusted denial — re-verification won't fix them.
+            # Fixable compliance denials (kyc_required, kyc_pending, kyc_failed) get the
+            # same UX as missing_identity: the gate mints a fresh verification session,
+            # the agent polls until status=verified, gets a fresh opc_..., and retries
+            # with X-Operator-Token. Unfixable reasons (sanctions_flagged, age_insufficient,
+            # jurisdiction_restricted) keep the bare wallet_not_trusted denial.
+            # `jurisdiction_restricted` is unfixable: the API only emits it after KYC is
+            # verified (the user's KYC'd country is in the blocked list — re-doing KYC
+            # won't change the country).
             if is_fixable_denial(result.reasons) and self._create_session_on_missing is not None:
                 session_reason = await try_create_session_denial_reason(
                     self._create_session_on_missing,

agentscore_commerce/identity/sanic.py

@@ -181,12 +181,14 @@ async def _agentscore_check(request: Request) -> HTTPResponse | None:
                 request.ctx.agentscore = result.raw
                 return None
 
-            # Fixable compliance denials (kyc_required, kyc_pending, kyc_failed,
-            # jurisdiction_required when not explicitly restricted) get the same UX as
-            # missing_identity: the gate mints a fresh verification session, the agent
-            # polls until status=verified, gets a fresh opc_..., and retries with
-            # X-Operator-Token. Unfixable reasons (sanctions, age, jurisdiction_restricted)
-            # keep the bare wallet_not_trusted denial — re-verification won't fix them.
+            # Fixable compliance denials (kyc_required, kyc_pending, kyc_failed) get the
+            # same UX as missing_identity: the gate mints a fresh verification session,
+            # the agent polls until status=verified, gets a fresh opc_..., and retries
+            # with X-Operator-Token. Unfixable reasons (sanctions_flagged, age_insufficient,
+            # jurisdiction_restricted) keep the bare wallet_not_trusted denial.
+            # `jurisdiction_restricted` is unfixable: the API only emits it after KYC is
+            # verified (the user's KYC'd country is in the blocked list — re-doing KYC
+            # won't change the country).
             if is_fixable_denial(result.reasons) and create_session_on_missing is not None:
                 session_reason = await try_create_session_denial_reason(
                     create_session_on_missing,

tests/test_denial.py

@@ -40,20 +40,29 @@ def test_returns_403_for_everything_else(self, code):
 
 class TestIsFixableDenial:
     def test_known_fixable_reasons_in_set(self):
-        for r in ("kyc_required", "kyc_pending", "kyc_failed", "jurisdiction_restricted"):
+        for r in ("kyc_required", "kyc_pending", "kyc_failed"):
             assert r in FIXABLE_DENIAL_REASONS
 
-    def test_empty_or_none_treated_as_fixable(self):
-        assert is_fixable_denial(None)
-        assert is_fixable_denial([])
+    def test_jurisdiction_restricted_is_unfixable(self):
+        # The API only emits jurisdiction_restricted AFTER KYC is verified, meaning the
+        # user's KYC'd country is in the merchant's blocked list. Re-doing KYC won't
+        # change the country — same shape as sanctions_flagged / age_insufficient.
+        assert "jurisdiction_restricted" not in FIXABLE_DENIAL_REASONS
+
+    def test_empty_or_none_returns_false(self):
+        # Without a known reason we can't promise a fix — default to bare denial.
+        assert not is_fixable_denial(None)
+        assert not is_fixable_denial([])
 
     def test_all_fixable_returns_true(self):
-        assert is_fixable_denial(["kyc_required", "jurisdiction_restricted"])
+        assert is_fixable_denial(["kyc_required", "kyc_pending"])
 
     def test_any_permanent_returns_false(self):
-        assert not is_fixable_denial(["sanctions_not_clear"])
-        assert not is_fixable_denial(["age_not_verified"])
-        assert not is_fixable_denial(["kyc_required", "sanctions_not_clear"])
+        assert not is_fixable_denial(["sanctions_flagged"])
+        assert not is_fixable_denial(["age_insufficient"])
+        assert not is_fixable_denial(["jurisdiction_restricted"])
+        assert not is_fixable_denial(["kyc_required", "sanctions_flagged"])
+        assert not is_fixable_denial(["kyc_required", "jurisdiction_restricted"])
 
 
 class TestBuildSignerMismatchBody: