Skip to content

feat(storyboard): any_of capability gates and object-subset contains - #3711

Merged
bokelley merged 1 commit into
mainfrom
feat/requires-capability-any-of
Nov 14, 2026
Merged

bokelley merged 1 commit into
mainfrom
feat/requires-capability-any-of

Conversation

@bokelley

Copy link
Copy Markdown
Contributor

Runner support for adcontextprotocol/adcp#8998.

Why

adcontextprotocol/adcp#8996 lets a 3.3 seller declare media_buy.audience_targeting without accepting inline member pushes. Such a seller lists supported_activation_methods without an entry whose pattern is sync_audiences. media_buy_seller/audience_buy_flow should run its member-push steps only when the seller accepts inline pushes:

supported_activation_methods is absent (the 3.2 meaning), OR it contains an object whose pattern is sync_audiences.

The runner couldn't express that. Gates had no OR, and contains matched objects by exact equality, while activation-method entries are open objects (additionalProperties: true).

What changes

any_of groups. requires_capability, phases[].requires_capability and each requires_all_capabilities entry may be an any_of list of two or more predicates. The group passes when one entry passes. Groups nest, and each entry keeps its own schema-default and no-raw-capabilities rules. any_of can't be combined with path or a matcher on the same object.

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 }

Object-subset contains / not_contains. An object value matches an array entry that carries every key of the value with a structurally equal value. The entry may carry other keys. Scalars and arrays still match by structural equality, and governance task-mode matching (adcp.governance_enforcement.tasks) is unchanged. No storyboard in the current compliance source uses an object contains outside the governance path, so existing grades don't move.

Loader. Every any_of group is validated: at least two entries, no sibling keys, and each entry is a well-formed predicate. requires_all_capabilities entries go through the same validator. Legacy singular path gates keep their historical, unvalidated loading.

API. New exports from @adcp/sdk/testing: evaluateCapabilityPredicateAgainstCapabilities(predicate, raw, adcpVersion?), isAnyOfCapabilityPredicate and capabilityPathPredicates. evaluateCapabilityPredicate(predicate, actual) throws a TypeError for an any_of predicate, because it has no single resolved value. describeStoryboardCapabilityGates renders a group as (a OR b). The compliance rollup's compliance_testing exclusion reads flattened paths.

Compatibility

Older runners keep working with older bundles, which use neither form. A bundle that uses them needs this release or later:

  • any_of on an older runner. The predicate has no path. With raw capabilities available, the runner throws in resolveCapabilityPath (undefined.split), so the storyboard errors. Without raw capabilities, it treats the gate as satisfied.
  • Object-subset contains on an older runner. It matches objects only by exact equality, so an entry with extra keys doesn't match and the gate skips.

The adcp storyboard change that uses this will pin the SDK release containing it. docs/guides/STORYBOARD-CAPABILITY-GATES.md documents the dialect and this behavior.

Tests

test/lib/storyboard-any-of-capability-gate.test.js (22 cases):

  • subset contains / not_contains, nested-value equality, unchanged scalar, array and governance matching;
  • any_of pass/fail, nested groups, the detail naming every alternative, the TypeError guard;
  • phase and root gates through runStoryboard: a no-push seller's phase grades not_applicable, and 3.2-shaped and sync_audiences sellers run it;
  • the legacy no-raw-capabilities fallback, and an any_of entry inside requires_all_capabilities that stays fail-closed;
  • loader validation.

Locally: the new file passes, and the existing capability-gate suites pass (storyboard-capability-gate, storyboard-compound-capability-gate, storyboard-phase-capability-cascade, storyboard-capability-rollup, capability-rollups, storyboard-requires-gate, storyboard-capability-discovery-terminal: 184/184). tsc --noEmit -p tsconfig.lib.json is clean.

🤖 Generated with Claude Code

Storyboard capability gates can now express an OR, and `contains` can match
an open object by a subset of its keys. adcontextprotocol/adcp#8998 needs both
to gate audience_buy_flow's member push on "supported_activation_methods is
absent, or lists an entry whose pattern is sync_audiences".

- requires_capability, phases[].requires_capability and each
  requires_all_capabilities entry may be an any_of group of two or more
  predicates. Groups nest; each entry keeps its own schema-default and
  no-raw-capabilities rules. The loader validates every any_of group.
- contains / not_contains with an object value match an entry carrying every
  key of the value with an equal value. Scalars, arrays and governance
  task-mode matching are unchanged.
- New exports evaluateCapabilityPredicateAgainstCapabilities,
  isAnyOfCapabilityPredicate and capabilityPathPredicates; the compliance
  rollup's compliance_testing exclusion reads flattened paths.
- docs/guides/STORYBOARD-CAPABILITY-GATES.md documents the gate dialect and
  how older runners treat the new forms.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@aao-secretariat aao-secretariat Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ladon verdict: Approve

Approve — clean, additive change with no blocking or Medium findings.

This PR adds any_of capability predicates plus object-subset contains/not_contains for storyboard gates (adcp#8998). Checked:

  • OR-composition is consistent across the three any_of evaluators (runner.ts:424, :445, :477): each returns null on the first passing alternative, else joins details; per-alternative no-raw-caps fallback and fail-closed behavior preserved by recursing through the same gate fn. Covered by the compound requires_all test.
  • capabilityEntryMatches (runner.ts:369) correctly narrows object-subset to top level; scalar/array equality and governance task-mode matching unchanged.
  • Loader: validateCapabilityPredicateShape/validateAnyOfGate faithfully extract and extend prior inline validation; legacy singular path gates stay unvalidated as documented.
  • comply.ts:1152 flattens via capabilityPathPredicates, fixing the compliance_testing exclusion no longer reading a missing .path off an any_of gate.
  • Changeset present, minor, accurately scoped; cross-runner-version behavior documented.
  • Witness-not-translator / official-transport constraints not implicated (testing-DSL change).

No no-auto-approve team match, gated_paths is false, high_risk is false, no findings. Falls through to row 9.

@bokelley
bokelley merged commit a824655 into main Nov 14, 2026
45 checks passed
@bokelley
bokelley deleted the feat/requires-capability-any-of branch November 14, 2026 15:15
bokelley added a commit to adcontextprotocol/adcp that referenced this pull request Nov 15, 2026
…support (#9013)

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 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant