@adcp/sdk 7.10.2 → 7.11.1

package/compliance/cache/3.1.0-rc.2/test-kits/nova-motors.yaml

@@ -0,0 +1,262 @@
+# Nova Motors — Signal-Focused Advertiser Test Kit
+#
+# Entity definition: fictional-entities.yaml → advertisers[nova_motors]
+# Data providers defined in this kit: see fictional-entities.yaml → data_providers
+#
+# This brand is registered as a sandbox brand in AgenticAdvertising.org (AAO).
+# Agents resolve novamotors.example via the standard AAO brand resolution path.
+# AAO returns the brand.json below but excludes sandbox brands from production
+# brand discovery results.
+
+id: nova_motors
+name: "Nova Motors"
+description: |
+  Signal-focused test kit for the Nova Motors Volta EV launch campaign.
+  Provides sample signal definitions, pricing options, and destination
+  configurations for testing signal agent storyboards.
+sandbox: true
+
+# security_baseline auth fixture — see acme-outdoor.yaml for semantics.
+#
+# probe_task is `get_signals` because this kit's primary consumers are
+# signal agents (specialisms/signal-owned, specialisms/signal-marketplace)
+# where list_creatives is not implemented. Non-signal storyboards that
+# reuse this kit (collection-lists, sales-broadcast-tv, sponsored-
+# intelligence) should select acme-outdoor for security_baseline, or
+# override probe_task at the storyboard layer.
+auth:
+  api_key: "demo-nova-motors-v1"
+  probe_task: get_signals
+
+brand:
+  house:
+    domain: "novamotors.example"
+    name: "Nova Motors"
+  brand_id: "nova_motors"
+  names:
+    - en: "Nova Motors"
+  description: "Electric vehicles for the next generation. The Volta EV — performance meets sustainability."
+  industry: "automotive"
+  keller_type: "master"
+  logos:
+    - url: "https://test-assets.adcontextprotocol.org/nova-motors/logo-primary.png"
+      orientation: "horizontal"
+      background: "light-bg"
+      variant: "primary"
+      width: 400
+      height: 100
+    - url: "https://test-assets.adcontextprotocol.org/nova-motors/logo-icon.png"
+      orientation: "square"
+      background: "transparent-bg"
+      variant: "icon"
+      width: 200
+      height: 200
+  colors:
+    primary: "#0D47A1"
+    secondary: "#00BFA5"
+    accent: "#FF6D00"
+    background: "#F5F5F5"
+    text: "#1A1A1A"
+  fonts:
+    heading:
+      family: "Inter"
+      weight: 700
+      url: "https://fonts.googleapis.com/css2?family=Inter:wght@700"
+    body:
+      family: "Inter"
+      weight: 400
+      url: "https://fonts.googleapis.com/css2?family=Inter"
+  tone:
+    voice: "Forward-thinking and precise. We speak to drivers who care about engineering and the planet — no greenwashing, no hype."
+    attributes:
+      - "innovative"
+      - "precise"
+      - "optimistic"
+    dos:
+      - "Lead with performance specs"
+      - "Reference sustainability with evidence"
+      - "Use clean, modern language"
+    donts:
+      - "Greenwash or overstate environmental claims"
+      - "Use legacy automotive clichés"
+      - "Condescend about range anxiety"
+
+campaign:
+  brand: "Nova Motors"
+  product: "Volta EV"
+  brief: "Reach in-market EV buyers with high purchase propensity, near dealerships, who haven't bought a Nova vehicle before."
+  budget: 250000
+  currency: "USD"
+  markets: ["US"]
+
+signals:
+  marketplace:
+    - signal_agent_segment_id: "trident_likely_ev_buyers"
+      name: "Likely EV Buyers"
+      data_provider_domain: "tridentauto.example"
+      signal_id: "likely_ev_buyers"
+      value_type: "binary"
+      signal_type: "marketplace"
+      coverage_percentage: 8
+      pricing:
+        - pricing_option_id: "po_trident_ev_cpm"
+          model: "cpm"
+          cpm: 3.50
+          currency: "USD"
+
+    - signal_agent_segment_id: "trident_purchase_propensity"
+      name: "Purchase Propensity"
+      data_provider_domain: "tridentauto.example"
+      signal_id: "purchase_propensity"
+      value_type: "numeric"
+      signal_type: "marketplace"
+      range:
+        min: 0
+        max: 1
+      coverage_percentage: 55
+      pricing:
+        - pricing_option_id: "po_trident_propensity_cpm"
+          model: "cpm"
+          cpm: 4.00
+          currency: "USD"
+
+    - signal_agent_segment_id: "meridian_competitor_visitors"
+      name: "Competitor Visitors"
+      data_provider_domain: "meridiangeo.example"
+      signal_id: "competitor_visitors"
+      value_type: "binary"
+      signal_type: "marketplace"
+      coverage_percentage: 6
+      pricing:
+        - pricing_option_id: "po_meridian_visitors_cpm"
+          model: "cpm"
+          cpm: 5.00
+          currency: "USD"
+
+    - signal_agent_segment_id: "shopgrid_new_to_brand"
+      name: "New to Brand"
+      data_provider_domain: "shopgrid.example"
+      signal_id: "new_to_brand"
+      value_type: "binary"
+      signal_type: "marketplace"
+      coverage_percentage: 25
+      pricing:
+        - pricing_option_id: "po_shopgrid_retail_cpm"
+          model: "cpm"
+          cpm: 3.50
+          currency: "USD"
+
+  owned:
+    - signal_agent_segment_id: "prism_high_ltv"
+      name: "High LTV Customers"
+      value_type: "binary"
+      signal_type: "owned"
+      coverage_percentage: 12
+      pricing:
+        - pricing_option_id: "po_prism_flat_monthly"
+          model: "flat_fee"
+          amount: 5000
+          period: "monthly"
+          currency: "USD"
+
+    - signal_agent_segment_id: "prism_cart_abandoner"
+      name: "Cart Abandoners"
+      value_type: "binary"
+      signal_type: "owned"
+      coverage_percentage: 18
+      pricing:
+        - pricing_option_id: "po_prism_abandoner_cpm"
+          model: "cpm"
+          cpm: 8.00
+          currency: "USD"
+
+    - signal_agent_segment_id: "prism_engagement_score"
+      name: "Engagement Score"
+      value_type: "numeric"
+      signal_type: "owned"
+      range:
+        min: 0
+        max: 100
+      coverage_percentage: 65
+      pricing:
+        - pricing_option_id: "po_prism_engagement_cpm"
+          model: "cpm"
+          cpm: 2.50
+          currency: "USD"
+
+    - signal_agent_segment_id: "prism_churn_risk"
+      name: "Churn Risk"
+      value_type: "categorical"
+      signal_type: "owned"
+      categories: ["low_risk", "medium_risk", "high_risk", "churned"]
+      coverage_percentage: 70
+      pricing:
+        - pricing_option_id: "po_prism_churn_pom"
+          model: "percent_of_media"
+          percent: 12
+          max_cpm: 3.00
+          currency: "USD"
+
+assets:
+  images:
+    - id: "hero_300x250"
+      url: "https://test-assets.adcontextprotocol.org/nova-motors/hero-300x250.jpg"
+      width: 300
+      height: 250
+      mime_type: "image/jpeg"
+      description: "Medium rectangle hero — Volta EV on coastal highway"
+
+    - id: "hero_728x90"
+      url: "https://test-assets.adcontextprotocol.org/nova-motors/hero-728x90.jpg"
+      width: 728
+      height: 90
+      mime_type: "image/jpeg"
+      description: "Leaderboard hero — Volta EV front profile with charging station"
+
+    - id: "hero_320x50"
+      url: "https://test-assets.adcontextprotocol.org/nova-motors/hero-320x50.jpg"
+      width: 320
+      height: 50
+      mime_type: "image/jpeg"
+      description: "Mobile banner hero — Volta EV dashboard detail"
+
+    - id: "hero_160x600"
+      url: "https://test-assets.adcontextprotocol.org/nova-motors/hero-160x600.jpg"
+      width: 160
+      height: 600
+      mime_type: "image/jpeg"
+      description: "Wide skyscraper hero — vertical Volta EV silhouette"
+
+    - id: "hero_master"
+      url: "https://test-assets.adcontextprotocol.org/nova-motors/hero-master.jpg"
+      width: 1200
+      height: 628
+      mime_type: "image/jpeg"
+      description: "Master hero image — high-res Volta EV in motion"
+
+  text:
+    headlines:
+      - "The Volta EV — 0 to 60 in 3.2s"
+      - "Performance Meets Sustainability"
+      - "Drive Electric. Drive Nova."
+    descriptions:
+      - "340 miles of range. 15-minute fast charge. The Volta EV is engineered for drivers who refuse to compromise."
+      - "Zero emissions, zero compromises. Test drive the Volta EV at your nearest Nova Motors dealer."
+    cta:
+      - "Reserve Yours"
+      - "Schedule a Test Drive"
+      - "Explore the Volta"
+
+  click_url: "https://novamotors.example/volta-ev"
+
+destinations:
+  platforms:
+    - type: "platform"
+      platform: "the-trade-desk"
+      account: "agency-123-ttd"
+    - type: "platform"
+      platform: "streamhaus"
+      account: "agency-ctv-seat-456"
+  agents:
+    - type: "agent"
+      agent_url: "https://wonderstruck.salesagents.example"

