Repository navigation
Description
Summary
The reference agent (server/src/training-agent) does not enforce three campaign-governance rules that the specification states as obligations on the governance agent. Two of them were named in the review of #9006 (comment, review comment). The third is the same kind of gap and was found in the same sweep.
- An
execute_onlydelegate can open a new action. The agent storesdelegations[].authorityand never reads it. - An execution check with an unknown
governance_context, or one issued for another plan, returnsVALIDATION_ERROR. The specification saysPERMISSION_DENIED. - A plan's
regionsare stored and never evaluated, so a regions-restricted plan approves country-wide actions.
None of these needs a specification change. Implementers compare their governance agents against this one, so each gap gives them a wrong baseline.
Current state
All paths are at b8b5097, the head of #9006, because that PR adds two of the sentences quoted here. Line numbers will move when it merges. Re-verify them at implementation time.
1. execute_only is not enforced
The rule. docs/governance/campaign/specification.mdx:340:
A pre-approved action is one whose opaque action binding already holds an approved intent check in this plan's lifecycle: an
execute_onlydelegate MAY act only on such an action, which includesaccept_proposalfor it. The governance agent MUST deny an intent check from anexecute_onlydelegate that would create a new binding or increase committed spend.
static/schemas/source/enums/delegation-authority.json:14 says the same in the enum description.
The agent. In server/src/training-agent/governance-handlers.ts:
:827acceptsauthorityon the tool schema, and:1353stores it on the plan.:2095-2165, the delegation evaluation, readsagentUrl,expiresAt,budgetLimitandmarkets. It does not readauthority. No other code underserver/src/training-agentreads it.
A test pins the wrong behaviour. server/tests/unit/training-agent.test.ts:18991 defines a plan whose only delegation is authority: 'execute_only'. The test at :19010, "approves delegation within budget limit", sends a fresh intent from that delegate and expects approved with a governance_context.
2. governance_context failures return the wrong error code
The rule. docs/governance/campaign/specification.mdx:215:
The governance agent verifies a presented
governance_context, and its match withplan_id, before it resolves plan access. A context that fails verification or was issued for another plan isPERMISSION_DENIED, whether or notplan_idexists.
static/schemas/source/enums/error-code.json:217 defines PERMISSION_DENIED to include a governance_context token that "is missing, fails verification, or was issued for a different plan, seller, or phase".
The agent. In handleCheckGovernance, governance-handlers.ts:
:1453: aplan_idthat differs from the plan the context was issued for returnsVALIDATION_ERROR, "plan_id does not match the governance_context binding.":1724: an execution check whose context matches no stored check returnsVALIDATION_ERROR, "governance_context is unknown or expired.":1737: an expired context returnsPERMISSION_DENIED. This case is already right.
The order is already right. Both checks run before the PLAN_NOT_FOUND return at :1929. Only the code is wrong.
The agent is inconsistent with itself. The seller-side tools return PERMISSION_DENIED for a fabricated context. training-agent.test.ts:24276 asserts it for create_media_buy, and :17234 for activate_signal.
3. Plan regions are not evaluated
The rule. docs/governance/campaign/specification.mdx:487:
The plan's
countriesandregionsfields also serve as geo enforcement: the governance agent MUST reject governed actions targeting markets outside the plan's allowed geography. A plan withregions: ["US-MA"]rejects actions not explicitly targeting Massachusetts, even if they are otherwise compliant. An action with no geographic targeting, or with country-level targeting only, is treated as targeting the whole country and is outside a regions-restricted plan: an intent check returnsconditionsnaming the region constraint, and an execution check returnsdenied.
The first two sentences are on main today. #9006 adds the third.
The agent. In governance-handlers.ts:
:797acceptsregions, and:1350stores it. Nothing reads it afterwards.extractFromPayloadreturnscountries,channels,flightand the budget. It does not extract a region, althoughstatic/schemas/source/core/targeting.json:34definesgeo_regions.plan.countriesis enforced with ageo_compliancefinding at:2249for intent checks and at:2392for execution checks.plan.regionshas no equivalent.
Problem
1. A restricted delegate commits new spend. A brand delegates an agency with authority: "execute_only" and a budget_limit of 25,000. The brand's intent is that the agency carries out actions the brand already approved. The agency sends a fresh create_media_buy intent for 20,000. The agent returns approved and issues a governance_context. The seller's execution check passes and the buy is committed. The specification says the governance agent MUST deny that intent check.
2. A credential failure looks like a malformed request. A seller runs an execution check with a context that the governance agent did not issue, or with a valid context and the wrong plan_id. The agent answers VALIDATION_ERROR. A client that branches on the code treats this as a request to correct and resend. The same agent answers PERMISSION_DENIED when the same fabricated context reaches create_media_buy.
3. A state-restricted plan approves a national buy. A plan has countries: ["US"] and regions: ["US-MA"]. The buyer sends an intent that targets the whole United States. The country check passes, the region is never compared, and the agent returns approved. The specification says conditions at intent and denied at execution.
Proposed change
All changes are in server/src/training-agent/governance-handlers.ts and its tests.
execute_only. In the delegation evaluation, when the caller's delegation hasauthority: "execute_only", add a criticaldelegation_authorityfinding to an intent check that would create a new action binding or increase committed spend. An intent check on a binding that already holds an approved intent check stays allowed, and so doesaccept_proposalfor it. The finding is critical, so the verdict isdeniedin every governance mode, as for thebudget_limitandmarketsfailures.governance_context. ReturnPERMISSION_DENIEDat the two sites above. Keep both checks ahead of plan resolution.regions. Extractgeo_regionsfrom the payload. When the plan hasregions, an action with no geography, with country-level geography only, or with a region outside the plan's list gets ageo_compliancefinding, the category thecountriescheck uses. An intent check returnsconditionsthat name the region constraint. An execution check returnsdenied.
Tests and fixtures affected
training-agent.test.ts:18991-19090: the delegation tests use anexecute_onlydelegate for fresh intents. Either the fixture changes toauthority: 'full', or the expectations change. New cases cover anexecute_onlydelegate that opens a new binding (denied), that raises committed spend on an existing binding (denied), and that acts on a pre-approved binding (allowed).- New cases for an unknown context and for a context issued for another plan, both expecting
PERMISSION_DENIED. - New cases for a regions-restricted plan: no geography, country only, a region outside the list, and a region inside it.
- Storyboards: no file under
static/compliance/sourceusesexecute_onlyoutside theplan_hashtest vectors, and I found no storyboard that expectsVALIDATION_ERRORfor a bad context. The storyboard matrix should confirm that.
Compatibility
This changes what the public test agent returns. A caller that relied on any of the three behaviours sees a different answer:
- A fresh intent from an
execute_onlydelegate changes fromapprovedtodenied. - A bad
governance_contextoncheck_governancechanges fromVALIDATION_ERRORtoPERMISSION_DENIED. - A country-wide action on a regions-restricted plan changes from
approvedtoconditionsordenied.
No schema, wire field or error code is added. Each new answer is the one the specification already requires.
Open questions
propose_only. The table atspecification.mdx:338says such a delegate "cannot execute without explicit approval". No normative sentence says what the governance agent returns. The agent does not read this level either. This issue leaves it alone unless the maintainers want a rule stated first.- "Increase committed spend". For an
execute_onlydelegate, does anupdate_media_buyintent that lowers or keeps the commitment on a pre-approved binding stay allowed? The sentence denies only an increase, and the proposal above follows it. consultation_context. Aplan_idthat does not match a presentedconsultation_contextreturnsVALIDATION_ERRORat:1456. The specification sentence covers onlygovernance_context. Should the two contexts behave the same?- A region outside the list, at intent. The specification gives
conditionsfor an action with no geography or with country-level geography. It does not say whether an intent that names a different region, such asUS-NYon aUS-MAplan, isconditionsordenied. The proposal above usesconditionsfor all three.
Not in this issue
- A storyboard that grades the every-mode denials and the byte identity of the two
PLAN_NOT_FOUNDcases. The review of feat(governance): settle the campaign-governance rules that were contradictory or undefined #9006 left it as a follow-up. - Which plan a
plan_idnames when two owners use the same ID and delegate the same agent. That question is open on feat(governance): settle the campaign-governance rules that were contradictory or undefined #9006.findAccessibleGovernancePlan(:336) returns the first match. - Rules that arrive with fix(governance): correct stale campaign-governance pages and schema descriptions #9015.
Related
- feat(governance): settle the campaign-governance rules that were contradictory or undefined #9006: adds the
execute_onlysentence and the context-verification sentence. Its description records theexecute_onlyandregionsgaps as not changed there. - Governance: campaign-governance coherence sweep — 8 page-vs-spec conflicts, 2 spec-vs-schema contradictions, 6 undefined behaviours #8733: the campaign-governance coherence sweep.
- Governance: let a plan delegation list the action kinds a delegate may take, and cap them per day #8871: proposes that a delegation list the action kinds a delegate may take. That is a new field. This issue is about enforcing the
authoritylevel that exists. - fix(governance): correct stale campaign-governance pages and schema descriptions #9015: the remaining errata from the sweep.
Activity
fix(training-agent): enforce execute_only, governance_context error c…
fix(training-agent): enforce execute_only, governance_context codes a…