Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/audience-buy-flow-push-gate.md
Original file line number Diff line number Diff line change
@@ -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.
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
87 changes: 85 additions & 2 deletions tests/sdk-runner-capability-gates.test.cjs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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'];
Expand All @@ -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\``);
}
Expand Down
Loading