spec(media-buy): close empty-valid_actions loophole + specify where partitioning belongs

[bokelley]

Summary

Post-#2993 follow-up tightening, surfaced by expert review of the stacked Tier-2 conformance PR (#3001). The merged #2993 rules create a loophole at their boundary that a seller could technically comply with while violating the intent. Two small tightenings close it.

The loophole

#2993 (merged) says:

1. Sales agents MUST return every account-owned buy regardless of creation surface.
2. Sales agents MUST NOT mark a buy read-only simply because it was created outside AdCP.
3. Business constraints on specific actions are expressed by omitting those actions from valid_actions.

Rules 1 + 2 forbid hiding the buy. Rule 3 says "omit the action you can't support." But taken together, a seller can comply with rules 1 and 2 by returning non-AdCP buys with a systematically empty valid_actions set — which is indistinguishable from hiding the buy and defeats the normative intent. A caller seeing "the buy exists but you can do nothing with it" gets the same user experience as "the buy does not exist."

Two clarifications

1. Creation surface is never a business reason

Sales agents MUST NOT omit an action from valid_actions — or return INVALID_STATE on an otherwise-valid update — solely because the buy was created outside AdCP. valid_actions omissions are legitimate only when grounded in contractual, platform, or policy constraints that would apply equally to an AdCP-created buy in the same state.

A seller that returns non-AdCP buys with a systematically empty valid_actions is non-conformant.

2. Partitioning belongs at the account boundary

When a seller has a legitimate reason to keep a set of buys outside a caller's operational reach — child-seller models, NDA-scoped PMP deals, sandbox-vs-production separation, tenant-level privacy partitions — the correct mechanism is a separate account the caller is not authorized to reference.

Within-account filtering (returning only a subset of an account's buys to a caller authorized on that account) reintroduces the shadow-ledger problem #2963 was specifically designed to eliminate. The account boundary is the AdCP primitive for access partitioning; get_agent_capabilities is the introspection surface for the scope granted on a given account.

Why file as a separate PR

#2993 is merged. Rather than re-opening that conversation, this PR adds a short, targeted tightening. Reviewers who approved #2993 can assess whether this further language is consistent with their prior intent — it reads as clarification, not change — and the diff is small enough (~32 lines across 3 files) to evaluate quickly.

Changes

• docs/media-buy/specification.mdx — new Partitioning belongs at the account boundary subsection under Account Ownership vs. Creation Surface; strengthened MUST-NOT language on empty valid_actions.
• docs/media-buy/task-reference/get_media_buys.mdx — mirrors the specification tightening.
• docs/media-buy/task-reference/update_media_buy.mdx — mirrors the specification tightening and calls out that INVALID_STATE cannot be used to reject updates on non-AdCP buys that would otherwise be valid.

No schema changes.

Test plan

• npm run build:schemas regenerates cleanly (verified)
• npm run typecheck passes (verified)
• Docs build verifies no broken links
• ad-tech-protocol-expert agrees the clarifications don't go beyond the spirit of spec(media-buy): get_media_buys MUST return all account-owned buys #2993

Related

• spec(media-buy): get_media_buys MUST return all account-owned buys #2993 (merged) — original account-ownership tightening this PR clarifies
• spec(accounts): per-account authorization on sync/list + RBAC error codes #2994 — get_agent_capabilities + attestation_verifier scope (cross-referenced from the new partitioning language)
• spec(conformance): AAO Verified mark via continuous delivery observability (transitional) #3001 — Tier-2 Production Verified (which is why this loophole was identified — Path B requires the seller to actually permit webhook attach on non-AdCP buys)

🤖 Generated with Claude Code