docs(media-buy): publish buyer and seller proposal negotiation guide

[bokelley]

Goal

Publish an implementation guide that lets buyer-agent and seller-agent developers implement AdCP 3.2 proposal negotiation correctly without reconstructing behavior from schemas and review history.

Parent program: #6556
Protocol implementation: #6547

Required content

Shared model

• Proposal state and immutable-lineage diagram: draft → revised drafts → committed hold → accepted proposal → amendment/cancellation successor.
• Capability table for total_budget, product_changes, criteria, alternatives, and ask-only fallback.
• Clear separation of task-level validation/capability errors from per-proposal outcomes.
• Limits, batching, idempotency, source visibility, authorization, expiry, and atomicity rules.

Buyer guide

• Capability discovery and request construction.
• Typed-first negotiation with ask reserved for subjective commercial preferences.
• Error-first response handling and safe discriminated-union access.
• Independent verification of budgets, product changes, targeting resolution, alternative count/digests, and unsatisfied subsets.
• Counteroffer selection, exact retry versus changed-request keys, finalization, expiry-aware acceptance, amendment, cancellation, and decline.

Seller guide

• Capability declaration and batch-wide preflight before mutation.
• Separation between SDK/protocol validation and application-owned commercial policy.
• Immutable successor generation, source lineage, digest generation, staged persistence, per-source outcomes, and atomic finalization.
• Security and operational guidance for cardinality, authorization, replay, logging, and transaction boundaries.

Examples

• One shared fictional scenario using Sam, Pinnacle Agency, and StreamHaus.
• Runnable examples for TypeScript, Python, Go, and Java as their SDK work lands.
• Exact revised, partial, unable, task-error, finalize, accept, amendment, and cancellation payloads.
• Link each example to the matching training-agent profile and storyboard.

Acceptance criteria

• Examples validate against current source schemas and are exercised in CI where possible.
• Documentation distinguishes normative requirements from recommendations and commercial-policy examples.
• A new implementor can run the documented buyer against the public training seller and reproduce the storyboard outcomes.
• Specialist training module S1 links to the guide and uses the same scenario terminology.

Dependencies

• feat(media-buy): structure proposal refinement negotiation #6547 for final protocol semantics.
• SDK and training-agent work under epic: make proposal negotiation easy to implement, teach, and verify #6556 for runnable examples.

Additional required content (contract hardening in #6547, efe48f522e)

• Constraint semantics table for all four typed constraints: total_budget, cpm (every purchase fixed cpm/vcpm in currency at or under max; auction/non-CPM pricing is unsatisfied), impressions (summed purchase impressions at or over min), flight (start_no_later_than needs a concrete start — asap is unsatisfied; end_no_earlier_than).
• The partial invariant: every draft on a partial satisfies every constraint absent from unsatisfied_constraints, whatever the reason_code — this is what lets buyers skip prose parsing.
• Reason-code selection guide: constraint_unsatisfiable precedence, commercially_declined is ask-only, hold_unavailable vs batch_aborted, double-finalize INVALID_STATE.
• Digest verification how-to: recompute sha256:base64url(sha256(JCS(commercial_terms))) and compare; treat digest agreement, not seller assertion, as the comparability guarantee.
• Lineage: parent_proposal_id chain walking for audit and amendment history.
• Hold governance for sellers: refusal semantics, concurrent-hold caps, choosing expires_at, when to answer submitted for re-underwriting.
• Negotiation security section for both sides: fence ask from pricing authority; rate-limit un-held constraint probing (price-oracle risk); only commercial_terms binds — prose never does.
• Adapter warning: legacy budget_range is a soft filter, compact total_budget a hard constraint — same shape, inverted semantics; more_like_this maps only lossily to ask.

[bokelley]

Triage

Classification: Feature — documentation
Bucket(s): web/site/docs, spec-adjacent enablement
Status: deferred
Milestone: 3.2.0

Blocked-on: #6547 — implementor guide requires final proposal-negotiation protocol semantics before content can land. Resurfaces on merge.

---

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

---

Generated by Claude Code

[bokelley]

The implementation guide and S1 alignment landed in #6588. All 10 exact payload examples are source-schema validated, digest checks use the SDK JCS implementation, and the guide links the canonical media_buy_seller/typed_proposal_negotiation storyboard. Leaving this issue open only for the final public-seller reproducibility criterion: #6558 must expose the deterministic SDK-backed profile before the documented scenario can be run end to end without a separate validator.

[bokelley]

Live public-profile verification after #6688: the constrained seller is healthy when pinned to the current wire bundle 3.2-beta.2. It advertises all seven lifecycle tools and reproduces the documented three-to-two flow (partial / alternatives_unavailable with two drafts, then revised with two under a new idempotency key). However, the guide still pins 3.2-beta.0 in its prose and runnable example. The public router no longer supports that exact ordinal, so it downshifts the call to 3.1 and the example fails its capability assertion. Leaving this issue open until the guide pin and expected response version are updated to 3.2-beta.2; then the live reproducibility criterion is satisfied.

[bokelley]

Triage

Classification: Doc fix
Bucket(s): web/site/docs
Status: drafting-pr

Draft PR #6690 updates the version pin from 3.2-beta.0 to 3.2-beta.2 across all three media-buy guide files (proposal-negotiation.mdx, media-buy/index.mdx, product-discovery/index.mdx) — 11 occurrences total, including the prose, the wireAdcpVersion workaround note, the const version object, and the capability assertion check that was failing against the public router.

One follow-up to confirm before merge: if adcp-client#2609 has shipped and ADCPMultiAgentClient.simple() can now target exact beta ordinals, the workaround note at line 497 of proposal-negotiation.mdx should be removed rather than retained with the updated version string.

---

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

---

Generated by Claude Code