Repository navigation
Description
The AdCP 3.x SDK audit found that Python has substantial legacy continuation support, but no general buyer entry point that negotiates a catalog-to-purchase workflow across 3.0, 3.1, and 3.2. An application upgrading its SDK should be able to keep buying under the older seller's semantics without maintaining two application workflows.
Audited release: adcp==8.0.0b14, source 813cf2ae. The audit ran 180 version, dispatch, lifecycle, and continuation tests. This describes that release; check current main before implementation.
What already works
- feat: implement durable legacy purchase continuation coordinator for AdCP 3.2 #1057 and merged feat(compat): add legacy purchase continuation coordinator #1059 provide
adcp.compat.purchase_continuation.LegacyPurchaseCoordinator, stores, replay, and reconciliation support. - Compact client methods dispatch the same-named task. They do not automatically select
get_products/create_media_buyon an older seller. - Existing server dispatch supports older callers. Do not replace working legacy methods or require compact-native sellers for an ordinary legacy purchase.
Scope and acceptance
- Provide and document an explicit SDK-local negotiated catalog/purchase helper using existing client methods and continuation machinery. Keep native task methods and signatures intact. Start with ordinary product listing and buying; this issue does not require wholesale parity with every TypeScript coordinator operation.
- Select advertised tools and the usable served contract. Support older seller responses without new feed/pricing metadata; preserve explicit loss reporting and the current opt-ins for weaker guarantees.
- Cover country-filtered listing and tokenless legacy purchase, including account/selection binding, idempotent retries, and recovery. Do not create fake feed tokens or infer stronger guarantees from successful legacy creation.
- Add 3.0/3.1/3.2 buyer–seller regression cases for both directions. New sellers must retain registered legacy handlers; unchanged older calls must continue to reach them. Distinguish routing tests from seller field-preservation and purchase tests.
- Include omitted version metadata, stable minor downshift, exact prerelease pins, and served-version validation. The audited payload resolver requires an explicit normalized version to be in its supported set; that alone is not an automatic buyer negotiation layer. Keep the distinction between an SDK default and an explicit contract requirement.
- Document which guarantees degrade and which operations remain application-owned. Use the current protocol version policy and existing compatibility losses.
Coordinate seller field-preservation cases with adcp#7403. This is an adoption helper and regression-coverage follow-up, not a request to change native signatures, introduce another loss-consent policy, or reimplement #1057.
Activity
bokelley commentedon Sep 11, 2026
Triage
Classification: Feature request
Bucket(s): client (label gap: no
clientlabel exists in this repo)Status: ready-to-implement
What the experts said:
LegacyPurchaseCoordinatorwas designed for this composition. Stopping short of TypeScript parity is consistent with the existing_SOURCE_VERSION_REboundary. Three open questions need design answers before coding (see brief below).My take: The continuation infrastructure from #1059 is solid and ready to host this orchestration layer. The issue is well-scoped — add a version-negotiating helper that drives
get_products→ continuation →create_media_buy, not a rewrite of anything that ships. The main pre-implementation questions are about served-version binding vs. downshift semantics and the adcp#7403 field-preservation coordination.Implementation brief:
New file:
src/adcp/compat/negotiated_catalog_purchase.py— aNegotiatedCatalogBuyer(or similar) class that:get_productsvia the existing client methodsLegacyPurchaseCoordinator.issue_legacy_create_continuationLegacyPurchaseCoordinator.continue_legacy_purchasefor the purchase stepAdapter registry gap:
src/adcp/compat/legacy/__init__.pycurrently only registers "2.5" adapters. Implementation must either add 3.0/3.1 native client-path entries or bypass the legacy adapter registry for those versions. This decision affects whether newsrc/adcp/compat/legacy/v3_0/andv3_1/stub modules are needed.Served-version binding:
_validate_source_discoveryvalidates against thesource_adcp_version. If a 3.2 seller responds with 3.2-only fields, the helper must use the actual response version as the binding key — silent downshift to 3.1 would fail schema validation. Clarify in the implementation: a 3.2 response on the legacy path → hard error + point tobuy_products, unless adcp#7403 settles the field-preservation contract.Tests:
tests/test_negotiated_catalog_purchase.pycovering the 3.0/3.1/3.2 buyer–seller matrix in both directions. Distinct routing tests from seller field-preservation and purchase tests per the acceptance criteria.Required checks:
pytest tests/test_negotiated_catalog_purchase.py,mypy src/adcp/compat/negotiated_catalog_purchase.py,ruff check/black --check.Non-breaking rationale: Pure addition — new optional class, no signature changes to existing public surfaces (
LegacyPurchaseCoordinator,ADCPClient,ADCPHandler).Triaged by Claude Code. Session: https://claude.ai/code/session_015bZqfxAxneh8tVrd2w7Ehq
Generated by Claude Code