Merge branch 'main' into fix/task-polling

Author: bokelley

.github/workflows/ci.yml

@@ -0,0 +1,92 @@
+# Agent resolution and publisher pins in AdCP 3.3
+
+This implementation follows [adcp#7882](https://github.com/adcontextprotocol/adcp/pull/7882)
+at commit `175bcd3b023244aeb97dbdcce8fed674ebd61302`. The protocol change
+is still under review. Historical bundled 3.1/3.2 schemas retain their published
+verifier constraints; these helpers implement the new canonical matching rules.
+
+Agent URLs are the primary selector. Scheme/host case, default ports, dot
+segments, and percent-encoded unreserved characters normalize; trailing slashes
+and tenant paths remain significant. Optional type and id selectors only narrow
+a URL match. Duplicate canonical matches within one collection fail, including
+duplicates with identical ids. House Portfolio operator discovery scans
+`house.agents[]` and all inline `brands[].agents[]`; repeated attestations across
+collections count once when their type and resolved JWKS source agree.
+
+Direct resolver construction and the shared resolver builder now require
+`agent_url`:
+
+```python
+from adcp.signing import BrandJsonJwksResolver
+
+resolver = BrandJsonJwksResolver(
+    "https://operator.example.com/brand.json",
+    agent_url="https://operator.example.com/sales",
+    agent_type="sales",
+)
+```
+
+Direct resolvers use operator-style collection selection, including all sibling
+collections in a House Portfolio unless `brand_id` selects one inline brand.
+For a relying-party record, select the surface's applicable collection explicitly;
+use `resolve_governance_jwks` for governance rather than an unscoped direct resolver.
+For operator discovery, `async_resolve_agent` and `verify_from_agent_url` invoke
+`get_adcp_capabilities` via MCP by default, or A2A with `protocol="a2a"`. They use
+the advertised `identity.brand_json_url`, enforce origin binding, and check every
+declared key origin. Cross-domain origin binding accepts `authorized_operators`
+only on a House Portfolio; its account-level brand/country scopes do not restrict
+key discovery. Discovery does not reuse onboarding mappings, so each call
+reconfirms the advertised operator record.
+
+[Discovery step 7](https://github.com/adcontextprotocol/adcp/blob/175bcd3b023244aeb97dbdcce8fed674ebd61302/docs/building/by-layer/L1/security.mdx#L1331)
+checks every advertised `identity.key_origins` purpose against the selected
+agent's JWKS source, including purposes other than the signature being verified.
+A different host for any purpose rejects discovery with
+`request_signature_key_origin_mismatch`, even when the active purpose matches.
+The SDK follows this explicit all-purpose rule. The draft's separate guidance
+on origin separation remains in tension with that rule pending clarification.
+
+For webhooks, use the asynchronous discovery helper:
+
+```python
+from adcp.webhooks import verify_webhook_from_agent_url
+
+sender = await verify_webhook_from_agent_url(
+    method=request.method,
+    url=str(request.url),
+    headers=request.headers,
+    body=await request.body(),
+    agent_url=media_buy.seller_url,
+    publisher_domains=media_buy.publisher_domains,
+)
+```
+
+The seller URL and applicable publishers must come from your own media-buy
+record. The helper discovers the operator's JWKS, intersects it with every
+applicable publisher's `adagents.json` pin, and refreshes publisher records before
+rejecting a pin mismatch. A pin never supplies a key missing from the operator
+JWKS. Matching uses RFC 7638 thumbprints, so a `kid` alone or a different key with
+the same `kid` does not qualify. Pins reject signatures created at or after their
+`revoked_at` timestamp. Operator key-origin checks
+still apply. An unknown `kid` triggers one JWKS refetch, with a 30-second cooldown.
+
+Sellers omitting `identity.brand_json_url` use the 3.x fallback: first their host's
+`/.well-known/brand.json`, then the registrable domain on a host 404. This path
+skips the advertised-record origin and key-origin checks. A malformed or
+unreachable advertised record never downgrades to the fallback. Webhook discovery
+failures return `webhook_signature_key_unknown` and log the specific
+`request_signature_*` cause. Fallback document resolution follows at most one
+`authoritative_location` or `house` indirection and rejects indirection chains.
+
+For a receiver that already resolves operator keys, `WebhookVerifyOptions`
+accepts `publisher_pins` keyed by the applicable publisher domain. Supply
+`refresh_publisher_pins`, a synchronous callback returning fresh pins for the same
+publisher set. A missing pin uses `None`; an empty pin accepts no key. Configure
+the operator JWKS resolver and capabilities `expected_key_origins` alongside it.
+
+Governance issuer matching is canonical. `resolve_governance_jwks` takes the
+authenticated buyer's exact record, `issuer`, and the governed request's
+`brand_domain`. It selects one applicable brand collection, preserving explicit
+brand overrides, and never searches sibling brands. For signed requests, pass
+`VerifiedSigner.operator_brand_json`, which `verify_from_agent_url` retains from
+discovery. Do not refetch a different document from the operator's host.

docs/agent-resolution-33.md

@@ -139,6 +139,21 @@ Missing authentication is rejected. Supply
 `caller_resolver` for a different trusted identity model; never choose consumer
 identity from the request body.
 
+`capability_block()` and installed capability discovery describe registered
+reporting offerings and installed components throughout the service lifetime.
+They are available before startup and remain stable while stopping, after
+closure, and after worker failure. An unconfigured service declares no reporting
+block. Use `service.ready` for local work admission; buyer tools report runtime
+unavailability separately. Discovery does not start workers or instantiate lazy
+platform tenants.
+
+Managed-production discovery also retains registered destination, signing and
+reconciliation declarations through shutdown or failure. Build-time discovery
+does not construct the production graph. The development memory production
+graph declares no durable production tier; Core memory services still declare
+their inline offerings. `ReportingProductionSupport.reporting_delivery()` keeps
+its runtime readiness check for operator and admission callers.
+
 ## Decisioning platforms and lazy routers
 
 Core `install()` accepts a `DecisioningPlatform`, including `LazyPlatformRouter`:
@@ -338,3 +353,15 @@ exact-read assertions after service recreation or durable recovery.
 
 See [`examples/reliable_reporting_adapters.py`](../examples/reliable_reporting_adapters.py)
 for compact GAM-like and FreeWheel-like adapter definitions.
+
+Installed Core and managed production reporting use one error policy at service
+admission. A created, stopping, closed, or failed service returns
+`SERVICE_UNAVAILABLE` with transient recovery. A missing authenticated caller
+returns `AUTH_REQUIRED`; explicit buyer configuration validation can raise
+`ReliableReportingConfigurationError(message, kind="invalid_request")`.
+Composition errors retain `INTERNAL_ERROR` and terminal recovery, with internal
+configuration details omitted from buyer responses. Ledger codes are preserved
+and receive the SDK's recovery classification for that code. Reporting cursor/
+input extensions are correctable, storage-unavailability extensions are transient,
+and unknown extension or integrity failures default to terminal. Disabled optional methods and aggregate delivery
+continue to delegate to the application.

docs/reliable-reporting-service.md

@@ -102,9 +102,12 @@ migrate, construct fresh support, validate, and restart. Arbitrary serving-time
 DDL or search-path mutation is not automatically detected. Bound database
 statement execution at the adopter/database layer.
 The support also binds the pool's concrete identity and checks its open state
-on each readiness request. Closing or replacing that pool withdraws the claim
+on each readiness request. Closing or replacing that pool rejects fresh work
 even while the immutable catalog proof remains cached; rebuild the support for
-a new pool.
+a new pool. Installed capability discovery retains the registered declarations
+through these failures and through shutdown. It neither checks runtime readiness
+nor requests a database connection; use `support.reporting_delivery()` for a
+local readiness projection.
 The projection queue and all configured notification queues must retain the
 same pool as the ledger. Warm discovery performs no pool checkout and stays
 available when that valid pool is temporarily saturated.
@@ -200,7 +203,9 @@ new rc.6 forecast. The current SDK does not advertise rc.3 as a live client or
 server pin. New mounts, advertised schemas and rendering use the supported
 packaged version. Cursor/checkpoint version mismatches fail closed only after
 caller and signed-position verification. Changing a production mount's captured
-protocol pin invalidates readiness even after a successful schema proof.
+protocol pin invalidates both the captured declaration and runtime readiness,
+even after a successful schema proof. Worker lifecycle transitions preserve the
+registered capability promises; protocol substitution does not.
 
 Integrated parents created representation-one snapshots without a protocol
 filter marker. Their original pages and checkpoints remain usable under rc.6,
@@ -362,7 +367,7 @@ unexpected-failure signal. Existing notification guards still
 check readiness before sampling and before dispatch; already-reserved work may
 finish under its existing transaction and deadline rules. Drain with `aclose()`,
 repair the failed component and construct fresh support to recover; the failed
-instance never silently restarts or regains its capability claim. A failing log
+instance never silently restarts or regains runtime readiness. A failing log
 sink cannot prevent the stop latch or change the safe public error.
 A PostgreSQL lock failure that exhausts the producer's bounded retries follows
 this same fail-stop policy. Other owned worker boundaries still propagate their

docs/reporting-production.md

@@ -290,3 +290,10 @@ if not result.ok:
 * **Hooks bypassing SSRF** — hooks run before SSRF, but SSRF validates the post-rewrite URL; the boundary holds.
 
 If your current sender doesn't have one of these properties, this is what you're trading up to.
+
+## Reporting-stream correlation on AdCP 3.2
+
+For scheduled `media_buy_delivery` notifications, see the
+[interim reporting operation ID guide](reporting-operation-id-3.2.md).
+It covers the optional registration extension, seller persistence and echo,
+and updating existing registrations before resuming scheduled delivery.

docs/webhooks/migration-from-fragmented-senders.md

@@ -0,0 +1,58 @@
+# Reporting correlation on AdCP 3.2
+
+AdCP 3.2.1 requires a buyer-supplied `operation_id` in scheduled delivery
+webhook envelopes, but its `reporting_webhook` schema does not declare that
+field. [adcp#7885](https://github.com/adcontextprotocol/adcp/issues/7885)
+tracks the gap; [adcp#7895](https://github.com/adcontextprotocol/adcp/pull/7895)
+proposes the field for 3.3.
+
+The SDK restores an optional `ReportingWebhook.operation_id` as an interim
+extension. The published registration schema permits additional fields.
+Use it only after confirming seller support during integration onboarding;
+a 3.2 seller may accept and ignore an unknown field. This agreement does not
+change the released 3.2 schema or require all 3.2 implementations to support it.
+It needs no `ext.{namespace}` wrapper inside `reporting_webhook`.
+
+```python
+from adcp.types import ReportingWebhook
+
+registration = ReportingWebhook(
+    url="https://buyer.example.com/webhooks/reporting",
+    operation_id="op_reporting_001",
+    authentication={
+        "schemes": ["Bearer"],
+        "credentials": "example_reporting_credential_32_chars",
+    },
+    reporting_frequency="daily",
+)
+wire_registration = registration.model_dump(mode="json")
+```
+
+Supply that registration through `buy_products`, `accept_proposal`,
+`control_media_buy`, or the legacy `create_media_buy` / `update_media_buy`
+API where supported. IDs use 1–255 characters from `A–Z`, `a–z`, `0–9`,
+`_`, `.`, `:`, and `-`, matching `PushNotificationConfig.operation_id`.
+Omission and `None` remain valid; default serialization omits an absent ID.
+Explicit malformed values fail model validation. Historical version-scoped
+models keep their pinned schema contracts, including the beta.6-required field
+in `adcp.types.v32`.
+
+For a seller implementing this agreement, persist the ID with the reporting
+registration, then pass that exact value to `WebhookSender.send_mcp(operation_id=...)`
+for every `media_buy_delivery` report. Preserve it on retries and keep existing
+authentication, required envelope fields, and per-delivery idempotency handling.
+The reporting-stream ID is independent of any task-status callback ID and does
+not replace a delivery's `idempotency_key`. Never derive it from the URL or
+fabricate it from a seller resource ID.
+
+For existing registrations without a buyer-supplied ID, flag the missing value
+and suppress scheduled sends on this interim path. Ask buyers to update their
+registration with an ID before resuming delivery. `get_media_buy_delivery`
+remains available while arranging support. Updating the SDK alone does not
+backfill seller storage or restart reports.
+
+Verify buyer serialization → seller validation → durable registration →
+scheduled send → authenticated receipt end to end before deployment. When a
+later protocol release defines the core field, its definition takes precedence
+over this interim agreement; remove the compatibility patch once generated
+models retain the field and the regression suite still passes.

docs/webhooks/reporting-operation-id-3.2.md

@@ -78,6 +78,12 @@ Related skills: `build-seller-agent`, `build-generative-seller-agent`,
 `build-signals-agent`. The seller storyboard tests live at
 [`../tests/test_seller_agent_storyboard.py`](../tests/test_seller_agent_storyboard.py).
 
+The reference seller stores injected sandbox delivery events and splits their
+traffic across packages by budget, then across declared format kinds using
+descending catalog-order weights. Simulated video impressions represent
+two-second play events for `time_based_views`; these values demonstrate
+reporting behavior rather than measurements from a serving engine.
+
 ## Authentication & multi-tenancy
 
 - [`mcp_with_auth_middleware.py`](mcp_with_auth_middleware.py) — multi-tenant MCP server with bearer-token auth via `BearerTokenAuthMiddleware` + `auth_context_factory`.

examples/README.md

@@ -156,3 +156,25 @@ serve(router, asgi_middleware=[(SubdomainTenantMiddleware, {...})])
 - **Cross-tenant state.** Each tenant is an island — its own
   inventory, its own buys, its own auth. The router never aggregates
   across tenants.
+
+The examples support tenant-scoped account discovery and `list_products`.
+Both catalogs return `cache_scope: public`; catalog pages ignore outcome
+criteria, as the compact catalog contract requires. The non-guaranteed
+platform offers its normal auction floor and a fixed CPM quote when the buyer
+requests fixed-price inventory.
+
+The sandbox controller's `seed_account` writes to the same account store used
+by normal requests. Fixtures, including their sandbox/live mode, resolve by
+explicit ID or natural account identity within the selected tenant. Account
+lists and fixture records do not cross tenant boundaries. The controller uses
+the framework's account mode gate; live accounts cannot invoke sandbox
+controls. Default local demo accounts are sandbox accounts.
+
+Buy responses retain the original commitment timestamp and advance revisions
+on successful updates. Cancellation moves a buy to `canceled`; a second
+cancellation returns `NOT_CANCELLABLE`.
+
+`force_get_products_arm` can register one sandbox business rejection for the
+next brief. Directives expire after five minutes and remain isolated by tenant,
+account, and authenticated caller. Anonymous requests use the example's public
+demo principal. Wholesale catalog reads leave the directive untouched.