RFC: allowed_actions on products + buys for pre-flight mutation discovery

[nastassiafulconis]

Background

Today there's no protocol-level way for a buyer to know which mutations are valid on a given buy before calling update_media_buy. The buyer sends an update, the seller rejects it mid-flight, and the buyer learns the rule by failing. Examples:

• can i extend the flight on this buy?
• can i decrease budget on a guaranteed buy that's already live?
• can i reallocate budget across packages once pacing has started?

agentic-api caught some of these with coarse checks (tool presence, feature flags, terminal status), but per-mutation rules fall through to runtime rejection because the spec doesn't declare them. context: scope3data/agentic-api#2060 and the discussion in #4425.

#4425 (orchestrator specialisms) solves an adjacent problem: telling sellers what kind of buyer i am. this RFC solves the other half: telling buyers what mutations a seller will actually accept on a given product, in a given state.

Proposal

frame it as actions, not fields. buyers think "can i extend, can i pause, can i reallocate," not "can i mutate end_time." actions wrap the per-field constraints (raisable vs lowerable, extendable vs shortenable) cleanly.

1. closed media_buy_action enum

initial set:

extend_flight, shorten_flight, update_flight_dates,
increase_budget, decrease_budget, reallocate_budget,
pause, resume, cancel,
update_targeting, update_pacing, update_frequency_caps,
update_creatives, replace_creative, update_creative_assignments,
add_package, remove_package

freeform strings kill interop. easier to extend the enum later than retract a vocabulary that's already in the wild.

2. normative action -> update_media_buy field mapping

each action must pin exactly which fields on update_media_buy it covers, otherwise sellers will disagree (does changing pacing_override count as update_pacing or update_targeting?) and the vocab collapses. straw-man table, WG to ratify:

action	fields on update_media_buy	semantic note
extend_flight	end_time (later)	end-date push only
shorten_flight	end_time (earlier)	end-date pull only
update_flight_dates	start_time and/or end_time (shift)	start-shift is distinct from extend/shorten
increase_budget	budget.total (raise)
decrease_budget	budget.total (lower)
reallocate_budget	packages[].budget	total unchanged, redistributed
pause / resume / cancel	status	state transitions
update_targeting	targeting_overlay
update_pacing	pacing
update_frequency_caps	frequency_caps
update_creatives	creatives[] metadata
replace_creative	creatives[].creative_id swap, assignments unchanged	distinct AM workflow from assignment changes
update_creative_assignments	package_assignments[]
add_package / remove_package	packages[] add/remove	line-item add/remove is the most common IO change

every entry MUST resolve to a disjoint field set (no action covers fields owned by another). buyer SDKs dispatch on the action -> field-set mapping.

3. allowed_actions[] and available_actions[]

allowed_actions[] on Product: advisory template. each entry:

{
  "action": "extend_flight",
  "modes": ["requires_proposal"],
  "allowed_statuses": ["live", "paused"]
}

available_actions[] on the buy (returned in get_media_buys / get_media_buy_delivery): authoritative. resolved per-buy against current status, negotiated terms, account tier, and any per-buy overrides. divergence from product-level is expected, not exceptional — negotiated terms and IO addenda live on the deal, not the SKU. same shape minus allowed_statuses (already filtered).

modes is a closed enum:

• self_serve: seller honors the request synchronously
• conditional_self_serve: seller auto-approves within tolerances, escalates outside them (covers PG on FreeWheel/Magnite/GAM, where small budget bumps clear but large ones queue)
• requires_proposal: routes through the proposal lifecycle (create_proposal / finalize_proposal); ties to media_buy.supports_proposals
• requires_approval: human-in-the-loop, async, no proposal artifact

binary self_serve vs requires_approval collapsed the PG middle and the proposal-lifecycle case into the same bucket; the four-way split keeps them distinct so SDKs know whether to expect a proposal task back, a pending-status poll, or an IO addendum.

4. ACTION_NOT_ALLOWED error with structured detail

not a bare code. payload:

{
  "code": "ACTION_NOT_ALLOWED",
  "attempted_action": "decrease_budget",
  "reason": "wrong_status",
  "currently_available_actions": ["pause", "extend_flight", "update_creatives"]
}

reason is a closed enum: wrong_status | not_supported_on_product | mode_mismatch | not_supported_on_buy. lets buyer SDKs offer a recovery path without re-fetching.

Out of scope (v1)

