RFC: define structured negotiation requests for refine_proposals

[bokelley]

Summary

Define the buyer-to-seller negotiation contract for refine_proposals. The compact lifecycle introduced by #6115 currently accepts free-text instructions, but does not distinguish a desired outcome, a hard constraint, a preference, or a request for alternative proposals. This leaves common asks such as “this is too expensive,” “keep the outcome but reduce the budget,” and “give me three meaningfully different options” without interoperable semantics.

This is the protocol gap underneath part of #6287. Competence advertisement can help a buyer predict whether free text will be understood, and proposal-level negotiation scope can say which terms a seller is willing to reconsider, but neither defines how a buyer requests a revision.

Problem

instructions implies command semantics: the seller is being told what it must do. Proposal negotiation is different. A buyer may express:

• constraints that a successful revision must satisfy, such as a maximum total budget;
• preferences the seller should optimize for when trade-offs are necessary;
• requested changes, such as adding or removing products;
• requested alternatives, including how many options and which dimensions should vary; and
• open-ended context that cannot yet be expressed in typed fields.

A single free-text field can carry all of these, but clients cannot reliably construct it, sellers cannot reliably validate it, and SDKs cannot distinguish a rejected commercial request from an unsupported or misunderstood instruction.

Proposed direction

Use a hybrid, outcome-oriented request model:

1. Rename the free-text concept from instructions to request or revision_request so the language does not imply mandatory compliance.
2. Define a small typed control plane for the highest-value negotiation intents:
   • budget and commercial constraints;
   • product inclusion, exclusion, and substitution;
   • desired number and diversity of alternatives;
   • preferences and acceptable trade-offs.
3. Retain a free-text field for the long tail rather than attempting to model negotiation as JSON Patch.
4. Require results to distinguish fully applied, partially applied, commercially declined, and unsupported/uninterpreted requests, including which structured constraints were not satisfied.

Illustrative only:

{
  "proposal_id": "prop_123",
  "action": "revise",
  "revision_request": {
    "constraints": {
      "max_total_budget": {
        "amount": 50000,
        "currency": "USD"
      }
    },
    "alternatives": {
      "count": 3,
      "vary": ["product_mix", "budget"]
    },
    "preferences": ["prioritize_reach"],
    "notes": "Premium video can be removed if necessary."
  }
}

The final schema should express desired outcomes and boundaries, not provide a field-by-field mutation language over the proposal object.

Relationship to adjacent work

• feat(media-buy): add compact AdCP 3.2 lifecycle #6115: introduces refine_proposals and the current instructions field. The design and implementation of this RFC should be based on that work, but should not expand or delay feat(media-buy): add compact AdCP 3.2 lifecycle #6115 itself.
• RFC: competence advertisement for AdCP agents — declare what an agent can do within its capabilities #6287: competence advertisement remains relevant for pre-engagement routing and for the unstructured remainder of negotiation. It is not a substitute for typed revision semantics.
• Proposal-level negotiation scope: a future negotiable_terms, revision_scope, or similar field would say what the seller is willing to reconsider for a particular proposal. This RFC defines how the buyer asks for that reconsideration.

Design principles

• Proposal snapshots remain immutable; revision creates a successor proposal.
• A draft proposal is not implicitly negotiable in every dimension.
• A committed proposal has firm held terms, but may still be the source of a successor amendment or cancellation proposal.
• Structured requests must be usable by deterministic clients and SDKs without an LLM.
• Free text remains available for expressive negotiation that the typed surface does not cover.

Open questions

1. Should the top-level field be request, revision_request, or another noun?
2. What is the minimum useful typed vocabulary without recreating the entire proposal schema?
3. Should constraints and preferences use stable IDs so results can report which ones were applied or unsatisfied?
4. How should sellers distinguish “commercially declined,” “unsupported request type,” and “could not interpret free text”?
5. Should sellers advertise supported typed refinement dimensions through capabilities, leaving “competence” only for conversational interpretation?

Sequencing

Treat this as a separate RFC. Once the shape is agreed, implement it in a PR stacked on #6115 (or rebased onto main after #6115 lands), rather than adding more scope to #6115.

[bokelley]

Triage

Classification: RFC
Bucket(s): spec / protocol, media-buy
Status: deferred

My take: This RFC depends on #6115, which introduces refine_proposals and the instructions field and has not yet merged. The sequencing is explicit in the issue body: implementation should stack on or rebase onto main after #6115 lands. Expanding #6115 to include this RFC's scope would delay a PR already in human review — the right path is to let #6115 ship first, then pick this RFC up.

Blocked-on: #6115 — resurfaces on merge.

---

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

---

Generated by Claude Code

[lukasz-pubx]

Review against the RFC's stated foundation — #6115 @ d5f5c3d7c — with positions on each open question.

The problem is real and the direction is right: instructions (proposal-refinement.json) carries command semantics the negotiation surface shouldn't have, and "outcomes and boundaries, not JSON Patch" matches the compact lifecycle's own philosophy (commercial-terms.json: "This is the authoritative audit and refinement snapshot; allocations and narrative fields are explanatory views"). The design-principles section restates #6115's immutability semantics accurately.

One structural gap first, because it reshapes several open questions: the same tree already contains a second, partially-typed negotiation surface — get_products refine mode (product-refinement.json), with action: include|omit|more_like_this, free-text ask, absolute filters.budget_range, and per-ask outcome reporting via refinement_applied[]. Much of this RFC's proposed control plane already exists there in embryo, and refine-proposals-response.json explicitly bans refinement_applied. Unless addressed, this RFC creates a third negotiation grammar. Position: the typed vocabulary should be shared — reuse the refine[] shapes (include/omit, budget_range) rather than minting parallel ones, or explicitly declare get_products refine mode legacy for the compact lifecycle. Silence on the relationship is the only unacceptable outcome.

