feat(media-buy): add compact AdCP 3.2 lifecycle

.agents/sdk-shim-ledger.json

@@ -24,12 +24,13 @@
     "owner": "compliance",
     "upstream": "adcontextprotocol/adcp-client#2105",
     "problem": "The SDK package ships a snapshot of compliance bundles, schema bundles, and generated validators. Current PR storyboard runs need to grade current repo source before a new protocol bundle exists.",
-    "localBehavior": "Build current compliance/schema bundles, copy them into the SDK cache, and patch generated validators for same-PR controller enums and request/response schema additions.",
+    "localBehavior": "Build current compliance/schema bundles, copy them into the SDK cache, and patch generated validators for same-PR controller enums and request/response schema additions. The patch regression suite also loads the installed generated response validator to prove the additive account response remains consumable by the pinned 3.1 SDK.",
     "releaseFollowUp": "This overlay is validation-only and does not publish generated types. After the protocol release, regenerate and publish @adcp/sdk, then explicitly upgrade pinned downstream consumers including agentic-api.",
     "removalCondition": "Remove when the storyboard matrix passes current compliance and schema roots through public SDK options instead of overlaying the SDK cache.",
     "paths": [
       "scripts/overlay-compliance-cache.sh",
-      "scripts/run-storyboards-matrix.sh"
+      "scripts/run-storyboards-matrix.sh",
+      "tests/patch-sdk-rc15.test.cjs"
     ],
     "terms": [
       "node_modules/@adcp/sdk/compliance/cache",

.changeset/secure-get-products-idempotency.md

@@ -5,3 +5,4 @@
 Add the compact AdCP 3.2 product and MediaBuy lifecycle: `list_products`, `request_proposals`, `refine_proposals`, `decline_proposals`, `buy_products`, `accept_proposal`, and `control_media_buy`. The task-specific contracts separate offer discovery, immutable draft proposal creation, explicit finalization with inventory reservation, terminal decline, direct purchase, proposal acceptance, and operational delivery control while retaining `get_products`, `create_media_buy`, and `update_media_buy` as compatibility facades throughout 3.x. New purchase and control inputs never accept inline creatives; commercial amendments and negotiated cancellations fork an accepted proposal, while operational controls remain revision-checked. Compact purchase snapshots preserve resolved package flight, billing-measurement, performance, and reporting terms. A shared opportunity reference connects planning-cycle context through purchase without duplicating proposal version identity. Canonical inputs use stable brand keys, catalog references, and compact account and optimization types so brand assets, legacy named formats, creative provenance, and compliance payloads do not transitively enter the clean tools. Publish machine-readable SDK fallback grades and task-result schema resolution, plus MCP production, media-buy, and creative catalogs that remove presentation annotations without changing validation semantics. The role catalogs select active 3.2 seller-hosted operations and publish client-side input-only prompt views while retaining output and terminal task-result schemas in their parent validation catalogs.
 
 Preserve the AdCP 3.1 inventory-reservation contract in the compact lifecycle: requested and revised proposals remain immutable drafts until `refine_proposals` finalizes them, and a finalized `committed` snapshot guarantees inventory is held until `expires_at`. Add `countries` and `property_list` product-attribute filters, and publish compact task-specific async envelopes for consultative proposal planning and re-underwriting.
+Let compact BrandKeys qualify commercial advertiser identity with canonical `countries[]` without turning identity into delivery targeting. Extend buyer-declared natural accounts with an operator-owned unit (`id` plus mutable display `name`), optional immutable account currency, and sandbox identity. These fields round-trip through `sync_accounts` and `list_accounts`; the operator unit remains explicitly distinct from the seller/storefront `account_id`. Require sellers implementing 3.2 advertiser-account provisioning to advertise fixed versus per-media-buy account currency support while keeping the additive field optional on the shared 3.x response schema for 3.1 compatibility, and define only the BrandKey projection of a compatibility BrandRef as account identity.

docs/accounts/overview.mdx

@@ -18,6 +18,7 @@ Seven questions underlie every AdCP transaction:
 | How does the operator authenticate?      | Seller capabilities | `require_operator_auth` determines who must authenticate and which account reference shape is expected.                                                                                                                                                                                                                                    |
 | What am I allowed to do on this account? | Caller scope        | The `authorization` object on each per-account entry in [`sync_accounts`](/docs/accounts/tasks/sync_accounts) and [`list_accounts`](/docs/accounts/tasks/list_accounts) responses describes `allowed_tasks`, `field_scopes`, `scope_name`, and `read_only` for the calling agent. See [Caller authorization](#caller-authorization) below. |
 | Who gets billed?                         | Account terms       | Buyer passes `billing` in `sync_accounts` — `operator`, `agent`, or `advertiser` — when a choice is needed. A lazy-provisioning seller uses an unambiguous capability or onboarding default.                                                                                                                                                  |
+| Where is currency selected?              | Seller capabilities | `supported_account_currency_modes` declares whether `currency` is fixed on the advertiser account, selected per media buy, or both.                                                                                                                                                                                                         |
 | What was consumed?                       | Usage reporting     | `report_usage` informs vendor agents how their services were used after delivery                                                                                                                                                                                                                                                           |
 
 The seller declares the account model in [`get_adcp_capabilities`](/docs/protocol/get_adcp_capabilities) via `require_operator_auth`. That field declares who must authenticate; it does not by itself declare whether OAuth is used, whether `list_accounts` is exposed, or which `sync_accounts` modes are supported.
@@ -43,7 +44,9 @@ The Accounts Protocol applies across all vendor protocols. An orchestrator estab
 | Governance      | Content standards billing                                |
 | Creative        | Creative service billing                                 |
 
-The account reference may be a seller-assigned `account_id` (seller-owned namespaces, usually `require_operator_auth: true`) or a natural key — `brand` + `operator` (buyer-declared accounts, `require_operator_auth: false`). For buyer-declared accounts, the natural-key `AccountRef` MUST remain valid on subsequent calls even if the seller also echoes an internal `account_id`. For sandbox, account-id namespaces use pre-existing test accounts discovered via `list_accounts` or supplied out-of-band. Buyer-declared accounts use `sandbox: true` in `sync_accounts`, or in the natural-key `AccountRef` when a lazy-provisioning seller declares sandbox support and needs no other buyer-supplied setup. See [Account references](/docs/building/by-layer/L2/accounts-and-agents#account-references) for details.
+The account reference may be a seller/storefront-assigned `account_id` (seller-owned namespaces, usually `require_operator_auth: true`) or a buyer-declared advertiser key — `brand` + `operator` + optional `operator_unit`, `currency`, and `sandbox` (`require_operator_auth: false`). In this vocabulary, **brand identity** is the BrandKey projection (`domain`, optional `brand_id`, canonicalized `countries[]`); **operator identity** is the operator domain plus optional `operator_unit.id`; and **advertiser account identity** is the complete natural key, including currency and sandbox disposition. Mutable `operator_unit.name` and broader BrandRef overrides are not identity. `operator_unit.id` is deliberately separate from the seller's `account_id`. For buyer-declared accounts, the complete natural-key `AccountRef` MUST remain valid on subsequent calls and round-trip through `list_accounts`, even if the seller also echoes an internal `account_id`. See [Account references](/docs/building/by-layer/L2/accounts-and-agents#account-references) for details.
+
+`billing` names the party the seller invoices for this account relationship. It is not a payment rail or settlement selector. AdCP does not currently standardize per-media-buy choice between an intermediary clearing flow and direct settlement; implementations must not encode that distinction by silently changing the meaning of `billing`.
 
 ## Account Status Lifecycle
 
@@ -289,14 +292,14 @@ The Accounts Protocol operates with four party types. See [Accounts and agents](
 
 | Party        | Role                          | Identified by                                             |
 | ------------ | ----------------------------- | --------------------------------------------------------- |
-| Brand        | Whose products are advertised | `brand.domain` + optional `brand.brand_id` via brand.json |
+| Brand        | Whose products are advertised | `brand.domain` + optional `brand.brand_id`/`brand.countries[]` via brand.json |
 | Operator     | Who drives the buys           | Domain (e.g., `pinnacle-media.com`)                       |
 | Agent        | What software places the buys | Authenticated session                                     |
 | Vendor agent | The seller's AdCP agent       | `agent_url`                                               |
 
 ## Tasks
 
-**Account discovery (normative).** Every agent accepting accounts MUST expose at least one of `list_accounts` or `sync_accounts`. A seller-defined account-id namespace MAY omit both only when account IDs are supplied out-of-band and no account settings are managed through AdCP. Buyer-declared-account sellers normally expose `sync_accounts` to establish the relationship and SHOULD also expose `list_accounts` for cold-start recovery. A buyer-declared seller MAY omit `sync_accounts` only when it lazily provisions from the natural key, can resolve every required setting without buyer input, and exposes `list_accounts`; this makes auto-provisioning plus a read-only `list_accounts` conformant for that narrow case. For account-id namespaces, `sync_accounts` is settings-update only in 3.0.x unless a future explicit capability declares account-id provisioning. See [Required tasks by protocol](/docs/protocol/required-tasks#any-agent-accepting-accounts).
+**Account discovery (normative).** Every agent accepting accounts MUST expose at least one of `list_accounts` or `sync_accounts`. A seller-defined account-id namespace MAY omit both only when account IDs are supplied out-of-band and no account settings are managed through AdCP. Buyer-declared-account sellers normally expose `sync_accounts` to establish the relationship and SHOULD also expose `list_accounts` for cold-start recovery: a stateless buyer cannot reconstruct lost advertiser natural keys by replaying `sync_accounts`. `list_accounts` therefore returns the brand, operator, and optional operator unit, currency, and sandbox fields needed to compose the reference again. A buyer-declared seller MAY omit `sync_accounts` only when it lazily provisions from the complete natural key, can resolve every required setting without buyer input, and exposes `list_accounts`. For account-id namespaces, `sync_accounts` is settings-update only in 3.0.x unless a future explicit capability declares account-id provisioning. See [Required tasks by protocol](/docs/protocol/required-tasks#any-agent-accepting-accounts).
 
 | Task                                                                    | Purpose                                                                                                                                                                                                               |
 | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

docs/accounts/provisioning-walkthrough.mdx

@@ -86,6 +86,7 @@ Sam calls `get_adcp_capabilities` before choosing an account workflow. The relev
   "account": {
     "require_operator_auth": false,
     "supported_billing": ["operator", "agent", "advertiser"],
+    "supported_account_currency_modes": ["fixed", "per_media_buy"],
     "notifications": {
       "supported": true,
       "registration_task": "sync_accounts",
@@ -97,7 +98,7 @@ Sam calls `get_adcp_capabilities` before choosing an account workflow. The relev
 }
 ```
 
-`require_operator_auth: false` selects buyer-declared provisioning. `supported_billing` tells Sam which billing values the seller accepts at the capability level; it does not guarantee that every authenticated buyer agent is commercially authorized for every advertised value.
+`require_operator_auth: false` selects buyer-declared provisioning. `supported_billing` tells Sam which invoiced parties the seller accepts at the capability level; it does not guarantee that every authenticated buyer agent is commercially authorized for every advertised value. `supported_account_currency_modes` tells Sam whether to include one immutable account `currency`, omit it for per-media-buy selection, or choose either model.
 
 The `notifications` block selects the preferred observation strategy: register a durable subscriber during provisioning, treat each webhook as an invalidation signal, and repair from `list_accounts`. If the block is absent or `supported` is `false`, poll instead.