Skip to content

Governance: decide whether aggregated-spend thresholds sum across sellers, and fix two statements left open by #8733 #9083

Open

Description

@lukasz-pubx

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.

  1. 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.
  2. The specification says that sellers declare the aggregation window. The capability describes a governance agent, and a seller cannot compute the key.
  3. get-plan-audit-logs-request.json still 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 a plan_id is 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_required trigger 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_principal so 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_days in [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 account field — 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 :423 forbids 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.

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 same owner_principal, across every seller. Fragmentation across plans, or across sellers, does not reset the aggregate." The sentences on owner_principal and 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 on owner_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,500 create_media_buy with a third seller, expected outcome: escalate.
  • get-adcp-capabilities-response.json:3064: "Aggregation is keyed on owner_principal".
  • In the same example, :431 says "Plan sets a human_review_required trigger at $10,000 committed spend". A plan cannot set one. human_review_required is a boolean (sync-plans-request.json:310-312), and docs/reference/known-limitations.mdx:111 lists 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 :398 to one seller, say in :427 how a reallocation between two sellers is counted, and add the cross-seller split to docs/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 :423 restriction 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. :398 and :427 then state a guarantee that :402 and :423 prevent 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_days nor aggregate_committed appears under server/ or static/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, :431 and the conformance table, :442
  • static/schemas/source/protocol/get-adcp-capabilities-response.json: the aggregation_window_days description at :3064
  • static/schemas/source/governance/get-plan-audit-logs-request.json: the plan_ids description at :21
  • docs/reference/known-limitations.mdx: only if the first alternative is chosen
  • Deliberately untouched: sync-plans-request.json, every wire field, plan_hash

Acceptance criteria

  1. The specification states one aggregation key for the three thresholds that :398 names, and the example at :398, the rule at :423, the reallocation paragraph at :427 and the conformance table all agree with it.
  2. The conformance table has a row whose prior aggregate was committed with a different seller than the incoming commit, with the expected outcome stated.
  3. The specification and the capability description name the same party as the one that declares aggregation_window_days.
  4. The plan_ids description in get-plan-audit-logs-request.json no longer mentions an account, and agrees with the plan_id description in sync-plans-request.json.

Related

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions