@adcp/client 4.22.1 → 4.24.0

package/storyboards/media_buy_state_machine.yaml

@@ -1,17 +1,16 @@
 id: media_buy_state_machine
 version: "1.0.0"
 title: "Media buy state machine lifecycle"
-category: media_buy_seller
-track: media_buy
+category: media_buy_state_machine
 summary: "Validates media buy state transitions: create, pause, resume, cancel, and terminal state enforcement."
-
+track: media_buy
 required_tools:
   - create_media_buy
   - update_media_buy
 
 narrative: |
-  A media buy has a well-defined state machine: draft, pending_approval, confirmed, active,
-  paused, completed, canceled. Transitions between states must follow the spec — you cannot
+  A media buy has a well-defined state machine: pending_creatives, pending_start, active,
+  paused, completed, rejected, canceled. Transitions between states must follow the spec — you cannot
   resume a canceled buy or pause a completed one.
 
   This storyboard creates a media buy, walks it through pause/resume/cancel transitions, then
@@ -44,7 +43,7 @@ phases:
     title: "Create a media buy"
     narrative: |
       Discover products and create a media buy to use for state transition testing.
-      The media buy ID is captured and passed to subsequent phases via context.
+      The media buy ID is captured and passed to subsequent phases.
 
     steps:
       - id: discover_products
@@ -53,22 +52,22 @@ phases:
           Send a brief to get available products with pricing options. The first product
           with a pricing option will be used to create the test media buy.
         task: get_products
-        requires_tool: 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 with:
           - product_id
           - pricing_options with pricing_option_id
+
         sample_request:
           buying_mode: "brief"
           brief: "Display advertising products for state machine testing"
           brand:
             domain: "acmeoutdoor.com"
-        context_outputs:
-          - path: "products[0].product_id"
-            key: "product_id"
-          - path: "products[0].pricing_options[0].pricing_option_id"
-            key: "pricing_option_id"
+
         validations:
           - check: response_schema
             description: "Response matches get-products-response.json schema"
@@ -79,176 +78,178 @@ phases:
       - id: create_buy
         title: "Create the test media buy"
         narrative: |
-          Create a media buy using the discovered product. The media_buy_id is captured
-          for use in all subsequent state transition steps.
+          Create a media buy using the discovered product. This buy will be used for
+          all subsequent state transition tests.
         task: create_media_buy
-        requires_tool: 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: |
-          Return a media buy with:
-          - media_buy_id: platform-assigned identifier
-          - status: confirmed, active, or pending_approval
+          Return an active media buy with:
+          - media_buy_id
+          - status: active
+
         sample_request:
-          account:
-            brand:
-              domain: "acmeoutdoor.com"
-            operator: "pinnacle-agency.com"
           brand:
             domain: "acmeoutdoor.com"
           start_time: "2026-05-01T00:00:00Z"
           end_time: "2026-05-31T23:59:59Z"
           packages:
-            - product_id: "$context.product_id"
-              budget: 5000
-              pricing_option_id: "$context.pricing_option_id"
-        context_outputs:
-          - path: "media_buy_id"
-            key: "media_buy_id"
-          - path: "media_buy.media_buy_id"
-            key: "media_buy_id"
+            - product_id: "test-product"
+              budget: 10000
+              pricing_option_id: "test-pricing"
+
         validations:
           - check: response_schema
             description: "Response matches create-media-buy-response.json schema"
           - check: field_present
             path: "media_buy_id"
-            description: "Response contains a media_buy_id"
+            description: "Response includes a media_buy_id"
 
   - id: state_transitions
-    title: "State transitions: pause, resume, cancel"
+    title: "Valid state transitions"
     narrative: |
-      Exercise the core state transitions on the media buy. Pause puts the buy on hold
-      (status becomes paused), resume reactivates it (status becomes active), and cancel
-      terminates it permanently (status becomes canceled).
-
-      Each transition is validated by checking the returned status field.
+      Exercise the valid state transitions: pause, resume, and cancel. Each transition
+      must update the status field correctly.
 
     steps:
       - id: pause_buy
         title: "Pause the media buy"
         narrative: |
           Pause the active media buy. The status should transition to paused.
-          This is a reversible operation — the buy can be resumed later.
         task: update_media_buy