constraint metadata on actions (max delta, bounds, "decrease budget but not below already-spent"). real, but defer to v2 so this proposal doesn't bog down. natural home: extend the requires predicate language being proposed in #4425 rather than ship a parallel grammar. v1 ships the action vocabulary + normative field mapping + modes + structured rejection; sellers reject mid-flight on constraint violations and the SDK surfaces the rejection to the buyer.

Open questions

1. action granularity edge cases. is reallocate_budget one action or split inter-package vs intra-package? does update_creatives need to split metadata-vs-asset changes? worth WG discussion before locking the enum.
2. interaction with RFC: orchestrator specialisms (role-tagged compatibility for buyer/orchestrator agents) #4425. if orchestrator specialisms land, does available_actions[] get filtered/narrowed per orchestrator role, or stay flat and let the buyer reconcile? leaning flat.
3. declaration drift. supports_proposals and similar flags rot when sellers list them defensively. should allowed_actions carry a last_verified timestamp or honored-rate expectation, or is that a v2 concern alongside constraint metadata?

[bokelley]

Strong proposal — and the framing is right. Specialisms (#4425) live at the agent/flow layer and answer "what kind of buyer am I"; actions live at the resource/state layer and answer "what mutations work on this specific buy right now." Different granularities of the same compatibility story; they don't compete.

A few thoughts:

Grader-verification synergy is worth calling out. The orchestrator specialism storyboards in #4425 become the natural place where available_actions declarations are grader-testable end-to-end. A buyer-guaranteed storyboard already drives the proposal-finalize-IO flow against a mock seller; adding a phase that reads available_actions from the resulting buy, attempts a mutation, and confirms the seller's response matches the declared mode (synchronous vs proposal task vs pending-approval) makes this RFC's declarations falsifiable through #4425's existing grader infrastructure. Mutual reinforcement — the action vocabulary becomes testable, and the orchestrator storyboards gain a concrete artifact to validate.

Reinforcing your lean on open Q #2. "Flat available_actions[], let the buyer reconcile" is the right call. Filtering by orchestrator role would force sellers to compute per-role views and conflate two different concepts — actions are facts about the resource, specialisms are facts about the agent claiming them. Don't merge.

Pushing back gently on the "natural home" comment for constraint metadata. Extending #4425's requires predicate language for v2 constraint metadata probably isn't the right fit. The two grammars have different semantic direction:

• requires (predicate language in RFC: orchestrator specialisms (role-tagged compatibility for buyer/orchestrator agents) #4425) is buyer-asserts-over-seller-capabilities at discovery time.
• Constraint metadata is seller-asserts-over-buyer-mutations at runtime.

Different evaluation context, different vocabulary, different consumer. Cleaner to ship a constraint-specific grammar in v2 than overload one designed for the discovery case.

Four nudges on the v1 proposal:

1. Unmapped-field semantics. Spec should say what happens if a buyer touches a field on update_media_buy that's not in any action's field set. Lean strict: every mapped field maps to exactly one action; touching an unmapped field is an error class (UNMAPPED_FIELD or similar). Loose semantics here will produce vendor-specific drift.

2. update_creatives granularity. Your open Q Welcome to adcp Discussions! #1 — worth splitting before locking the enum. Three distinct AM workflows: update_creatives (metadata: name, weight, status), replace_creative (asset swap — already in your table), update_creative_assignments (package mapping). All three exist in real AM systems with different approval rules.

3. ACTION_NOT_ALLOWED.reason missing terms_violation. Action is structurally allowed (right status, supported on product, valid mode) but violates negotiated minimum spend / cancellation window / makegood policy. Real case, distinct from wrong_status / mode_mismatch. Worth a fifth enum value.

4. modes array semantics. Your example shows "modes": ["requires_proposal"] — array-valued. If an action can carry multiple modes (e.g., increase_budget is self_serve ≤20%, requires_approval above), how does the buyer know which applies for a specific request? That's where v2 constraint metadata wants to live. Worth specifying for v1 whether multiple modes means "any of these may apply" or "one of these is selected based on context provided elsewhere."

Open Q #3 (declaration drift) feels like a natural fit for the grader path — if allowed_actions claims are grader-verified through orchestrator storyboards attempting the actions and asserting on response shape, drift between declaration and behavior surfaces as test failures. AAO Verified attestation propagates to action declarations the same way it does to specialism claims.

🤖 Generated with Claude Code

[bokelley]

adding WG-agenda asks. the RFC framing is solid but i think it's bigger than "preflight discovery" once you pull on a few threads. flagging the asks here so we don't re-derive in the meeting.

1. storefront + get_products: this is bidirectional

allowed_actions[] on Product is half the story. the complement is required_actions[] on the brief — buyers express "i won't buy this if i can't self-serve cancel inside 72hr" and get_products filters accordingly. same vocabulary, opposite side of the table. matches the existing format-requirements / targeting-requirements pattern.

two consequences worth surfacing now:

• market enforcement of declaration honesty. sellers can't list extend_flight: self_serve defensively because buyers select on it. the brief-time filter is what keeps allowed_actions truthful — better answer than the last_verified timestamps in open Q3. defer Q3 to v2 confidently.
• storefront-level templates with product overrides. sellers with thousands of products won't author this per-SKU. needs to be a storefront default with per-product narrowing. otherwise sellers list defensively at every row and the catalog bloats.

2. modes are insufficient — actions need (mode, SLA, remedy)

the current mode enum captures whether you can do the action, not how long it takes or what happens when the seller misses the window. concrete failure mode:

"self-serve flight extension" with no SLA could mean instant or 5 days. a buyer who needs the extension for a flight change tomorrow gets the same yes-answer either way.

three orthogonal dimensions on each action:

• mode: who handles it (self/conditional/proposal/approval) — current RFC
• sla: timing expectations (response time, completion time)
• remedy: consequence on SLA breach (makegood, no-pay, refund) — composes with buy-terms

without SLA + remedy, mode: self_serve is an empty promise. with them, this becomes an enforceable contract surface, not just a hint surface.

3. timing nuance within actions: creative is the worst offender

replace_creative and update_creatives aren't single-mode actions in practice:

• remove a variant: usually instant, no approval
• swap a variant for a pre-approved one: instant or near-instant
• add a new variant: triggers approval cycle (24-48hr typical)

if the action vocabulary collapses these into one mode, the buyer can't tell whether they can pull a misbehaving variant immediately vs. waiting two days for re-approval. either:

• (a) split the action enum further (preferred — remove_creative, swap_pre_approved_creative, add_new_creative), or
• (b) keep the action and let sla differentiate within it

leaning (a) because SDK dispatch is cleaner and the verbs map to actual workflows. revisits the v1 enum question — i'd still trim other parts (the three current creative actions over-specify before sellers have shipped distinct workflows) but add a remove_creative because removal is the one action with a strong "i need this in minutes, not days" pressure.

4. composition with buy-terms negotiation (PR #1962)

cancel, shorten_flight, and creative removal all intersect with cancellation policy + makegoods that are being negotiated on the deal itself. two options:

• (a) each action carries optional terms_ref pointing into negotiated buy terms (cancellation policy, makegoods, SLA). action × terms = full picture.
• (b) modes/remedy expand to encode penalty inline.

prefer (a) — buy-terms stay the source of truth, actions stay the verb surface, mode enum doesn't double. but WG should ratify.

5. SLA-breach remedies need an explicit hook

if seller commits to "self-serve extend, 4hr SLA" and misses, what's the buyer's recourse? options to discuss:

• automatic makegood (compose with feat: structured measurement terms and cancellation policy #1962 makegood terms)
• right to non-payment / pro-rated payment
• escalation to proposal lifecycle (graceful degradation)

probably out of scope for v1 schema but the hook (a way to reference the remedy from the action declaration) needs to land in v1 so v2 can fill it in without re-shaping the schema.

6. SDK enforcement on both sides — this is the actual deliverable

vocabulary alone is paper. the value lands when SDKs enforce it:

client SDK (@adcp/client, adcp python):

• expose canExtendFlight(buy), canShortenFlight(buy), canRemoveCreative(buy, creative_id) as boolean queries against available_actions[]
• preflight update_media_buy calls: if the requested mutation isn't in available_actions, fail locally with ACTION_NOT_ALLOWED before the network call
• surface the structured rejection (reason, currently_available_actions) so UIs can render the right affordances
• buyer agents call into the SDK's predicate API to decide what to ask for, not into raw JSON

server SDK (sales-platform side):

• given (product, buy state, account, terms), compute available_actions[] from declarations + state machine, not hand-rolled in each handler
• enforce action validity at the dispatch boundary — handler never sees an invalid mutation, just an ACTION_NOT_ALLOWED response generated by the SDK
• this is the "user configures policy, SDK does state management" abstraction. matches the both-sides SDK pattern already in flight.

without SDK enforcement, every seller hand-implements the policy check and the spec degrades into runtime rejection theater. the RFC should explicitly take a position that v1 ships with SDK enforcement on both sides, not just schema.

summary of asks for WG

1. ratify bidirectional vocabulary — required_actions[] on briefs, filterable in get_products
2. expand from mode to (mode, sla, remedy) per action
3. storefront-level templates with per-product override semantics
4. split creative actions — at minimum add remove_creative as its own verb
5. ratify the terms_ref composition pattern with feat: structured measurement terms and cancellation policy #1962 rather than inline penalty modes
6. v1 ships with SDK enforcement on both sides, not schema only

happy to drive any of these if it helps unblock.

[bokelley]

follow-up: the asks above should compose with #4425's requires predicate grammar, not parallel it.

reading #4425 again — the requires language (equals / in / contains / present on capability fields) is the right home for both the bidirectional vocabulary and the (mode, SLA, remedy) dimensions. concretely:

bidirectional vocabulary via #4425's grammar, not a new required_actions[] construct:

{
  "requires": {
    "all_of": [
      { "available_actions": { "contains": "extend_flight:self_serve" } },
      { "available_actions": { "contains": "cancel:self_serve" } }
    ]
  }
}

same shape #4425 already proposes for activation methods, cloud region, etc. one grammar, many fields.

SLA / remedy as predicate-able fields on the action entry:

{
  "action": "extend_flight",
  "mode": "self_serve",
  "sla": { "response_max": "PT4H", "completion_max": "PT24H" },
  "terms_ref": "buy_terms.cancellation_policy"
}

then briefs can requires.all_of: [{ "available_actions.extend_flight.sla.response_max": { "lte": "PT4H" } }]. extends the predicate vocabulary (lte) but doesn't fork the grammar.

net: drop "ratify bidirectional vocabulary" as a standalone ask. replace with: the requires grammar in #4425 is the canonical caller-side requirement surface, and available_actions[] is a first-class field it can query. the rest of the asks above stay as written.

[nastassiafulconis]

yeah this composes nicely, one grammar > parallel vocab, agreed. few small things worth pinning before it locks:

1. the path syntax in the examples mixes two styles, "extend_flight:self_serve" colon-stringification vs available_actions.extend_flight.sla.response_max dotted-path. probably pick one (dotted-path is more flexible once SLA enters).

2. mode (singular) on the buy vs modes[] (plural) on the product template, is that the intent? makes sense if so, just want to confirm so the two response shapes are different on purpose.

3. terms_ref -> buy_terms.cancellation_policy, that namespace doesn't exist yet right? if it's a forward ref to commercial terms work fine, just want to make sure we're not implicitly proposing it here.

4. if some sellers declare SLAs on some actions and not others, predicate queries silently miss. probably want "SLA optional but absence = no commitment" spelled out so callers know to compose with present.

happy to fold whichever of these you want into the body.

[bokelley]

yeah all four land.

1. dotted-path everywhere, dropping the colon form. "extend_flight:self_serve" was a shortcut for flat contains and breaks the moment SLA enters. canonical:

{ "available_actions.extend_flight.mode": { "equals": "self_serve" } }
{ "available_actions.extend_flight.sla.response_max": { "lte": "PT4H" } }

contains only where the field genuinely is a flat array.

2. mode vs modes[] — intentional, worth spelling out. buy-side mode is singular because the buy has a concrete state, exactly one mode applies. product-template modes[] is plural because the seller advertises a set of conditional modes (e.g. self_serve ≤20%, requires_approval above) and which one fires is resolved at mutation time from buy state + request. different lifecycle stage, different shape, on purpose — but should say so in the body.

3. terms_ref — forward ref to #1962, will mark it. not implicitly proposing the namespace here. reads as "composes with whatever lands in #1962 buy-terms; pinned name is illustrative." if #1962 ships a different shape, the hook moves.

4. optional SLA + silent miss — good catch, needs to be explicit. "SLA optional, absence = no commitment" in the field doc, plus the compose pattern:

{ "all_of": [
    { "available_actions.extend_flight.sla": { "present": true } },
    { "available_actions.extend_flight.sla.response_max": { "lte": "PT4H" } }
] }

predicate semantics fail-closed on missing fields; callers need to know that's the contract or they match sellers who never declared one.

will fold into the main comment as a revision unless you'd rather the thread stay as the record.