Skip to content

SDK 10: implement AdCP 3.3 reporting subscriptions in the reliable-reporting runtime #1695

Open

Description

@bokelley

Python parity for adcontextprotocol/adcp-client#3504, on next (SDK 10 / AdCP 3.3).

Why

SDK 10 on AdCP 3.3.0-beta.1 ships the generated types for principal-level reporting subscriptions (RFC adcontextprotocol/adcp#8543 Part B, adcontextprotocol/adcp#8552), but no runtime. A seller built on the SDK can't list sync_principal in configuration_tasks, and a buyer has no helper to calculate the periods it's owed. Obligations, the ledger and receipts already live in the SDK, so the subscription runtime belongs here too. A host supplies only what it alone knows: which accounts a principal may read, and which buys an account holds.

Scope

The requirements are those of adcontextprotocol/adcp-client#3504, mapped to the Python runtime:

  1. Principal runtime. Opt-in acceptance, validation, readback (core/reporting-subscription-state.json) and versioning of sync_principal reporting_subscriptions, plus principal.changed with reason reporting_subscription_changed. With the option off, keep today's behaviour.
  2. Obligations. Host hooks for authorized accounts, authorization changes and buy facts. Selector resolution (exact / finest / all, ties to the lowest offering_id), precedence (a caller's own sync_accounts config beats any subscription; account_ids beats all-accounts), cutovers at period boundaries, account timezones, no clipping, and deterministic max_accounts.
  3. Status and lost authority. subscription_coverage[] with exceptions only, each over [from, until); accounts_unauthorized[]; receipts accepted after loss for status_retention_days; re-grant, with and without backfill_on_regrant.
  4. Managed delivery. Destinations from reporting_destinations, path-template expansion, account_id on every row, and per-account destinations.
  5. Capabilities. configuration_tasks, configuration_task only when sync_accounts is listed, the subscriptions block, and media_buy.reporting_subscriptions.
  6. Storage. adcp-reporting-storage PostgreSQL migrations for subscription versions, resolutions, exceptions and authority intervals; history retained as long as the obligations that cite it.
  7. Buyer. A pure expected_subscription_periods(...) coverage function over plain data, and consumer-runtime and client support.
  8. Conformance. Buyer-computed periods must equal seller-owed periods, period by period, across the cases listed in adcp-client#3504.

The spec is normative where it differs from the issue text. In particular, coverage starts at the first boundary at or after the latest of the version's accepted_at, the buy's confirmed_at and the account's authorization.authorized_at (see .changeset/pre/reporting-subscriptions.md in the spec repo).

10.0.0-beta.2 waits for this and for #1692.

Activity

  1. 113 remaining items

  2. bokelley commented on Oct 30, 2026

    @bokelley
    ContributorAuthor

    Status on next:

    Merged:

    Open: #1726, the PostgreSQL conformance test (restart, CAS, concurrency).

    Still remaining (TypeScript defers the same items in adcp-client#3509):

    1. Ledger materialization of owed subscription obligations. The producer must plan subscription generations keyed by (account, subscription_id, version, offering_id) from the owed periods rather than contiguous ordinals. That is a ledger-schema change and needs its own PR.
    2. Managed delivery wiring, which depends on 1: resolve the subscription's destination, expand path_template, put account_id on every delivered row, and re-check authority per delivery.
    3. Receipts after loss of authority in the sync_reporting_receipts / sync_reporting_status handlers, which depends on 1.
    4. A reference-seller conformance storyboard, once obligations are materialized.

    Until 1 lands, don't advertise media_buy.reporting_subscriptions (the engine docs say so).

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

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions