feat(media-buy): parity for product, proposal, and live-buy action assessment

[bokelley]

Summary

Add Python SDK parity for the product → proposal → live-MediaBuy action assessment and seller resolution model in adcontextprotocol/adcp#6750.

This should align behaviorally with the JavaScript SDK issue linked below while using idiomatic Python models and tagged unions. It is also a concrete slice of #1031 and complements the proposal API work in #1023.

Required behavior

• Generate models for product action constraints, proposal change_terms, allowed_statuses, seller_managed, and live change_term_id.
• Preserve AdCP 3.1 available_actions[].terms_ref as opaque compatibility data; never infer that it identifies a proposal term.
• Prefer change_term_id for 3.2 and reject/flag mismatched dual-field aliases.
• Represent the full absence of proposal change_terms as legacy unknown, distinct from an explicit array that omits an action.
• Expose buyer helpers that report available_now, wrong_status, not_negotiated, unsupported_by_product, currently_unavailable, or legacy_unknown.
• Preflight portable budget, flight, package-count, and effective-timing constraints when sufficient current state is available.
• Keep opaque conditions unknown until seller evaluation.
• Route canonical actions to control_media_buy, refine_proposals, or sync_creatives and treat seller_managed as normal asynchronous task processing.
• Expose seller helpers that materialize binding proposal terms deliberately and derive current available_actions[] from accepted terms, status, authorization, and governance delegation.
• Reuse canonical MediaBuy transition validation; do not introduce seller-review statuses.

Compatibility and tests

Build a version matrix covering:

• released AdCP 3.1.19 with terms_ref and valid_actions[];
• a released 3.2 beta bundle predating change_term_id;
• current 3.2 with status-scoped terms and all typed constraint kinds;
• equal and unequal alias pairs;
• product-supported/not-negotiated, negotiated/wrong-status, immediately available, seller-managed wrong-route, opaque-condition unknown, stale-revision race, and terminal-state cases;
• serialization round trips that retain unknown future enum values without treating the action as available;
• sync and async client surfaces plus Pydantic validation/error quality.

Package and run media_buy_seller/change_rights_state_projection and the expanded compact lifecycle storyboard from the matching AdCP bundle.

Acceptance criteria

• Python buyers can render the same “possible / promised / available now” explanation as JavaScript buyers.
• Python sellers can derive the same current action projection from identical inputs.
• Cross-SDK golden fixtures produce equivalent normalized results.
• Legacy compatibility never expands authority.

Upstream: adcontextprotocol/adcp#6750
JavaScript parity: adcontextprotocol/adcp-client#2664

[bokelley]

Triage

Classification: Feature request
Bucket(s): client, cross-repo (no matching repo labels — label gap noted)
Status: deferred

What the experts said:

Expert panel skipped — outcome is determined by a structural upstream dependency rather than a design question. This issue is a concrete child of open epic #1031, which carries an explicit non-goal: "Revisit proposal-negotiation APIs only after AdCP 3.2 is a signed stable release" and "Do not expose experimental AdCP 3.2 schemas through Python's stable public API yet." The complement issue #1023 is itself blocked on adcontextprotocol/adcp#6547 (final 3.2 schema/API shape).

My take: The scope here is well-specified and the parity intent is clear, but the upstream spec (adcp#6750) and the proposal API layer (#1023) must land first — and #1031 makes deferring 3.2 buyer/seller helpers explicit policy until 3.2 is a signed stable release. Revisit when #1023 unblocks.

Blocked-on: #1023 — resurfaces on merge

---

Triaged by Claude Code. Session: https://claude.ai/code/

---

Generated by Claude Code