@adcp/sdk 7.11.0 → 7.11.1

package/compliance/cache/3.1.0-rc.2/universal/fictional-entities.yaml

@@ -0,0 +1,307 @@
+# Fictional Entities for AdCP Storyboards & Training
+#
+# Canonical source: specs/character-bible.md at docs.adcontextprotocol.org
+#
+# This file mirrors the character bible's fictional companies for use in
+# storyboards, test kits, and client-side testing. All entities use the
+# IANA-reserved .example TLD.
+#
+# Rules:
+#   - Every fictional company MUST match the character bible
+#   - Do not invent new entities here — add them to the bible first
+#   - Test kits in test-kits/ expand on entities with full brand identity,
+#     sample assets, and signal definitions
+#   - Sandbox brands (advertisers) are resolvable via AgenticAdvertising.org
+#     because the registry imports getSandboxEntities() from @adcp/client
+#     directly — no seeding needed, these files are the single source of truth
+#
+# Adding a new entity:
+#   1. Add it to specs/character-bible.md in the adcp docs repo
+#   2. Mirror it here with domain and role
+#   3. If it's an advertiser, create a test kit in test-kits/ with sandbox: true
+#   4. Reference by id in storyboards
+
+# ============================================================
+# ADVERTISERS — brands that buy media through the protocol
+# ============================================================
+
+advertisers:
+  - id: acme_outdoor
+    name: "Acme Outdoor"
+    domain: "acmeoutdoor.example"
+    industry: retail
+    sandbox_brand: true
+    test_kit: "test-kits/acme-outdoor.yaml"
+    description: >
+      Premium outdoor gear company. The default advertiser for most storyboards.
+      Used in media buy, creative, governance, and compliance scenarios.
+    characters:
+      - "Sam Adeyemi (campaigns)"
+      - "Jordan Ochoa (governance)"
+
+  - id: nova_motors
+    name: "Nova Motors"
+    domain: "novamotors.example"
+    industry: automotive
+    sandbox_brand: true
+    test_kit: "test-kits/nova-motors.yaml"
+    description: >
+      Electric vehicle manufacturer launching the Volta EV. Used for signal,
+      brand protocol, and sponsored intelligence storyboards.
+    characters:
+      - "Tomoko Hara (brand operations)"
+      - "Sam Adeyemi (buyer)"
+
+  - id: bistro_oranje
+    name: "Bistro Oranje"
+    domain: "bistro-oranje.example"
+    industry: hospitality
+    sandbox_brand: true
+    test_kit: "test-kits/bistro-oranje.yaml"
+    description: >
+      Dutch restaurant chain. Used in rights licensing scenarios where
+      Carlos manages programmatic rights for ad campaigns.
+    characters:
+      - "Carlos (rights licensing)"
+
+  - id: summit_foods
+    name: "Summit Foods"
+    domain: "summitfoods.example"
+    industry: cpg
+    sandbox_brand: true
+    test_kit: "test-kits/summit-foods.yaml"
+    description: >
+      Organic food / CPG brand. Buys retail media inventory on ShopGrid
+      in commerce media scenarios.
+    characters: []
+
+  - id: osei_natural
+    name: "Osei Natural"
+    domain: "oseinatural.example"
+    industry: beauty
+    sandbox_brand: true
+    test_kit: "test-kits/osei-natural.yaml"
+    description: >
+      8-person natural skincare company based in Nairobi. Represents the
+      small business that advertising should serve but currently doesn't.
+    characters:
+      - "Amara Osei (founder)"
+
+# ============================================================
+# AGENCIES — media buying agencies that operate on behalf of advertisers
+# ============================================================
+
+agencies:
+  - id: pinnacle_agency
+    name: "Pinnacle Agency"
+    domain: "pinnacle-agency.example"
+    size: "~200 employees"
+    description: >
+      Full-service mid-size media buying agency. Acts as the operator (buyer)
+      in most storyboards, executing campaigns on behalf of Acme Outdoor and
+      other clients. Runs its own governance agent and hosts creative assets
+      on its CDN.
+    services:
+      cdn: "cdn.pinnacle-agency.example"
+      governance_agent: "governance.pinnacle-agency.example"
+    characters:
+      - "Alex Reeves (VP of media operations)"
+      - "Sam Adeyemi (senior media buyer)"
+      - "Jordan Ochoa (campaign operations manager)"
+      - "Maya Johal (creative strategist)"
+      - "Dayo Mensah (ad tech fellow)"
+      - "Carlos (programmatic buyer, Amsterdam office)"
+
+# ============================================================
+# PUBLISHERS & PLATFORMS — sell inventory or serve ads
+# ============================================================
+
+publishers:
+  - id: streamhaus
+    name: "StreamHaus"
+    domain: "streamhaus.example"
+    type: "CTV publisher / SSP"
+    size: "~80 employees"
+    description: >
+      Mid-size streaming video platform. Exposes inventory to buyer agents
+      through AdCP rather than building a self-serve dashboard. Validates
+      creatives and fulfills media buys.
+    characters:
+      - "Priya Nair (director of ad products)"
+
+  - id: outdoornet
+    name: "OutdoorNet"
+    domain: "outdoornet.example"
+    type: "Display ad network"
+    description: >
+      Display advertising network. One of Sam's multiple sellers in
+      multi-platform media buying scenarios.
+
+  - id: podtrail
+    name: "PodTrail"
+    domain: "podtrail.example"
+    type: "Podcast ad platform"
+    description: >
+      Podcast-specific seller platform. One of Sam's distribution partners
+      in multi-platform campaigns.
+
+  - id: commhub
+    name: "CommHub"
+    domain: "commhub.example"
+    type: "Social platform"
+    description: >
+      Social media network used in creative strategy and distribution
+      scenarios. Maya's creative channel.
+    characters:
+      - "Maya Johal (creative strategist)"
+
+  - id: shopgrid
+    name: "ShopGrid"
+    domain: "shopgrid.example"
+    type: "Retail marketplace + media network"
+    size: "~3,000 employees"
+    description: >
+      E-commerce marketplace that also operates a retail media network.
+      Summit Foods buys inventory here. Also provides retail purchase
+      data signals (new-to-brand identification).
+    characters:
+      - "Daniel Park (VP of retail media)"
+
+  # --- Property governance fixtures ---
+  # These publishers appear in property governance storyboards as
+  # allow/block list entries. They are thematically consistent with
+  # Acme Outdoor's target audience.
+
+  - id: outdoor_magazine
+    name: "Outdoor Magazine"
+    domain: "outdoormagazine.example"
+    type: "Publisher property"
+    description: "Outdoor lifestyle publication. Allow-listed in property governance."
+
+  - id: hiking_trails
+    name: "Hiking Trails"
+    domain: "hikingtrails.example"
+    type: "Publisher property"
+    description: "Hiking trail guide and community site. Allow-listed in property governance."
+
+  - id: camping_gear
+    name: "Camping Gear Reviews"
+    domain: "campinggear.example"
+    type: "Publisher property"
+    description: "Camping equipment review site. Used in property governance."
+
+  - id: mountaineering
+    name: "Mountaineering Weekly"
+    domain: "mountaineering.example"
+    type: "Publisher property"
+    description: "Mountaineering news and community. Used in property governance."
+
+  - id: test_publisher
+    name: "Test Publisher"
+    domain: "test-publisher.example"
+    type: "Publisher property"
+    description: "Generic publisher for content standards validation."
+
+# ============================================================
+# DATA PROVIDERS — companies that sell audience/signal data
+# ============================================================
+
+data_providers:
+  - id: trident_auto
+    name: "Trident Auto Data"
+    domain: "tridentauto.example"
+    description: >
+      Automotive purchase intent data provider. Supplies EV buyer likelihood
+      and purchase propensity signals for the Nova Motors campaign.
+    characters:
+      - "Kai Lindgren (signals walkthrough)"
+
+  - id: meridian_geo
+    name: "Meridian Geo"
+    domain: "meridiangeo.example"
+    size: "~25 employees"
+    description: >
+      Geolocation data startup. Supplies competitor visitor signals
+      based on physical location data.
+    characters:
+      - "Kai Lindgren (head of partnerships)"
+
+  - id: prism
+    name: "Prism"
+    domain: "prism.example"
+    description: >
+      Nova Motors' first-party data platform. Provides owned signals from
+      CRM and behavioral data: customer lifetime value, cart abandonment,
+      engagement scoring, and churn risk.
+
+# ============================================================
+# RIGHTS & LICENSING
+# ============================================================
+
+rights:
+  - id: loti_entertainment
+    name: "Loti Entertainment"
+    domain: "loti-entertainment.example"
+    type: "Talent agency"
+    description: >
+      Represents talent and manages rights in the licensing ecosystem.
+      Used in rights licensing scenarios alongside Bistro Oranje.
+
+# ============================================================
+# COLLECTIONS — addressable content catalogs for collection_list targeting
+# ============================================================
+#
+# These collections back the CollectionListReference fixtures used in
+# media buy targeting scenarios. Thematically consistent with the
+# advertisers above: outdoor programming for Acme Outdoor, automotive
+# content for Nova Motors.
+#
+# distribution_ids use realistic identifier types (imdb_id, gracenote_id)
+# so matching logic can be exercised against the same shapes a production
+# collection agent would return.
+
+collections:
+  # --- Outdoor programming (matches Acme Outdoor campaigns) ---
+  - id: trail_life_series
+    name: "Trail Life"
+    kind: "series"
+    genre: "outdoor"
+    collection_rid: "rid:outdoor:trail_life"
+    distribution_ids:
+      - type: imdb_id
+        value: "tt9100001"
+      - type: gracenote_id
+        value: "SH_OUTDOOR_TRAIL_LIFE"
+    description: "Multi-part outdoor adventure series. Used as matching inventory for outdoor campaigns."
+
+  - id: summit_stories_series
+    name: "Summit Stories"
+    kind: "series"
+    genre: "outdoor"
+    collection_rid: "rid:outdoor:summit_stories"
+    distribution_ids:
+      - type: imdb_id
+        value: "tt9100002"
+    description: "Mountaineering documentary series. Used as matching inventory for outdoor campaigns."
+
+  # --- Automotive programming (matches Nova Motors campaigns) ---
+  - id: ev_insider_series
+    name: "EV Insider"
+    kind: "series"
+    genre: "automotive"
+    collection_rid: "rid:auto:ev_insider"
+    distribution_ids:
+      - type: gracenote_id
+        value: "SH_AUTO_EV_INSIDER"
+    description: "Electric vehicle review series. Used as matching inventory for Nova Motors campaigns."
+
+  # --- Unrelated programming (used to validate no-match scenarios) ---
+  - id: cooking_bistros_series
+    name: "Bistro Kitchen"
+    kind: "series"
+    genre: "food"
+    collection_rid: "rid:food:bistro_kitchen"
+    distribution_ids:
+      - type: imdb_id
+        value: "tt9200001"
+    description: "Cooking show. Used to validate that unrelated collections do NOT match outdoor targeting."

