@adcp/sdk 16.4.0 → 16.6.0

package/compliance/cache/{3.2.5 → 3.2.7}/universal/storyboard-schema.yaml

@@ -642,6 +642,62 @@
 #   See runner-output-contract.yaml > fixture_resolution_result for evidence and
 #   `fixture_unsatisfied` grading. See governance decision DR-0010.
 #
+# creative_build_probe: object (optional; runner preparation, not agent capability)
+#   context_prefix: lowercase context namespace for the atomic route/input binding
+#   message: brief used only by the bounded automatic generation recipe
+#
+#   Requires the creative_build_probe_runner implementation described in
+#   test-kits/creative-build-probe-runner.yaml. Build steps use requires_contract:
+#   creative_build_probe_runner. Unsupported engines keep existing contract and
+#   vacuous-pass guards; discovery steps need no build-preparation contract.
+#
+#   Operator recipes belong in the brand kit selected by prerequisites.test_kit,
+#   or in the runner's explicit test_kit/--test-kit override, for example:
+#
+#     creative_build_probes:
+#       - match:
+#           - path: /capability_id
+#             operator: equals
+#             value: provisioned_image_transform
+#         input:
+#           creative_manifest:
+#             format_kind: image
+#             assets:
+#               image_main:
+#                 asset_type: image
+#                 url: https://test-assets.example/provisioned.jpg
+#                 width: 300
+#                 height: 250
+#
+#   Match clauses use the existing fixture-resolution DSL against the complete
+#   supported_formats entry. Operators assert valid input for every matched route.
+#   Input fields: message (brief/guidance), creative_manifest (generation or
+#   transformation), creative_id (has_creative_library), transformer_id/config
+#   (supports_transformers), and a provisioned target_format_id when the selected
+#   request supports legacy routing. FormatID is an object, for example
+#   {agent_url: https://formats.example, id: sandbox_named_format}.
+#   For this probe contract, config is transformer-bound
+#   and library/inline sources are unambiguous; these are fixture authoring rules,
+#   not new restrictions on build_creative wire requests. Omitted recipe fields
+#   stay absent, including message. Never embed credentials or trust material.
+#
+#   Automatic generation needs a unique routable build operation, generation
+#   support, complete understood constraints and a schema-valid minimal source
+#   manifest. Legacy omitted operations mean build; absent IDs remain legal but
+#   unaddressable through capability-ID routing. A provisioned selected-version
+#   target_format_id recipe can use existing legacy routing instead. Catalog order
+#   is not an operation/input contract. Inert metadata
+#   does not disable the probe. Other declared/unknown constraints need a recipe.
+#
+#   Bind exactly one <prefix>_capability_id or <prefix>_target_format_id plus
+#   supplied <prefix>_message, _creative_manifest,
+#   _creative_id, _transformer_id and _config; inject optional fields through
+#   context_inputs. Resolved evidence includes creative_format:<prefix>, selected
+#   capability or named-format identity and exact match clauses. Missing fixtures/preconditions
+#   report fixture_unsatisfied with zero security credit. Invalid advertised
+#   catalogs produce a structured failed validation; malformed operator recipes
+#   are authoring errors. No global contribution/accounting rules change.
+#
 # --- Test kit flavors ---
 #
 # Files under `static/compliance/source/test-kits/` come in two shapes. The
@@ -1469,6 +1525,8 @@
 #                are matched as deep subsets),
 #                "array_length" (asserts exact array cardinality with `value`,
 #                or an inclusive range with `min` / `max`),
+#                "all_fields_present" (every item of an array carries a field;
+#                see "all_fields_present check" below),
 #                "status_code", "http_status", "http_status_in",
 #                "error_code", "on_401_require_header", "resource_equals_agent_url",
 #                "oauth_metadata_graph",
@@ -1635,6 +1693,27 @@
 #   `actual`. For a missing/non-array path, failure output instead uses
 #   `expected: "array"` and the observed value as `actual` (null when absent).
 #