-        requires_tool: update_media_buy
+        schema_ref: "media-buy/update-media-buy-request.json"
+        response_schema_ref: "media-buy/update-media-buy-response.json"
+        doc_ref: "/media-buy/task-reference/update_media_buy"
+        comply_scenario: media_buy_lifecycle
         stateful: true
         expected: |
-          Return the media buy with status: paused.
+          Media buy status transitions to paused.
+
         sample_request:
-          media_buy_id: "$context.media_buy_id"
+          media_buy_id: "test-media-buy"
           paused: true
+
         validations:
-          - check: field_value
+          - check: field_present
             path: "status"
-            value: "paused"
-            description: "Media buy status is paused"
+            description: "Response includes updated status"
 
       - id: resume_buy
         title: "Resume the media buy"
         narrative: |
-          Resume the paused media buy. The status should transition back to active
-          (or pending_activation on some platforms).
+          Resume the paused media buy. The status should transition back to active.
         task: update_media_buy
-        requires_tool: update_media_buy
+        schema_ref: "media-buy/update-media-buy-request.json"
+        response_schema_ref: "media-buy/update-media-buy-response.json"
+        doc_ref: "/media-buy/task-reference/update_media_buy"
+        comply_scenario: media_buy_lifecycle
         stateful: true
         expected: |
-          Return the media buy with status: active or pending_activation.
+          Media buy status transitions back to active.
+
         sample_request:
-          media_buy_id: "$context.media_buy_id"
+          media_buy_id: "test-media-buy"
           paused: false
+
         validations:
           - check: field_present
             path: "status"
-            description: "Response contains a status field after resume"
+            description: "Response includes updated status"
 
       - id: cancel_buy
         title: "Cancel the media buy"
         narrative: |
-          Cancel the media buy permanently. The status should transition to canceled.
-          This is a terminal state — no further transitions are allowed.
+          Cancel the media buy. This is a terminal transition — the buy cannot be
+          resumed or modified after cancellation.
         task: update_media_buy
-        requires_tool: update_media_buy
+        schema_ref: "media-buy/update-media-buy-request.json"
+        response_schema_ref: "media-buy/update-media-buy-response.json"
+        doc_ref: "/media-buy/task-reference/update_media_buy"
+        comply_scenario: media_buy_lifecycle
         stateful: true
         expected: |
-          Return the media buy with status: canceled.
+          Media buy status transitions to canceled. This is terminal.
+
         sample_request:
-          media_buy_id: "$context.media_buy_id"
+          media_buy_id: "test-media-buy"
           canceled: true
-          cancellation_reason: "AdCP compliance test — state machine scenario"
+
         validations:
-          - check: field_value
+          - check: field_present
             path: "status"
-            value: "canceled"
-            description: "Media buy status is canceled"
+            description: "Response includes canceled status"
 
   - id: terminal_enforcement
     title: "Terminal state enforcement"
     narrative: |
-      Once a media buy is canceled or completed, the agent must reject any further
-      state changes. Attempting to pause, resume, or re-cancel a terminated buy should
-      return an error — typically INVALID_STATE_TRANSITION or INVALID_STATE.
-
-      This validates that the state machine is properly enforced and buyers can trust
-      that terminal states are final.
+      Verify that the agent rejects state transitions on a canceled media buy. Pausing,
+      resuming, or re-canceling a terminal buy must return an error.
 
     steps:
       - id: pause_canceled_buy
-        title: "Pause a canceled media buy (expect rejection)"
+        title: "Reject pause on canceled buy"
         narrative: |
-          Attempt to pause the canceled media buy. The agent should reject this with
-          an error indicating the state transition is invalid.
+          Attempt to pause a canceled media buy. The agent must reject this with
+          INVALID_STATE_TRANSITION.
         task: update_media_buy
-        requires_tool: update_media_buy
-        expect_error: true
+        schema_ref: "media-buy/update-media-buy-request.json"
+        response_schema_ref: "media-buy/update-media-buy-response.json"
+        doc_ref: "/media-buy/task-reference/update_media_buy"
+        comply_scenario: terminal_state_enforcement
         stateful: true
         expected: |
-          Reject with an error containing:
-          - code: INVALID_STATE_TRANSITION, INVALID_STATE, or similar
-          - The buy must remain in canceled status
+          Reject with INVALID_STATE_TRANSITION — cannot pause a canceled buy.
+
         sample_request:
