From 6fdbeb1f6aaf011d5f004b18c4ac0c3e1914e1a8 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Sat, 14 Nov 2026 09:28:52 -0500 Subject: [PATCH] fix(compliance): gate audience_buy_flow's member push on inline-push support From 3.3 a seller can declare media_buy.audience_targeting without accepting inline member pushes (#8996). audience_buy_flow pushed CRM members to every audience_targeting seller, so a conformant no-push seller failed at the push. The audience_binding, create_buy_with_audience and delivery_check phases now run only when supported_activation_methods is absent (the 3.2 meaning) or lists an entry whose pattern is sync_audiences. A no-push seller grades those phases not_applicable and still runs setup and the unbound-audience rejection. The gate uses the runner's any_of predicate and object-subset contains (adcontextprotocol/adcp-client#3711). The gate-shape lint accepts any_of, and a runner test pins the gating for no-push, push and 3.2-shaped sellers. Closes #8998 Co-Authored-By: Claude Opus 5.5 --- .changeset/audience-buy-flow-push-gate.md | 5 ++ .../scenarios/audience_buy_flow.yaml | 44 ++++++++++ tests/sdk-runner-capability-gates.test.cjs | 87 ++++++++++++++++++- 3 files changed, 134 insertions(+), 2 deletions(-) create mode 100644 .changeset/audience-buy-flow-push-gate.md diff --git a/.changeset/audience-buy-flow-push-gate.md b/.changeset/audience-buy-flow-push-gate.md new file mode 100644 index 00000000000..ebe40b197b6 --- /dev/null +++ b/.changeset/audience-buy-flow-push-gate.md @@ -0,0 +1,5 @@ +--- +"adcontextprotocol": patch +--- + +`media_buy_seller/audience_buy_flow` runs its member push only for a seller that accepts inline member pushes (#8998). The `audience_binding`, `create_buy_with_audience` and `delivery_check` phases are gated on `media_buy.audience_targeting.supported_activation_methods` being absent (the 3.2 meaning) or listing an entry whose `pattern` is `sync_audiences`. A 3.3 seller that declares `audience_targeting` without inline push (#8996) now grades those phases `not_applicable` instead of failing at the push, and still runs setup and the unbound-audience rejection. The gate uses the storyboard runner's `any_of` capability predicate and object-subset `contains` (adcontextprotocol/adcp-client#3711), so the bundle needs an `@adcp/sdk` release that supports them. diff --git a/static/compliance/source/protocols/media-buy/scenarios/audience_buy_flow.yaml b/static/compliance/source/protocols/media-buy/scenarios/audience_buy_flow.yaml index 12a64578c9e..399b88567b2 100644 --- a/static/compliance/source/protocols/media-buy/scenarios/audience_buy_flow.yaml +++ b/static/compliance/source/protocols/media-buy/scenarios/audience_buy_flow.yaml @@ -15,6 +15,12 @@ requires: # (e.g., a DSP that accepts buyer-uploaded CRM lists but doesn't expose # discovery/deletion semantics). Requires runner support for the `present:` # matcher (adcp-client >= 7.6.0). +# +# Since 3.3, audience_targeting alone does not promise inline member push +# (adcp#8996). The audience_binding, create_buy_with_audience and +# delivery_check phases carry their own gate on inline push. A seller without +# it still runs setup and the unbound-audience rejection, which apply to +# every audience_targeting seller. requires_capability: path: media_buy.audience_targeting present: true @@ -61,6 +67,13 @@ narrative: | get-media-buy-delivery-response.json today. A follow-up scenario gated on a sub-capability bit will land per-audience attribution. + Inline member push is optional from 3.3: a seller that declares + audience_targeting with supported_activation_methods lacking the + sync_audiences pattern rejects member deltas and binds audiences through + discovery or a source reference instead. For such a seller, the push, + the positive buy and the delivery check grade not_applicable, and only + behavior 3 (the unbound-id rejection) is asserted. + Audience suppression via audience_exclude follows the same binding contract (rejected if the audience_id wasn't registered) but is not exercised twice here — one positive + one negative on audience_include is @@ -170,6 +183,19 @@ phases: - id: audience_binding title: "Register the CRM audience" + # Member push: runs only when the seller accepts inline member pushes, + # that is when supported_activation_methods is absent (the 3.2 meaning) + # or lists the sync_audiences pattern (adcp#8996). A seller that declares + # audience_targeting without inline push grades this phase, and the + # phases that use the pushed audience, not_applicable. Requires runner + # support for any_of and object-subset contains (adcp-client#3711). + requires_capability: + any_of: + - path: media_buy.audience_targeting.supported_activation_methods + present: false + - path: media_buy.audience_targeting.supported_activation_methods + contains: + pattern: sync_audiences narrative: | The audience-targeted buy cannot be created without a registered audience_id. This phase exercises the binding — sync_audiences returns @@ -229,6 +255,15 @@ phases: - id: create_buy_with_audience title: "Create a buy whose targeting binds to the registered audience" + # Uses the audience pushed in audience_binding, so it carries the same + # inline-push gate. + requires_capability: + any_of: + - path: media_buy.audience_targeting.supported_activation_methods + present: false + - path: media_buy.audience_targeting.supported_activation_methods + contains: + pattern: sync_audiences narrative: | The buyer creates a media buy whose package targeting_overlay carries audience_include referencing the registered audience_id. The seller @@ -325,6 +360,15 @@ phases: - id: delivery_check title: "Delivery reporting for the audience-targeted buy" + # Reports on the buy created in create_buy_with_audience, so it carries + # the same inline-push gate. + requires_capability: + any_of: + - path: media_buy.audience_targeting.supported_activation_methods + present: false + - path: media_buy.audience_targeting.supported_activation_methods + contains: + pattern: sync_audiences narrative: | The discriminating assertion of the audience buy mode is the binding contract proven above. Delivery reporting here verifies the diff --git a/tests/sdk-runner-capability-gates.test.cjs b/tests/sdk-runner-capability-gates.test.cjs index 9d5a2849c70..f419f8d24e9 100644 --- a/tests/sdk-runner-capability-gates.test.cjs +++ b/tests/sdk-runner-capability-gates.test.cjs @@ -451,6 +451,77 @@ test('runStoryboard skips a not_contains-gated phase when the array contains the assert.match(result.phases[0].steps[0].error, /must not contain "operator"/); }); +test('audience_buy_flow runs the member push only for sellers that accept inline pushes', async () => { + // adcp#8998: from 3.3 a seller can declare audience_targeting without + // inline member push (adcp#8996). Its push, positive buy and delivery + // phases grade not_applicable; setup and the unbound-audience rejection + // still run. Needs any_of and object-subset contains (adcp-client#3711). + const source = loadMediaBuyStoryboard('audience_buy_flow'); + const storyboard = { + ...source, + prerequisites: undefined, + fixtures: undefined, + phases: source.phases.map(phase => ({ + ...phase, + steps: phase.steps.map(step => ({ ...step, validations: [] })), + })), + }; + const tools = ['get_adcp_capabilities', 'sync_accounts', ...storyboard.required_tools]; + const gated = ['audience_binding', 'create_buy_with_audience', 'delivery_check']; + const run = async methods => { + const calls = []; + const result = await runStoryboard('https://seller.example/mcp', storyboard, { + protocol: 'mcp', + _profile: { + name: 'Audience seller', + tools, + raw_capabilities: { + media_buy: { + audience_targeting: { + supported_identifier_types: ['hashed_email'], + ...(methods === undefined ? {} : { supported_activation_methods: methods }), + }, + }, + }, + }, + agentTools: tools, + _client: { + async executeTask(name) { + calls.push(name); + return { + success: true, + data: { + accounts: [{ account_id: 'acct-1', status: 'active' }], + products: [], + audiences: [{ audience_id: 'acmeoutdoor-loyal-customers', action: 'created' }], + media_buy_id: 'mb-1', + success: true, + }, + }; + }, + }, + }); + const skippedPhases = result.phases + .filter(phase => phase.steps.every(step => step.skipped && step.skip?.reason === 'not_applicable')) + .map(phase => phase.phase_id); + return { calls, skippedPhases }; + }; + + const noPush = await run([ + { pattern: 'tmp_identity_match', buyer_agent: { agent_url: 'https://buyer.example/a2a' } }, + { pattern: 'dataset_query', vendor: { domain: 'data-cloud.example' } }, + ]); + assert.deepEqual(noPush.skippedPhases, gated); + assert.ok(!noPush.calls.includes('sync_audiences'), 'no member push is sent to a no-push seller'); + assert.ok(noPush.calls.includes('create_media_buy'), 'the unbound-audience rejection still runs'); + + for (const methods of [undefined, [{ pattern: 'sync_audiences' }, { pattern: 'dataset_query', vendor: { domain: 'd.example' } }]]) { + const push = await run(methods); + assert.deepEqual(push.skippedPhases, [], JSON.stringify(methods)); + assert.ok(push.calls.includes('sync_audiences')); + } +}); + test('runStoryboard structurally matches object-valued governance task gates', async () => { const storyboardPath = path.join( __dirname, @@ -1410,8 +1481,8 @@ test('measurement acceptance is split from the universal rejection scenario', as }); test('storyboard capability gates use the schema shape the runner evaluates', () => { - // requires_capability is a single predicate; compound AND gates belong in - // requires_all_capabilities. A malformed gate (e.g. `requires_capability: + // requires_capability is a single predicate or an any_of group; compound + // AND gates belong in requires_all_capabilities. A malformed gate (e.g. `requires_capability: // { all: [...] }`) crashes the runner before any step executes. const sourceRoot = path.join(__dirname, '..', 'static', 'compliance', 'source'); const matchers = ['equals', 'contains', 'not_contains', 'present']; @@ -1421,6 +1492,18 @@ test('storyboard capability gates use the schema shape the runner evaluates', () problems.push(`${where}: predicate must be an object`); return; } + // OR-composition (adcp-client#3711): an any_of group of two or more + // predicates, with no sibling keys. + if ('any_of' in predicate) { + const siblings = Object.keys(predicate).filter(key => key !== 'any_of'); + if (siblings.length > 0) problems.push(`${where}: any_of cannot be combined with ${siblings.join(', ')}`); + if (!Array.isArray(predicate.any_of) || predicate.any_of.length < 2) { + problems.push(`${where}: any_of must list at least two predicates`); + return; + } + predicate.any_of.forEach((entry, index) => checkPredicate(entry, `${where}.any_of[${index}]`)); + return; + } if (typeof predicate.path !== 'string' || predicate.path.length === 0) { problems.push(`${where}: predicate is missing a string \`path\``); }