feat(negotiation): add first-class buyer and seller proposal APIs

[bokelley]

Context

Add first-class AdCP 3.2 proposal-negotiation support to the Python client and seller framework, aligned with #6450 and adcontextprotocol/adcp#6547.

Parent program: adcontextprotocol/adcp#6556

Acceptance criteria

Buyer APIs

• Typed/Pydantic request and discriminated response models for refine_proposals.
• Capability-aware builders that distinguish typed dimensions from free-text ask and enforce seller/protocol limits before transport.
• Verification helpers for ordered results, hard-budget satisfaction, product changes, unique alternatives, unsatisfied subsets, committed holds, and expiry-aware acceptance.
• A documented orchestration example covering revised, partial counteroffer, unable, finalization, exact retry, and changed-request idempotency.
• Error-first handling for task-level UNSUPPORTED_FEATURE and VALIDATION_ERROR.

Seller framework

• Handler/ProposalManager support for declaring refinement capabilities and performing batch-wide preflight before mutation.
• Application callbacks own commercial decisions; framework helpers own protocol validation, result classification, immutable proposal lineage, response validation, and atomic finalize hooks.
• Compatibility with the existing decisioning and proposal-manager architecture rather than a parallel negotiation subsystem.

Verification

• Tests cover every outcome/reason code, mixed batches, cardinality boundaries, fail-closed budgets, partial alternatives, source unavailability, idempotency, and finalize rollback.
• Add runnable buyer and seller examples compatible with the AdCP training seller scenario in epic: make proposal negotiation easy to implement, teach, and verify adcp#6556.
• Document legacy get_products refinement fallback limits.

Dependency

Blocked on the final 3.2 schema/API shape from adcontextprotocol/adcp#6547.

Out of scope

• Commercial pricing or optimization policy.

[bokelley]

Triage

Classification: Feature request
Bucket(s): client, handlers, cross-repo (no matching repo labels found — noted in run summary)
Status: deferred
Milestone: omitted (blocked/epic)

What the experts said:

• ad-tech-protocol-expert: refine_proposals task shape belongs to the finalized AdCP 3.2 schema in adcp#6547; implementing against a draft risks protocol drift and non-trivial rework — defer is correct.
• adtech-product-expert: The scope (buyer typed models + seller ProposalManager + comprehensive test matrix + runnable examples) is the right surface for a coordinated milestone addition, but the upstream spec lock is a hard prerequisite — premature implementation creates buyer/seller interop ambiguity before the wire shape stabilizes.

My take: Defer: Blocked-on. The issue correctly calls out the dependency; the Python implementation can't safely proceed until adcp#6547 finalizes the 3.2 schema shape. When the blocker resolves, the epic-sized scope here (buyer client surface, seller handler/ProposalManager, outcome/reason test coverage, runnable examples) warrants a planning pass to decompose into sequenced PRs before execution begins.

Blocked-on: adcontextprotocol/adcp#6547 — resurfaces on merge.

---

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

---

Generated by Claude Code

[bokelley]

The protocol surface grew in adcontextprotocol/adcp#6547 (efe48f522e) after a pre-merge red team. Delta to pick up on top of the original acceptance criteria:

• Three new typed constraints alongside total_budget: cpm {max, currency} (every purchase priced fixed cpm/vcpm in currency at or under max), impressions {min} (summed purchase impressions), flight {start_no_later_than?, end_no_earlier_than?} (checked against envelope start_time/end_time; asap never satisfies a start bound). Builders, validators, and capability gating should cover all of them.
• Dimension rename: the capability value is product_changes (was product_selection in the draft); dimensions now match request field names exactly.
• unsatisfied_constraints is open strings, not a closed enum — parse it as constraint keys echoed from the request, and don't bake an enum into generated types.
• New reason codes hold_unavailable and batch_aborted, plus a precedence rule worth encoding in verification helpers: constraint_unsatisfiable wins whenever a typed constraint failed; typed failures never surface as commercially_declined. Double-finalize of a held draft is task-level INVALID_STATE.
• Lineage: every returned proposal must carry parent_proposal_id equal to the entry's source_proposal_id — a cheap, high-value response-verification check.
• Digest verification is now normative: terms_digest = sha256: + base64url(SHA-256(RFC 8785 JCS of commercial_terms)). Buyer helpers should recompute and compare rather than trusting the string, and treat alternative distinctness as distinct commercial_terms.
• Partial invariant: on partial, every draft satisfies every constraint absent from unsatisfied_constraints — verification helpers can and should assert this.
• UNSUPPORTED_FEATURE details now follow error-details/unsupported-refinement-dimension.json (unsupported_dimension + echoed supported_dimensions) — useful for typed error recovery.

Python-specific note: digest verification needs an RFC 8785 (JCS) canonicalizer — rfc8785 on PyPI is the reference-quality choice; pin it rather than hand-rolling number serialization.

[bokelley]

Triage

Classification: Feature request
Bucket(s): client, handlers, cross-repo
Status: ready-to-implement

What the experts said:

• ad-tech-protocol-expert: Delta fits AdCP patterns; constraint_unsatisfiable precedence is normative MUST; use rfc8785 (already pinned) for JCS digest — json.dumps is non-compliant; two spec ambiguities flagged (vCPM under cpm; flight naming vs IO schema).
• adtech-product-expert: Sequence core + seller first, helpers + examples follow-on; batch preflight in framework intercept, not callback; minor bump to 7.1.0.

My take: adcp#6547 has merged — blocker resolved. Both experts agree: ready to implement, sequenced. Two spec ambiguities (vCPM coverage under cpm; flight field naming vs IO schema) are worth a quick confirm from @bokelley but don't block Track 1 modeling.

• Track 1 (core): cpm {max, currency}, impressions {min}, flight {start_no_later_than?, end_no_earlier_than?} Pydantic constraint models; refine_proposals request/response with unsatisfied_constraints: list[str] (open string — no enum); product_changes capability dimension; lineage assert (parent_proposal_id == source_proposal_id); terms_digest helper via rfc8785 + fixture round-trip test; reason codes hold_unavailable/batch_aborted; conformance MUST constraint_unsatisfiable > commercially_declined; batch preflight in proposal_dispatch.py. Files: src/adcp/types/, src/adcp/decisioning/proposal_{dispatch,manager}.py.
• Track 2 (after Track 1 merges): Buyer verification helpers; 7-scenario orchestration example (external negotiation log required — parent_proposal_id is single-parent only); typed UNSUPPORTED_FEATURE recovery per unsupported-refinement-dimension.json.

---

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

---

Generated by Claude Code