package/compliance/cache/3.1.0-rc.2/universal/get-media-buys-pagination-integrity.yaml

@@ -0,0 +1,160 @@
+id: get_media_buys_pagination_integrity
+version: "1.0.0"
+title: "Pagination shape — get_media_buys"
+category: schema_validation
+summary: "Validates that get_media_buys responses carry a well-formed pagination envelope honoring the cursor↔has_more invariant."
+track: core
+required_tools:
+  - get_media_buys
+
+narrative: |
+  Every paginated read in AdCP returns a `pagination` envelope satisfying
+  the cursor↔has_more invariant: `has_more=true` carries a `cursor`,
+  `has_more=false` omits it. The full multi-page round-trip is exercised
+  against `list_creatives` (`pagination_integrity.yaml`); this storyboard
+  verifies the simpler invariant — that `get_media_buys` emits a valid
+  pagination block on every successful response.
+
+  The runner seeds three media buys via `controller_seeding: true`. The
+  storyboard's get_media_buys call lands on an ID-lookup path because the
+  current `@adcp/client` request-builder injects `media_buy_ids` from
+  context (see adcp-client request-builder.js — broad-list queries
+  through the SDK are not yet supported for `get_media_buys`). On the
+  ID-lookup path the agent MUST still emit `pagination`, with
+  `has_more: false` and no cursor, and SHOULD volunteer `total_count`
+  reflecting the matched set.
+
+  An agent that omits the `pagination` block entirely on this call —
+  triage's pre-#3122 behavior — fails the first-page assertion. The
+  multi-page round-trip is parked under adcontextprotocol/adcp-client
+  for the request-builder gap; once that lands, this storyboard becomes
+  a candidate for upgrade to a seeded continuation+terminal walk like
+  `pagination_integrity.yaml`.
+
+agent:
+  interaction_model: stateful_preloaded
+  capabilities:
+    - sells_media
+  examples:
+    - "Any AdCP media buy seller exposing get_media_buys"
+
+caller:
+  role: buyer_agent
+  example: "Compliance test harness"
+
+prerequisites:
+  description: |
+    The runner seeds three media buys via `controller_seeding: true`.
+    Each fixture only needs media_buy_id, status, and currency for
+    get_media_buys to surface the entry. The full multi-page walk is
+    deferred until the SDK supports broad-list queries on
+    get_media_buys (see request-builder.js gap).
+  test_kit: "test-kits/acme-outdoor.yaml"
+  controller_seeding: true
+
+fixtures:
+  media_buys:
+    - media_buy_id: "pagination_integrity_mb_1"
+      status: "active"
+      currency: "USD"
+    - media_buy_id: "pagination_integrity_mb_2"
+      status: "active"
+      currency: "USD"
+    - media_buy_id: "pagination_integrity_mb_3"
+      status: "active"
+      currency: "USD"
+
+phases:
+  - id: capability_discovery
+    title: "Capability discovery"
+    narrative: |
+      Confirm the agent supports the media buy protocol before
+      exercising get_media_buys.
+    steps:
+      - id: get_capabilities
+        title: "Check agent capabilities"
+        narrative: |
+          Verify the agent declares media_buy in supported_protocols
+          before driving get_media_buys.
+        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.
+
+        sample_request:
+          context:
+            correlation_id: "get_media_buys_pagination_integrity--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: "get_media_buys_pagination_integrity--get_capabilities"
+            description: "Context correlation_id returned unchanged"
+
+  - id: pagination_shape
+    title: "Verify pagination envelope on get_media_buys"
+    narrative: |
+      With three media buys seeded, the agent's response MUST carry a
+      well-formed `pagination` envelope. On the ID-lookup path
+      (current SDK request-builder default), the envelope is terminal:
+      `has_more=false`, no cursor. Agents that omit the envelope
+      altogether fail this assertion — that's the dishonest shape this
+      storyboard catches.
+
+    steps:
+      - id: list_call
+        title: "Call get_media_buys and verify pagination shape"
+        narrative: |
+          The buyer requests media buys. Whatever path the SDK
+          request-builder selects (today: ID-lookup with the most
+          recently seeded media_buy_id), the agent MUST emit a valid
+          `pagination` envelope satisfying the cursor↔has_more
+          invariant.
+        task: get_media_buys
+        schema_ref: "media-buy/get-media-buys-request.json"
+        response_schema_ref: "media-buy/get-media-buys-response.json"
+        doc_ref: "/media-buy/task-reference/get_media_buys"
+        comply_scenario: get_media_buys_pagination_integrity
+        stateful: true
+        expected: |
+          Return media_buys with a `pagination` envelope:
+          - pagination.has_more is a boolean (false on terminal ID-lookup)
+          - pagination.cursor absent or null when has_more is false
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+
+          context:
+            correlation_id: "get_media_buys_pagination_integrity--list_call"
+        validations:
+          - check: response_schema
+            description: "Response matches get-media-buys-response.json schema"
+          - check: field_present
+            path: "pagination"
+            description: "get_media_buys MUST emit a pagination envelope on every response"
+          - check: field_present
+            path: "pagination.has_more"
+            description: "pagination.has_more is REQUIRED per /schemas/core/pagination-response.json"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "get_media_buys_pagination_integrity--list_call"
+            description: "Context correlation_id returned unchanged"

