Repository navigation
Description
Summary
#8733 closed with three questions that an edit could not settle. Two are in the aggregated-spend section of the campaign-governance specification. The third is one schema description. This issue carries them so that they are not lost when #8733 closes.
- The aggregation key is per seller, so the split that the section exists to stop still passes when it is spread across sellers. The specification also forbids a governance agent from closing that gap on its own.
- The specification says that sellers declare the aggregation window. The capability describes a governance agent, and a seller cannot compute the key.
get-plan-audit-logs-request.jsonstill describes plans as scoping an account. No governance schema carries an account, and since feat(governance): settle the campaign-governance rules that were contradictory or undefined #9006 aplan_idis unique only per owner principal.
Every quote below is from the tree pinned at 61a1638493297b2119a41e4cd918e00fc42a5811. Line numbers should be re-verified at implementation time.
Current state
The section and its purpose, docs/governance/campaign/specification.mdx:398:
Governance thresholds (
reallocation_threshold,human_review_requiredtrigger points, registry-policy dollar floors) MUST be evaluated against aggregated committed spend over a trailing window, not per-plan or per-media-buy in isolation. A buyer that fragments a $999,900 intended spend into 100 × $9,999 buys — each individually below an operator's $10,000 human-review threshold — would otherwise bypass review entirely. This is a fragmentation attack on governance, not a legitimate usage pattern, and the governance agent MUST close it.
The key, :402:
All plans attributable to the same
(owner_principal, seller_agent)tuple — fragmentation across plans owned by the same principal does not reset the aggregate. [...] A delegation does NOT mint a fresh per-agent aggregation window, because otherwise the delegation surface itself reopens the fragmentation hole ($999,900 split across 100 sub-agents, each getting their own $9,999 budget).
The limit on widening, :423:
Governance agents MAY evaluate narrower aggregation scopes additionally (per-brand, per-campaign) but MUST NOT evaluate any scope broader than the declared window without operator sign-off. "Broader" covers both dimensions: a longer trailing window (time) and a wider key tuple (e.g., collapsing across
owner_principalso two buyer principals share an aggregate).
Reallocation, :427:
A buyer cannot sidestep a $25,000 reallocation threshold by fragmenting one $30,000 reallocation into six $4,999 updates — each update's delta accumulates into the trailing-window aggregate and trips the threshold once the cumulative delta crosses it.
The threshold that sentence refers to, static/schemas/source/governance/sync-plans-request.json:71:
The orchestrator can reallocate spend across sellers, channels, or purchase types up to this threshold per change without asking a human.
Who declares the window, specification.mdx:442:
Sellers and governance agents declare their aggregation window via
governance.aggregation_window_daysin [get_adcp_capabilities]
The capability itself, static/schemas/source/protocol/get-adcp-capabilities-response.json:3064:
Trailing window (in days) over which this governance agent aggregates committed spend when evaluating dollar-valued thresholds [...] Aggregation is keyed on (owner_principal, seller_agent), where owner_principal is the authenticated buyer principal that synchronized the plan
The audit-log request, static/schemas/source/governance/get-plan-audit-logs-request.json:21:
Plan IDs to retrieve. For a single plan, pass a one-element array. Plans uniquely scope account and operator; do not include a separate
accountfield — the governance agent resolves account from each plan.
The key was (buyer_agent, seller_agent, account_id) when #2490 added the section. #8931 changed it to (owner_principal, seller_agent), because no governance schema has ever carried an account_id. The description of #2490 and its review give no reason for the seller element. The review asked only whether delegated agents share the aggregate.
Problem
1. A split across sellers passes
A governance agent declares aggregation_window_days: 30. The operator's human-review trigger is $10,000. In one week a buyer principal places 100 buys of $9,999, each with a different seller.
- Under the key at
:402, each buy lands in its own(owner_principal, seller_agent)aggregate. Every aggregate is $9,999. No buy is escalated, and $999,900 is committed without review. - These are the numbers of the section's own example at
:398, which says the governance agent MUST close this. - The agent may not close it by itself. Summing across sellers is "a wider key tuple", which
:423forbids without operator sign-off.
The section already rejects the same hole in the delegation dimension. :402 says that a delegation does not get its own window, because the split across 100 sub-agents would otherwise pass. The seller dimension is the same split with a different divisor.
Reallocation has the same problem, and here the two texts disagree directly. reallocation_threshold is defined across sellers (sync-plans-request.json:71). :427 says that six $4,999 updates accumulate and trip a $25,000 threshold. Under the per-seller key they accumulate only when all six updates go to one seller. Six updates to six sellers sit in six aggregates, and none trips.
Two conformant governance agents now give different answers to the same sequence of requests. One follows :398 and :427, sums across sellers and escalates from the second buy on. The other follows :402 and :423, keeps one aggregate per seller and approves all 100.
None of the three thresholds that the section names is defined per seller. reallocation_threshold is a plan field that spans sellers. Neither the plan schema nor the policy schemas define a human-review trigger or a dollar floor per seller. The one per-seller limit in a plan is budget.per_seller_max_pct (sync-plans-request.json:64), and it is a share of the plan's budget, not a trailing-window threshold.
2. Sellers are said to declare a window they cannot evaluate
specification.mdx:442 says that sellers and governance agents declare the window. The capability description says "this governance agent aggregates", and every MUST in the section is on the governance agent.
A seller also cannot compute the key. owner_principal is "the authenticated buyer principal that synchronized the plan" (:402). A seller is not a party to sync_plans. It sees the buyer-side agent that calls it, and :402 says that a delegated sub-agent is not the owner. So a seller cannot tell whether two callers share one aggregate.
The sentence appears to come from #2490, whose description says the capability "lets buyers check the seller's declared window". Nothing in the section says what a seller would aggregate or against which threshold.
3. The audit-log request describes an account
The plan_ids description at get-plan-audit-logs-request.json:21 makes two statements that no longer hold.
- "Plans uniquely scope account and operator." Since feat(governance): settle the campaign-governance rules that were contradictory or undefined #9006 a
plan_idis unique per owner principal only (sync-plans-request.json:31: "Two principals may use the sameplan_id"). - "the governance agent resolves account from each plan." No schema under
static/schemas/source/governance/containsaccount_id. The two sibling requests were reworded by feat(governance): define cross-role enforcement #6214.check-governance-request.json:233now says: "A plan is owned by the authenticated buyer principal that synchronized it; plan_id is an identifier, not an account credential."
There is also a gap behind the wording. #9006 says what check_governance does when a caller can access more than one plan with the plan_id it sends (tasks/sync_plans.mdx:114: VALIDATION_ERROR, and neither plan is evaluated). Nothing says what get_plan_audit_logs does in the same case. tasks/get_plan_audit_logs.mdx:361 says only that "tenant identity is resolved from the submitted IDs".
Proposed change
1. Buyer-side thresholds sum across sellers
Key the aggregate on owner_principal. All changes are normative and are in prose and one schema description. No wire field changes.
specification.mdx:402: the first bullet becomes "All plans owned by the sameowner_principal, across every seller. Fragmentation across plans, or across sellers, does not reset the aggregate." The sentences onowner_principaland on delegation stay as they are.- Add one sentence: a limit that a plan defines per seller, such as
budget.per_seller_max_pct, is evaluated per seller and is not part of this aggregate. :423: the example of a wider key stays valid. A per-seller aggregate becomes one of the narrower scopes that an agent MAY evaluate additionally.:431, the conformance example: key it onowner_principal, and add a third row in which the prior aggregate was committed with other sellers. Prior aggregate $8,000 across two sellers, incoming $2,500create_media_buywith a third seller, expected outcome: escalate.get-adcp-capabilities-response.json:3064: "Aggregation is keyed on owner_principal".- In the same example,
:431says "Plan sets ahuman_review_requiredtrigger at $10,000 committed spend". A plan cannot set one.human_review_requiredis a boolean (sync-plans-request.json:310-312), anddocs/reference/known-limitations.mdx:111lists approval thresholds as configuration of the operator's agent, not of the protocol. The sentence should say that the operator configures the trigger.
2. Only governance agents declare the window
specification.mdx:442 becomes "Governance agents declare their aggregation window via governance.aggregation_window_days". The rest of the paragraph already speaks of "a governance agent declaring aggregation_window_days: 7".
3. The plan_ids description
Replace the two sentences with the wording of the sibling schemas: "A plan is owned by the authenticated buyer principal that synchronized it, and a plan_id is unique per owner principal. The request carries no account field." Description only.
The case of a caller that can access two plans with the same ID should get the same answer on get_plan_audit_logs as on check_governance. #9077 is open on that question for check_governance, so the answer belongs there, extended to this task.
Alternatives considered
- Keep the per-seller key and declare the cross-seller split out of scope. This is the smaller change. It needs three edits to be consistent: narrow the "MUST close it" in
:398to one seller, say in:427how a reallocation between two sellers is counted, and add the cross-seller split todocs/reference/known-limitations.mdx. A buyer that relies on the human-review trigger would then need its own control across sellers. - Keep the per-seller key as the MUST and allow the wider sum. Lift the
:423restriction for the seller dimension, so that an agent MAY sum across sellers. This removes the contradiction but keeps the interoperability problem: two conformant agents still escalate different buys. - Define what a seller aggregates, as an alternative to item 2. This would need a seller-side threshold and a key that a seller can compute, and the specification has neither today.
- Do nothing.
:398and:427then state a guarantee that:402and:423prevent an agent from giving.
The first alternative and the proposal both leave the section consistent. The proposal is preferred because it keeps the guarantee that the section states, and because the section already uses the same reasoning for delegations.
Compatibility and migration
- Item 1 changes behaviour for a governance agent that implements the key as written. Its aggregates get larger, so thresholds are reached earlier and more actions are escalated. No request or response field changes, and a caller sees only verdicts that it must already handle.
- The key already changes once in 3.3. docs(governance): align campaign-governance pages with the specification and schemas #8931 replaced
(buyer_agent, seller_agent, account_id)with(owner_principal, seller_agent). If item 1 is accepted after 3.3.0, an implementer changes the same key twice. - Experimental surface. The governance request schemas carry
"x-status": "experimental". - Reference agent and compliance suite. Neither
aggregation_window_daysnoraggregate_committedappears underserver/orstatic/compliance/. The reference agent does not declare the capability, and no storyboard grades the section, so no existing test changes. - Items 2 and 3 change no behaviour of a governance agent. Item 2 removes a statement about sellers that no rule supports. Item 3 is a description.
Files affected (as of 61a1638; re-verify at implementation)
docs/governance/campaign/specification.mdx::398,:402,:423,:431and the conformance table,:442static/schemas/source/protocol/get-adcp-capabilities-response.json: theaggregation_window_daysdescription at:3064static/schemas/source/governance/get-plan-audit-logs-request.json: theplan_idsdescription at:21docs/reference/known-limitations.mdx: only if the first alternative is chosen- Deliberately untouched:
sync-plans-request.json, every wire field,plan_hash
Acceptance criteria
- The specification states one aggregation key for the three thresholds that
:398names, and the example at:398, the rule at:423, the reallocation paragraph at:427and the conformance table all agree with it. - The conformance table has a row whose prior aggregate was committed with a different seller than the incoming commit, with the expected outcome stated.
- The specification and the capability description name the same party as the one that declares
aggregation_window_days. - The
plan_idsdescription inget-plan-audit-logs-request.jsonno longer mentions an account, and agrees with theplan_iddescription insync-plans-request.json.
Related
- Governance: campaign-governance coherence sweep — 8 page-vs-spec conflicts, 2 spec-vs-schema contradictions, 6 undefined behaviours #8733: the coherence sweep that these three questions come from. They are its item C5, "Still open".
- docs(governance): align campaign-governance pages with the specification and schemas #8931 (PR): changed the key to
(owner_principal, seller_agent)and left these questions for a decision. - spec(governance): add aggregation_window_days capability + fragmentation-defense section #2490 (PR): added the aggregated-spend section and the capability.
- feat(governance): settle the campaign-governance rules that were contradictory or undefined #9006 (PR): made
plan_idunique per owner principal and defined plan access forcheck_governance. - Governance: let check_governance name the plan owner when a plan_id is ambiguous (3.4) #9077: an ambiguous
plan_idoncheck_governance. Item 3 asks that its answer coverget_plan_audit_logstoo. - feat(governance): define cross-role enforcement #6214 (PR): reworded the two sibling request schemas for the owner-principal model.
Activity