BREAKING: Field alignment v2 — constraint prefixes, cnf restructure, risk_data, VCT versioning

[genereda]

Aligns the VI SDK and specification to the updated AP2 mandate schema.
Supersedes #21.

Breaking changes

Constraint type prefixes (all under mandate.*)

Old	New
mandate.checkout.allowed_merchant	mandate.checkout.allowed_merchants
payment.allowed_payee	mandate.payment.allowed_payees
payment.amount	mandate.payment.amount_range
payment.reference	mandate.payment.reference
payment.budget	mandate.payment.budget
payment.recurrence	mandate.payment.recurrence
payment.agent_recurrence	mandate.payment.agent_recurrence

Field name normalization inside constraint dicts

Constraint	Old field name	New field name
mandate.checkout.allowed_merchants	allowed_merchants	allowed
mandate.payment.allowed_payees	allowed_payees	allowed

The constraint type still distinguishes merchants from payees. The
intra-dict field name collapses to the common word allowed.

cnf.kid → cnf.jwk.kid

L2 cnf serialization restructured from sibling layout to nested:

// before
"cnf": { "jwk": {...}, "kid": "agent-key-1" }

// after
"cnf": { "jwk": {..., "kid": "agent-key-1"} }

Verifier now reads kid from inside the jwk object. Python field name
cnf_kid on CheckoutMandate / PaymentMandate unchanged.

Frequency enum — full ISO 20022 code set

Replaces the previous small set with the 12 ISO 20022 codes:

INDA, DAIL, WEEK, TOWK, TWMN, MNTH, TOMN, QUTR, FOMN,
SEMI, YEAR, TYEA.

Migration: MONTHLY→MNTH, ANNUALLY/YEARLY→YEAR, WEEKLY→WEEK,
DAILY→DAIL, QUARTERLY→QUTR, BIWEEKLY→TOWK.

VCT versioning

Every mandate VCT gains a .1 suffix.

Old	New
mandate.checkout.open	mandate.checkout.open.1
mandate.payment.open	mandate.payment.open.1
mandate.checkout	mandate.checkout.1
mandate.payment	mandate.payment.1

Consumers that hardcoded VCT strings must update.

New features

• PaymentBudgetConstraint.min — optional per-transaction minimum
  (integer minor units). Validated positive on construction.
• check_constraints(constraint_policy=...) — per-type strictness
  override. Verifiers can opt specific constraint types into STRICT while
  remaining PERMISSIVE overall. Open mandates still reject unknown
  constraints regardless of policy.
• CheckoutLineItemsConstraint.match_mode — "minimum" (default) or
  "exact". In exact mode each items entry must be fulfilled by at
  least one of its acceptable products. Unknown values fail closed.
• PaymentMandate.risk_data ({device_id, ip_address}) — documented
  as an optional L2 payment mandate disclosure for device signals.
• L2 aud / kid / iss semantics documented — aud targets the
  agent at L2, the payment network at L3a, the merchant at L3b; kid
  header references the L1 device key; iss identifies the credential
  provider.

Spec clarifications

• §3.1 — L1 signer corrected to "Issuer" (not "Credential Provider").
• §4.1 — merchant constraint: design-rationale note explaining why
  website is REQUIRED and id is OPTIONAL (WYSIWYS — what you see is
  what you sign).
• §5 — new "Per-Constraint Policy Overrides" subsection for
  constraint_policy.
• §10.1 (new) — "VCT Versioning" explainer under the VCT Registry.

Testing

• 326 tests pass (was 308 pre-PR; +18 new for constraint_policy,
  match_mode, risk_data, min on PaymentBudgetConstraint).
• ruff check clean, ruff format --check clean.
• Python matrix 3.10–3.13 exercised via CI on merge.

Commits

1. 1236f6e — BREAKING: field alignment per AP2 schema updates
2. 4ea0e5d — Add risk_data, L2 aud/kid/iss, VCT versioning,
   constraint_policy, match_mode

[fahads9]

Looks good. Just one correction:

In credential-format.md:

1. Section 4.4.2, mandate.payment.1: The currency and amount must be within a 'payment_amount' object.

Approved outside of this.

[genereda]

Thanks Fahad, fixed.

§4.4.2 (Immediate Payment Mandate) now uses the nested payment_amount object to match §5.6 (L3a) and the SDK's PaymentMandate.to_dict() output.

I also updated three spots that carried the same legacy flat shape, so the doc reads consistently:

• spec/credential-format.md §11.1, Payment Mandate Disclosure (Immediate) JSON example
• spec/credential-format.md §11.2, L3a payment mandate disclosure JSON example
• spec/README.md, Immediate mode walkthrough narrative bullet

Folded into the features commit as a fixup. Diff stays at 2 commits. PTAL.