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

[bokelley]

Context

AdCP 3.2 adds structured proposal negotiation through refine_proposals (#6450, adcontextprotocol/adcp#6547). @adcp/sdk should make the safe path the easy path for both buyer and seller agents. This is the primary SDK implementation because the AdCP training agent will consume these primitives.

Parent program: adcontextprotocol/adcp#6556

Buyer-side acceptance criteria

• Expose typed request/result unions for refine_proposals, including revised, partial, unable, and finalized without unsafe field access.
• Provide capability-aware request construction for total_budget, product_changes, alternatives, and criteria.
• Reject unsupported dimensions and requests above max_alternatives, the protocol maximum of 10 alternatives, or 25 refinements before transport.
• Provide response verification helpers for ordering, alternative count, unique terms_digest, total-budget currency/bounds, product include/omit actions, and machine-readable unsatisfied subsets.
• Provide an orchestration example/helper covering exact idempotent retry, changed-request keys, counteroffer selection, finalization, hold expiry, and acceptance.
• Surface task-level errors before exposing success fields.

Seller-side acceptance criteria

• Provide handler/server primitives for declaring proposal_refinement capabilities and validating a complete batch before mutation.
• Model commercial evaluation as an application callback; the SDK validates and classifies results but does not choose business terms.
• Provide helpers/hooks for immutable successor creation, source lineage, terms_digest, and staging writes until response validation succeeds.
• Support atomic finalize batches and rollback/no-write behavior on preflight failure.
• Validate generated responses against the source request before returning or persisting.

Tests and examples

• Unit tests cover all reason codes, capability omissions, mixed-batch rejection, 10/25 boundaries, partial alternatives, and finalization atomicity.
• Add runnable buyer and seller examples that can target the AdCP training agent profile from epic: make proposal negotiation easy to implement, teach, and verify adcp#6556.
• Document public APIs and migration/fallback behavior for legacy get_products refinement.

Dependency

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

Out of scope

• Commercial optimization, pricing strategy, or LLM interpretation policy.

[bokelley]

Triage

Classification: Feature request
Bucket(s): library, dx, cross-repo
Status: deferred

My take: This issue requires the finalized AdCP 3.2 refine_proposals wire contract from adcontextprotocol/adcp#6547 before any SDK primitives can be defined; building buyer/seller helpers against a draft schema would embed unstable API surface. Deferring until the upstream spec lands.

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

---

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

---

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.

TS-specific note: @adcp/sdk already exports the canonicalize used by the reference implementation, so the digest-verification helper is a thin wrapper.