+# all_fields_present check:
+#   Asserts that every item of one array carries a field. `path` MUST contain
+#   exactly one `[*]` segment: the part before it names the array, the part
+#   after it (non-empty, no further wildcards) names the field on each item,
+#   e.g. `products[*].format_options` or `media_buys[*].packages`. An item
+#   carries the field when it resolves to a value other than null. The check
+#   fails when any item lacks the field; failure output uses the authored path
+#   as `expected`, the RFC 6901 pointers of the offending items' fields as
+#   `actual`, and the first of them as `json_pointer`.
+#
+#   When the array is absent, null, or empty there is nothing to inspect: the
+#   runner MUST grade the validation not_applicable, never a vacuous pass
+#   (runner-output-contract.yaml > validation_result > notes >
+#   all_fields_present_not_applicable). Pair it with `field_present` on the array when the
+#   array itself is required. A path that resolves to a non-array fails.
+#
+#   Introduced for AdCP 4.0 compatibility checks
+#   (universal/v4-compatibility.yaml), where "not observable" and "passed"
+#   are different answers. Runners older than this check grade it
+#   not_applicable under the forward-compat rule, which reports the same way.
+#
 # OAuth discovery graph — use `check: oauth_metadata_graph`:
 #   Applies only to a `protected_resource_metadata` runner task. Starting from
 #   the RFC 9728 document returned by that task, the runner validates the full

package/compliance/cache/3.2.7/universal/v4-compatibility.yaml

