feat(decisioning): expose adcp_version for DecisioningPlatform servers

[bokelley]

Summary

SDK 8 adds version-scoped MCP schemas and dispatch, but the public DecisioningPlatform composition path does not expose a way to set the handler's protocol pin.

Both of these public functions lack an adcp_version parameter:

• adcp.decisioning.serve.create_adcp_server_from_platform()
• adcp.decisioning.serve()

The factory always constructs PlatformHandler(...) without a pin, and PlatformHandler does not implement get_adcp_version(). As a result, adcp.server.mcp_tools._resolve_handler_adcp_version(handler, None) returns None.

That makes a DecisioningPlatform-based seller fall back to the SDK's unversioned/current 3.2 model schemas for MCP discovery even when the seller advertises and enforces AdCP 3.1. For example, beta.4's unversioned ListCreativesRequest advertises the 3.2-only assignment_projection and assignment_limit fields; the bundled 3.1 schema correctly omits them.

Current workaround

An adopter must either bypass adcp.decisioning.serve() or mutate the generated handler's private state:

handler, executor, registry = create_adcp_server_from_platform(platform)
handler._adcp_version = "3.1"

Once set, the existing server resolver correctly selects the bundled 3.1 discovery schemas and uses 3.1 as the default unnegotiated dispatch version.

Suggested API

Add adcp_version: str | None = None to both DecisioningPlatform composition functions, resolve/validate it consistently with the other SDK constructor surfaces, and attach the resolved pin to PlatformHandler.

A regression test could assert that a platform created with adcp_version="3.1":

1. resolves to "3.1" through _resolve_handler_adcp_version;
2. advertises the bundled 3.1 MCP request/output schemas; and
3. uses 3.1 for unversioned dispatch.

Environment

• adcp==8.0.0b4
• Python 3.13
• multi-tenant seller using LazyPlatformRouter + adcp.decisioning.serve()

[bokelley]

Triage

Classification: Feature request
Bucket(s): client / handlers (decisioning serve surface)
Status: ready-to-implement

What the experts said:

• code-reviewer: Non-breaking — adding adcp_version: str | None = None to both public entry points and PlatformHandler.__init__; get_adcp_version() method is the right surface over _adcp_version mutation; use a format guard (re.fullmatch(r"\d+\.\d+", ...)) at the public API boundary. Also flagged a pre-existing bug: serve() silently drops its media_buy_store param without forwarding it to create_adcp_server_from_platform() — worth fixing in the same PR.
• dx-expert: Use the existing resolve_adcp_version() from adcp._version for validation — it's already used by ADCPClient and ADCPServerBuilder and handles format errors, same-major fencing, and canonical normalization. Note that resolve_adcp_version(None) returns the SDK's packaged pin (not None), so _adcp_version will always be a str after construction — document accordingly. Also flagged a broken module-level docstring in src/adcp/decisioning/__init__.py (code example passes create_adcp_server_from_platform's 3-tuple where serve() expects a DecisioningPlatform).

My take: This is a real functional gap — PlatformHandler is the only adopter-facing handler constructor without adcp_version support, causing DecisioningPlatform servers to silently use 3.2 discovery schemas regardless of their advertised protocol version. The fix is non-breaking and has a clear implementation path consistent with ADCPClient and ADCPServerBuilder.

Implementation scope:

• src/adcp/decisioning/handler.py: Add adcp_version: str | None = None to PlatformHandler.__init__; store self._adcp_version = resolve_adcp_version(adcp_version) (import from adcp._version); add def get_adcp_version(self) -> str: return self._adcp_version. Note _adcp_version will always be a non-None str — document that "None defaults to the SDK's packaged protocol pin."
• src/adcp/decisioning/serve.py: Add adcp_version: str | None = None to both create_adcp_server_from_platform() and serve(). Thread it into PlatformHandler(...) and the create_adcp_server_from_platform() call inside serve(). Bonus fix: forward the silently-dropped media_buy_store param while here.
• src/adcp/decisioning/__init__.py: Fix the broken module-level code example (passes create_adcp_server_from_platform's 3-tuple to serve(), which expects a DecisioningPlatform).
• Tests: assert handler.get_adcp_version() == "3.1" when passed, _resolve_handler_adcp_version(handler, None) == "3.1", explicit version overrides handler value, None defaults to SDK-packaged version, malformed version raises ConfigurationError.
• Follow-up (out of scope): LazyPlatformRouter/PlatformRouter construct PlatformHandler instances internally — once PlatformHandler.__init__ gains adcp_version, routers need to thread it too.

Run make lint && make typecheck-all && pytest before opening a PR.

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01TWA9d2v29yRETL76E5XC5W

---

Generated by Claude Code