-          media_buy_id: "$context.media_buy_id"
+          media_buy_id: "test-media-buy"
           paused: true
+
         validations:
-          - check: error_code
-            value: "INVALID_STATE_TRANSITION"
-            description: "Error code indicates invalid state transition"
+          - check: field_present
+            path: "errors"
+            description: "Response contains an error for invalid transition"
 
       - id: resume_canceled_buy
-        title: "Resume a canceled media buy (expect rejection)"
+        title: "Reject resume on canceled buy"
         narrative: |
-          Attempt to resume the canceled media buy. The agent should reject this —
-          canceled is a terminal state and cannot be reversed.
+          Attempt to resume a canceled media buy. The agent must reject this with
+          INVALID_STATE_TRANSITION.
         task: update_media_buy
-        requires_tool: update_media_buy
-        expect_error: true
+        schema_ref: "media-buy/update-media-buy-request.json"
+        response_schema_ref: "media-buy/update-media-buy-response.json"
+        doc_ref: "/media-buy/task-reference/update_media_buy"
+        comply_scenario: terminal_state_enforcement
         stateful: true
         expected: |
-          Reject with an error. Canceled media buys cannot be resumed.
+          Reject with INVALID_STATE_TRANSITION — cannot resume a canceled buy.
+
         sample_request:
-          media_buy_id: "$context.media_buy_id"
+          media_buy_id: "test-media-buy"
           paused: false
+
         validations:
-          - check: error_code
-            value: "INVALID_STATE_TRANSITION"
-            description: "Error code indicates invalid state transition"
+          - check: field_present
+            path: "errors"
+            description: "Response contains an error for invalid transition"
 
       - id: recancel_buy
-        title: "Re-cancel an already canceled media buy"
+        title: "Handle re-cancel of canceled buy"
         narrative: |
-          Attempt to cancel a buy that is already canceled. The agent may either
-          reject with INVALID_STATE_TRANSITION or accept idempotently. Both are
-          acceptable — what matters is no crash or unstructured error.
+          Attempt to cancel an already-canceled media buy. The agent should either
+          return an error or accept it idempotently.
         task: update_media_buy
-        requires_tool: update_media_buy
+        schema_ref: "media-buy/update-media-buy-request.json"
+        response_schema_ref: "media-buy/update-media-buy-response.json"
+        doc_ref: "/media-buy/task-reference/update_media_buy"
+        comply_scenario: terminal_state_enforcement
         stateful: true
         expected: |
-          Either:
-          - Reject with INVALID_STATE_TRANSITION (strict)
-          - Accept idempotently and return status: canceled (permissive)
-          Both are acceptable behaviors.
+          Either reject with INVALID_STATE_TRANSITION or accept idempotently.
+          Both behaviors are valid.
+
         sample_request:
-          media_buy_id: "$context.media_buy_id"
+          media_buy_id: "test-media-buy"
           canceled: true
-        validations:
-          - check: field_present
-            path: "status"
-            description: "Response contains a status field (canceled) or a structured error"

package/storyboards/property_governance.yaml