@@ -0,0 +1,331 @@
+# AdCP 4.0 compatibility checks
+#
+# Registry of the checks that tell a 3.x agent what AdCP 4.0 removes or
+# tightens that the agent still depends on. This file is not a storyboard: it
+# has no phases and the runner does not execute it. It names each check and
+# says where the suite observes it, so a report can join run output against
+# this list and show every check as passed, failing (with the fix), or not
+# observable.
+#
+# Grading on 3.x
+# --------------
+# The checks are advisory throughout 3.x. A check added for 4.0 readiness
+# MUST NOT fail a 3.x conformance run:
+#
+#   - A validation added only for 4.0 readiness declares `severity: advisory`
+#     with `permanent_advisory`. It MUST NOT use `expires_after_version`,
+#     which promotes on runner version, not on the spec version an agent is
+#     graded against.
+#   - A check MAY instead point at a validation that is already required on
+#     3.x for its own reasons (for example, release-precision version
+#     advertisement is a 3.2 certification requirement). Pointing at it adds
+#     no new failure.
+#   - A check observed through a runner notice inherits the notice contract:
+#     notices never change pass/fail counters.
+#
+# Every canonical notice code with `effective_version: "4.0"` in
+# runner-output-contract.yaml is a check here under the same id, whether the
+# registry observes it through that notice or through a validation.
+#
+# Each check is graded in the storyboard step that already makes the call it
+# needs. The suite does not add a separate 4.0 storyboard, because a task
+# error in a new step would itself become a 3.x failure.
+#
+# Deriving the report
+# -------------------
+# For each check, against one compliance run of one agent:
+#
+#   observed_by.validation (a storyboard, the steps that may grade the
+#   check, and a validation whose `id` equals the check id; when several
+#   steps are listed, they are alternative branches and at most one runs)
+#     passed          the validation_result with this `id` has passed: true
+#                     and was graded (not not_applicable).
+#     failing         the validation_result has passed: false. Show `fix`.
+#     not observable  the storyboard did not run, the step was skipped, or
+#                     the validation graded not_applicable (for example, a
+#                     runner older than the check kind, or nothing to inspect).
+#
+#   observed_by.notice (a canonical notice code in runner-output-contract.yaml)
+#     failing         the run emitted a notice with this code. Show `fix`.
+#     passed          one of `storyboards` ran to completion and emitted no
+#                     notice with this code, AND the runner is known to emit
+#                     this code. Canonical notices are SHOULD-emit, so absence
+#                     from a runner that never emits the code proves nothing.
+#     not observable  none of `storyboards` ran, or the runner is not known
+#                     to emit this code.
+#
+#   Prefer a validation. Use a notice only when no existing step can express
+#   the detection rule as a validation.
+#
+#   observed_by.none
+#     not observable  always. `reason` says why a 3.x agent cannot show it.
+#
+# Adding a check
+# --------------
+# Every 4.0 issue that removes or tightens something an agent relies on
+# declares a stable check id and a one-line detection rule, then adds an entry
+# here in the same PR as the validation or notice that observes it. Add a
+# check only once the 4.0 change is decided; proposals still under working
+# group review stay out until they are accepted.
+#
+#   id              stable snake_case id, `<subject>_removed_in_4_0` or
+#                   `<subject>_required_in_4_0`. Never renamed: dashboards
+#                   aggregate by id. Equals the validation `id` or notice
+#                   `code` that observes it.
+#   issue           tracking issue number on adcontextprotocol/adcp.
+#   change          removal | new_requirement
+#   applies_to      the agent roles the check speaks to.
+#   detection       one line: what the check looks for.
+#   fix             what the agent changes before 4.0.
+#   observed_by     exactly one of validation, notice, or none (see above).
+#   schema_sites    optional: the schema nodes marked `x-removed-in: "4.0.0"`
+#                   whose removal this check covers, as
+#                   `<path under static/schemas/source>#<JSON Pointer>`.
+#
+# Schema removals
+# ---------------
+# Every schema node marked `x-removed-in: "4.0.0"` appears exactly once: in a
+# check's `schema_sites`, or in `schema_removals_not_checked` with its 4.0
+# tracking issue and the reason no check covers it yet (most often a
+# buyer-sent request field, which a seller run cannot observe). Marking a node
+# for 4.0 removal therefore forces a decision here and a tracking issue. `tests/schema-deprecation-metadata.test.cjs` requires the
+# marker on every deprecated node whose description says it is removed in 4.0.
+#
+# Each id has an anchor of the same name on the migration guide
+# (`migration_guide` below). `scripts/lint-v4-compatibility-registry.cjs`
+# checks the ids, the observing validations and notices, and the anchors.
+
+id: v4_compatibility
+version: "1.0.0"
+title: "AdCP 4.0 compatibility checks"
+target_version: "4.0"
+migration_guide: "docs/reference/migration/v4-compatibility.mdx"
+
+checks:
+  - id: format_ids_removed_in_4_0
+    issue: 7629
+    change: removal
+    applies_to: [sellers]
+    detection: "A product returned by get_products declares format_ids without format_options."
+    fix: >-
+      Author canonical format_options[] on every product. format_ids may stay
+      as a projection for older 3.x buyers until 4.0, but 4.0 buyers read
+      format_options only.
+    observed_by:
+      validation:
+        storyboard: media_buy_seller
+        steps: [get_products_brief, get_products_brief_buyer_selected_timezone]
+    schema_sites:
+      - "core/product.json#/properties/format_ids"
+
+  - id: major_versions_removed_in_4_0
+    issue: 3572
+    change: removal
+    applies_to: [all_agents]
+    detection: "get_adcp_capabilities declares adcp.major_versions without adcp.supported_versions."
+    fix: >-
+      Advertise every release you speak in adcp.supported_versions
+      (release-precision strings such as "3.2"). Keep adcp.major_versions
+      through 3.x; 4.0 removes it.
+    observed_by:
+      validation:
+        storyboard: version_negotiation
+        steps: [get_capabilities_with_version]
+    schema_sites:
+      - "protocol/get-adcp-capabilities-response.json#/properties/adcp/properties/major_versions"
+
+  - id: adcp_version_echo_required_in_4_0
+    issue: 3572
+    change: new_requirement
+    applies_to: [all_agents]
+    detection: "The response envelope does not echo the served release in adcp_version."
+    fix: >-
+      Echo the release you served in adcp_version on every response envelope.
+      4.0 makes the echo a MUST and removes the adcp_major_version fallback.
+    observed_by:
+      validation:
+        storyboard: version_negotiation
+        steps: [get_capabilities_with_version]
+
+  - id: signed_requests_specialism_deprecated
+    issue: 3078
+    change: removal
+    applies_to: [all_agents]
+    detection: "get_adcp_capabilities lists the signed-requests specialism."
+    fix: >-
+      Drop signed-requests from specialisms and advertise
+      request_signing.supported: true instead. 4.0 removes the enum value.
+    observed_by:
+      notice:
+        storyboards: [signed_requests]
+
+  - id: request_signing_required_in_4_0
+    issue: 2307
+    change: new_requirement
+    applies_to: [sellers]
+    detection: "get_adcp_capabilities does not advertise request_signing.supported: true."
+    fix: >-
+      Verify RFC 9421 request signatures and advertise
+      request_signing.supported: true. 4.0 requires signing on
+      spend-committing operations.
+    observed_by:
+      validation:
+        storyboard: media_buy_seller
+        steps: [get_capabilities]
+
+  - id: legacy_hmac_fallback_removed_in_4_0
+    issue: 4205
+    change: removal
+    applies_to: [all_agents]
+    detection: "get_adcp_capabilities advertises webhook_signing.legacy_hmac_fallback: true."
+    fix: >-
+      Sign webhooks with RFC 9421 only and stop advertising
+      legacy_hmac_fallback. 4.0 removes the HMAC fallback.
+    observed_by:
+      validation:
+        storyboard: capability_discovery
+        steps: [get_capabilities]
+    schema_sites:
+      - "protocol/get-adcp-capabilities-response.json#/properties/webhook_signing/properties/legacy_hmac_fallback"
+
+# Schema nodes marked for 4.0 removal that no check covers yet. `change` names
+# the removal, `issue` is its 4.0 tracking issue (required), and `reason` says
+# why a 3.x agent is not graded on it.
+schema_removals_not_checked:
+  - change: "Exact plural format_ids in requests"
+    issue: 7629
+    reason: >-
+      Buyer-sent fields. Sellers keep accepting them through 3.x, and a seller
+      run cannot observe whether a buyer still sends them.
+    sites:
+      - "brand/acquire-rights-request.json#/properties/campaign/properties/format_ids"
+      - "core/creative-filters.json#/properties/format_ids"
+      - "core/product-filters.json#/properties/format_ids"
+      - "creative/list-creative-formats-request.json#/properties/format_ids"
+      - "media-buy/list-creative-formats-request.json#/properties/format_ids"
+      - "media-buy/package-request.json#/properties/format_ids"
+
+  - change: "Exact plural format_ids projections outside the product"
+    issue: 7629
+    reason: >-
+      Seller-emitted projections of the product's canonical declaration.
+      format_ids_removed_in_4_0 grades the authoring change on the product;
+      these projections are not graded separately yet.
+    sites:
+      - "core/package.json#/properties/format_ids"
+      - "core/placement.json#/properties/format_ids"
+      - "core/registry-event.json#/$defs/agentProfilePayload/properties/format_ids"
+      - "media-buy/acceptance-policy-requirement.json#/oneOf/13/properties/format_ids"
+      - "media-buy/get-media-buys-response.json#/properties/media_buys/items/properties/packages/items/properties/format_ids"
+      - "trusted-match/available-package.json#/properties/format_ids"
+
+  - change: "Format-level build and pricing surface, replaced by list_transformers and v1_format_ref"
+    issue: 8377
+    reason: >-
+      Creative-agent surface deprecated in 3.1. The response fields are
+      observable on list_creative_formats but not graded yet; the request
+      fields are buyer-sent.
+    sites:
+      - "core/format.json#/properties/input_format_ids"
+      - "core/format.json#/properties/output_format_ids"
+      - "core/format.json#/properties/pricing_options"
+      - "core/format.json#/properties/canonical_parameters"
+      - "creative/list-creative-formats-request.json#/properties/include_pricing"
+      - "creative/list-creative-formats-request.json#/properties/account"
+      - "media-buy/list-creative-formats-request.json#/properties/account"
+
+  - change: "Legacy Bearer and HMAC webhook authentication"
+    issue: 4205
+    reason: >-
+      Buyer-sent webhook registration. The seller-side dependency is graded by
+      legacy_hmac_fallback_removed_in_4_0.
+    sites:
+      - "core/agent-notification-config.json#/properties/authentication"
+      - "core/notification-config.json#/properties/authentication"
+      - "core/push-notification-config.json#/properties/authentication"
+      - "core/reporting-webhook.json#/properties/authentication"
+      - "enums/auth-scheme.json#"
+      - "media-buy/create-media-buy-request.json#/properties/artifact_webhook/properties/authentication"
+
+  - change: "Major-precision version fields outside capabilities"
+    issue: 3572
+    reason: >-
+      Request envelopes are buyer-sent. supported_majors appears only on a
+      VERSION_UNSUPPORTED error, which the suite does not provoke yet.
+      Trusted Match requests are outside seller runs.
+    sites:
+      - "core/version-envelope.json#/properties/adcp_major_version"
+      - "error-details/version-unsupported.json#/properties/supported_majors"
+      - "trusted-match/context-match-request.json#/properties/adcp_major_version"
+      - "trusted-match/identity-match-request.json#/properties/adcp_major_version"
+
+  - change: "Flat valid_actions vocabulary, replaced by available_actions"
+    issue: 8378
+    reason: >-
+      Seller-emitted and observable on create, update, and get_media_buys
+      responses, but not graded yet.
+    sites:
+      - "media-buy/create-media-buy-response.json#/oneOf/0/properties/valid_actions"
+      - "media-buy/get-media-buys-response.json#/properties/media_buys/items/properties/valid_actions"
+      - "media-buy/update-media-buy-response.json#/oneOf/0/properties/valid_actions"
+
+  - change: "Response-wide delivery currency and aggregated_totals"
+    issue: 8379
+    reason: >-
+      Seller-emitted legacy rollups that 4.0 buyers stop reading. Observable on
+      get_media_buy_delivery but not graded yet.
+    sites:
+      - "media-buy/get-media-buy-delivery-response.json#/properties/currency"
+      - "media-buy/get-media-buy-delivery-response.json#/properties/aggregated_totals"
+      - "media-buy/media-buy-delivery-webhook-result.json#/properties/currency"
+
+  - change: "Inline creatives in create_media_buy and update_media_buy"
+    issue: 8380
+    reason: >-
+      Seller capability declaration (media_buy.features.inline_creative_management).
+      Observable on get_adcp_capabilities but not graded yet.
+    sites:
+      - "core/media-buy-features.json#/properties/inline_creative_management"
+
+  - change: "plan_id on create_media_buy"
+    issue: 8381
+    reason: "Buyer-sent field, replaced by governance_context on the envelope."
+    sites:
+      - "media-buy/create-media-buy-request.json#/properties/plan_id"
+
+  - change: "get_signals top-level max_results"
+    issue: 8382
+    reason: "Buyer-sent field, replaced by pagination.max_results."
+    sites:
+      - "signals/get-signals-request.json#/properties/max_results"
+
+  - change: "get_creative_delivery pagination.total"
+    issue: 8383
+    reason: >-
+      3.x already requires total_count alongside it, so dropping the alias
+      needs no agent change.
+    sites:
+      - "creative/get-creative-delivery-response.json#/properties/pagination/properties/total"
+
+  - change: "property_list_changed signature marker"
+    issue: 8384
+    reason: >-
+      3.x requires the literal rfc9421 marker and receivers already ignore it,
+      so dropping the field needs no agent change.
+    sites:
+      - "property/property-list-changed-webhook.json#/properties/signature"
+
+  - change: "Single-token tmpx on identity_match responses"
+    issue: 8385
+    reason: "Trusted Match router output, outside seller runs. Replaced by tmpx_providers."
+    sites:
+      - "trusted-match/identity-match-response.json#/properties/tmpx"
+
+  - change: "3.1 compatibility projections for older buyers"
+    issue: 8386
+    reason: >-
+      Projections a 3.2 seller emits only for 3.1 peers (a native 3.2 seller
+      must not emit purchase_continuation). Not graded.
+    sites:
+      - "core/media-buy-legacy-terms-ref.json#"
+      - "media-buy/request-proposals-response.json#/properties/purchase_continuation"

