You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 6bee0ca
Browse filesBrowse the repository at this point in the historyBrowse files
feat(reporting): apply the AdCP 3.3.0-beta.3 seller rules for subscriptions
The seller engine follows the rest of adcp#8619 and #8620:
- Admission under max_accounts orders candidates by authorized_at, then
account_id in byte order, and keeps it sticky. A candidate with another
open account-level exception still holds its place.
- Several pacing or analytics subscriptions may apply to one account and
purpose. Where two resolve the same offering for a package, the lowest
subscription_id owes it and each other records a package-level overridden
exception naming the package_ids. Coverage, on both sides, removes those
packages while the entry is open. Billing stays one per account at a scope
level.
- Membership edits apply in place. Adding or removing account_ids and
changing exclude_account_ids keep subscription_version and accepted_at.
A removed account opens an excluded_by_buyer entry from the cutover and
stays listed as excluded. An added account gets one closed entry for the
time before it joined. The buyer's coverage reads the intervals rather
than the current membership.
- destination_overrides route an account to another destination. Coverage
resolves against that destination's method, the engine routes its
per-account resolution, and owed sets carry the override as the version's
destination for the managed binding. Registration checks that every
override names an existing destination, and that one routing several
accounts uses account_id in its path_template.
- The readback lists 16 prior versions and 1,000 accounts inline, with their
totals. get_principal reporting_subscription_page pages the rest from the
engine's state document, which now keeps the full lists.
- AccountReady carries resolution, the matched or created account's money
terms, effective_at for an updated money change, and not_carried_over.
The buyer facade no longer bumps subscription_version for a membership
edit.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Copy file name to clipboardExpand all lines: MIGRATION_v9_to_v10.md
+1Lines changed: 1 addition & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,6 +16,7 @@ the SDK-relevant inventory is [docs/adcp-3.3-sdk-inventory.md](docs/adcp-3.3-sdk
16
16
| AdCP 3.3.0-beta.3 composes the protocol envelope on every task response | adcontextprotocol/adcp#8547: every response root composes `core/protocol-envelope.json`, which composes `core/version-envelope.json`, so generated responses inherit `ProtocolEnvelope` alone (no separate `AdcpVersionEnvelope` base) and the local copies of envelope fields are gone. Submitted, working and input-required bodies compose `core/task-submitted.json` / `task-working.json` / `task-input-required.json`: a submitted arm still pins `status` to `submitted` and requires `task_id`. `task_id` (non-empty) and the task-level `message` (at most 2,000 characters) each have one definition (`core/task-id.json`, `core/task-message.json`); fields that refer to them stay typed `str` with those constraints, so no caller has to wrap a value. `TaskId`, `TaskMessage`, `TaskSubmitted`, `TaskWorking` and `TaskInputRequired` are generated. Consequences for handlers: `list_products` and `decline_proposals` now carry `status` (the server stamps `completed`; the 3.3 → 3.2 conversion still drops it for 3.2 callers); an absent `replayed` reads as `false` and `replayed: false` is valid; and on governance responses `status` is the task status, so a `check_governance` result names its decision in `verdict` and `report_plan_outcome` in `outcome_state`, never in `status`. |
17
17
| AdCP 3.3.0-beta.3 adds live creative updates, account-request money terms and reporting-subscription fields | Experimental `creative.live_updates` (`LiveUpdatePolicy`, `CreativeStagedUpdate`, `creative.staged_update_changed` and `CreativeStagedUpdateChangedWebhook`, error code `CREATIVE_LIVE_UPDATE_UNSUPPORTED` with `CreativeLiveUpdateUnsupportedDetails`). `request_account` outcomes carry `account` money terms on `matched` / `created`, `effective_at` on an `updated` money change, and `not_carried_over`. Reporting subscriptions gain `destination_overrides[]`, the paged readback (`prior_versions_count`, `accounts_with_exceptions_count`, `accounts_unauthorized_count`, `get_principal` `reporting_subscription_page`), `authorization.regranted_at`, `flight_history[]` and `cancellation_effective_at` on media buys, `available_from` / `withdrawn_at` on offerings and `stub` on billing obligations. `comply_test_controller` adds the `reporting_subscription_probe` scenario: override `TestControllerStore.reporting_subscription_probe` to serve it. Generated renames: `PriorVersion` is `ReportingSubscriptionPriorVersion`, `AccountsWithException` is `ReportingSubscriptionAccountExceptions`, and `AccountsUnauthorizedItem` is `ReportingSubscriptionUnauthorizedAccount`. |
18
18
| The reporting-subscription surface is served from 3.3.0-beta.3 on, unprojected | The beta.1 / beta.2 field projections are gone, with the preview module that patched the fields onto the models: `project_offering`, `project_reporting_delivery`, `project_subscription_state`, `project_subscription_coverage` and `serves_settled_subscription_fields` are removed from `adcp.reporting.subscriptions`, and `ReportingSubscriptionEngine.subscription_coverage()` no longer takes `adcp_version`. One predicate, `adcp.reporting.subscriptions.serves_subscriptions(adcp_version)` (from `SUBSCRIPTIONS_MIN_ADCP_VERSION`, `3.3.0-beta.3`), gates the whole surface: capabilities, `get_reporting_status` coverage (including `status: "inactive"` with `deactivated_at`) and the principal readback. A caller served an earlier release gets none of it. The extensible `reporting-dimension` vocabulary accepts unknown values on selectors, offerings and the capability block. |
19
+
| Reporting-subscription registration follows the 3.3.0-beta.3 rules | A caller may hold several pacing or analytics subscriptions per account and purpose (the lowest `subscription_id` owes a shared offering; the others record a package-level `overridden` exception), while billing stays one per account at a scope level and must use `match: exact` with `dimensions`. Membership edits (`scope.account_ids`, `exclude_account_ids`) no longer need a new `subscription_version`, and `client.reporting.subscribe` no longer bumps the version for them. `destination_overrides` must name existing destinations. The readback lists 16 prior versions and 1,000 accounts inline with `*_count` totals; page the rest with `get_principal``reporting_subscription_page`. A partial grant refuses an unlisted reporting task with `SCOPE_INSUFFICIENT`. `AccountReady` gains `resolution`, `billing`, `billing_entity`, `payment_terms`, `effective_at` and `not_carried_over`. |
19
20
| A server that restricts `supported_versions` runs on its newest listed release | Any server (`create_mcp_server`, `create_a2a_server`, `serve`, `MCPToolSet`, `ADCPAgentExecutor`, `create_tool_caller`, `PlatformHandler`, `create_adcp_server_from_platform`) with `supported_versions=["3.2"]` and no `adcp_version` runs its handlers on 3.2, instead of raising because the SDK default is outside the list. Pass `adcp_version` explicitly to choose another listed release. |
20
21
|`server_version` pins keep wire precision |`ADCPClient(server_version=...)` and `get_server_version()` keep a 3.x pin at release precision: `"3.1.0-beta.1"` reads back as `"3.1-beta.1"` (SDK 9 reported the bundle key, `"3.1.0-beta.1"`). Stable pins still collapse (`"3.0.7"` → `"3.0"`). |
21
22
| A server pin governs its handlers | Handlers run on one *application version*: the server's `adcp_version` pin, else the newest release in its `supported_versions`, else the packaged `3.3-beta.3`. Every dispatch path (MCP, A2A, `create_tool_caller`, the Decisioning dispatcher) converts a buyer's request to that release before validation, unknown-field policy and typed parsing, and converts the handler's response back to the buyer's release: up to `3.3-beta.2`, unchanged for a same-release buyer, or down to 3.1 / 3.0. `resolve_requested_adcp_version(params)` inside a handler returns the application version; `ToolContext.application_adcp_version` reports it directly, and `ToolContext.resolved_adcp_version` still reports the buyer's negotiated version. A 3.2-pinned seller's dict handlers therefore see exactly 3.2 payloads, its requests and responses are validated against the 3.2 schemas (with strict validation, a response its own 3.2 contract refuses fails before conversion), and a conversion the target schema refuses fails as `ADCPVersionConversionError` / `VERSION_UNSUPPORTED` instead of reaching the peer invalid. Typed handler parameters (`params: GetProductsRequest`) and typed responses still use the generated 3.3 classes: they are additive supersets of 3.2, so a 3.2 payload parses into them unchanged and dumps back as the same 3.2 payload, but a field 3.3 added reads as unset (its model default) on a 3.2 server. The unpinned default is unchanged: handlers receive `3.3-beta.2`. |
Copy file name to clipboardExpand all lines: docs/adcp-3.3-sdk-inventory.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -281,8 +281,8 @@ in it.
281
281
| Wire pin |`3.3.0-beta.3` / `3.3-beta.3`. `3.3-beta.2` is no longer advertised or accepted as a pin (as with `3.3-beta.0`, `3.3-beta.1` and the 3.2 candidates); its cache and compliance trees stay in the source tree and leave the wheel. | done |
282
282
| Protocol envelope composition (adcontextprotocol/adcp#8547) | Every task response and async status payload composes `core/protocol-envelope.json`, which composes `core/version-envelope.json`; submitted, working and input-required bodies compose `core/task-submitted.json` / `task-working.json` / `task-input-required.json`; `task_id` and the task-level `message` have one definition each (`core/task-id.json`, `core/task-message.json`). | generated (the #1741 codegen layout). The response-arm emitter folds the composed task-state schema into each arm, so submitted arms keep `status: submitted` and a required `task_id`; `get_task_status`'s required `task_id` / `status` take the envelope's declarations instead of `Any`; `task_id` / `message` references generate as constrained `str`|
283
283
| Live creative updates | Experimental `creative.live_updates`, `staged_update` on `list_creatives` / `sync_creatives`, the `creative.staged_update_changed` notification, `CREATIVE_LIVE_UPDATE_UNSUPPORTED`. | generated; no handler wiring (no new task) |
284
-
| Account requests | Money terms on `matched` / `created`, `effective_at` on `updated` money changes, `not_carried_over` on a separate account, consistent `currency` / `timezone` changeability. | generated; the `accounts.ensure` outcome mapping follows in the account slice|
285
-
| Reporting subscriptions (adcontextprotocol/adcp#8613, #8617, #8618, #8619, #8622) |`status: "inactive"` with `deactivated_at` on coverage; billing `stub` obligations and `cancellation_effective_at`; `flight_history[]`, `authorization.regranted_at`, `packages[].reporting_delivery_offering_ids`, offering `available_from` / `withdrawn_at`; sticky admission and per-package resolution, `destination_overrides[]`, the paged readback (`*_count`, `reporting_subscription_page`), in-place membership edits, several pacing / analytics feeds per purpose, `SCOPE_INSUFFICIENT` for partial grants, `account_id` in `primary_keys`; the day-start rule and the other period-arithmetic rulings. | generated. `_reporting_subscription_preview` and the beta.1 / beta.2 projections are removed; `serves_subscriptions` is the one version predicate. Engine conformance to the beta.3 rules and the re-pinned coverage vectors follow in the next slice|
284
+
| Account requests | Money terms on `matched` / `created`, `effective_at` on `updated` money changes, `not_carried_over` on a separate account, consistent `currency` / `timezone` changeability. | generated; `AccountReady` carries `resolution`, the money terms (`billing`, `billing_entity`, `payment_terms`), `effective_at` and `not_carried_over`|
285
+
| Reporting subscriptions (adcontextprotocol/adcp#8613, #8617, #8618, #8619, #8622) |`status: "inactive"` with `deactivated_at` on coverage; billing `stub` obligations and `cancellation_effective_at`; `flight_history[]`, `authorization.regranted_at`, `packages[].reporting_delivery_offering_ids`, offering `available_from` / `withdrawn_at`; sticky admission and per-package resolution, `destination_overrides[]`, the paged readback (`*_count`, `reporting_subscription_page`), in-place membership edits, several pacing / analytics feeds per purpose, `SCOPE_INSUFFICIENT` for partial grants, `account_id` in `primary_keys`; the day-start rule and the other period-arithmetic rulings. | generated. `_reporting_subscription_preview` and the beta.1 / beta.2 projections are removed; `serves_subscriptions` is the one version predicate. The coverage rule and the seller engine follow every listed rule, and the parity test runs the spec's 120 beta.3 vectors|
286
286
| Extensible `reporting-dimension`| The schema marks the vocabulary `x-extensible`; the generator closes it. |`adcp.types._forward_compat` reopens the five fields that carry it to the vocabulary's `x-pattern`|
287
287
|`comply_test_controller``reporting_subscription_probe`|`revoke_grant`, `regrant`, `reduce_grant` (`allowed_tasks`), `set_account_timezone` (`timezone`), `advance_time` (`target_time`). |`TestControllerStore.reporting_subscription_probe` hook with parameter validation; not implemented by default |
288
288
| Generated renames |`PriorVersion` → `ReportingSubscriptionPriorVersion`, `AccountsWithException` → `ReportingSubscriptionAccountExceptions`, `AccountsUnauthorizedItem` → `ReportingSubscriptionUnauthorizedAccount`; numbered names renumber (`Status20` → `Status54`, ...). `adcp.types._generated.AllowedTask` now resolves to the controller's `allowed_tasks` item (both are task-name tokens); `adcp.types.domains.core.AllowedTask` is unchanged. | generated |
Copy file name to clipboardExpand all lines: docs/reporting-subscriptions-buyer.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -21,7 +21,7 @@ result = await client.reporting.subscribe(
21
21
result.action, result.subscription_version
22
22
```
23
23
24
-
-**Versioning.** The version is bumped only when the selector, scope, destination, `reconciliation_mode`, `exclude_account_ids` or `operator_domains` change.
24
+
-**Versioning.** The version is bumped only when the selector, the scope kind, the destination or its `destination_overrides`, `reconciliation_mode` or `operator_domains` change. Adding or removing `account_ids`, and changing `exclude_account_ids`, apply in place (3.3.0-beta.3): the seller records each edit per account as an `excluded_by_buyer` interval, so periods that started before a removal stay owed and an added account is owed only from when it joined.
25
25
-**Pre-dispatch checks.** These fail with `dispatched=False`:
Copy file name to clipboardExpand all lines: docs/reporting-subscriptions-seller.md
+10Lines changed: 10 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -31,6 +31,16 @@ The SDK reads these surfaces under each principal's identity. A principal sees e
31
31
32
32
A decisioning `Account` carries `timezone=` and `operator=`. An account without a timezone is refused rather than read as UTC.
33
33
34
+
## AdCP 3.3.0-beta.3 rules the engine applies
35
+
36
+
-**Admission under `max_accounts`.** Candidates are ordered by `authorization.authorized_at`, then `account_id` in byte order, and an admitted account keeps its slot. A waiting candidate carries a `capacity` exception.
37
+
-**Several feeds per purpose.** A caller may hold several pacing or analytics subscriptions for one account. Where two resolve the same offering for a package, the lowest `subscription_id` owes it and the other records an `overridden` exception naming the `package_ids`. Billing stays one per account at a scope level.
38
+
-**Membership in place.** Membership edits (`account_ids`, `exclude_account_ids`) keep the version. A removed account stays listed, `excluded`, with an `excluded_by_buyer` entry from the cutover. An added account gets a closed entry covering the time before it joined.
39
+
-**`destination_overrides`.** An account named by an override, by `account_ids` or `operator_domains`, resolves against the override's destination method. Its owed sets carry the override as the version's `destination`, so `bind_managed_generation` binds and checks the override's `path_template`.
40
+
-**Bounded readback.**`prior_versions` lists the 16 newest inline, and the account lists 1,000, each with a total count. `get_principal``reporting_subscription_page` pages the rest from the engine's state.
41
+
-**Partial grants.** A grant that keeps the account covered refuses a task it does not list with `SCOPE_INSUFFICIENT`.
42
+
-**Billing stubs and `regranted_at`.** A billing cutover owes a stub obligation (`stub: true`), and `list_accounts` serves `authorization.regranted_at`.
43
+
34
44
## What the SDK derives
35
45
36
46
-**The principal runtime.**`install()` serves `get_principal` and `sync_principal` and advertises the principal section. The service's `PrincipalService` is `reporting.principals`.
0 commit comments