@@ -0,0 +1,239 @@
+id: property_governance
+version: "1.0.0"
+title: "Property governance"
+category: property_governance
+summary: "Manage brand safety property lists — create inclusion/exclusion lists, query and update them, validate delivery compliance."
+track: governance
+required_tools:
+  - create_property_list
+
+narrative: |
+  You run a governance agent that manages property lists for brand safety. Buyers create
+  inclusion and exclusion lists that define where their ads can and cannot appear. Your
+  agent stores these lists, lets buyers query and update them, and validates that actual
+  ad delivery complied with the property constraints.
+
+  Property governance is how brands control their environment. An inclusion list says
+  "only show my ads on these properties." An exclusion list says "never show my ads here."
+  The validation step checks after the fact: did the seller actually respect the lists?
+
+  This storyboard covers the full property list lifecycle: creating lists, querying them,
+  updating and deleting, and validating that delivery matched the constraints.
+
+agent:
+  interaction_model: governance_agent
+  capabilities:
+    - property_governance
+    - brand_safety
+  examples:
+    - "IAS"
+    - "DoubleVerify"
+    - "GARM-aligned platforms"
+    - "Brand safety services"
+
+caller:
+  role: buyer_agent
+  example: "Pinnacle Agency (buyer)"
+
+prerequisites:
+  description: |
+    The caller needs a brand identity and property domain knowledge. The test kit
+    provides a sample brand with campaign context.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: create_list
+    title: "Create property lists"
+    narrative: |
+      The buyer creates inclusion and exclusion property lists for the campaign. These
+      define the safe and unsafe environments for the brand's ads.
+
+    steps:
+      - id: create_inclusion_list
+        title: "Create an inclusion list"
+        narrative: |
+          The buyer creates an inclusion list specifying which properties (domains,
+          apps, channels) are approved for ad placement.
+        task: create_property_list
+        schema_ref: "property/create-property-list-request.json"
+        response_schema_ref: "property/create-property-list-response.json"
+        doc_ref: "/governance/property/tasks/property_lists"
+        comply_scenario: governance_property_lists
+        stateful: true
+        expected: |
+          Return the created property list:
+          - list_id: platform-assigned identifier
+          - list_type: inclusion
+          - Properties registered
+          - Status: active
+
+        sample_request:
+          brand:
+            domain: "acmeoutdoor.com"
+          list_type: "inclusion"
+          name: "Acme Outdoor approved properties"
+          properties:
+            - domain: "outdoormagazine.example.com"
+            - domain: "hikingtrails.example.com"
+            - domain: "campinggear.example.com"
+
+        validations:
+          - check: response_schema
+            description: "Response matches create-property-list-response.json schema"
+
+  - id: list_and_get
+    title: "Query property lists"
+    narrative: |
+      The buyer lists all property lists for the account and retrieves a specific list
+      to inspect its contents.
+
+    steps:
+      - id: list_property_lists
+        title: "List all property lists"
+        narrative: |
+          The buyer lists all property lists for the brand. The response includes list
+          metadata (name, type, property count) without full property details.
+        task: list_property_lists
+        schema_ref: "property/list-property-lists-request.json"
+        response_schema_ref: "property/list-property-lists-response.json"
+        doc_ref: "/governance/property/tasks/property_lists"
+        comply_scenario: property_list_filters
+        stateful: true
+        expected: |
+          Return property list summaries:
+          - Array of lists with list_id, name, list_type, property_count
+          - Includes both inclusion and exclusion lists
+
+        sample_request:
+          brand:
+            domain: "acmeoutdoor.com"
+
+        validations:
+          - check: response_schema
+            description: "Response matches list-property-lists-response.json schema"
+
+      - id: get_property_list
+        title: "Get a specific property list"
+        narrative: |
+          The buyer retrieves the full details of a specific property list, including
+          all properties in the list.
+        task: get_property_list
+        schema_ref: "property/get-property-list-request.json"
+        response_schema_ref: "property/get-property-list-response.json"
+        doc_ref: "/governance/property/tasks/property_lists"
+        comply_scenario: governance_property_lists
+        stateful: true
+        expected: |
+          Return the full property list:
+          - list_id, name, list_type
+          - All properties in the list with their details
+
+        sample_request:
+          list_id: "pl_acme_inclusion_001"
+
+        validations:
+          - check: response_schema
+            description: "Response matches get-property-list-response.json schema"
+
+  - id: update_list
+    title: "Update property lists"
+    narrative: |
+      The buyer modifies an existing property list — adding or removing properties
+      as brand safety requirements evolve.
+
+    steps:
+      - id: update_property_list
+        title: "Update a property list"
+        narrative: |
+          The buyer adds new properties to or removes properties from an existing list.
+        task: update_property_list
+        schema_ref: "property/update-property-list-request.json"
+        response_schema_ref: "property/update-property-list-response.json"
+        doc_ref: "/governance/property/tasks/property_lists"
+        comply_scenario: governance_property_lists
+        stateful: true
+        expected: |
+          Return the updated property list:
+          - Updated property count
+          - Confirmation of additions and removals
+
+        sample_request:
+          list_id: "pl_acme_inclusion_001"
+          add:
+            - domain: "mountaineering.example.com"
+          remove:
+            - domain: "campinggear.example.com"
+
+        validations:
+          - check: response_schema
+            description: "Response matches update-property-list-response.json schema"
+
+  - id: delete_list
+    title: "Delete a property list"
+    narrative: |
+      The buyer removes a property list that is no longer needed. Active media buys
+      referencing the list should be notified.
+
+    steps:
+      - id: delete_property_list
+        title: "Delete a property list"
+        narrative: |
+          The buyer deletes a property list. The governance agent removes the list and
+          returns confirmation.
+        task: delete_property_list
+        schema_ref: "property/delete-property-list-request.json"
+        response_schema_ref: "property/delete-property-list-response.json"
+        doc_ref: "/governance/property/tasks/property_lists"
+        comply_scenario: governance_property_lists
+        stateful: true
+        expected: |
+          Confirm deletion:
+          - list_id: the deleted list
+          - status: deleted
+
+        sample_request:
+          list_id: "pl_acme_inclusion_001"
+
+        validations:
+          - check: response_schema
+            description: "Response matches delete-property-list-response.json schema"
+
+  - id: delivery_validation
+    title: "Validate delivery compliance"
+    narrative: |
+      After ads have been delivered, the buyer validates that the seller respected the
+      property lists. The governance agent checks actual delivery data against the
+      inclusion/exclusion constraints.
+
+    steps:
+      - id: validate_property_delivery
+        title: "Validate property compliance"
+        narrative: |
+          The buyer submits delivery data and the governance agent checks whether all
+          placements complied with the property lists. Non-compliant placements are
+          flagged with details.
+        task: validate_property_delivery
+        schema_ref: "property/validate-property-delivery-request.json"
+        response_schema_ref: "property/validate-property-delivery-response.json"
+        doc_ref: "/governance/property/tasks/validate_property_delivery"
+        comply_scenario: governance_property_lists
+        stateful: true
+        expected: |
+          Return validation results:
+          - compliant: boolean overall status
+          - Per-placement compliance status
+          - Violations with details (property, list, severity)
+
+        sample_request:
+          brand:
+            domain: "acmeoutdoor.com"
+          list_id: "pl_acme_inclusion_001"
+          delivery:
+            - property: "outdoormagazine.example.com"
+              impressions: 50000
+            - property: "randomsite.example.com"
+              impressions: 200
+
+        validations:
+          - check: response_schema
+            description: "Response matches validate-property-delivery-response.json schema"