package/compliance/cache/{3.2.5 → 3.2.7}/universal/version-negotiation.yaml

@@ -32,6 +32,11 @@ narrative: |
   surfaces were advisory in the released 3.1 compliance bundles and are blocking
   in this 3.2 source bundle. Released bundles remain immutable.
 
+  Both checks also carry AdCP 4.0 compatibility ids
+  (`major_versions_removed_in_4_0`, `adcp_version_echo_required_in_4_0`; see
+  `universal/v4-compatibility.yaml`). 4.0 removes the major-precision fields,
+  so these release-precision surfaces become the only version declaration.
+
   Scope: protocol envelope and capabilities advertisement only. The
   `VERSION_UNSUPPORTED` error path (buyer pins a release outside the seller's
   `supported_versions`) is exercised separately by error_compliance — running it
@@ -106,11 +111,13 @@ phases:
             path: "adcp.major_versions"
             description: "Legacy major-precision advertisement present (required through 3.x)"
 
-          - check: field_present
+          - id: major_versions_removed_in_4_0
+            check: field_present
             path: "adcp.supported_versions"
             description: "Seller advertises release-precision supported_versions (required for 3.2 certification)"
 
-          - check: envelope_field_present
+          - id: adcp_version_echo_required_in_4_0
+            check: envelope_field_present
             path: "adcp_version"
             description: "Seller echoes adcp_version on the response envelope (required for 3.2 certification)"
 

