Skip to content

reporting: serve only report definitions at contract_version 1.0 or 1.1 to callers pinned below 3.3 #1906

Open

Description

@bokelley

Problem

AdCP 3.3.0-beta.6 adds report-definition contract_version 1.2 (adcontextprotocol/adcp#8971, PR #8983). Receivers built from 3.2 have a contract_version enum closed at ["1.0", "1.1"]. So the spec requires that a caller pinned below 3.3 is served only offerings whose definitions are 1.0 or 1.1.

SDK-hosted reporting doesn't apply that rule. ReportingService.capability_block(adcp_version=...) projects every installed offering, whatever the caller's version. Nothing refuses a configuration that selects a 1.2-definition offering for a 3.2 caller. A seller on the managed service that publishes a 1.2 definition would hand 3.2 buyers a definition they can't parse.

The offering pins its definition only by report_definition_uri + report_definition_sha256. The version lives inside the definition document, so the SDK needs the definition (or its version) to apply the rule.

Spec reference (3.3.0-beta.6)

  • core/reporting-report-definition.json contract_version: enum 1.0, 1.1, 1.2. At 1.2, a definition with media_buy_id in dimensions must also list package_id.
  • spec(reporting): report definitions at contract_version 1.2 require a package_id dimension (#8971) adcp#8983, "How a seller and a buyer get 1.2": "callers pinned below 3.3 accept only 1.0 and 1.1, so a seller MUST serve them offerings whose definitions are 1.0 or 1.1, and a 1.2 offering is …". It's the same version-pin rule the surface already uses for configuration_task.
  • Docs: get_reporting_status and sync_principal, in the report-definition and configuration sections.

Fix sketch

  1. Record the version. When an offering is registered with the managed or production service, record its report definition's contract_version. The production path already verifies the definition bytes against the pinned sha256 (ReportingMaterializationVerifier.definition_bytes). An offering registered without its definition should declare the version explicitly, or default to "unknown", which is withheld from below-3.3 callers.
  2. Capabilities. In capability_block / inject_capabilities, withhold offerings whose definition is newer than 1.1 when adcp_version is below 3.3.
  3. Configuration. Refuse a below-3.3 caller's configuration (sync_accounts reporting_delivery_configs, sync_principal reporting subscriptions) that names a 1.2 offering. Use the same error as an unknown or unavailable offering.
  4. Tests. A 3.2 caller's capabilities omit the 1.2 offering, and a 3.3-beta.6 caller sees it. A 3.2 configuration naming it is refused.

Code locations (next at 807141962)

  • src/adcp/reporting/service.py:
    • ReportingService.capability_block(adcp_version=...) (1888) and _capability_block (1907), which projects offerings from each source's capability_offerings;
    • inject_capabilities(..., adcp_version=...) (1963);
    • source registration with capability_offerings (314–392).
  • src/adcp/reporting/production/offerings.py: ReportingProductionOffering (39), which checks report_definition_uri / report_definition_sha256 (85), and check_configuration (311).
  • src/adcp/reporting/materializer/verification.py: the verifier that already holds definition_bytes.
  • src/adcp/reporting_inspection.py: since feat(protocol)!: adopt the signed AdCP 3.3.0-beta.6 bundle #1901 the buyer-side manifest inspector validates definitions against the pinned schema, which includes the 1.2 rule.

Activity

  1. added
    enhancementNew feature or request
    no-triageSkip the Claude triage bot — human or designated agent will handle this issue
    sdk-10SDK 10 (next branch, AdCP 3.3)
    on Nov 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestno-triageSkip the Claude triage bot — human or designated agent will handle this issuesdk-10SDK 10 (next branch, AdCP 3.3)

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions