Accept or publish AdCP 3.1-beta.5 wire version

[bokelley]

Summary

The current Python SDK release used by Sales Agent rejects requests that carry the current JS SDK / Agentic wire envelope value:

{"adcp_version": "3.1-beta.5"}

Local runtime with adcp @ git+https://github.com/adcontextprotocol/adcp-client-python.git@v6.3.0-beta.4 reports:

adcp.validation.envelope.SUPPORTED_WIRE_VERSIONS = ('3.0', '3.1-beta.4', '2.5')

and detect_wire_version({"adcp_version": "3.1-beta.5"}) raises UnsupportedVersionError because normalize_to_release_precision() preserves the prerelease patch label and the strict supported set does not include beta.5.

Downstream impact

Prebid Sales Agent had to add a local compatibility shim in bokelley/salesagent#632 so embedded/managed tenants can interoperate with current buyers emitting 3.1-beta.5 while the Python SDK pin is still on 3.1-beta.4.

That shim patches:

• adcp.validation.envelope.SUPPORTED_WIRE_VERSIONS
• adcp.validation.envelope.detect_wire_version

so the strict dispatcher path accepts 3.1-beta.5 as wire-compatible.

Ask

Please either:

1. publish a Python SDK prerelease whose SUPPORTED_WIRE_VERSIONS includes 3.1-beta.5, or
2. make detect_wire_version() tolerant of wire-compatible 3.1 beta patch aliases when the request/response envelope shape has not changed.

Suggested acceptance criteria

• detect_wire_version({"adcp_version": "3.1-beta.5"}) returns "3.1-beta.5" or another documented compatible 3.1 release-precision value instead of raising.
• Server dispatch/envelope validation accepts 3.1-beta.5 requests without adopter monkeypatching.
• Capabilities helpers advertise the exact supported wire versions consistently with runtime validation.

Related downstream validation

Sales Agent PR #632 is green with the local shim:

• make quality
• focused managed-tenant webhook integration slice
• GitHub CI: lint/typecheck, unit, integration shards, E2E, quickstart, security audit, storyboard gates, GHCR build

[bokelley]

Triage

Classification: Bug
Bucket(s): validation (no validation label exists in repo — noted in run summary)
Status: ready-for-human
Milestone: (omitted — prerelease cycle)

What the experts said:

• ad-tech-protocol-expert: Option B (fuzzy beta-patch matching) is unsound — each 3.1-beta.N is its own schema-cache bucket (schemas/cache/3.1.0-beta.3/, 3.1.0-beta.4/ are distinct); accepting 3.1-beta.5 while serving 3.1-beta.4 schemas violates the context-echo contract and causes a schema-loader cache miss. Option A (bump ADCP_VERSION to beta.5) is protocol-correct; VERSION_UNSUPPORTED + supported_versions is the designed buyer-retry path.
• code-reviewer: Blocker on Option A — get_supported_adcp_versions() removes 3.1-beta.4 from SUPPORTED_WIRE_VERSIONS entirely on a version bump, hard-rejecting existing beta.4 sellers. Option B's return value is wrong (returning the claimed "3.1-beta.5" causes a schema-loader KeyError unless the loader is family-aware). Recommends Option C: add SUPPORTED_PRERELEASE_SIBLINGS = ("3.1-beta.5",) into SUPPORTED_WIRE_VERSIONS construction in envelope.py, plus a schema-loader alias "3.1-beta.5" → "3.1-beta.4".

My take: Experts diverge on whether dropping beta.4 buyers is acceptable (protocol says yes; code-reviewer says regression for mixed deployments). The hard blocker for all options is the missing schemas/cache/3.1.0-beta.5/ directory — any path that accepts 3.1-beta.5 wire requests will fail at schema validation without new schema files or a loader alias.

Decision needed from @bokelley before implementation:

• Option A (bump ADCP_VERSION → 3.1.0-beta.5): run python scripts/sync_schemas.py to populate schemas/cache/3.1.0-beta.5/, bump pyproject.toml to 6.3.0b5; beta.4 sellers get VERSION_UNSUPPORTED (spec-correct retry path).
• Option C (dual sibling support): add SUPPORTED_PRERELEASE_SIBLINGS = ("3.1-beta.5",) to SUPPORTED_WIRE_VERSIONS in src/adcp/validation/envelope.py; add a schema-loader alias in src/adcp/validation/schema_loader.py mapping "3.1-beta.5" → "3.1-beta.4" (no new schema files needed); keeps both beta versions accepted simultaneously. Either option needs new tests in tests/test_validation_envelope.py covering prerelease-sibling accept/reject cases and pinned return value.

---

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

---

Generated by Claude Code