package/compliance/cache/{3.2.5 → 3.2.7}/universal/webhook-emission.yaml

@@ -215,6 +215,7 @@ phases:
             operator: "pinnacle-agency.example"
             operator_unit:
               id: "compliance-webhook_emission-904960ed"
+            sandbox: true
         context_outputs:
           - path: "task_completion.products"
             key: "products"
@@ -269,6 +270,7 @@ phases:
             operator: "pinnacle-agency.example"
             operator_unit:
               id: "compliance-webhook_emission-904960ed"
+            sandbox: true
           # The runner rolls elapsed sample dates to a fresh seven-day flight.
           start_time: "2025-01-01T00:00:00Z"
           end_time: "2025-01-08T00:00:00Z"
@@ -349,6 +351,7 @@ phases:
             operator: "pinnacle-agency.example"
             operator_unit:
               id: "compliance-webhook_emission-904960ed"
+            sandbox: true
           # The runner rolls elapsed sample dates to a fresh seven-day flight.
           start_time: "2025-01-01T00:00:00Z"
           end_time: "2025-01-08T00:00:00Z"
@@ -432,6 +435,7 @@ phases:
             operator: "pinnacle-agency.example"
             operator_unit:
               id: "compliance-webhook_emission-904960ed"
+            sandbox: true
           # The runner rolls elapsed sample dates to a fresh seven-day flight.
           start_time: "2025-01-01T00:00:00Z"
           end_time: "2025-01-08T00:00:00Z"
