feat(decisioning): mock-mode upstream URL routing (Phase 2)

[bokelley]

Summary

Phase 2 of the lifecycle-state-and-sandbox-authority work. When a resolved Account has mode='mock', the framework points the adapter's UpstreamHttpClient at the per-tenant mock-server fixture URL declared on account.metadata['mock_upstream_url']. Adapter business logic runs unchanged across all three modes; only the upstream URL changes per request.

Reframe vs. earlier proposal sketches. The proposal doc envisioned the SDK forwarding mock-mode tool calls out-of-process to a bin/adcp.js mock-server AdCP-MCP forwarder. The earlier agent on this work correctly determined that doesn't fit the existing mock-server (it's a per-specialism upstream-API REST fixture, not an MCP forwarder). The user (proposal author) confirmed the right model: the adapter knows its own production URL (GAM is always googleads.googleapis.com, Kevel is always api.kevel.co); mock-mode just swaps the upstream URL the adapter's HTTP client points at. Adapter code runs unchanged.

Surface

• DecisioningPlatform.upstream_url: str | None — adopter declares the production upstream URL on their subclass (e.g. "https://googleads.googleapis.com"). None is allowed for pure in-process platforms.
• DecisioningPlatform.upstream_for(ctx, *, auth=None, default_headers=None, timeout=30.0, treat_404_as_none=True) -> UpstreamHttpClient — returns a cached client pointed at the right URL for ctx.account.mode. Fail-closes with AdcpError(code='CONFIGURATION_ERROR', recovery='terminal') when:
  • mode='mock' and metadata['mock_upstream_url'] is missing/empty/non-string.
  • mode='live' / mode='sandbox' and platform.upstream_url is None.
• get_mock_upstream_url(account) -> str | None — type-safe accessor that handles dict, non-mapping, missing, empty, and non-string cases.

Cache key: (base_url, id(auth)), per-platform-instance. Different platform instances don't share clients (no cross-adapter auth-header leak); different auth strategies on the same platform get distinct clients (the auth is injected at construction and can't be swapped per-request from a cached client).

What ships

File	Change
src/adcp/decisioning/account_mode.py	Add get_mock_upstream_url(account) helper.
src/adcp/decisioning/platform.py	Add upstream_url class attr + upstream_for(ctx) method + per-instance cache.
src/adcp/decisioning/types.py	Document metadata['mock_upstream_url'] contract on Account docstring.
src/adcp/decisioning/__init__.py	Export get_mock_upstream_url.
tests/test_upstream_for.py	22 tests — routing, fail-closed, cache identity, auth threading.
tests/test_error_code_conformance.py	Allowlist CONFIGURATION_ERROR (server-side adopter-misconfig signal, distinct from INVALID_REQUEST and SERVICE_UNAVAILABLE).
examples/hello_mock_seller.py	Single platform with four accounts demonstrating live, sandbox, mock-A (port 4500), mock-B (port 4501).
docs/handler-authoring.md	New section: "Account modes and mock-mode upstream routing".

Hello-mock four-account example

class HelloMockPlatform(DecisioningPlatform, SalesPlatform):
    upstream_url = "https://example-ad-server.invalid/api"

    accounts = ExplicitAccounts(loader=lambda aid: {
        "acct_live":    Account(id=aid, mode="live"),
        "acct_sandbox": Account(id=aid, mode="sandbox"),
        "acct_mock_a":  Account(id=aid, mode="mock",
                                metadata={"mock_upstream_url": "http://localhost:4500"}),
        "acct_mock_b":  Account(id=aid, mode="mock",
                                metadata={"mock_upstream_url": "http://localhost:4501"}),
    }[aid])

    async def get_products(self, req, ctx):
        client = self.upstream_for(ctx)  # base_url depends on ctx.account.mode
        ...

Mock-server lifecycle is not managed by the SDK. Adopters or CI start bin/adcp.js mock-server <specialism> and populate the URL on mock-mode accounts in their AccountStore.resolve.

What's NOT in this PR

• Multi-platform routing (PlatformRouter) — separate work (feat(examples): multi-platform-per-process proof — mock platforms with PlatformRouter, refactor v3 reference seller along the way #477).
• AdCP-MCP forwarder / MockBackendClient — doesn't fit the existing mock-server.
• comply_test_controller routing changes — Phase 1's gate stays as-is.
• Phase 3 composition / opt-out for adopters with bespoke sandbox needs.

References

• Phase 1: feat(decisioning): Account.mode + sandbox-authority gate for comply_test_controller (Phase 1) #483 (Account.mode + comply-controller gate)
• JS umbrella: feat(server): Account.mode + sandbox-account authority gate for comply controller adcp-client#1435
• Proposal: docs/proposals/lifecycle-state-and-sandbox-authority.md

Test plan

• pytest tests/test_upstream_for.py -v (22 tests pass)
• pytest tests/ full regression (3604 passed, 32 skipped, 0 failed)
• ruff check src/ tests/test_upstream_for.py examples/hello_mock_seller.py
• mypy src/adcp/ (768 source files, 0 errors)
• Boot python examples/hello_mock_seller.py — MCP listening on http://0.0.0.0:3001/mcp without errors
• Reviewer: confirm cache key shape (base_url, id(auth)) matches expected pooling semantics
• Reviewer: confirm CONFIGURATION_ERROR allowlist entry is acceptable, or suggest spec-conformant alternative

🤖 Generated with Claude Code