fix: A2A top-level failures return failed Task with AdCP envelope, not JSON-RPC InternalError

.mypy-untyped-defs-baseline

@@ -1 +1 @@
-227
+212

.ruff-complexity-baseline

@@ -1,5 +1,5 @@
 {
-  "C901": 183,
-  "PLR0912": 134,
-  "PLR0915": 108
+  "C901": 181,
+  "PLR0912": 133,
+  "PLR0915": 106
 }

docker-compose.e2e.yml

@@ -58,6 +58,10 @@ services:
       SUPER_ADMIN_EMAILS: ${SUPER_ADMIN_EMAILS:-}
       ADCP_TESTING: ${ADCP_TESTING:-true}
       ADCP_AUTH_TEST_MODE: ${ADCP_AUTH_TEST_MODE:-true}
+      # Exact callback host admitted by the development-only protocol webhook
+      # seam.  Standalone host tests override this with host.docker.internal;
+      # the in-network runner uses its stable "tests" alias.
+      ADCP_WEBHOOK_TEST_HOST: ${ADCP_WEBHOOK_TEST_HOST:-tests}
       # The SERVER must know about the pinned in-network creative agent: sync/
       # create flows resolve format specs server-side, and references carry the
       # PUBLIC canonical agent_url — without this, the registry's connection
@@ -180,6 +184,9 @@ services:
       # network alias (requires `docker compose run --use-aliases`). 'tests' is
       # not 'localhost', so the server does NOT rewrite it to host.docker.internal.
       ADCP_WEBHOOK_HOST: tests
+      # Exact in-network callback host allowed only by the development-mode
+      # protocol-webhook validator. Production has no private-host override.
+      ADCP_WEBHOOK_TEST_HOST: tests
       # Pinned reference creative agent, reachable in-network by service name
       # (no host :9999). Clears the 18 test_creative_agent_live integration tests.
       CREATIVE_AGENT_URL: http://creative-agent:8080/api/creative-agent

docker-compose.yml

@@ -86,6 +86,12 @@ services:
       ADCP_SALES_PORT: "8080"
       # Enable test login mode for development
       ADCP_AUTH_TEST_MODE: "true"
+      # Declare development EXPLICITLY. Security gates that relax for development fail
+      # closed on an absent or unrecognised value, so the relaxation has to be stated
+      # rather than inferred from omission — see
+      # WebhookURLValidator._require_https_for_callback, which requires HTTPS for AdCP
+      # callbacks unless this reads "development". docker-compose.e2e.yml already sets it.
+      ENVIRONMENT: development
       # Development settings (venv at /opt/venv in image — see Dockerfile UV_PROJECT_ENVIRONMENT)
       PYTHONPATH: "/app"
       PYTHONUNBUFFERED: "1"

docs/adcp-spec-version.md

@@ -41,32 +41,26 @@ uv run python -c "import adcp; print(adcp.get_adcp_spec_version())"
 across `pyproject.toml`, the test's `EXPECTED_SPEC_VERSION` constant, and
 this document.
 