@@ -472,6 +476,7 @@ phases:
             operator: "pinnacle-agency.example"
             operator_unit:
               id: "compliance-webhook_emission-904960ed"
+            sandbox: true
           # The runner rolls elapsed sample dates to a fresh seven-day flight.
           start_time: "2025-01-01T00:00:00Z"
           end_time: "2025-01-08T00:00:00Z"
@@ -726,6 +731,7 @@ phases:
             operator: "pinnacle-agency.example"
             operator_unit:
               id: "compliance-webhook_emission-904960ed"
+            sandbox: true
           # The runner rolls elapsed sample dates to a fresh seven-day flight.
           start_time: "2025-01-01T00:00:00Z"
           end_time: "2025-01-08T00:00:00Z"
@@ -875,6 +881,7 @@ phases:
             operator: "pinnacle-agency.example"
             operator_unit:
               id: "compliance-webhook_emission-904960ed"
+            sandbox: true
           # The runner rolls elapsed sample dates to a fresh seven-day flight.
           start_time: "2025-01-01T00:00:00Z"
           end_time: "2025-01-08T00:00:00Z"

package/dist/lib/adapters/version/3.0/brand-fields.d.mts

@@ -1,3 +1,9 @@
-import type { VersionAdapter } from '../types.mjs';
+import type { VersionAdapter, VersionDrift } from '../types.mjs';
 export declare const createMediaBuyAdapter: VersionAdapter;
 export declare const getProductsAdapter: VersionAdapter;
+export declare const updateMediaBuyAdapter: VersionAdapter;
+/** Convert only creative asset positions, never opaque ext/provenance objects. */
+export declare function downgradeCreativeTrackers(params: unknown): {
+    params: unknown;
+    drift?: VersionDrift;
+};

package/dist/lib/adapters/version/3.0/brand-fields.d.ts

@@ -1,3 +1,9 @@
-import type { VersionAdapter } from '../types';
+import type { VersionAdapter, VersionDrift } from '../types';
 export declare const createMediaBuyAdapter: VersionAdapter;
 export declare const getProductsAdapter: VersionAdapter;
+export declare const updateMediaBuyAdapter: VersionAdapter;
+/** Convert only creative asset positions, never opaque ext/provenance objects. */
+export declare function downgradeCreativeTrackers(params: unknown): {
+    params: unknown;
+    drift?: VersionDrift;
+};