package/compliance/cache/3.1.0-rc.2/universal/get-signals-pagination-integrity.yaml

@@ -0,0 +1,210 @@
+id: get_signals_pagination_integrity
+version: "1.0.0"
+title: "get_signals pagination cursor integrity"
+category: schema_validation
+summary: "Validates the cursor↔has_more invariant on a paginated get_signals response by walking from a continuation page to the next page under a broad query."
+track: signals
+required_tools:
+  - get_signals
+
+narrative: |
+  `get_signals` is the buyer's primary entry point into the signals
+  marketplace. The response carries the standard `pagination` envelope, so
+  the cursor↔has_more invariant that gates `list_creatives` (covered by
+  universal/pagination-integrity) gates this endpoint too.
+
+  This storyboard sends a deliberately broad `signal_spec` ("audience") so
+  any non-trivial signal set matches more than one entry, then asks
+  for `pagination.max_results: 1`. Conformant agents MUST report
+  `has_more: true` with a `cursor` on this page — an agent that caps
+  internally and reports `has_more: false` while more candidates match
+  fails the page-1 assertion. That's the dishonest-pagination shape this
+  storyboard exists to catch.
+
+  After capturing the cursor, the storyboard follows it on the second
+  call. The terminal state of that page depends on the agent's signal set
+  size and is not pinned — the second-page validations check
+  response-schema conformance only. The cursor↔has_more invariant on
+  any single page is enforced statically across all schema and storyboard
+  fixtures by `scripts/lint-pagination-invariant.cjs`; the storyboard's
+  job is the runtime catch on the page where the agent first decides
+  whether to honor `max_results`.
+
+  Signal set sizing: agents whose signal sets return zero or one match for
+  "audience" SHOULD avoid claiming signal-marketplace behavior rather than
+  passing this storyboard with a one-page result — a signal marketplace with
+  a single audience signal isn't a marketplace.
+  When such an agent runs the storyboard the first-page assertion fails
+  loud, which is the right grading: this is not a `not_applicable` case,
+  it's a too-thin signal set claiming behavior it can't honor.
+
+agent:
+  interaction_model: marketplace_catalog
+  capabilities: []
+  examples:
+    - "Any AdCP agent that exposes a paginated get_signals over a non-trivial signal set"
+
+caller:
+  role: buyer_agent
+  example: "Compliance test harness"
+
+prerequisites:
+  description: |
+    No fixtures required. The agent's signal set is treated as given —
+    the storyboard sends a broad query and asserts pagination shape
+    invariants on whatever match set the agent returns. Any agent
+    claiming signal-marketplace behavior SHOULD have a non-trivial signal set matching
+    "audience".
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: capability_discovery
+    title: "Capability discovery"
+    narrative: |
+      Confirm the agent supports the signals protocol before exercising
+      get_signals.
+    steps:
+      - id: get_capabilities
+        title: "Check agent capabilities"
+        narrative: |
+          Verify that the agent declares signals in supported_protocols
+          before driving paginated get_signals.
+        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 signals in supported_protocols.
+
+        sample_request:
+          context:
+            correlation_id: "get_signals_pagination_integrity--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: "get_signals_pagination_integrity--get_capabilities"
+            description: "Context correlation_id returned unchanged"
+
+  - id: pagination_walk
+    title: "Walk pages with a small max_results"
+    narrative: |
+      A broad `signal_spec` ("audience") against any non-trivial signals
+      signal set matches more than one entry. With `max_results: 1` the
+      first call MUST return a continuation page; the second call follows
+      the captured cursor.
+
+    steps:
+      - id: first_page
+        title: "Request the first page with max_results=1"
+        narrative: |
+          The buyer asks for up to one signal under a broad
+          natural-language query. Agents whose signal sets contain more than
+          one match (the expected case for any agent claiming
+          signal-marketplace behavior) MUST report `has_more=true` and a `cursor` the
+          buyer can follow.
+
+          The runner captures `pagination.cursor` into
+          `$context.signals_next_cursor` for the follow-up step. If the
+          agent reports `has_more=false` while more matches exist (the
+          dishonest pagination case), the field_value check on
+          `pagination.has_more` fires — surfacing the bug class this
+          storyboard exists to catch.
+        task: get_signals
+        schema_ref: "signals/get-signals-request.json"
+        response_schema_ref: "signals/get-signals-response.json"
+        doc_ref: "/signals/tasks/get_signals"
+        comply_scenario: get_signals_pagination_integrity
+        stateful: true
+        context_outputs:
+          - name: signals_next_cursor
+            path: "pagination.cursor"
+        expected: |
+          Return up to one signal matching the broad audience query with:
+          - pagination.has_more = true
+          - pagination.cursor present (an opaque continuation token)
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          signal_spec: "audience"
+          pagination:
+            max_results: 1
+
+          context:
+            correlation_id: "get_signals_pagination_integrity--first_page"
+        validations:
+          - check: response_schema
+            description: "Response matches get-signals-response.json schema"
+          - check: field_value
+            path: "pagination.has_more"
+            value: true
+            description: "A broad query against any non-trivial signal set must yield more than one match — first page is non-terminal"
+          - check: field_present
+            path: "pagination.cursor"
+            description: "has_more=true requires a cursor — without one the caller cannot continue"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "get_signals_pagination_integrity--first_page"
+            description: "Context correlation_id returned unchanged"
+
+      - id: next_page
+        title: "Follow the cursor"
+        narrative: |
+          The buyer follows the captured cursor under the same broad
+          query. The terminal state of this page depends on the agent's
+          signal set size — some agents exhaust the result set in two
+          pages, others continue paginating — so we do not pin
+          `has_more` here. Schema conformance MUST hold; the
+          cursor↔has_more invariant on this page is enforced by
+          `scripts/lint-pagination-invariant.cjs` against any sample
+          fixture and by the round-trip on `universal/
+          pagination-integrity.yaml`.
+        task: get_signals
+        schema_ref: "signals/get-signals-request.json"
+        response_schema_ref: "signals/get-signals-response.json"
+        doc_ref: "/signals/tasks/get_signals"
+        comply_scenario: get_signals_pagination_integrity
+        stateful: true
+        expected: |
+          Return the next page of signals with a schema-valid response.
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          signal_spec: "audience"
+          pagination:
+            cursor: "$context.signals_next_cursor"
+            max_results: 1
+
+          context:
+            correlation_id: "get_signals_pagination_integrity--next_page"
+        validations:
+          - check: response_schema
+            description: "Response matches get-signals-response.json schema"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "get_signals_pagination_integrity--next_page"
+            description: "Context correlation_id returned unchanged"