@adcp/sdk 6.9.0 → 6.10.0

package/compliance/cache/3.0.6.previous/specialisms/governance-spend-authority/index.yaml

@@ -0,0 +1,330 @@
+id: governance_spend_authority
+version: "1.0.0"
+title: "Campaign governance — conditional approval"
+protocol: governance
+category: governance_spend_authority
+summary: "Governance agent approves a media buy with conditions. Buyer re-checks after meeting the conditions."
+track: campaign_governance
+required_tools:
+  - sync_plans
+  - check_governance
+
+# Cross-step assertion (adcp#2639): silent on approval runs; fires only
+# if a seller surfaces a denial signal mid-flow and then still mutates
+# the plan's resources. Kept wired here so any future "conditions not
+# met → denied" phase added to this storyboard is automatically gated.
+# Cross-step assertion (adcp#2664): status.monotonic rejects media_buy
+# status transitions observed across steps that aren't on the spec
+# lifecycle graph — e.g. active → pending_creatives.
+invariants:
+  - governance.denial_blocks_mutation
+  - status.monotonic
+
+narrative: |
+  The buyer's governance agent evaluates a media buy that falls within spending authority but
+  triggers policy conditions — for example, the buy targets a channel that requires weekly
+  reporting, or the creative format requires brand safety review.
+
+  The governance agent returns approved_with_conditions, attaching conditions the buyer must
+  honor during the campaign. The buyer can proceed with the media buy by passing the
+  governance context, but the conditions are binding.
+
+  This storyboard tests the middle path between outright approval and denial: the buy is
+  allowed, but with strings attached.
+
+agent:
+  interaction_model: media_buy_seller
+  capabilities:
+    - sells_media
+    - governance_aware
+  examples:
+    - "Publisher platform with governance support"
+    - "SSP that respects governance checks"
+
+caller:
+  role: buyer_agent
+  example: "Pinnacle Agency (buyer)"
+
+prerequisites:
+  description: |
+    The caller needs a brand identity, operator credentials, and a governance agent URL.
+    The governance plan defines policy conditions that trigger on specific buy parameters.
+  test_kit: "test-kits/acme-outdoor.yaml"
+  controller_seeding: true
+
+fixtures:
+  products:
+    - product_id: "sports_ctv_q2"
+      delivery_type: "guaranteed"
+      channels: ["ctv"]
+      format_ids:
+        - id: "video_30s"
+    - product_id: "lifestyle_display_q2"
+      delivery_type: "guaranteed"
+      channels: ["display"]
+      format_ids:
+        - id: "display_300x250"
+  pricing_options:
+    - product_id: "sports_ctv_q2"
+      pricing_option_id: "cpm_guaranteed"
+      pricing_model: "cpm"
+      currency: "USD"
+      fixed_price: 45.0
+    - product_id: "lifestyle_display_q2"
+      pricing_option_id: "cpm_standard"
+      pricing_model: "cpm"
+      currency: "USD"
+      fixed_price: 8.0
+  plans:
+    - plan_id: "gov_acme_spend_authority_q2_2027"
+      brand:
+        domain: "acmeoutdoor.example"
+      objectives: "Full spending authority with conditional policies on CTV reporting and UGC brand safety"
+      budget:
+        total: 100000
+        currency: "USD"
+        reallocation_unlimited: true
+      flight:
+        start: "2027-01-01T00:00:00Z"
+        end: "2027-12-31T23:59:59Z"
+      countries: ["US"]
+      custom_policies:
+        - policy_id: "ctv_weekly_reporting"
+          enforcement: "must"
+          policy: "CTV buys require weekly delivery reporting."
+        - policy_id: "ugc_brand_safety"
+          enforcement: "must"
+          policy: "UGC placements require brand safety review before go-live."
+
+phases:
+  - id: capability_discovery
+    title: "Capability discovery"
+    narrative: |
+      The buyer calls get_adcp_capabilities to confirm the agent supports media buying before sending briefs or creating buys.
+
+    steps:
+      - id: get_capabilities
+        title: "Check agent capabilities"
+        narrative: |
+          Verify that the agent declares the expected protocol support before
+          proceeding with domain-specific operations.
+        task: get_adcp_capabilities
+        schema_ref: "protocol/get-adcp-capabilities-request.json"
+        response_schema_ref: "protocol/get-adcp-capabilities-response.json"
+        doc_ref: "/protocol/get_adcp_capabilities"
+        comply_scenario: capability_discovery
+        stateful: false
+        expected: |
+          Return capabilities declaring media_buy in supported_protocols, confirming the agent sells media.
+        sample_request:
+          context:
+            correlation_id: "governance_spend_authority--get_capabilities"
+        validations:
+          - check: response_schema
+            description: "Response matches get-adcp-capabilities-response.json schema"
+          - check: field_present
+            path: "supported_protocols"
+            description: "Agent declares supported protocols"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "governance_spend_authority--get_capabilities"
+            description: "Context correlation_id returned unchanged"
+  - id: plan_registration
+    title: "Register governance plan with policy conditions"
+    narrative: |
+      The buyer registers a governance plan that allows the agent full spending authority
+      but attaches policy conditions for specific channels or formats. Buys that trigger
+      these policies are approved with conditions rather than denied.
+
+    steps:
+      - id: sync_plans
+        title: "Register a governance plan with policy conditions"
+        narrative: |
+          The buyer's governance agent registers a plan with full spending authority but
+          custom policies that require weekly reporting for CTV buys and brand safety
+          review for user-generated content placements.
+        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"
+        comply_scenario: governance_spend_authority
+        stateful: true
+        expected: |
+          Acknowledge the governance plan:
+          - plan_id: identifier for this governance plan
+          - custom_policies: policy conditions registered
+
+        sample_request:
+          idempotency_key: "governance-spend-authority-sync-plans-v1"
+          plans:
+            - plan_id: "gov_acme_spend_authority_q2_2027"
+              brand:
+                domain: "acmeoutdoor.example"
+              objectives: "Full spending authority with conditional policies on CTV reporting and UGC brand safety"
+              budget:
+                total: 100000
+                currency: "USD"
+                reallocation_unlimited: true
+              flight:
+                start: "2027-01-01T00:00:00Z"
+                end: "2027-12-31T23:59:59Z"
+              countries: ["US"]
+              custom_policies:
+                - policy_id: "ctv_weekly_reporting"
+                  enforcement: "must"
+                  policy: "CTV buys require weekly delivery reporting."
+                - policy_id: "ugc_brand_safety"
+                  enforcement: "must"
+                  policy: "UGC placements require brand safety review before go-live."
+
+          context:
+            correlation_id: "governance_spend_authority--sync_plans"
+        context_outputs:
+          - name: plan_id
+            path: 'plans[0].plan_id'
+        validations:
+          - check: response_schema
+            description: "Response matches sync-plans-response.json schema"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "governance_spend_authority--sync_plans"
+            description: "Context correlation_id returned unchanged"
+          - check: field_present
+            path: "plans[0].plan_id"
+            description: "Governance agent assigns plan_id — must be echoed in check_governance"
+          - check: field_present
+            path: "plans[0].version"
+            description: "Plan includes version for concurrency"
+  - id: governance_check_conditions
+    title: "Governance check — approved with conditions"
+    narrative: |
+      The buyer proposes a media buy that includes CTV inventory. The governance agent
+      approves the buy but attaches the weekly reporting condition from the plan. The
+      buyer receives a governance context that encodes these conditions.
+
+    steps:
+      - id: check_governance_conditions
+        title: "Pre-buy governance check (approved with conditions)"
+        narrative: |
+          The buyer calls check_governance with a media buy that includes CTV products.
+          The governance agent approves the buy but attaches conditions: weekly delivery
+          reporting is required for the CTV line items.
+        task: check_governance
+        schema_ref: "governance/check-governance-request.json"
+        response_schema_ref: "governance/check-governance-response.json"
+        doc_ref: "/governance/campaign/tasks/check_governance"
+        comply_scenario: governance_spend_authority
+        stateful: true
+        expected: |
+          Return an approved governance decision with conditions:
+          - decision: approved
+          - conditions: array of requirements the buyer must honor
+            - e.g., "Weekly delivery reporting required for CTV line items"
+          - governance_context: token the buyer passes to create_media_buy
+          - findings: may include warning-severity findings noting the conditions
+
+        sample_request:
+          plan_id: "$context.plan_id"
+          caller: "https://pinnacle-agency.example"
+          tool: "create_media_buy"
+          payload:
+            account:
+              brand:
+                domain: "acmeoutdoor.example"
+              operator: "pinnacle-agency.example"
+            total_budget: 40000
+            packages:
+              - product_id: "sports_ctv_q2"
+                budget: 25000
+              - product_id: "lifestyle_display_q2"
+                budget: 15000
+
+          context:
+            correlation_id: "governance_spend_authority--check_governance_conditions"
+        validations:
+          - check: response_schema
+            description: "Response matches check-governance-response.json schema"
+          - check: field_present
+            path: "status"
+            description: "Response contains a governance decision"
+          - check: field_present
+            path: "conditions"
+            description: "Approval includes conditions"
+          - check: field_present
+            path: "governance_context"
+            description: "Response includes governance context for the media buy"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "governance_spend_authority--check_governance_conditions"
+            description: "Context correlation_id returned unchanged"
+  - id: create_buy_with_conditions
+    title: "Create media buy with governance conditions"
+    narrative: |
+      The buyer creates the media buy, passing the governance context from the conditional
+      approval. The seller validates the governance approval and confirms the buy. The
+      conditions from the governance check are now binding for the campaign duration.
+
+    steps:
+      - id: create_media_buy
+        title: "Create a media buy with conditional governance approval"
+        narrative: |
+          The buyer creates the media buy with the governance_context token from the
+          conditional approval. The seller confirms the buy. The buyer is now bound by
+          the conditions (weekly reporting for CTV line items).
+        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: governance_spend_authority
+        stateful: true
+        expected: |
+          Confirm the media buy with governance approval:
+          - media_buy_id: your platform's identifier
+          - status: active
+          - governance_context: echoed back confirming governance was validated
+          - packages: line items
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          brand:
+            domain: "acmeoutdoor.example"
+          governance_context: "gov_ctx_acme_conditional_approved"
+          start_time: "2026-04-01T00:00:00Z"
+          end_time: "2026-06-30T23:59:59Z"
+          packages:
+            - product_id: "sports_ctv_q2"
+              budget: 25000
+              pricing_option_id: "cpm_guaranteed"
+            - product_id: "lifestyle_display_q2"
+              budget: 15000
+              pricing_option_id: "cpm_standard"
+
+          idempotency_key: "$generate:uuid_v4#governance_spend_authority_create_buy_with_conditions_create_media_buy"
+          context:
+            correlation_id: "governance_spend_authority--create_media_buy"
+        validations:
+          - check: response_schema
+            description: "Response matches create-media-buy-response.json schema"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "governance_spend_authority--create_media_buy"
+            description: "Context correlation_id returned unchanged"