RFC: media-buy-level total budget on UpdateMediaBuyRequest

[bokelley]

Background

UpdateMediaBuyRequest currently exposes packages: list[PackageUpdate] and new_packages for budget changes — buyers can only update budgets package-by-package. There's no aggregate "rebudget the whole buy proportionally" verb.

Real-world use case

Buyers want to do "I want to extend this campaign by $5K, redistribute proportionally across active packages." Today this requires the buyer to read current package budgets via get_media_buys, compute per-package allocations, and send an enumerated packages: [...] list. That's:

• Stateful — needs a read before the write
• Race-prone — packages could change between read and write
• Verbose — buyer carries logic the server already has

salesagent (Prebid AdCP reference implementation) documents this scenario as UC-003 obligation #4 and currently exposes a budget field at the top level of UpdateMediaBuyRequest for it. That field is a salesagent extension and not spec-conformant.

Proposed addition

```json
{
"total_budget": {
"type": "object",
"description": "New aggregate budget for the whole media buy. Server distributes proportionally across active packages.",
"properties": {
"amount": {"type": "number", "minimum": 0},
"currency": {"type": "string", "pattern": "^[A-Z]{3}$"},
"redistribution_strategy": {
"type": "string",
"enum": ["proportional", "even", "preserve_relative"],
"default": "proportional"
}
},
"required": ["amount", "currency"]
}
}
```

Open questions

• Naming — total_budget mirrors CreateMediaBuyRequest.total_budget, but budget_total or aggregate_budget could work.
• Mutual exclusion with packages: [...] — should sending both be a validation error, or should packages overrides win for the named ones?
• Strategy enum — preserve_relative (keep current ratios) is the expected default; happy to refine.

salesagent migration path: move local budget field to ext.salesagent.budget until this lands. Filed as part of cleanup PR bokelley/salesagent#208.

[bokelley]

Triage

Classification: RFC / spec extension — Feature request
Bucket(s): spec / protocol, media-buy
Status: ready-for-human
Milestone: 3.1.0 (minor — new optional field, main only; not 3.0.x-eligible)

What the experts said:

• ad-tech-protocol-expert: Use case validated by salesagent precedent. Two blockers: (1) proportional and preserve_relative are operationally indistinguishable as named — both read as "scale by current ratios" — and the RFC contradicts itself on which should be the default; (2) mutual exclusion with packages is unresolved and additionalProperties: true means silent conflicts today; GAM/OpenRTB both reject ambiguous budget fields explicitly. Also flagged: core/media-buy.json has total_budget as a bare number (same name, different shape); revision semantics need normative guidance for a multi-package atomic mutation.
• adtech-product-expert: Workflow gap is real (read-modify-write race, though revision already mitigates it); the redistribution_strategy enum is an enforcement trap — no observable compliance vector means sellers will implement only proportional regardless of what the buyer sends, which creates false buyer confidence. Recommend capability-gating strategies or removing the enum from v1. Also: governance budget-extraction in governance-handlers.ts reads total_budget as a bare number; that path will need migration.

My take: The RFC is directionally sound — additive optional field, non-breaking once design questions are settled, total_budget naming is fine. Three decisions need WG consensus before this can move to Execute.

---

@bokelley, your call on three items:

1 — Mutual exclusion when both total_budget and packages are sent:

Option A — validation error (both experts recommend):

// Normative prose: "Sellers MUST return VALIDATION_ERROR when total_budget
// and packages are both present in the same request."
+ if/then/else or `not: {required: ["packages"]}` inside the schema

Option B — packages overrides win for named items:

{
  "total_budget": {"amount": 105000, "currency": "USD"},
  "packages": [{"package_id": "pkg_abc", "budget": 60000}]
}
// pkg_abc → $60K explicit; remainder redistributed from $45K

Option A prevents silent seller divergence. Option B adds flexibility but produces unpredictable behavior at scale.

---

2 — redistribution_strategy enum: remove from v1, or fix naming and keep:

Option A — remove from v1, capability-gate later:

- "redistribution_strategy": { "enum": ["proportional","even","preserve_relative"] }
// Sellers implement one strategy; advertise it in capabilities when WG defines them

Option B — keep but rename to make the data source unambiguous:

{
  "redistribution_strategy": {
    "enum": ["proposal_allocations", "current_ratios", "even"],
    "default": "current_ratios"
  }
}
// proposal_allocations = original get_products percentages
// current_ratios       = live pacing split at mutation time

Protocol expert also suggests floor_remaining as a fourth value (distribute only unspent delta). Option A reduces seller compliance surface significantly; Option B gives buyers control if compliance vectors are added later.

---

3 — Should revision be REQUIRED when total_budget is used?

A total_budget redistribution mutates multiple packages atomically. Today revision is optional. With this new verb, a stale-revision conflict mid-redistribution could produce a partial write. A normative "MUST provide revision with total_budget" statement (or an atomic-or-nothing rollback guarantee) would close this gap.

---

Triaged by Claude Code. Session: https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}

---

Generated by Claude Code