Q1 — field name. Neither request nor revision_request. Rename instructions → ask, matching the noun the sibling refinement surface already uses with exactly the intended non-command semantics ("What the buyer is asking for on this proposal"), and flatten the typed members to entry level rather than nesting a wrapper — action: "revise" already declares what the wrapper would restate: {proposal_id, action: "revise", constraints: {...}, alternatives: {...}, ask: "..."}.

Sequencing corollary: the rename is the one item that gets strictly more expensive once #6115 merges — pre-merge it's a one-line schema edit, post-merge a breaking rename on a just-shipped 3.2 surface. Suggest splitting proposed-direction point 1 out of this RFC and landing just the rename in #6115 (or an immediate pre-release follow-up), keeping points 2–4 stacked as proposed.

Q2 — minimum typed vocabulary. Inclusion test: a dimension earns a typed field only if a deterministic seller can mechanically verify satisfaction against commercial_terms. That yields: budget ceiling (checks against commercial_terms.total_budget; reuse the budget_range {min, max, currency} shape), product include/omit (reuse the existing action enum verbatim; substitution is omit + free text), and alternatives count. The vary: [...] dimension enum and typed preferences both fail the test — "prioritize_reach" is unfalsifiable, so two conformant sellers can honor it divergently and both claim compliance. Keep both in free text for v1.

Q3 — stable IDs. Not needed if constraints is a keyed object (as the RFC's own illustration already shows): the key is the stable ID for free, and results report unsatisfied_constraints: ["max_total_budget"]. IDs only become a problem for arrays, so don't use arrays. One semantic to pin: a draft violating a hard constraint must never return as revised — it's partial with violated keys listed, or unable. The current partial definition ("an honest draft plus explanatory notes") doesn't yet say this.

Q4 — distinguishing declined / unsupported / uninterpreted. Add a machine-readable reason_code enum to the unable and partial branches, in the house style of proposal-decline-reason.json (snake_case + enumDescriptions): roughly commercially_declined, constraint_unsatisfiable, unsupported_dimension, uninterpreted, with free-text reason as detail. uninterpreted is what makes "usable by deterministic clients without an LLM" real on the seller side — an LLM-less seller can honestly report "typed parts applied, free text ignored." Decide jointly with Q5: once dimensions are capability-advertised, an unadvertised-dimension request is a buyer error and a task-level UNSUPPORTED_FEATURE rejection is defensible; per-item unable is the fallback posture without capabilities.

Q5 — capabilities vs competence. Yes, split exactly as suggested. The docs already draw this line in prose (refinement.mdx: the refine capability "does not guarantee that the seller understands every negotiation strategy or has commercial flexibility on price"), and supports_refinement in the creative block is precedent for feature-grained flags. Typed dimensions are parse-level, deterministic support — capability territory, and pre-flight discovery matters for buyers constructing typed requests. Competence (#6287) then covers only free-text interpretation quality. Two caveats to carry into the design: acknowledge the deliberate counter-precedent (multi-finalize has no flag; "the failure response is the discovery surface") and say why the core negotiation vocabulary warrants pre-flight discovery where that edge case didn't; and keep the doctrine explicit that capabilities declare what a seller can parse and validate, never what it will commercially concede.

One more structural cost to price in: alternatives breaks the current response cardinality. refine-proposals-response.json promises "One ordered immutable revision or finalization result per requested source proposal" and the revised branch carries a single proposal. alternatives.count: 3 means one entry yields N proposals — a response-schema change the RFC should name (e.g., a proposals[]-carrying outcome, or N results echoing one source_proposal_id) rather than discover at PR time.

[bokelley]

Implementation follow-through is tracked in #6556, with linked TypeScript, Python, Go, Java, training-agent, implementor-doc, and conformance-storyboard deliverables. This keeps SDK and training adoption tied to the negotiation contract defined here and implemented by #6547.

[bokelley]

Before finalizing #6547 we ran a four-way red team (protocol, market fit, adversarial security, implementor DX) plus a market scan against IAB Tech Lab's AAMP. The resulting contract hardening landed in efe48f522e — full breakdown in this PR comment.

Headlines relative to the design discussed here:

• The typed dimension set grew to include cpm, impressions, and flight — rate and volume are the Welcome to adcp Discussions! #1/Remove targeting_template and add pluggable product catalog system #2 items real desks negotiate, and both are as mechanically verifiable against commercial_terms as total_budget.
• product_selection was renamed product_changes so capability dimensions match request fields exactly.
• Reason-code semantics are now deterministic: constraint_unsatisfiable takes precedence, commercially_declined is reserved for ask-level refusals, and finalize failures have honest vocabulary (hold_unavailable, batch_aborted, double-finalize INVALID_STATE).
• Every refinement successor carries parent_proposal_id, and terms_digest is normatively buyer-recomputable (RFC 8785 JCS + sha256) with alternative distinctness defined on terms, not digest strings.
• New normative security text treats ask as untrusted input and flags deterministic constraint responses as a floor-price oracle sellers should rate-limit.

The AAMP scan found its published negotiation surface (seller-agent OpenAPI, AAMP 2.3) types exactly one dimension — buyer_price in integer micros over serial rounds, with no inventory-hold primitive — so this contract is strictly more expressive and a future bridge is a mapping exercise. The implementation program (#6556 and its SDK/training/storyboard children) has been updated to target the hardened surface.

🤖 Generated with Claude Code