Skip to content

bug(versioning): 8.0.0 servers reject every 8.0.0rc3 client (3.2-rc.7) and sellers have no supported way to bridge it #1279

Closed

Description

@bokelley

Summary

An adcp 8.0.0 server rejects every adcp 8.0.0rc3 client with VERSION_UNSUPPORTED, and there is no supported way for a seller to bridge the gap.

  • rc3's ADCPClient stamps adcp_version: "3.2-rc.7" on every request, and it has no fallback when a seller rejects that version.
  • 8.0.0 bundles only the stable 3.2 schemas, so SUPPORTED_WIRE_VERSIONS is ('3.0', '3.1', '3.2', '2.5').
  • An 8.0.0 client can't pin 3.2-rc.7 either. resolve_adcp_version raises ConfigurationError.

So every buyer still on rc3 breaks against every seller that upgraded. rc3 shipped 2026-09-30 and 8.0.0 on 2026-10-01, so plenty of rc3 buyers will still be in production.

Reproduction (adcp 8.0.0)

import asyncio

from adcp import ADCPClient
from adcp.server import ADCPHandler
from adcp.server.mcp_tools import create_tool_caller
from adcp.types.core import AgentConfig, Protocol


class Seller(ADCPHandler):
    async def get_products(self, params, context=None):
        return {"products": []}


async def main():
    call = create_tool_caller(Seller(), "get_products")
    try:
        await call({"adcp_version": "3.2-rc.7", "buying_mode": "brief", "brief": "video"})
    except Exception as exc:
        print("server:", exc.errors[0].code)
    try:
        ADCPClient(AgentConfig(id="s", agent_uri="http://localhost/mcp/", protocol=Protocol.MCP),
                   adcp_version="3.2-rc.7")
    except Exception as exc:
        print("client:", type(exc).__name__)

asyncio.run(main())

Output:

server: VERSION_UNSUPPORTED
client: ConfigurationError

Why bridging rc.7 is safe

I compared the bundled 3.2.0-rc.7 schemas (8.0.0rc3) with the 3.2 / AdCP 3.2.1 schemas (8.0.0). Every change from rc.7 to 3.2.1 only adds to the contract:

  • new optional properties (execution_requirements, collections, targeting_resolution, seller_optimized_*, reporting_period.timezone, outcome_target.cost_per, ...);
  • outcome_target.volume is no longer required;
  • the product.json allOf conditionals are reordered;
  • no property was removed, no enum value was removed, and no field became newly required on a request.

An rc.7 request is therefore a valid 3.2.1 request. The reporting code already treats 3.2-rc.6, 3.2-rc.7 and 3.2 as one family (reporting/feed/snapshot.py:257, reporting/submissions/models.py:41).

What sellers do today

To keep serving rc3 buyers, Embedded Sales Agent overwrites adcp.validation.envelope.SUPPORTED_WIRE_VERSIONS. It also replaces adcp.validation.envelope.detect_wire_version with a wrapper that returns "3.2" for "3.2-rc.7". That works only because create_tool_caller imports detect_wire_version inside the function body on every call, which is an internal detail. The triage on #883 named the correct shape for this: an explicit alias with a pinned test, not a pattern match.

Ask

Either of these would remove the monkeypatch:

  1. Ship a bridge in the SDK: accept 3.2-rc.7 and validate and serve it as 3.2, at least for the 8.0.x line.
  2. Or add a public, explicit seller-side option, for example serve(..., adcp_version_aliases={"3.2-rc.7": "3.2"}). It would add the alias to the accepted wire versions, route validation to the target bundle, and advertise the alias in supported_versions.

Activity

  1. added
    bugSomething isn't working
    enhancementNew feature or request
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Oct 2, 2026
  2. bokelley commented on Oct 2, 2026

    @bokelley
    ContributorAuthor

    Triage

    Classification: Bug (production regression) + Feature request (public alias API)
    Bucket(s): validation, client — no matching repo labels found for these; noted for label-gap tracking
    Status: ready-to-implement
    Milestone: 8.0.1 (bug fix); alias API as separate 8.1.0

    What the experts said:

    • ad-tech-protocol-expert: Aliasing "3.2-rc.7" → "3.2" is semantically sound given an additive-only rc→stable transition; is_adcp_version_at_least and _compare_prerelease in _version.py already encode this; the reporting subsystem already treats rc.6/rc.7/3.2 as one family. Ship the internal bridge as a patch (8.0.1); defer the public adcp_version_aliases= API to a separate 8.1.0 minor.
    • code-reviewer: Rejects the static alias-table approach (stale entries pile up, every future RC needs a new entry). Recommends semantic pre-release stripping instead: after normalize_to_release_precision yields a value not in supported, check whether normalized.split("-", 1)[0] (the stable base) is in supported and return that. Two-line fix, handles all future RC strings with zero code changes at RC time. Implementation is narrow-scope / low-entropy but requires the semantic strategy to be specified explicitly, otherwise a naive implementation would reach for a static map.

    My take: Both experts converge — the fix is non-breaking, additive, and the semantic stripping approach is clearly better architecture than a static alias map. The client-side resolve_adcp_version return value must be the base string ("3.2"), not the rc string ("3.2-rc.7"), since the function contract requires a wire-ready release-precision value. The public alias API is a legitimate follow-on feature but is not needed to close this regression.

    Implementation brief:

    • src/adcp/validation/envelope.py — detect_wire_version (lines 98–99): After normalized not in supported, add a pre-release base fallback before raising UnsupportedVersionError:

      if normalized not in supported:
          base = normalized.split("-", 1)[0]
          if base in supported:
              return base
          raise UnsupportedVersionError(explicit, supported)

      This returns the stable base ("3.2") when the server knows that version, without changing what normalize_to_release_precision emits.

    • src/adcp/_version.py — resolve_adcp_version (lines 218–223): Apply the same fallback after normalize_to_release_precision(raw) — if normalized not in supported but normalized.split("-", 1)[0] is in get_supported_adcp_versions(), return the base. Update the ConfigurationError message to note that RC strings for supported base versions are also accepted, so "3.3-rc.1" gives a clear error when "3.3" isn't known yet.

    • Required tests (tests/test_validation_envelope.py + tests/test_adcp_version_option.py):

      • detect_wire_version({"adcp_version": "3.2-rc.7"}, supported=...) → "3.2" (primary regression)
      • detect_wire_version({"adcp_version": "3.1-rc.7"}, supported=(..., "3.1")) → "3.1" (generality)
      • detect_wire_version({"adcp_version": "3.3-rc.1"}, supported=("3.0", "3.1", "3.2")) → raises UnsupportedVersionError (no stable base in supported)
      • resolve_adcp_version("3.2-rc.7") → "3.2"; resolve_adcp_version("3.3-rc.1") → raises ConfigurationError
      • Full regression: all currently-accepted values continue to return the same results
    • Non-breaking rationale: Purely additive — previously-rejected wire values now succeed, no existing accepted value changes behavior. COMPATIBLE_ADCP_VERSIONS itself need not change; the fallback acts at the acceptance check, not at the supported-set definition.

    • Do not change: normalize_to_release_precision (intentionally preserves pre-release tags), SUPPORTED_WIRE_VERSIONS definition, or .github/** / pyproject.toml.


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


    Generated by Claude Code

  3. added and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Oct 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions