feat(sdk): per-instance adcp_version pin + wire emission (Stage 2 + 3a)

[bokelley]

Summary

Adds Stripe-style per-instance protocol-version pinning to the Python SDK and wires it onto the wire. Buyers pin once at construction and the SDK auto-injects adcp_version (release-precision string) on every outbound request and emits it from server capability responses.

This is the Python analog of @adcp/client PR #1044, extended one stage further. Built against adcontextprotocol/adcp#3493 — merged 2026-04-29, shipping in the next 3.0.x patch release.

Stages in this PR

Stage 2 — Constructor option + getter (commit 1)

• src/adcp/_version.py — new module. COMPATIBLE_ADCP_VERSIONS = (\"3.0\", \"3.1\"), ADCP_MAJOR_VERSION = 3, parse_adcp_major_version(), resolve_adcp_version(). Release-precision canonical; patch-precision (\"3.0.1\") accepted for back-compat with the legacy ADCP_VERSION file shape.
• ConfigurationError added to src/adcp/exceptions.py for cross-major and unparseable pins.
• All four constructor surfaces wired: ADCPClient, ADCPMultiAgentClient, ADCPServerBuilder, adcp_server() factory. Each exposes get_adcp_version() -> str.

Stage 3a — Wire emission (commit 2)

Client side:

• ProtocolAdapter gains envelope_enricher hook + _enrich_outgoing_params() helper. Runs after idempotency injection, before schema validation.
• MCPAdapter._call_mcp_tool and A2AAdapter._call_a2a_tool both apply the enricher to outbound params.
• ADCPClient.__init__ installs an enricher that prepends adcp_version=self._adcp_version to every outbound request. Caller-supplied values on the params dict win — the enricher is the default, not an override.

Server side:

• capabilities_response() accepts adcp_version, supported_versions, build_version. Emits supported_versions (release-precision list, authoritative for buyer pinning) and build_version (advisory full semver, for incident triage) on the adcp block, plus top-level adcp_version on the response envelope.
• Legacy major_versions still emitted for back-compat through 3.x.
• ADCPServerBuilder's auto-generated get_adcp_capabilities handler threads the builder's pinned adcp_version into capabilities_response().

Spec-conformance fix — release-precision normalization (commit 3)

The merged spec (core/version-envelope.json) requires:

SDKs that read full-semver values from bundle metadata (e.g. ComplianceIndex.published_version = "3.1.0-beta.1") MUST normalize to release-precision ("3.1-beta.1") before emitting on the wire — meta-field values are NOT valid wire values.

The packaged ADCP_VERSION file ships full-semver (\"3.0.0\" today). Stage 2/3a were passing it through unchanged, which is non-compliant.

• New normalize_to_release_precision() helper in _version.py: \"3.0.0\" → \"3.0\", \"3.0.1\" → \"3.0\", \"3.1.0-rc.1\" → \"3.1-rc.1\", release-precision unchanged.
• Applied in resolve_adcp_version() so the stored pin and wire emission are always release-precision regardless of input shape.
• get_adcp_version() returns the normalized form.

Tests

67 new tests across two files — all passing. Pre-existing test sweep clean.

• tests/test_adcp_version_option.py — 57 tests: defaults, valid pins, cross-major rejection, unparseable strings, normalization (patch → release), pre-release tag preservation, all four constructor surfaces.
• tests/test_adcp_version_wire.py — 10 tests: envelope injection, caller override, capability response shape, auto-capabilities handler.

Validation

• ruff check src/ — clean
• mypy src/adcp/ — no new errors (96 pre-existing, unchanged)
• pytest tests/test_adcp_version_*.py -v — 67/67 pass
• Sanity sweep on tests/test_client.py, tests/test_capabilities.py, tests/test_helpers.py — no regressions

Out of scope (Stage 3b, separate PR)

• Schema sync from upstream latest.tgz — when run against the post-merge dev snapshot, codegen drift from the asset-union refactor (3.0.2-beta.0) eliminates *1 discriminator artifacts that aliases.py references. That sync requires its own PR for the alias-rewire work, separate from version-negotiation. Tracked.
• Per-version schema cache — version-keyed schemas/cache/<version>/ layout, SchemaRegistry replacing the module-level _state singleton in validation/schema_loader.py.
• Response-echo validation — read response's adcp_version and validate against that release's schema. Today the response field passes through on TaskResult.data[\"adcp_version\"].
• Server handler-side dispatch — surface the buyer's pinned adcp_version from the request envelope to handlers via tool_context.
• Per-version Pydantic generator — Stripe-style latest-superset rules so a single Pydantic surface accepts response shapes from any supported release.
• version_unsupported error classification — Python-side wrapper around the new error data shape from the protocol PR.

How to use it

from adcp import ADCPClient
from adcp.types import AgentConfig, Protocol

client = ADCPClient(
    AgentConfig(id=\"seller\", agent_uri=\"https://...\", protocol=Protocol.MCP),
    adcp_version=\"3.1\",  # release-precision pin
)

client.get_adcp_version()  # \"3.1\"
# Every outbound request now carries adcp_version=\"3.1\" on the wire.

from adcp.server.builder import adcp_server

server = adcp_server(\"my-seller\", adcp_version=\"3.1\")

@server.get_products
async def get_products(params, context=None):
    return {\"products\": [...]}

# Auto-generated get_adcp_capabilities now emits:
#   { \"adcp_version\": \"3.1\",
#     \"adcp\": { \"major_versions\": [3], \"supported_versions\": [\"3.1\"], ... } }