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

[bokelley]

3.2 decision: take the minimal atomic form.

• Add total_budget using the existing {amount, currency} shape from create_media_buy; no redistribution-strategy enum in 3.2.
• It is mutually exclusive with both packages and new_packages; sending any combination is VALIDATION_ERROR, not precedence/override behavior.
• The seller scales the existing active package allocations proportionally to their current committed budgets and applies the mutation atomically. It MUST reject rather than partially update when any package cannot accept its derived amount.
• Currency must match the existing media buy. Existing revision/idempotency rules apply; a supplied stale revision fails the entire mutation.
• The success response/readback must expose the resulting per-package budgets so the redistribution is auditable.

Alternative strategies and capability-gated allocation policies can be a later extension once they have conformance vectors.