package/compliance/cache/3.1.0-rc.2/test-kits/osei-natural.yaml

@@ -0,0 +1,126 @@
+# Osei Natural — Beauty Advertiser Test Kit
+#
+# Entity definition: fictional-entities.yaml → advertisers[osei_natural]
+#
+# 8-person natural skincare company based in Nairobi. Represents the small
+# business that advertising should serve but currently doesn't.
+#
+# This brand is registered as a sandbox brand in AgenticAdvertising.org (AAO).
+# Agents resolve oseinatural.example via the standard AAO brand resolution path.
+# AAO returns the brand.json below but excludes sandbox brands from production
+# brand discovery results.
+
+id: osei_natural
+name: "Osei Natural"
+description: "Natural skincare brand for small-business advertiser storyboard testing"
+sandbox: true
+
+# security_baseline auth fixture — see acme-outdoor.yaml for semantics.
+auth:
+  api_key: "demo-osei-natural-v1"
+  probe_task: list_creatives
+
+brand:
+  house:
+    domain: "oseinatural.example"
+    name: "Osei Natural"
+  brand_id: "osei_natural"
+  names:
+    - en: "Osei Natural"
+  description: "Natural skincare rooted in East African botanicals. Small-batch, founder-led, and unapologetically simple."
+  industry: "beauty"
+  keller_type: "master"
+  logos:
+    - url: "https://test-assets.adcontextprotocol.org/osei-natural/logo-primary.png"
+      orientation: "horizontal"
+      background: "light-bg"
+      variant: "primary"
+      width: 400
+      height: 100
+    - url: "https://test-assets.adcontextprotocol.org/osei-natural/logo-icon.png"
+      orientation: "square"
+      background: "transparent-bg"
+      variant: "icon"
+      width: 200
+      height: 200
+  colors:
+    primary: "#5D4037"
+    secondary: "#C8E6C9"
+    accent: "#FF8F00"
+    background: "#FBF7F4"
+    text: "#2E2E2E"
+  fonts:
+    heading:
+      family: "Cormorant Garamond"
+      weight: 600
+      url: "https://fonts.googleapis.com/css2?family=Cormorant+Garamond:wght@600"
+    body:
+      family: "Lato"
+      weight: 400
+      url: "https://fonts.googleapis.com/css2?family=Lato"
+  tone:
+    voice: "Calm, grounded, and personal. Amara speaks directly to customers like a trusted friend sharing what works."
+    attributes:
+      - "authentic"
+      - "gentle"
+      - "personal"
+    dos:
+      - "Name specific botanicals and their origins"
+      - "Use first-person when appropriate — the founder is the brand"
+      - "Keep it warm and conversational"
+    donts:
+      - "Use clinical or pharmaceutical language"
+      - "Make anti-aging claims — Osei Natural is about care, not correction"
+      - "Erase the brand's Kenyan identity — it's a feature, not a detail"
+
+assets:
+  images:
+    - id: "hero_300x250"
+      url: "https://test-assets.adcontextprotocol.org/osei-natural/hero-300x250.jpg"
+      width: 300
+      height: 250
+      mime_type: "image/jpeg"
+      description: "Medium rectangle hero — product jars with botanical ingredients"
+
+    - id: "hero_728x90"
+      url: "https://test-assets.adcontextprotocol.org/osei-natural/hero-728x90.jpg"
+      width: 728
+      height: 90
+      mime_type: "image/jpeg"
+      description: "Leaderboard hero — Amara in workshop with shea butter"
+
+    - id: "hero_320x50"
+      url: "https://test-assets.adcontextprotocol.org/osei-natural/hero-320x50.jpg"
+      width: 320
+      height: 50
+      mime_type: "image/jpeg"
+      description: "Mobile banner hero — close-up of baobab oil serum"
+
+    - id: "hero_160x600"
+      url: "https://test-assets.adcontextprotocol.org/osei-natural/hero-160x600.jpg"
+      width: 160
+      height: 600
+      mime_type: "image/jpeg"
+      description: "Wide skyscraper hero — vertical product lineup on linen"
+
+    - id: "hero_master"
+      url: "https://test-assets.adcontextprotocol.org/osei-natural/hero-master.jpg"
+      width: 1200
+      height: 628
+      mime_type: "image/jpeg"
+      description: "Master hero image — high-res flat lay of full product range"
+
+  text:
+    headlines:
+      - "Your Skin Deserves Better Ingredients"
+      - "Small-Batch Skincare from Nairobi"
+      - "Rooted in East African Botanicals"
+    descriptions:
+      - "Shea butter, baobab oil, and aloe — sourced from East African growers, blended by hand in Nairobi. Osei Natural."
+      - "Eight people, twelve products, zero compromises. Natural skincare that actually works."
+    cta:
+      - "Shop the Collection"
+      - "Meet the Founder"
+      - "Try a Sample Kit"
+
+  click_url: "https://oseinatural.example/shop"

