Stage 3 follow-ups: cross-version harness, downshift, type surfacing, 4.0 cleanup

[bokelley]

Context

Stage 3 of the per-instance adcpVersion work has shipped:

• Phase A (feat(validation): per-AdCP-version schema loader (Stage 3 Phase A) #1052 — 5.24.0): per-version schema loader (getValidator(toolName, dir, version), resolveBundleKey, hasSchemaBundle)
• Phase B+C (feat: wire adcpVersion per-instance through validators + protocol; lift fence (Stage 3 B+C) #1053 — 5.24.0): per-instance plumbing through validators + wire-level adcp_major_version + governance forwarding + Phase C fence-lift (cross-major pins accepted when bundle ships)
• AdCP 3.1 envelope (feat: AdCP 3.1 release-precision version envelope (spec #3493) #1067 — 5.25.0): adcp_version (release-precision string) emission per spec PR adcontextprotocol/adcp#3493, capability parsing, server-side honor + echo + field-disagreement, extractVersionUnsupportedDetails helper

This issue captures the deferred follow-ups that were intentionally scoped out of those PRs.

Work items

1. Stage 3 Phase D — cross-version test harness

Spin up a 3.1 seller (createAdcpServer({ adcpVersion: '3.1.0-beta.1' })) and a 3.0 buyer (new SingleAgentClient({ adcpVersion: '3.0.1' })) in the same Node process. Assert the matrix:

Buyer	Seller	Expected
3.0	3.0	full support, baseline
3.1	3.1	full support, both fields on the wire
3.0	3.1	works — 3.1 sellers MUST accept 3.0 buyers per minor compat
3.1	3.0	works for 3.0-shaped requests; new 3.1-only features get VERSION_UNSUPPORTED
3.x	4.0 (when shipped)	clean VERSION_UNSUPPORTED, no silent corruption

This was the original Phase D goal in #1053's changeset. Blocked on the AdCP spec repo tagging a 3.1.0-beta.X release containing #3493 — without 3.1 schemas in the SDK build, there's no second bundle to test against.

2. Multi-version "release served" downshift on response echo

Per spec PR #3493 rule 6: a 3.1 seller serving a 3.0 buyer at 3.0 MUST echo adcp_version: '3.0', not '3.1'. Today's SDK (#1067) always echoes the seller's own pin via injectVersionIntoResponse. Correct for single-version sellers; wrong for sellers that declare multiple supported_versions.

Requires:

• Server config knob for declaring multi-version capability (likely supportedVersions: string[] on createAdcpServer config, mapping to adcp.supported_versions on capability response)
• Dispatch threads incoming request.adcp_version through to injectVersionIntoResponse
• Pick the highest mutually-supported version, echo that
• Test coverage in the Phase D matrix above

3. Buyer-side response-echo introspection (typed signal on TaskResult)

Today the seller's adcp_version echo is in the response body but the SDK doesn't surface it as a typed signal on TaskResult. Callers can read it directly from result.data.adcp_version. Adding result.adcpVersion?: string (and probably result.versionDowngraded?: boolean derived by comparing to the buyer's pin) makes downgrade-detection a first-class observable.

4. Compliance storyboard 3.1 tracks

When adcontextprotocol/adcp publishes the 3.1 storyboard tarball, our compliance/cache/ resync via npm run sync-schemas pulls new tracks. Adopters then run adcp storyboard run --version 3.1.0-beta.1 against their dev deployments. No SDK code change needed — purely a documentation/sample update once the tarball lands.

5. AdCP 4.0 cleanup

When AdCP 4.0 ships and adcp_major_version is removed per spec PR #3493's migration table:

• Drop integer wire emission from buildVersionEnvelope
• Drop majorVersions integer array from parseCapabilitiesResponse / AdcpCapabilities
• Remove requireV3 deprecated alias on SingleAgentClient and AgentClient
• Retire the legacy Agent class entirely (deprecation warning lands in feat: wire adcpVersion per-instance through validators + protocol; lift fence (Stage 3 B+C) #1053)
• Drop requireV3ForMutations config option
• Field-disagreement check becomes single-field absence (no adcp_major_version to disagree with)

Major SDK bump. Far in the future.

6. Widen AdcpMajorVersion type when major-4 schemas land

Currently AdcpMajorVersion = 2 | 3 in src/lib/version.ts. When AdCP 4.x schemas ship, widen to 2 | 3 | 4 at source. Mechanical change. Required for requireSupportedMajor's legacy-path cast to stay sound.

Related

• #984 covers items adjacent to this list — the mechanical ADCP_VERSION bump from 3.0 → 3.1 once the spec repo tags. This issue layers on top of chore(schemas): bump cache from 3.0.0 to 3.1.0 once upstream releases #984: do chore(schemas): bump cache from 3.0.0 to 3.1.0 once upstream releases #984's bump first, then the items here become unblocked.
• #1052 / #1053 / #1067 — completed Stage 3 work
• adcontextprotocol/adcp#3493 (merged) — the spec PR that defines the 3.1 envelope
• adcontextprotocol/adcp#984 (this repo's chore(schemas): bump cache from 3.0.0 to 3.1.0 once upstream releases #984 above) — schema-cache bump

Out of scope

• Wire-shape changes (already shipped in feat: AdCP 3.1 release-precision version envelope (spec #3493) #1067)
• Spec changes (done upstream)
• Anything that doesn't depend on AdCP 3.1+ schemas being available

[bokelley]

Triage

Classification: tracking (follow-up bundle)
Bucket(s): library, conformance, schema-sync (no matching repo labels exist — gap noted)
Status: deferred

My take: All six work items are explicitly sequenced after #984 (schema cache bump 3.0 → 3.1). Items 1, 4, 5, and 6 also carry external blockers (upstream 3.1.0-beta.X tag; AdCP 4.0 ship). Nothing here is actionable until #984 merges.

Blocked-on: #984 — resurfaces on merge

---

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

---

Generated by Claude Code