hardening(identity): make AssessResult.account_verification a typed field

The UCP profile builder reads the typed AssessResult.operator_verification
first then falls back to data.raw, but the typed account_verification branch
was unreachable because the field wasn't declared on the dataclass. Add the
optional account_verification: dict[str, Any] | None field for symmetry with
operator_verification (mirrors node-commerce AgentScoreData.account_verification),
populate it in AgentScoreClient._project, and adjust the UCP builder to read
the typed field directly.

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

Author: vvillait88

agentscore_commerce/identity/client.py

@@ -218,6 +218,9 @@ def _project(self, data: dict[str, Any]) -> AssessResult:
             else None
         )
 
+        av_data = data.get("account_verification")
+        account_verification = av_data if isinstance(av_data, dict) else None
+
         # SDK populates `quota` on the AssessResponse from X-Quota-* headers. Surface up
         # to adapters so merchants can monitor approach-to-cap proactively.
         quota_raw = data.get("quota")
@@ -237,6 +240,7 @@ def _project(self, data: dict[str, Any]) -> AssessResult:
             reasons=reasons,
             identity_method=data.get("identity_method"),
             operator_verification=operator_verification,
+            account_verification=account_verification,
             resolved_operator=data.get("resolved_operator"),
             verify_url=data.get("verify_url"),
             policy_result=data.get("policy_result"),

agentscore_commerce/identity/types.py

@@ -308,6 +308,11 @@ class AssessResult:
     reasons: list[str] = field(default_factory=list)
     identity_method: str | None = None
     operator_verification: OperatorVerification | None = None
+    # Account-level verification block (KYC level, age bracket, jurisdiction,
+    # sanctions verdict). Mirrors node-commerce's typed AgentScoreData.account_verification
+    # field so a hand-constructed AssessResult emits the same UCP claims in both
+    # languages without a raw-dict round trip.
+    account_verification: dict[str, Any] | None = None
     resolved_operator: str | None = None
     verify_url: str | None = None
     policy_result: PolicyResult | None = None

agentscore_commerce/identity/ucp.py

@@ -21,7 +21,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, cast
 
 if TYPE_CHECKING:
     from agentscore_commerce.identity.types import AssessResult
@@ -279,28 +279,29 @@ async def ucp_profile():
         # ``raw``; if a caller hand-constructs an AssessResult with mismatched
         # typed and raw verification blocks, both languages must pick the same
         # source so a profile signed in one verifies in the other.
-        typed_op = getattr(data, "operator_verification", None)
-        if typed_op is not None and not isinstance(typed_op, dict):
+        typed_op = data.operator_verification
+        operator_verification: dict[str, Any] = {}
+        if isinstance(typed_op, dict):
+            operator_verification = cast("dict[str, Any]", typed_op)
+        elif typed_op is not None:
             # Convert OperatorVerification dataclass to a plain dict.
             operator_verification = {
                 "level": getattr(typed_op, "level", None),
                 "operator_type": getattr(typed_op, "operator_type", None),
                 "verified_at": getattr(typed_op, "verified_at", None),
             }
-        else:
-            operator_verification = typed_op
         if not operator_verification:
             raw = data.raw or {}
-            operator_verification = raw.get("operator_verification") if isinstance(raw, dict) else None
-        if not isinstance(operator_verification, dict):
-            operator_verification = {}
+            raw_op = raw.get("operator_verification") if isinstance(raw, dict) else None
+            if isinstance(raw_op, dict):
+                operator_verification = raw_op
 
-        account_verification = getattr(data, "account_verification", None)
+        account_verification: dict[str, Any] = data.account_verification or {}
         if not account_verification:
             raw = data.raw or {}
-            account_verification = raw.get("account_verification") if isinstance(raw, dict) else None
-        if not isinstance(account_verification, dict):
-            account_verification = {}
+            raw_av = raw.get("account_verification") if isinstance(raw, dict) else None
+            if isinstance(raw_av, dict):
+                account_verification = raw_av
         # `dict.get(k) or DEFAULT` (not `dict.get(k, DEFAULT)`) coerces both a
         # missing key AND a present-but-falsy (None / "") value to the default,
         # matching the node sibling's `||` semantics. The API can return

tests/test_ucp.py

@@ -183,9 +183,9 @@ def test_coerces_empty_string_verified_at_to_none() -> None:
 
 
 # Typed-field fallback: production callers populate `data.raw`, but a
-# hand-constructed AssessResult (no raw) should still surface the operator
-# verification block via the typed `AssessResult.operator_verification` field
-# and the (optional) `account_verification` attribute. Mirrors the node sibling's
+# hand-constructed AssessResult (no raw) should still surface the verification
+# block via the typed `AssessResult.operator_verification` /
+# `AssessResult.account_verification` fields. Mirrors the node sibling's
 # typed-field read path.
 
 
@@ -209,22 +209,22 @@ def test_typed_operator_verification_fallback_when_raw_is_none() -> None:
     assert claims["verified_at"] == "2026-04-01T00:00:00Z"
 
 
-def test_typed_account_verification_fallback_via_setattr() -> None:
-    # `AssessResult` doesn't declare `account_verification` as a typed field, but
-    # a caller can still attach one ad-hoc. The fallback reads it via getattr so
-    # parity with the node sibling holds whichever way the caller populates it.
+def test_typed_account_verification_fallback_when_raw_is_none() -> None:
+    # `AssessResult.account_verification` is a typed optional field; a
+    # hand-constructed result populates it directly via the constructor and the
+    # builder reads it without consulting `raw`.
     result = AssessResult(
         allow=True,
         resolved_operator="op_typed",
         operator_verification=OperatorVerification(level="verified"),
+        account_verification={
+            "kyc_level": "verified",
+            "age_bracket": "21+",
+            "jurisdiction": "US",
+            "sanctions_clear": True,
+        },
         raw=None,
     )
-    result.account_verification = {  # type: ignore[attr-defined]
-        "kyc_level": "verified",
-        "age_bracket": "21+",
-        "jurisdiction": "US",
-        "sanctions_clear": True,
-    }
     profile = build_ucp_profile(**_base_kwargs(), data=result)
     d = profile.to_dict()
     cap = next(c for c in d["capabilities"] if c["name"] == AGENTSCORE_UCP_CAPABILITY)
@@ -247,12 +247,12 @@ def test_typed_takes_precedence_over_raw() -> None:
         allow=True,
         resolved_operator="op_xyz",
         operator_verification=OperatorVerification(level="verified"),
+        account_verification={"kyc_level": "verified"},
         raw={
             "operator_verification": {"level": "none"},
             "account_verification": {"kyc_level": "none"},
         },
     )
-    result.account_verification = {"kyc_level": "verified"}  # type: ignore[attr-defined]
     profile = build_ucp_profile(**_base_kwargs(), data=result)
     cap = next(c for c in profile.capabilities if c.name == AGENTSCORE_UCP_CAPABILITY)
     # Typed `account_verification.kyc_level == 'verified'` wins over the