package/compliance/cache/3.1.0-rc.2/test-kits/parallel-dispatch-runner.yaml

@@ -0,0 +1,196 @@
+# Parallel Dispatch Runner — Harness Contract Test Kit
+#
+# Applies to:
+#   - universal/idempotency.yaml (concurrent-retry phase — verifies the
+#     first-insert-wins rule under L1/security.mdx#idempotency rule 9 by firing
+#     two requests with the same idempotency_key in parallel and grading the
+#     outcome).
+#   - Any future storyboard that needs to verify behavior under concurrent
+#     dispatch (e.g., racing webhook deliveries, racing sync calls).
+#
+# Storyboards are sequential by default — steps run one after another in YAML
+# order, with each step's response observed before the next is dispatched.
+# That model cannot exercise rule 9 (concurrent retry / first-insert-wins),
+# because the second request would always arrive after the first's response
+# has been observed.
+#
+# This test-kit defines the coordination contract between a runner that
+# supports firing N requests in parallel and storyboards that need that
+# capability. The runner's parallel dispatch happens at the @adcp/client
+# layer (or its Python/Go equivalents) using the SDK's batch-call primitive,
+# NOT at the YAML-step boundary — the storyboard author MUST NOT try to
+# express parallelism via separate sequential steps.
+
+id: parallel_dispatch_runner
+applies_to:
+  universals:
+    - idempotency
+
+description: |
+  Coordination contract between a runner that supports parallel request
+  dispatch and a storyboard step that needs to exercise concurrent-retry
+  semantics. The runner fires N >= 2 logically-simultaneous requests (same
+  `idempotency_key`, same canonical payload) and observes all responses, then
+  asserts on the cross-response invariants the storyboard step declares.
+
+endpoint_scope: sandbox
+# Concurrent-retry tests on storyboards that drive spend-committing operations
+# (create_media_buy in particular) would create real commitments on retry-
+# replay-success paths. Graders MUST target a sandbox/staging endpoint. Agents
+# claiming the specialism SHOULD expose a dedicated grading endpoint.
+
+harness_mode: black_box
+
+# --- Parallelism mechanism ---
+#
+# Two viable shapes with different observation properties. The runner selects
+# per run mode; storyboard authors SHOULD NOT assume a specific mode.
+#
+#   process_local (default for lint/fast runs):
+#     The runner calls the SDK's batch-call primitive (Promise.all in JS,
+#     asyncio.gather in Python, sync.WaitGroup in Go) to dispatch N requests
+#     from the same process before awaiting any of their responses.
+#     Inter-request scheduling is at the SDK/transport level, NOT at the YAML-
+#     step level. Sufficient to exercise the seller's INSERT race; not
+#     sufficient to exercise true network-level interleaving (the runner's
+#     event loop still drains in deterministic order under most schedulers).
+#
+#   distributed (optional, full-conformance runs):
+#     The runner dispatches the N requests from N independent worker processes
+#     (or N independent CI shards) using a barrier-wait synchronization point.
+#     All workers block on the barrier and unblock simultaneously, producing
+#     true network-level concurrency. Materially more expensive operationally;
+#     reserved for AdCP Verified grading and rule-9-specific deep checks.
+#
+# The specialism grades observable seller behavior; the dispatch mechanism is
+# an implementation detail below the conformance seam. A seller that passes
+# under process_local MUST also pass under distributed for the same storyboard
+# — any divergence is a conformance bug in the runner, not a legitimate
+# seller-behavior difference.
+
+# --- Step-level coordination keys ---
+#
+# A storyboard step requiring this contract declares:
+#
+#   requires_contract: parallel_dispatch_runner
+#   parallel_dispatch:
+#     count: 2                       # required, integer >= 2, <= 10
+#     same_idempotency_key: true     # required for rule-9 tests; future
+#                                    #   non-idempotency parallel tests MAY
+#                                    #   set this false
+#     barrier_timeout_ms: 5000       # optional; default 5000ms — how long the
+#                                    #   runner waits at the barrier before
+#                                    #   firing requests anyway (covers slow
+#                                    #   distributed workers)
+#
+# The runner injects identical sample_request bodies on all N dispatches —
+# specifically including the same expansion of any `$generate:uuid_v4#alias`
+# placeholder, so the seller sees the same canonical hash on every replica.
+# Distinct correlation_ids per dispatch ARE allowed (and recommended) because
+# `context` is excluded from the canonical hash (see L1/security.mdx Payload
+# equivalence) — using distinct correlation_ids lets the runner trace which
+# response came from which dispatch in its output.
+
+parallel_dispatch_step_contract:
+  required_step_fields:
+    - parallel_dispatch.count
+    - parallel_dispatch.same_idempotency_key
+  optional_step_fields:
+    - parallel_dispatch.barrier_timeout_ms
+  count_min: 2
+  count_max: 10
+  # 10 is a soft ceiling: every runner mode (process_local, distributed) MUST
+  # support up to 10 parallel dispatches. Storyboards needing higher fan-out
+  # SHOULD justify it in a step comment; the runner MAY reject counts above
+  # 10 to bound test runtime.
+
+# --- Validation primitives ---
+#
+# Steps requiring parallel dispatch declare validations against the array of
+# responses, not a single response. The storyboard step's validations[] block
+# acquires two cross-response check kinds that are not available in
+# sequential-dispatch steps:
+#
+#   - check: cross_response_field_equal
+#     path: "media_buy_id"
+#     description: |
+#       All N responses (including IDEMPOTENCY_IN_FLIGHT-then-retried
+#       responses, resolved to their eventual cached response) MUST carry the
+#       same value at the named path. A divergence is a rule-9 violation —
+#       the seller produced two distinct resources for the same key.
+#
+#   - check: cross_response_count_distinct
+#     path: "media_buy_id"
+#     allowed_values: [1]
+#     description: |
+#       The set of distinct values observed at the named path across all N
+#       responses MUST have cardinality equal to one of allowed_values. For
+#       rule-9 tests, allowed_values: [1] — exactly one resource was created.
+#
+# Standard per-response checks (response_schema, field_present, error_code,
+# etc.) apply to each response individually; the runner runs them N times
+# and aggregates pass/fail per the storyboard's existing severity rules.
+
+cross_response_check_kinds:
+  - cross_response_field_equal
+  - cross_response_count_distinct
+
+# --- Resolution of IDEMPOTENCY_IN_FLIGHT in cross-response checks ---
+#
+# A seller adopting the reject-and-redirect policy under rule 9 may return
+# IDEMPOTENCY_IN_FLIGHT on the second (or later) dispatched request rather
+# than wait-and-replay. The runner MUST resolve IDEMPOTENCY_IN_FLIGHT
+# responses to their eventual cached response before applying cross-response
+# checks: when the runner observes IDEMPOTENCY_IN_FLIGHT, it waits the
+# `error.details.retry_after` seconds and retries the SAME idempotency_key
+# (per the buyer-side normative behavior). The cross-response check then
+# operates on the resolved response set, not the raw initial set.
+#
+# Maximum total wall-time for one in-flight resolution is bounded by the
+# runner's overall step-timeout budget. Sellers returning IDEMPOTENCY_IN_FLIGHT
+# with a retry_after that exceeds the runner's budget will fail the step on
+# timeout — graded as `step_timeout`, not `rule_9_violation`. Sellers tuning
+# retry_after for production traffic SHOULD test their values against the
+# runner's documented timeout (default 60s; CI configurable).
+
+# --- What the contract does NOT cover ---
+#
+# Network-level packet timing / ordering. process_local mode delivers requests
+# in deterministic event-loop order; distributed mode introduces real
+# interleaving but does not synthesize adversarial packet schedules. Sellers
+# whose correctness depends on adversarial network conditions need additional
+# fault-injection harnesses outside this contract.
+#
+# Multi-account / multi-agent racing. The contract dispatches N requests
+# within a single (authenticated_agent, account) scope — the same scope as
+# the idempotency key itself. Storyboards needing to exercise cross-scope
+# races (e.g., agency-vs-direct-buyer collisions on a shared natural key)
+# require a separate contract.
+#
+# Crash injection. The contract does not interrupt the seller mid-request.
+# Storyboards testing seller behavior under crashes / restarts / failovers
+# need a separate fault-injection harness — out of scope here.
+
+# --- Reviewer checks ---
+#
+# Some properties of rule 9 cannot be programmatically graded by this
+# contract and MUST be confirmed by reviewer inspection of the seller's
+# implementation and runbook:
+#
+#   - The seller's claim-row / unique-constraint pattern actually backs the
+#     observed first-insert-wins behavior (not a happy-path race that
+#     coincidentally avoided the conflict in the test run).
+#   - The seller's downstream reconciliation pattern (rule 10) is documented
+#     in the operational runbook. The contract observes only the buyer-
+#     visible response surface; the downstream-side behavior is not directly
+#     observable from a black-box harness.
+#   - The seller's in-flight detection does NOT leak across scope boundaries
+#     — an attacker authenticated as agent B with a stolen key from agent A
+#     receives the same response shape and timing whether agent A's row is
+#     in flight, completed, or never existed. Verified by manual probing,
+#     not by this contract.
+
+reviewer_checks:
+  - "Confirm the seller's claim-row / unique-constraint implementation backs the observed first-insert-wins behavior, rather than a happy-path race the test happened to avoid (review code or runbook describing the INSERT … ON CONFLICT pattern on the scope tuple)."
+  - "Confirm the seller's downstream-reconciliation pattern (rule 10) is documented in their operational runbook: which downstream calls use write-claim-before-invoke and which thread the buyer-key (or a derivative)."
+  - "Confirm the seller's in-flight state does NOT leak across (authenticated_agent, account_id) scope boundaries — probe with a stolen key from a different scope and verify the response shape and timing match the never-seen-key path."