@adcp/sdk 7.10.2 → 7.11.1

package/compliance/cache/3.1.0-rc.2/specialisms/sales-proposal-mode/index.yaml

@@ -0,0 +1,586 @@
+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/proposal_finalize_asap_timing
+  - media_buy_seller/proposal_not_found_errors
+  - 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: |
+  **DEPRECATED in 3.1 — see https://github.com/adcontextprotocol/adcp/issues/3823**
+  Proposal-driven flows now grade under `sales-guaranteed`, capability-gated on
+  `media_buy.supports_proposals` (see #3844). Sellers that currently declare
+  `sales-proposal-mode` should drop it and declare `sales-guaranteed` plus
+  `media_buy.supports_proposals: true` instead. This storyboard is retained for
+  backward compat through 3.x and removed at 4.0. The `media_buy_seller/proposal_finalize`
+  scenario lives under `sales-guaranteed.requires_scenarios`.
+
+  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: "$context.proposal_id"
+              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: finalize_proposal
+    title: "Finalize the proposal"
+    narrative: |
+      Before accepting, the buyer requests finalization. This transitions the proposal from
+      draft (indicative pricing) to committed (firm pricing with inventory hold). For
+      guaranteed inventory, finalization also produces an insertion order the buyer
+      countersigns when calling create_media_buy.
+
+    steps:
+      - id: get_products_finalize
+        title: "Finalize the refined proposal"
+        narrative: |
+          The buyer requests finalization on the refined proposal. The seller commits
+          firm pricing and (for guaranteed inventory) returns an insertion order with
+          a signature requirement.
+        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 finalized proposal with committed status:
+          - proposals[0].proposal_status: committed
+          - proposals[0].expires_at: timestamp for the inventory hold window
+          - For guaranteed inventory, proposals[0].insertion_order with io_id
+          - The proposal is ready to accept via create_media_buy
+
+        sample_request:
+          buying_mode: "refine"
+          refine:
+            - scope: "proposal"
+              proposal_id: "$context.proposal_id"
+              action: "finalize"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+
+          context:
+            correlation_id: "sales_proposal_mode--get_products_finalize"
+
+        context_outputs:
+          - path: "proposals[0].insertion_order.io_id"
+            key: "io_id"
+
+        validations:
+          - check: response_schema
+            description: "Response matches get-products-response.json schema"
+          - check: field_present
+            path: "proposals"
+            description: "Response contains the finalized proposal"
+  - 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: "$context.proposal_id"
+          total_budget:
+            amount: 50000
+            currency: "USD"
+          start_time: "2026-04-01T00:00:00Z"
+          end_time: "2026-06-30T23:59:59Z"
+          io_acceptance:
+            io_id: "$context.io_id"
+            accepted_at: "2026-03-15T14:30:00Z"
+            signatory: "ops@acmeoutdoor.example"
+
+          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"