feat: add structured Risk Payload schema for Section 7.4 risk signals

[ayushozha]

Summary

• Define TripConditionType, TripConditionStatus, FCBState, TripCondition, and RiskPayload Pydantic models in new src/ap2/types/risk.py for structured risk signal exchange (Section 7.4)
• Add optional risk_payload: RiskPayload field to IntentMandate, CartMandate, and PaymentMandateContents in mandate.py
• Export new types from src/ap2/types/__init__.py

Test plan

• Verify RiskPayload can be instantiated with valid enum values and serialized to JSON
• Verify IntentMandate, CartMandate, and PaymentMandateContents accept optional risk_payload field
• Verify backward compatibility: existing mandate instantiation without risk_payload still works
• Verify enum values match Section 7.4 specification

Fixes #163

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a comprehensive framework for structured risk signal exchange, aligning with Section 7.4 specifications. It establishes new Pydantic models to represent various aspects of risk assessment, such as trip conditions and fiduciary circuit breaker states, and integrates this risk information directly into existing mandate structures. This enhancement provides a standardized mechanism for agents to communicate and act upon runtime risk governance data.

Highlights

• New Risk Models Defined: Pydantic models for TripConditionType, TripConditionStatus, FCBState, TripCondition, and RiskPayload were defined in a new file src/ap2/types/risk.py to structure risk signals.
• Risk Payload Integration: An optional risk_payload field was added to IntentMandate, CartMandate, and PaymentMandateContents to carry risk assessment data within mandate structures.
• Type Export: The newly defined risk-related types were exported from src/ap2/types/__init__.py to make them accessible throughout the system.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

The pull request introduces a new structured risk payload schema, including Fiduciary Circuit Breaker (FCB) states and various trip conditions, and integrates this payload into existing mandate types. Review feedback suggests using typing.List for type hints to ensure broader Python version compatibility and recommends alphabetically sorting imports for improved code organization.

[gemini-code-assist]

To improve code organization and readability, it's good practice to sort imports alphabetically. This helps in quickly locating modules and maintaining a consistent style across the codebase.

Suggested change

	from datetime import datetime
	from datetime import timezone
	from enum import Enum
	from typing import Optional
	from pydantic import BaseModel
	from pydantic import Field
	from datetime import datetime, timezone
	from enum import Enum
	from typing import Optional
	from pydantic import BaseModel, Field

[ravyg]

Hi @ayush — just flagging that PR #165 already addresses Issue #163 with a fairly comprehensive implementation covering:

Python Pydantic models + Go type definitions
Full FCB state machine (CLOSED → OPEN → HALF_OPEN → TERMINATED)
Human escalation protocol modeling
Documentation (docs/topics/fiduciary-circuit-breaker.md)
33 tests across both languages

It's been open and in review for a while now. This PR appears to reimplement much of the same surface area (FCBState, TripCondition, RiskPayload, etc.) without referencing or building on that existing work.
I do like the idea of wiring risk_payload into the mandate models — that's something #165 doesn't do yet — but that would make more sense as a follow-up PR or as a suggested change on #165 rather than a parallel reimplementation.
Could we coordinate here? Happy to incorporate the mandate integration into #165, or discuss if you see a reason for a different approach. Just want to avoid duplicated effort and make sure we're building on each other's work rather than around it.

[ravyg]

Hey @ayushozha, thanks for your contribution on Issue #163.
I've incorporated the core ideas from your PR — wiring risk signals into the mandate chain and distinguishing behavioral risk from identity risk — into my PR #165, which has the more complete FCB implementation (Go types, 27 Python tests, 11 Go tests, and documentation).
I've added you as a co-author on the commit to give you credit:
feat(types): integrate risk_payload into mandates and add CREDENTIAL_CHECK condition

Refs: #163, #187

Co-Authored-By: ayushozha <[email protected]>

One ask: The Google CLA check is currently failing because the Co-Authored-By trailer requires all contributors to have signed the CLA. Could you sign it here? https://cla.developers.google.com/
Once that's done, the check will pass and we can get this merged.

I'll wait until Mar 27 for the CLA to go through. If it's not signed by then, I'll still credit you in the commit message body and with an @ mention — but just a heads up, that approach won't show up as a contribution on your GitHub profile or in the repo's contributor list.
Either way, your ideas are credited and referenced. Let me know if you have any questions.

[ayushozha]

Hey @ravyg, thanks for the heads up! I've signed the Google CLA and fixed the commit author email — the CLA check is now passing. Everything should be good to go on your end for PR #165 as well. Appreciate the credit!