Epic: Tier 1 — version-negotiation work before 3.1 GA

[bokelley]

Context

Tracking issue for all version-negotiation work that needs to land before 3.1 GA (~late June 2026). The spec change shipped via PR #3493; this epic tracks the downstream work that turns the spec into a usable contract for the ecosystem.

Work items

• Python SDK PR Fix semantic version sorting for agreements #294 merge — release-precision pinning + 54 tests. (adcontextprotocol/adcp-client-python#294 — merged 2026-04-30)
• adcp-go SDK support — release-precision pinning, dual-emit, response echo handling, typed VERSION_UNSUPPORTED error. Draft schema/types PR up at adcontextprotocol/adcp-go#107; constructor + typed error + echo helpers are the deferred Tier 1 deliverable.
• @adcp/client.ComplianceIndex type bump — add published_version: string to the TypeScript interface so consumers can read the preferred field. Until this lands, downstream code falls back to legacy adcp_version alias via typed cast.
• Compliance grader storyboard that exercises adcp_version request emission and response echo. Advisory at 3.1 per the migration table in docs/reference/versioning.mdx. Landed in docs+compliance: 3.1 release notes + version-negotiation storyboard (#3570) #4702.
• 3.1 release notes with a dedicated "Pin your release" section showing constructor usage across JS/Python/Go. Landed in docs+compliance: 3.1 release notes + version-negotiation storyboard (#3570) #4702.
• Training agent emits the new fields (training-agent: emit adcp.supported_versions and adcp_version envelope echo (#3570 follow-up) #4711) — adcp.supported_versions on capabilities + adcp_version envelope echo. Reference implementation currently passes the storyboard only because the new validations are advisory; needs to demonstrate the new shape before 3.2 cutover flips advisory → required.
• End-to-end Scope3 deployment — first production use of adcp_version request emit + response echo + capabilities supported_versions. Catches anything the spec PR didn't.
• Branch cleanup — delete bokelley/version-negotiation-rfc from origin (post-merge housekeeping).

Done when

• All three SDKs (JS / Python / Go) emit adcp_version on requests with adcp_major_version mirror.
• Compliance grader runs scenarios and reports presence as advisory.
• Reference implementation (training agent) emits both new fields so adopters have a working example.
• 3.1 GA ships with documented adopter path.

Related

• Spec: PR spec(versioning): release-precision protocol version negotiation #3493 (merged as 6eadf0663)
• RFC: specs/version-negotiation.md
• User-facing doc: docs/reference/versioning.mdx
• Docs + storyboard PR: docs+compliance: 3.1 release notes + version-negotiation storyboard (#3570) #4702
• Training-agent follow-up: training-agent: emit adcp.supported_versions and adcp_version envelope echo (#3570 follow-up) #4711
• Tier 2 epic: Epic: Tier 2 — version-negotiation work in 3.1 → 3.2 cycle #3571
• Tier 3 epic: Epic: Tier 3 — close the loop on version-negotiation at 4.0 #3572
• Schema-draft bump: Migrate JSON Schema source from draft-07 to 2019-09 (4.0) #3534
• Envelope-pattern tracker: Catalog envelope-level fields and migrate to allOf shared-envelope pattern #3535

[bokelley]

adcp-go SDK draft PR filed: adcontextprotocol/adcp-go#107.

Scope: schema bundle bump + generator allOf-handling + regenerated types (40 request/response structs gain AdcpVersion). Tests green. Pinned to latest for now; needs re-pin to the next named version before merge.

SDK ergonomics (constructor option, typed VersionUnsupportedError, response-echo helpers, wire-shape normalization) deliberately scoped out of that PR — they remain Tier 1 work items here.