@adcp/sdk 14.0.0-rc.37 → 14.0.0-rc.39

package/compliance/cache/3.1.0-beta.7/protocols/media-buy/scenarios/frequency_cap_enforcement.yaml

@@ -1,309 +0,0 @@
-id: media_buy_seller/frequency_cap_enforcement
-version: "1.0.0"
-title: "Seller honors a package-level frequency cap and reports observed frequency at-or-below the cap"
-category: media_buy_seller
-summary: "Verifies that a seller advertising frequency_capping accepts a package-level frequency_cap (max_impressions + per + window form) on create_media_buy and, after simulated delivery, reports observed reach and frequency on get_media_buy_delivery with the observed frequency at-or-below the requested cap. Runtime-enforcement scenario — no rejection arm. Sellers without frequency_capping grade not_applicable."
-track: media_buy
-
-# Gate: scenario runs only when the seller declares frequency_capping (object
-# presence indicates the seller honors targeting.frequency_cap and rejects
-# caps it cannot enforce rather than silently dropping them). Sellers without
-# the capability — many programmatic exchanges that pass frequency control
-# upstream to the bidder, broadcast TV inventory where caps are managed at
-# the schedule level — grade `not_applicable`, not failing. Requires runner
-# support for the `present:` matcher (adcp-client >= 7.6.0).
-requires_capability:
-  path: media_buy.frequency_capping
-  present: true
-
-required_tools:
-  - get_products
-  - create_media_buy
-  - get_media_buy_delivery
-  - comply_test_controller
-
-invariants:
-  - status.monotonic
-
-narrative: |
-  Frequency capping is a runtime-enforcement contract, not a buy-time
-  validation. The buyer attaches a frequency_cap to a package's
-  targeting_overlay declaring "no more than N impressions per entity in
-  a given window"; the seller commits to enforcing that ceiling during
-  delivery and reporting observed reach + frequency in delivery totals
-  so the buyer can verify enforcement.
-
-  This scenario is the buy-mode contract test on the cap side. Unlike
-  audience_buy_flow and performance_buy_flow, there is no unbound-id
-  rejection phase — frequency_cap is a numeric constraint, not a pointer
-  to a registered resource, so there's nothing structurally analogous to
-  reject against. The discriminating assertion is the observed frequency
-  in delivery: a seller that silently drops the cap would deliver to its
-  natural frequency distribution (typically well above the cap when the
-  buy is impression-heavy relative to reach), and observed frequency
-  would exceed the requested max_impressions ceiling.
-
-  Discriminating behaviors this scenario verifies:
-  1. create_media_buy with a package whose targeting_overlay.frequency_cap
-     carries the cap form (max_impressions + per + window) is accepted —
-     the response carries a media_buy_id used for subsequent delivery
-     checks. Cap-form (not cooldown-form `suppress`) is asserted because
-     it's the form that declares a numeric ceiling on exposures, which
-     this scenario verifies enforcement of.
-  2. get_media_buy_delivery for the capped buy reports `totals.reach`
-     (computed; frequency needs a denominator) and `totals.frequency`
-     (observed average exposures per reach unit). frequency_capping:
-     present commits the seller to surfacing these metrics — without them
-     the buyer cannot verify cap enforcement.
-  3. The observed frequency is at-or-below the requested cap of 3
-     impressions per individual per day. Asserted as `field_less_than`
-     against a literal threshold of 3.01 — the storyboard-schema check
-     enum exposes strict less-than via `field_less_than` with a literal
-     `value:` (see static/compliance/source/universal/storyboard-schema.yaml).
-     A native `<=` / `max:` matcher does not exist today; the strict-less-
-     than form with a small epsilon above the cap is the strongest
-     literal-threshold assertion available. A runner extension adding a
-     `field_at_most` / `field_lte` check enum would let this assertion
-     drop the epsilon and target the literal cap value — captured as a
-     soft follow-up; the cap-enforcement signal is already discriminating
-     without it.
-
-  Per-package frequency breakdown (a row carrying its own cap and observed
-  values) is deliberately NOT asserted here — delivery-metrics.json carries
-  frequency at the totals level, and per-package frequency reporting isn't
-  a first-class shape today. A follow-up scenario gated on a sub-capability
-  bit could land per-package frequency attribution.
-
-agent:
-  interaction_model: media_buy_seller
-  capabilities:
-    - sells_media
-    - supports_non_guaranteed
-    - frequency_capping
-  examples:
-    - "DSPs honoring buyer-supplied frequency caps on direct buys"
-    - "Walled-garden platforms with per-user impression ceilings"
-    - "CTV platforms with household-level frequency management"
-    - "Retail-media networks with logged-in-account cap enforcement"
-
-caller:
-  role: buyer_agent
-  example: "Pinnacle Agency (buyer)"
-
-prerequisites:
-  description: |
-    The seller must implement comply_test_controller with simulate_delivery.
-    simulate_delivery injects impressions and spend; the seller then
-    computes reach and frequency at delivery-report time from its internal
-    user-graph model so get_media_buy_delivery has totals.reach and
-    totals.frequency to return.
-
-    The buyer fixture supplies a brand, an operator, and a small display
-    buy sufficient to exercise frequency-cap acceptance and observed-
-    frequency reporting.
-  test_kit: "test-kits/acme-outdoor.yaml"
-  controller_seeding: true
-
-fixtures:
-  products:
-    - product_id: "frequency_capped_display_q2"
-      delivery_type: "non_guaranteed"
-      channels: ["display"]
-      format_ids:
-        - id: "display_300x250"
-  pricing_options:
-    - product_id: "frequency_capped_display_q2"
-      pricing_option_id: "auction_cpm"
-      pricing_model: "cpm"
-      currency: "USD"
-      floor_price: 2.00
-
-phases:
-
-  - id: setup
-    title: "Establish account and discover products"
-    steps:
-      - id: sync_accounts
-        title: "Establish account"
-        task: sync_accounts
-        schema_ref: "account/sync-accounts-request.json"
-        response_schema_ref: "account/sync-accounts-response.json"
-        doc_ref: "/accounts/tasks/sync_accounts"
-        stateful: true
-        expected: |
-          Return the account with account_id and status active.
-        sample_request:
-          accounts:
-            - brand:
-                domain: "acmeoutdoor.example"
-              operator: "pinnacle-agency.example"
-              billing: "operator"
-          idempotency_key: "$generate:uuid_v4#frequency_cap_enforcement_setup_sync_accounts"
-        validations:
-          - check: response_schema
-            description: "Response matches sync-accounts-response.json schema"
-          - check: field_present
-            path: "accounts[0].account_id"
-            description: "Account has a platform-assigned ID"
-
-      - id: get_products_for_frequency_cap
-        title: "Discover products"
-        task: get_products
-        schema_ref: "media-buy/get-products-request.json"
-        response_schema_ref: "media-buy/get-products-response.json"
-        doc_ref: "/media-buy/task-reference/get_products"
-        stateful: false
-        expected: |
-          Return at least one display product compatible with package-level
-          frequency_cap targeting overlays.
-        sample_request:
-          buying_mode: "brief"
-          brief: "Display inventory, US adults 25-54, Q2 flight, ~$15K budget. Frequency-capped at 3 impressions per individual per day."
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-        validations:
-          - check: response_schema
-            description: "Response matches get-products-response.json schema"
-          - check: field_present
-            path: "products"
-            description: "Response contains products"
-
-  - id: create_buy_with_frequency_cap
-    title: "Create a buy whose package carries a frequency_cap"
-    narrative: |
-      The buyer creates a media buy whose package targeting_overlay carries
-      a frequency_cap in the cap form (max_impressions + per + window). The
-      seller should accept and return a media_buy_id. Cap-form (not
-      cooldown-form `suppress`) is the assertion target because it declares
-      the numeric ceiling whose enforcement this scenario verifies.
-
-    steps:
-      - id: create_media_buy_with_frequency_cap
-        title: "Create media buy with frequency_cap in targeting_overlay"
-        task: create_media_buy
-        schema_ref: "media-buy/create-media-buy-request.json"
-        response_schema_ref: "media-buy/create-media-buy-response.json"
-        doc_ref: "/media-buy/task-reference/create_media_buy"
-        stateful: true
-        expected: |
-          Create the media buy. Response carries a media_buy_id used for
-          subsequent get_media_buy_delivery calls.
-        sample_request:
-          brand:
-            domain: "acmeoutdoor.example"
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-          start_time: "2026-06-01T00:00:00Z"
-          end_time: "2026-06-30T23:59:59Z"
-          packages:
-            - product_id: "frequency_capped_display_q2"
-              budget: 15000
-              pricing_option_id: "auction_cpm"
-              targeting_overlay:
-                frequency_cap:
-                  max_impressions: 3
-                  per: "individuals"
-                  window:
-                    interval: 1
-                    unit: "days"
-          idempotency_key: "$generate:uuid_v4#frequency_cap_enforcement_create_buy_create_media_buy"
-        context_outputs:
-          - name: media_buy_id
-            path: "media_buy_id"
-        validations:
-          - check: response_schema
-            description: "Response matches create-media-buy-response.json schema"
-          - check: field_present
-            path: "media_buy_id"
-            description: "Media buy has a platform-assigned ID"
-
-  - id: simulate_delivery_with_observed_frequency
-    title: "Inject impressions sufficient to test cap enforcement"
-    narrative: |
-      simulate_delivery injects an impression count well above the natural
-      reach of the targeted audience — the seller must clamp delivery (or
-      report clamped delivery) such that observed frequency stays at-or-
-      below the requested cap of 3 impressions per individual per day. A
-      seller silently dropping the cap would surface frequency well above
-      3 for impression-heavy buys against a small audience.
-
-    steps:
-      - id: simulate_capped_delivery
-        title: "Inject impressions + spend for the capped buy"
-        task: comply_test_controller
-        requires_tool: comply_test_controller
-        stateful: true
-        expected: |
-          The test controller acknowledges the simulated delivery.
-        sample_request:
-          account:
-            sandbox: true
-          scenario: "simulate_delivery"
-          params:
-            media_buy_id: "$context.media_buy_id"
-            impressions: 8550
-            reported_spend:
-              amount: 1500.00
-              currency: "USD"
-        validations:
-          - check: field_value
-            path: "success"
-            allowed_values: [true]
-            description: "Delivery simulation succeeds"
-
-  - id: assert_frequency_observed_within_cap
-    title: "Verify delivery reports reach + frequency at-or-below the cap"
-    narrative: |
-      The discriminating assertion of the frequency-cap mode. Delivery
-      reporting MUST surface totals.reach and totals.frequency (per
-      delivery-metrics.json — frequency requires a reach denominator to
-      be interpretable, and frequency_capping: present commits the seller
-      to populating these) and the observed frequency MUST be at-or-below
-      the requested cap of 3 impressions per individual per day.
-
-      Strict-less-than threshold is set at 3.01 because the storyboard-
-      schema check enum exposes `field_less_than` with a literal `value:`
-      as the only single-step numeric-comparison matcher today — there is
-      no native `<=` / `field_at_most` form. The 0.01 epsilon lets the
-      assertion target the cap literal (3) without rejecting honest
-      sellers that report frequency at exactly 3.0. A future runner
-      extension adding `field_at_most` would let this drop to a literal
-      `value: 3` without the epsilon; the cap-enforcement signal is
-      already discriminating without it.
-
-    steps:
-      - id: get_capped_delivery
-        title: "Get delivery and verify reach + frequency within cap"
-        task: get_media_buy_delivery
-        schema_ref: "media-buy/get-media-buy-delivery-request.json"
-        response_schema_ref: "media-buy/get-media-buy-delivery-response.json"
-        doc_ref: "/media-buy/task-reference/get_media_buy_delivery"
-        stateful: true
-        expected: |
-          Delivery response includes totals.reach and totals.frequency for
-          the capped buy, with observed frequency at-or-below the cap of 3.
-        sample_request:
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-          media_buy_ids:
-            - "$context.media_buy_id"
-          include_package_daily_breakdown: true
-        validations:
-          - check: response_schema
-            description: "Response matches get-media-buy-delivery-response.json schema"
-          - check: field_present
-            path: "media_buy_deliveries[0].totals.reach"
-            description: "Reach surfaced at the buy level — frequency needs a denominator to be interpretable"
-          - check: field_present
-            path: "media_buy_deliveries[0].totals.frequency"
-            description: "Observed frequency surfaced at the buy level — frequency_capping: present commits the seller to populating this"
-          - check: field_less_than
-            path: "media_buy_deliveries[0].totals.frequency"
-            value: 3.01
-            description: "Observed frequency is at-or-below the requested cap of 3 impressions per individual per day (strict less-than against 3.01 with 0.01 epsilon — see phase narrative)"

