@adcp/sdk 5.23.0 → 5.25.0

package/compliance/cache/3.0.0/specialisms/sales-proposal-mode/index.yaml

@@ -1,520 +0,0 @@
-id: sales_proposal_mode
-version: "1.0.0"
-title: "Media buy via proposal acceptance"
-protocol: media-buy
-category: sales_proposal_mode
-summary: "Seller agent that generates curated media plan proposals the buyer can review, refine, and accept."
-track: media_buy
-required_tools:
-  - get_products
-  - create_media_buy
-requires_scenarios:
-  - media_buy_seller/proposal_finalize
-  - media_buy_seller/delivery_reporting
-  - media_buy_seller/measurement_terms_rejected
-  - media_buy_seller/pending_creatives_to_start
-  - media_buy_seller/inventory_list_targeting
-  - media_buy_seller/inventory_list_no_match
-  - media_buy_seller/invalid_transitions
-
-# Cross-step assertion (adcp#2664). status.monotonic rejects resource
-# status transitions observed across steps that aren't on the spec
-# lifecycle graph — e.g. committed → draft on a proposal or active →
-# pending_creatives on a media_buy.
-invariants:
-  - status.monotonic
-
-narrative: |
-  Your seller generates curated media plan proposals. The buyer sends a brief, your platform
-  returns products alongside proposals — curated bundles with budget allocations and rationale
-  for each recommendation. The buyer reviews, optionally refines, and then accepts a proposal
-  as-is instead of manually building packages.
-
-  Proposal mode is the recommended flow for buyers who trust the seller's product
-  recommendations. Instead of the buyer cherry-picking individual products and assembling
-  packages, the seller's AI builds an optimized media plan that the buyer can accept with a
-  single call.
-
-  This storyboard walks through the proposal lifecycle: brief, proposal generation, optional
-  refinement, acceptance, creative sync, and delivery monitoring.
-
-agent:
-  interaction_model: media_buy_seller
-  capabilities:
-    - sells_media
-    - accepts_briefs
-    - generates_proposals
-  examples:
-    - "Full-service publisher with AI planning"
-    - "Retail media network with curated packages"
-    - "Premium video platform with proposal engine"
-
-caller:
-  role: buyer_agent
-  example: "Pinnacle Agency (buyer)"
-
-prerequisites:
-  description: |
-    The caller needs a brand identity and operator credentials for account setup.
-    The test kit provides a sample brand (Acme Outdoor) with campaign parameters
-    suitable for testing the proposal acceptance flow.
-  test_kit: "test-kits/acme-outdoor.yaml"
-
-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: "sales_proposal_mode--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: "sales_proposal_mode--get_capabilities"
-            description: "Context correlation_id returned unchanged"
-  - id: account_setup
-    title: "Account setup"
-    narrative: |
-      The buyer establishes an account relationship with your platform before
-      requesting proposals.
-
-    steps:
-      - id: sync_accounts
-        title: "Establish account relationship"
-        narrative: |
-          The buyer registers their brand and operator with your platform.
-        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: your platform's identifier for this relationship
-          - action: created or updated
-          - status: active or pending_approval
-          - payment_terms: net_30, prepay, etc.
-
-        sample_request:
-          accounts:
-            - brand:
-                domain: "acmeoutdoor.example"
-              operator: "pinnacle-agency.example"
-              billing: "operator"
-              payment_terms: "net_30"
-
-          idempotency_key: "$generate:uuid_v4#sales_proposal_mode_account_setup_sync_accounts"
-          context:
-            correlation_id: "sales_proposal_mode--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"
-
-          - check: field_present
-            path: "context"
-            description: "Response echoes back the context object"
-          - check: field_value
-            path: "context.correlation_id"
-            value: "sales_proposal_mode--sync_accounts"
-            description: "Context correlation_id returned unchanged"
-  - id: brief_with_proposals
-    title: "Brief with proposals"
-    narrative: |
-      The buyer sends a brief. Your platform returns products and — because you support
-      proposal mode — also returns proposals: curated media plans with budget allocations,
-      product selections, and rationale for each recommendation. The buyer can review
-      multiple proposals side by side.
-
-    steps:
-      - id: get_products_brief
-        title: "Send a brief and receive proposals"
-        narrative: |
-          The buyer describes what they want. Your platform returns products alongside
-          one or more proposals. Each proposal bundles products with budget allocations
-          and explains why those products were selected and how the budget was distributed.
-
-          Proposals give the buyer a ready-to-accept media plan instead of requiring
-          manual package assembly.
-        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 and proposals matching the brief:
-          - products: individual products with pricing and forecasts
-          - proposals: curated media plans, each containing:
-            - proposal_id: unique identifier for this proposal
-            - name: descriptive label (e.g., "Balanced Reach Plan")
-            - budget_allocations: how the total budget is split across products
-            - rationale: why these products were selected and how the budget was distributed
-            - total_budget: sum of allocations
-            - forecast: aggregate impressions, reach, frequency
-
-        sample_request:
-          buying_mode: "brief"
-          brief: "Premium video and display across outdoor lifestyle and sports. Q2 flight, $50K total budget. Adults 25-54, US and Canada. Looking for a balanced plan across CTV, online video, and display."
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-
-          context:
-            correlation_id: "sales_proposal_mode--get_products_brief"
-        validations:
-          - check: response_schema
-            description: "Response matches get-products-response.json schema"
-          - check: field_present
-            path: "products"
-            description: "Response contains a products array"
-          - check: field_present
-            path: "proposals"
-            description: "Response contains a proposals array"
-          - check: field_present
-            path: "proposals[0].proposal_id"
-            description: "Each proposal has a proposal_id"
-
-          - check: field_present
-            path: "context"
-            description: "Response echoes back the context object"
-          - check: field_value
-            path: "context.correlation_id"
-            value: "sales_proposal_mode--get_products_brief"
-            description: "Context correlation_id returned unchanged"
-          - check: field_present
-            path: "products[0].format_ids"
-            description: "Products include format_ids for creative requirements"
-          - check: field_present
-            path: "products[0].format_ids[0].agent_url"
-            description: "Format IDs include agent_url — must match this agent's URL"
-          - check: field_present
-            path: "products[0].format_ids[0].id"
-            description: "Format IDs include id — must be accepted back in sync_creatives"
-  - id: review_refine
-    title: "Refine a proposal"
-    narrative: |
-      The buyer reviews the proposals and wants to adjust one. They call get_products
-      in refine mode targeting a specific proposal_id. The refinement might adjust
-      budget splits, swap a product, or add constraints. Your platform returns the
-      updated proposal.
-
-    steps:
-      - id: get_products_refine
-        title: "Refine a specific proposal"
-        narrative: |
-          The buyer targets a specific proposal for refinement. They reference the
-          proposal_id and describe what they want to change. Your platform applies
-          the refinements to that proposal and returns the updated version.
-        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: true
-        expected: |
-          Return the refined proposal:
-          - proposals: updated proposal reflecting the requested changes
-          - refinement_applied: how each refinement was handled
-          - Updated budget allocations, product selections, and forecasts
-          - products: updated product set if products were swapped
-
-        sample_request:
-          buying_mode: "refine"
-          refine:
-            - scope: "proposal"
-              proposal_id: "balanced_reach_q2"
-              ask: "Shift 60% of budget to CTV. Drop the display product and redistribute that budget to video."
-            - scope: "request"
-              ask: "All products must support frequency capping at 3 per day."
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-
-          context:
-            correlation_id: "sales_proposal_mode--get_products_refine"
-        validations:
-          - check: response_schema
-            description: "Response matches get-products-response.json schema"
-          - check: field_present
-            path: "proposals"
-            description: "Response contains updated proposals"
-
-          - check: field_present
-            path: "context"
-            description: "Response echoes back the context object"
-          - check: field_value
-            path: "context.correlation_id"
-            value: "sales_proposal_mode--get_products_refine"
-            description: "Context correlation_id returned unchanged"
-          - check: field_present
-            path: "products[0].format_ids"
-            description: "Products include format_ids for creative requirements"
-          - check: field_present
-            path: "products[0].format_ids[0].agent_url"
-            description: "Format IDs include agent_url — must match this agent's URL"
-          - check: field_present
-            path: "products[0].format_ids[0].id"
-            description: "Format IDs include id — must be accepted back in sync_creatives"
-  - id: accept_proposal
-    title: "Accept the proposal"
-    narrative: |
-      The buyer is satisfied with the refined proposal and accepts it by creating a
-      media buy with the proposal_id. Instead of specifying individual packages, the
-      buyer passes the proposal_id and total_budget. Your platform converts the proposal
-      into an active media buy with the exact product selections and budget allocations
-      from the proposal.
-
-    steps:
-      - id: create_media_buy
-        title: "Create a media buy from proposal"
-        narrative: |
-          The buyer accepts a proposal by passing proposal_id to create_media_buy. The
-          buyer does NOT specify a packages array — the platform uses the proposal's
-          product selections and budget allocations to build the packages automatically.
-
-          This is the key difference from manual package creation: the buyer trusts the
-          seller's recommendation and accepts the plan as-is.
-        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: |
-          Convert the proposal into an active media buy:
-          - media_buy_id: your platform's identifier
-          - status: active
-          - confirmed_at: timestamp
-          - packages: line items derived from the proposal's budget allocations
-          - proposal_id: echoed back to confirm which proposal was accepted
-          - valid_actions: creative sync, pause, get_delivery
-
-        sample_request:
-          brand:
-            domain: "acmeoutdoor.example"
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-          proposal_id: "balanced_reach_q2"
-          total_budget:
-            amount: 50000
-            currency: "USD"
-          start_time: "2026-04-01T00:00:00Z"
-          end_time: "2026-06-30T23:59:59Z"
-
-          idempotency_key: "$generate:uuid_v4#sales_proposal_mode_accept_proposal_create_media_buy"
-          context:
-            correlation_id: "sales_proposal_mode--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: "context"
-            description: "Response echoes back the context object"
-          - check: field_value
-            path: "context.correlation_id"
-            value: "sales_proposal_mode--create_media_buy"
-            description: "Context correlation_id returned unchanged"
-  - id: creative_sync
-    title: "Creative sync"
-    narrative: |
-      With the proposal accepted and the media buy confirmed, the buyer syncs creative
-      assets. The buyer first checks what formats the accepted products require, then
-      pushes matching creative assets.
-
-    steps:
-      - id: list_formats
-        title: "Check creative format requirements"
-        narrative: |
-          The buyer confirms what creative formats the accepted proposal's products
-          require. Your platform returns format specs with asset requirements.
-        task: list_creative_formats
-        schema_ref: "creative/list-creative-formats-request.json"
-        response_schema_ref: "creative/list-creative-formats-response.json"
-        doc_ref: "/creative/task-reference/list_creative_formats"
-        comply_scenario: creative_lifecycle
-        stateful: false
-        expected: |
-          Return creative formats your platform accepts. Each format should define:
-          - format_id with your agent_url and unique id
-          - Asset requirements (dimensions, file sizes, mime types)
-          - Render dimensions
-
-        sample_request:
-          context:
-            correlation_id: "sales_proposal_mode--list_formats"
-
-        validations:
-          - check: response_schema
-            description: "Response matches list-creative-formats-response.json schema"
-          - check: field_present
-            path: "formats"
-            description: "Response contains formats array"
-
-          - check: field_present
-            path: "context"
-            description: "Response echoes back the context object"
-          - check: field_value
-            path: "context.correlation_id"
-            value: "sales_proposal_mode--list_formats"
-            description: "Context correlation_id returned unchanged"
-          - check: field_present
-            path: "formats[0].format_id.agent_url"
-            description: "Format IDs include agent_url"
-          - check: field_present
-            path: "formats[0].format_id.id"
-            description: "Format IDs include id — must match those in get_products"
-      - id: sync_creatives
-        title: "Push creative assets"
-        narrative: |
-          The buyer uploads creative assets for the products in the accepted proposal.
-          Your platform validates each creative against the format specs and returns
-          per-creative status.
-        task: sync_creatives
-        schema_ref: "creative/sync-creatives-request.json"
-        response_schema_ref: "creative/sync-creatives-response.json"
-        doc_ref: "/creative/task-reference/sync_creatives"
-        comply_scenario: creative_sync
-        stateful: true
-        expected: |
-          Accept and validate creatives:
-          - Per-creative action: created or updated
-          - Per-creative status: accepted, pending_review, or rejected
-          - Validation errors for rejected creatives
-
-        sample_request:
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-          creatives:
-            - creative_id: "video_30s_trail_pro"
-              name: "Trail Pro 3000 - 30s CTV Spot"
-              format_id:
-                agent_url: "https://your-platform.example.com"
-                id: "ssai_30s"
-              assets:
-                video:
-                  asset_type: "video"
-                  url: "https://cdn.pinnacle-agency.example/trail-pro-30s.mp4"
-                  width: 1920
-                  height: 1080
-                  duration_ms: 30000
-                  mime_type: "video/mp4"
-            - creative_id: "video_15s_trail_pro"
-              name: "Trail Pro 3000 - 15s Online Video"
-              format_id:
-                agent_url: "https://your-platform.example.com"
-                id: "preroll_15s"
-              assets:
-                video:
-                  asset_type: "video"
-                  url: "https://cdn.pinnacle-agency.example/trail-pro-15s.mp4"
-                  width: 1920
-                  height: 1080
-                  duration_ms: 15000
-                  mime_type: "video/mp4"
-
-          idempotency_key: "$generate:uuid_v4#sales_proposal_mode_creative_sync_sync_creatives"
-          context:
-            correlation_id: "sales_proposal_mode--sync_creatives"
-        validations:
-          - check: response_schema
-            description: "Response matches sync-creatives-response.json schema"
-          - check: field_present
-            path: "creatives[0].action"
-            description: "Each creative has an action (created/updated)"
-
-          - check: field_present
-            path: "context"
-            description: "Response echoes back the context object"
-          - check: field_value
-            path: "context.correlation_id"
-            value: "sales_proposal_mode--sync_creatives"
-            description: "Context correlation_id returned unchanged"
-  - id: delivery
-    title: "Delivery and reporting"
-    narrative: |
-      The campaign from the accepted proposal is live. The buyer monitors delivery
-      to verify the proposal's forecasts are tracking.
-
-    steps:
-      - id: get_delivery
-        title: "Check delivery metrics"
-        narrative: |
-          The buyer requests delivery data for the media buy created from the proposal.
-          Your platform returns performance metrics that the buyer can compare against
-          the proposal's original forecasts.
-        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"
-        comply_scenario: reporting_flow
-        stateful: true
-        expected: |
-          Return delivery metrics for the media buy:
-          - Per-package delivery: impressions, clicks, spend, completion rates
-          - Pacing against the proposal's original forecast
-          - Budget utilization: spent vs. committed per package
-          - Daily breakdown if requested
-
-        sample_request:
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-          media_buy_ids:
-            - "$context.media_buy_id"
-          include_package_daily_breakdown: true
-
-          context:
-            correlation_id: "sales_proposal_mode--get_delivery"
-        validations:
-          - check: response_schema
-            description: "Response matches get-media-buy-delivery-response.json schema"
-          - check: field_present
-            path: "media_buy_deliveries"
-            description: "Response contains media buy delivery data"
-
-          - check: field_present
-            path: "context"
-            description: "Response echoes back the context object"
-          - check: field_value
-            path: "context.correlation_id"
-            value: "sales_proposal_mode--get_delivery"
-            description: "Context correlation_id returned unchanged"