-## Behavior target vs SDK pin
-
-The SDK **pin** (3.1.0-beta.3) fixes the request/response *type shapes* we
-build against. It does **not** always fix the graded *behavior*. One field
-diverges deliberately: the `media_buy_status` dual-emit on
-create-/update-media-buy responses.
-
-- **beta.3 storyboard** (`dist/compliance/3.1.0-beta.3/.../pending_creatives_to_start.yaml`,
-  ~L131-134) grades the body `status` as `field_value_or_absent` that MUST equal
-  `media_buy_status` — the deprecated "both identical" model (#4908).
-- **Target GA** — graded by the published **3.1.0** compliance
-  (`dist/compliance/3.1.0/.../pending_creatives_to_start.yaml`, ~L146-153;
-  `3.1.1` is byte-identical for this storyboard) — grades `media_buy_status`
-  as `field_value` (the DOMAIN status) and the top-level `status` as
-  `field_value` `'completed'` (the PROTOCOL `TaskStatus`, protocol envelope).
-  The two are DIFFERENT namespaces and are NOT identical.
-
-Our wire already implements the divergent (target GA) model:
+## Behavior sources vs SDK pin
+
+The pin and the behavior target are the same version (3.1.1). What differs is
+the ROLE of each artifact: the SDK **pin** fixes the request/response *type
+shapes* we build against, and it does not replace the authoritative prose and
+compliance storyboards for protocol behavior. For example, the published
+**3.1.1** `pending_creatives_to_start.yaml` storyboard grades `media_buy_status`
+as `field_value` (the DOMAIN status) and the top-level `status` as
+`field_value` `'completed'` (the PROTOCOL `TaskStatus`, protocol envelope).
+The two are DIFFERENT namespaces and are NOT identical.
+
+Our wire implements that two-namespace model:
 `TaskResultEnvelope._serialize` sets the top-level `status` to the protocol
 `TaskStatus`, while the domain status survives under `media_buy_status`
 (`src/core/schemas/_base.py` `_mirror_media_buy_status`). The dual-emit
 validator only backfills the deprecated **body** `status` from the domain
 `media_buy_status` for the deprecation window; it does not touch the wire
 top-level `status`.
 
-**Known SDK type defect (SDK not authoritative):** adcp 5.7 types the response
+**Historical SDK type defect (SDK not authoritative):** adcp 5.7 typed the response
 `status` as `MediaBuyStatus | None`, but the wire top-level `status` carries a
 protocol `TaskStatus` (`submitted` / `completed`). This is fine because that
 protocol value lives on `TaskResultEnvelope.status` (typed `str`), never on the
@@ -77,6 +71,67 @@ SDK-typed body field. Grounding for the divergent behavior is the value-pinned
 `tests/bdd/steps/domain/uc002_create_media_buy.py` (see PR #1417).
 `tests/unit/test_adcp_spec_version.py` only guards the SDK pin, not this behavior.
 
+## Authentication error classification
+
+The immutable AdCP **v3.1.1** source is tag `v3.1.1`, commit
+`467fd93d77112baf9e094e18980119edcd3a4d07`. Its
+`static/schemas/source/enums/error-code.json` metadata requires sellers to
+return:
+
+- `AUTH_MISSING` when no standard `Authorization` header was included
+  (`correctable`: provide credentials and retry).
+- `AUTH_INVALID` when an `Authorization` header was present but rejected
+  (`terminal`, except the spec's one-time OAuth refresh allowance).
+
+Prebid Sales Agent applies that split at every A2A, MCP, and REST wire
+boundary. The legacy `x-adcp-auth` extension remains accepted as an input
+channel, but it does not change the standard header-presence classifier.
+Direct `_impl` helpers retain deprecated `AUTH_REQUIRED` only where no wire
+credential-presence information exists.
+
+This behavior is **ungraded** by the official conformance storyboards:
+`dist/compliance/3.1.1/universal/error-compliance.yaml` contains no
+`AUTH_*` scenario. The two codes are covered by the repository's cross-transport
+wire tests, and by the pinned fixture at
+`tests/fixtures/adcp_schemas_pinned/enums/error-code.json`.
+
+### What the pinned fixture does and does not vendor
+
+The fixture tree is vendored at commit `04f59d2d5` (the v3.1 cut, 2026-05-13), **not**
+at `v3.1.1`. The two AUTH entries above are transplanted from `467fd93d` and declared as
+a supplement in `tests/fixtures/adcp_schemas_pinned/_refresh.py`, because production
+emits both codes and the recovery-conformance guard resolves them against this file.
+
+So the fixture is **not** a complete v3.1.1 vocabulary: it carries the base commit's
+codes plus exactly that declared supplement, and it lags published 3.1.1 by a number of
+codes and several `enumMetadata` suggestion texts. That gap is real and tracked
+separately — the point of declaring it is that the tree no longer claims a fidelity it
+does not have.
+
+`tests/unit/test_pinned_schema_provenance.py` enforces the claim against the bytes:
+`PINNED_SHA` must match the generated `_manifest.py`, every vendored file must match its
+recorded digest, and the error-code enum must equal the base vocabulary plus exactly the
+declared supplement. Advancing the pin therefore requires actually re-running
+`_refresh.py` — editing the constant alone fails.
+
+## Protocol callback URL transport policy
+
+The pinned AdCP **v3.1.1** source defines
+`static/schemas/source/core/push-notification-config.json#properties/url` as a
+generic URI. It does not mandate acceptance of plaintext HTTP callback URLs.
+The authoritative
+`dist/compliance/3.1.1/universal/webhook-emission.yaml` storyboard (version
+1.3.0) uses an operator-supplied **HTTPS** receiver in `proxy_url` mode and
+grades payload idempotency, operation correlation, retry behavior, and RFC 9421
+signing. It does not grade whether an implementation accepts HTTP callback
+registration.
+
+Prebid Sales Agent therefore treats HTTPS-only production callbacks as an
+implementation security policy: production rejects HTTP before persisting or
+sending a callback, while the exact-host development seam remains available
+for the Docker E2E receiver. This restriction is **ungraded** by the 3.1.1
+storyboard and does not replace its signing or idempotency requirements.
+
 ## Wire negotiation
 
 AdCP wire values for `adcp_version` are release-precision (`"3.0"`,

docs/test-obligations/BR-UC-011-manage-accounts.md

@@ -115,7 +115,7 @@ High impact. Account management is a new protocol domain in adcp 3.x. The schema
 **Layer** behavioral
 **Given** no authentication
 **When** the buyer sends `sync_accounts`
-**Then** the request is rejected with AUTH_REQUIRED
+**Then** every wire transport rejects the request with AUTH_MISSING
 **Business Rule:** BR-12
 **Priority:** P0
 
@@ -209,14 +209,14 @@ High impact. Account management is a new protocol domain in adcp 3.x. The schema
 **Business Rule:** BR-10
 **Priority:** P0
 
-### Extension A: AUTH_REQUIRED
+### Extension A: Authentication errors
 
 #### Scenario: Missing auth token on sync_accounts
 **Obligation ID** UC-011-EXT-A-01
 **Layer** behavioral
 **Given** no Bearer token in request
 **When** the buyer sends `sync_accounts`
-**Then** the response is error variant with `AUTH_REQUIRED`
+**Then** every wire transport returns an error variant with `AUTH_MISSING`
 **And** no accounts are modified
 **And** context is echoed
 **Business Rule:** BR-12, POST-F1
@@ -227,15 +227,15 @@ High impact. Account management is a new protocol domain in adcp 3.x. The schema
 **Layer** behavioral
 **Given** an expired Bearer token
 **When** the buyer sends `sync_accounts`
-**Then** the response is error variant with `AUTH_REQUIRED`
+**Then** every wire transport returns an error variant with `AUTH_INVALID`
 **Priority:** P1
 
 #### Scenario: Malformed auth token on sync_accounts
 **Obligation ID** UC-011-EXT-A-03
 **Layer** behavioral
 **Given** a malformed Bearer token
 **When** the buyer sends `sync_accounts`
-**Then** the response is error variant with `AUTH_REQUIRED`
+**Then** every wire transport returns an error variant with `AUTH_INVALID`
 **Priority:** P1
 
 ### Extension B: SYNC_PARTIAL_FAILURE
@@ -394,7 +394,7 @@ High impact. Account management is a new protocol domain in adcp 3.x. The schema
 **Obligation ID** UC-011-EXT-G-03
 **Layer** schema
 **Given** an unauthenticated buyer sending sync_accounts with `context: {"trace": "t1"}`
-**When** the AUTH_REQUIRED error is returned
+**When** the wire transport returns AUTH_MISSING
 **Then** the error response includes `context: {"trace": "t1"}`
 **Business Rule:** POST-F3
 **Priority:** P1
@@ -430,7 +430,7 @@ High impact. Account management is a new protocol domain in adcp 3.x. The schema
 #### Scenario: sync-accounts-response error variant
 **Obligation ID** UC-011-SCHEMA-03
 **Layer** schema
-**Given** an operation-level error response (e.g., AUTH_REQUIRED)
+**Given** an operation-level error response (e.g., AUTH_MISSING, AUTH_INVALID, or AUTH_REQUIRED)
 **When** serialized
 **Then** it validates against `sync-accounts-response.json` (error oneOf variant)
 **And** has errors array

docs/test-obligations/UC-002-create-media-buy.md

@@ -768,7 +768,8 @@ Source: UC-002-ext-c.md, BR-RULE-013
 **Layer** schema
 **Given** `start_time` is an ISO 8601 datetime that is in the past
 **When** the system validates timing
-**Then** it returns error: "Invalid start time: {value}. Start time cannot be in the past."
+**Then** it returns `INVALID_REQUEST` with static message "Start time cannot be in the past."
+**And** the error identifies `field: start_time`, includes a corrective suggestion, and does not echo request timestamps
 **Business Rule:** BR-RULE-013 INV-2
 **Priority:** P0
 
@@ -777,7 +778,8 @@ Source: UC-002-ext-c.md, BR-RULE-013
 **Layer** schema
 **Given** `end_time` is before or equal to `start_time`
 **When** the system validates timing
-**Then** it returns error: "Invalid time range: end time ({end}) must be after start time ({start})."
+**Then** it returns `INVALID_REQUEST` with static message "End time must be after start time."
+**And** the error identifies `field: end_time`, includes a corrective suggestion, and does not echo request timestamps
 **Business Rule:** BR-RULE-013 INV-3
 **Priority:** P0
 

docs/test-obligations/bdd-traceability.yaml

@@ -876,6 +876,12 @@ mappings:
       upstream_refs: ["BR-UC-002-ext-d"]
       business_rules: []
       status: new
+    - adcp_scenario_id: "T-UC-002-ext-nl-unsupported"
+      adcp_feature: "BR-UC-002-create-media-buy.feature"
+      obligation_id: null
+      upstream_refs: ["transport-errors.mdx#Layer-Separation"]
+      business_rules: []
+      status: new
     - adcp_scenario_id: "T-UC-002-ext-e"
       adcp_feature: "BR-UC-002-create-media-buy.feature"
       obligation_id: null

docs/test-obligations/business-rules.md

@@ -931,16 +931,17 @@ Then an empty accounts array is returned (not an error)
 ### BR-RULE-055: Account Operation Authentication Policy
 **Obligation ID** BR-RULE-055-01
 **Layer** behavioral
-**Invariant:** sync_accounts requires valid auth. list_accounts works without auth but scopes results. Unauthenticated list returns empty array.
+**Invariant:** sync_accounts and list_accounts require valid auth. list_accounts scopes results to accounts visible to the authenticated agent.
+**Grounded in:** dist/docs/3.1.1/accounts/tasks/list_accounts.mdx:8 ("Returns all accounts the authenticated agent can operate..."); dist/docs/3.1.1/protocol/required-tasks.mdx:118 (list_accounts discovers "seller-assigned accounts" for a resolved credential, unlike the plain "Required" no-auth-caveat discovery tasks in the same table). Not a single explicit "MUST require authentication" sentence — inferred consistently across both passages from a task that is meaningless without a resolved identity to scope against.
 **Scenario:**
 ```gherkin
-Given no valid authentication
-When sync_accounts is called
-Then AUTH_REQUIRED error is returned
-
 Given no authentication
-When list_accounts is called
-Then an empty accounts array is returned (not an error)
+When sync_accounts or list_accounts is called
+Then every wire transport returns AUTH_MISSING
+
+Given rejected authentication credentials
+When sync_accounts or list_accounts is called
+Then every wire transport returns AUTH_INVALID
 ```
 **Priority:** P0
 **Affected by 3.6:** Yes -- accounts domain is new in v3

docs/test-obligations/constraints.md

@@ -1635,11 +1635,14 @@ Then status=pending_approval with setup.message
 ### account_auth_policy: Account Authentication Policy
 **Obligation ID** CONSTR-ACCOUNT-AUTH-POLICY-01
 **Layer** behavioral
-**Requirement:** sync_accounts requires valid auth. list_accounts allows anonymous (empty results).
+**Requirement:** sync_accounts and list_accounts require valid authentication.
 **Scenario:**
 ```gherkin
-Given no auth on sync_accounts
-Then AUTH_REQUIRED error
+Given no auth on sync_accounts or list_accounts
+Then every wire transport returns AUTH_MISSING
+
+Given rejected auth on sync_accounts or list_accounts
+Then every wire transport returns AUTH_INVALID
 ```
 **Priority:** P0
 **Affected by 3.6:** Yes -- accounts domain is new in v3