package/compliance/cache/3.1.0-beta.7/protocols/media-buy/scenarios/governance_approved.yaml

@@ -1,214 +0,0 @@
-id: media_buy_seller/governance_approved
-version: "1.0.0"
-title: "Seller creates buy when governance approves"
-category: media_buy_seller
-summary: "Verifies that the seller creates a media buy when governance approves the transaction."
-track: media_buy
-required_tools:
-  - sync_governance
-  - get_products
-  - create_media_buy
-
-narrative: |
-  This is a multi-agent test. The test harness sets up a permissive governance plan on
-  a governance agent with a $100K budget, then registers that agent with the seller.
-  The buyer creates a $25K buy which falls within limits.
-
-  When the seller calls check_governance during create_media_buy, the governance agent
-  approves. The seller must confirm the buy normally.
-
-  By default, the governance agent is the training agent at test-agent.adcontextprotocol.org.
-  Override by supplying a different `governance_agent_url` in the run's initial context
-  (e.g., via `--context` on `adcp storyboard run` once the CLI supports it).
-
-context:
-  governance_agent_url: "https://test-agent.adcontextprotocol.org"
-
-agent:
-  interaction_model: media_buy_seller
-  capabilities:
-    - sells_media
-    - governance_aware
-  examples:
-    - "Any media buy seller with governance support"
-
-caller:
-  role: buyer_agent
-  example: "Pinnacle Agency (buyer)"
-
-prerequisites:
-  description: |
-    A governance agent that supports sync_plans and check_governance.
-  test_kit: "test-kits/acme-outdoor.yaml"
-  controller_seeding: true
-
-fixtures:
-  products:
-    - product_id: "outdoor_display_q2"
-      delivery_type: "guaranteed"
-      channels: ["display"]
-      format_ids:
-        - id: "display_300x250"
-    - product_id: "outdoor_video_q2"
-      delivery_type: "guaranteed"
-      channels: ["video"]
-      format_ids:
-        - id: "video_15s"
-  pricing_options:
-    - product_id: "outdoor_display_q2"
-      pricing_option_id: "cpm_standard"
-      pricing_model: "cpm"
-      currency: "USD"
-      fixed_price: 8.0
-    - product_id: "outdoor_video_q2"
-      pricing_option_id: "cpm_standard"
-      pricing_model: "cpm"
-      currency: "USD"
-      fixed_price: 12.0
-
-phases:
-  - id: governance_plan_setup
-    title: "Set up permissive governance plan"
-    narrative: |
-      Create a governance plan on the governance agent with a high budget ($100K).
-      The subsequent $25K buy will fall within these limits and should be approved.
-
-    steps:
-      - id: sync_plans
-        title: "Create permissive governance plan"
-        task: sync_plans
-        schema_ref: "governance/sync-plans-request.json"
-        response_schema_ref: "governance/sync-plans-response.json"
-        doc_ref: "/governance/campaign/tasks/sync_plans"
-        stateful: true
-        expected: |
-          The governance agent acknowledges the plan with a plan_id.
-        sample_request:
-          idempotency_key: "$generate:uuid_v4#governance_approved_sync_plans"
-          plans:
-            - plan_id: "comply-gov-approved-plan"
-              brand:
-                domain: "acmeoutdoor.example"
-              objectives: "Q2 outdoor lifestyle campaign — display and video"
-              budget:
-                total: 100000
-                currency: "USD"
-                reallocation_threshold: 100000
-              flight:
-                start: "2026-04-01T00:00:00Z"
-                end: "2026-06-30T23:59:59Z"
-              countries: ["US", "CA"]
-        validations:
-          - check: response_schema
-            description: "Response matches sync-plans-response.json schema"
-
-  - id: seller_setup
-    title: "Account and governance registration on seller"
-    steps:
-      - id: sync_accounts
-        title: "Establish account with seller"
-        task: sync_accounts
-        schema_ref: "account/sync-accounts-request.json"
-        response_schema_ref: "account/sync-accounts-response.json"
-        doc_ref: "/accounts/tasks/sync_accounts"
-        stateful: true
-        expected: |
-          Return the account with account_id and status active.
-        sample_request:
-          accounts:
-            - brand:
-                domain: "acmeoutdoor.example"
-              operator: "pinnacle-agency.example"
-              billing: "operator"
-              payment_terms: "net_30"
-          idempotency_key: "$generate:uuid_v4#media_buy_seller_governance_approved_seller_setup_sync_accounts"
-        validations:
-          - check: response_schema
-            description: "Response matches sync-accounts-response.json schema"
-          - check: field_present
-            path: "accounts[0].account_id"
-            description: "Account has a platform-assigned ID"
-
-      - id: sync_governance
-        title: "Register governance agent with seller"
-        task: sync_governance
-        schema_ref: "account/sync-governance-request.json"
-        response_schema_ref: "account/sync-governance-response.json"
-        doc_ref: "/accounts/tasks/sync_governance"
-        stateful: true
-        expected: |
-          Acknowledge the governance agent registration.
-        sample_request:
-          accounts:
-            - account:
-                brand:
-                  domain: "acmeoutdoor.example"
-                operator: "pinnacle-agency.example"
-              governance_agents:
-                - url: "$context.governance_agent_url"
-                  authentication:
-                    schemes: ["Bearer"]
-                    credentials: "gov-token-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
-          idempotency_key: "$generate:uuid_v4#media_buy_seller_governance_approved_seller_setup_sync_governance"
-        validations:
-          - check: response_schema
-            description: "Response matches sync-governance-response.json schema"
-
-  - id: buy_approved
-    title: "Create buy within governance limits"
-    steps:
-      - id: get_products_brief
-        title: "Discover products"
-        task: get_products
-        schema_ref: "media-buy/get-products-request.json"
-        response_schema_ref: "media-buy/get-products-response.json"
-        doc_ref: "/media-buy/task-reference/get_products"
-        comply_scenario: full_sales_flow
-        stateful: false
-        expected: |
-          Return products matching the brief.
-        sample_request:
-          buying_mode: "brief"
-          brief: "Display and video inventory on outdoor lifestyle content. Q2 flight, $25K budget. Adults 25-54, US."
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-        validations:
-          - check: response_schema
-            description: "Response matches get-products-response.json schema"
-          - check: field_present
-            path: "products"
-            description: "Response contains products"
-
-      - id: create_media_buy
-        title: "Create buy (governance approves)"
-        task: create_media_buy
-        schema_ref: "media-buy/create-media-buy-request.json"
-        response_schema_ref: "media-buy/create-media-buy-response.json"
-        doc_ref: "/media-buy/task-reference/create_media_buy"
-        comply_scenario: create_media_buy
-        stateful: true
-        expected: |
-          The buy succeeds — governance approved because the $25K buy is within
-          the plan's $100K budget.
-        sample_request:
-          brand:
-            domain: "acmeoutdoor.example"
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-          start_time: "2026-04-01T00:00:00Z"
-          end_time: "2026-06-30T23:59:59Z"
-          packages:
-            - product_id: "outdoor_display_q2"
-              budget: 15000
-              pricing_option_id: "cpm_standard"
-            - product_id: "outdoor_video_q2"
-              budget: 10000
-              pricing_option_id: "cpm_standard"
-          idempotency_key: "$generate:uuid_v4#media_buy_seller_governance_approved_buy_approved_create_media_buy"
-        validations:
-          - check: response_schema
-            description: "Response matches create-media-buy-response.json schema"