package/storyboards/schema.yaml

@@ -13,12 +13,12 @@
 # id: string (unique identifier, e.g., "creative_template")
 # version: string (semver, e.g., "1.0.0")
 # title: string (human-readable title)
-# category: enum (creative_template | creative_ad_server | creative_sales_agent | creative_generative | media_buy_seller | media_buy_guaranteed_approval | media_buy_non_guaranteed | media_buy_proposal_mode | media_buy_governance_escalation | media_buy_catalog_creative | signal_marketplace | signal_owned)
+# category: enum (capability_discovery | schema_validation | behavioral_analysis | error_compliance | creative_template | creative_ad_server | creative_sales_agent | creative_generative | creative_lifecycle | media_buy_seller | media_buy_generative_seller | media_buy_guaranteed_approval | media_buy_non_guaranteed | media_buy_proposal_mode | media_buy_governance_escalation | media_buy_catalog_creative | media_buy_state_machine | campaign_governance_denied | campaign_governance_conditions | campaign_governance_delivery | signal_marketplace | signal_owned | social_platform | si_session | brand_rights | property_governance | content_standards | audience_sync)
 # summary: string (one-line description for listings)
 # narrative: string (paragraph explaining the overall flow)
 #
 # agent:
-#   interaction_model: enum (stateless_transform | stateful_preloaded | stateful_push | stateless_generate | media_buy_seller | marketplace_catalog | owned_signals)
+#   interaction_model: enum (stateless_transform | stateful_preloaded | stateful_push | stateless_generate | media_buy_seller | marketplace_catalog | owned_signals | si_platform | brand_rights_holder | governance_agent)
 #   capabilities: string[] (AdCP capability flags: supports_transformation, has_creative_library, supports_generation, sells_media, accepts_briefs, supports_guaranteed, supports_non_guaranteed, catalog_signals)
 #   examples: string[] (real-world examples: "Celtra", "Innovid")
 #
@@ -62,4 +62,5 @@
 #
 # check: string (what to validate: "response_schema", "field_present", "field_value", "status_code")
 # path: string (JSON path to the field, e.g., "formats[0].format_id")
+# value: any (expected value — string, number, or boolean; required when check is "field_value")
 # description: string (human-readable description of validation)