feat(server): add a reverse legacy facade for compact media-buy handlers

[bokelley]

The AdCP 3.x SDK lifecycle audit separates two compatibility directions. #1146 owns the buyer-side coordinator (one modern buying workflow against older sellers). This issue owns the reverse, seller-side direction: an established buyer calling get_products / create_media_buy against a seller whose implementation is built around list_products / buy_products.

Today, registering or implementing compact handlers does not automatically implement the legacy handlers. Adopters therefore cannot move their seller core to the compact lifecycle and preserve established buyers without maintaining their own compatibility layer.

Desired adopter experience

A seller should be able to:

1. implement the compact lifecycle as its canonical business logic;
2. explicitly enable an SDK-provided legacy facade;
3. continue serving compatible legacy calls without duplicating purchase logic; and
4. receive a clear, fail-closed result when a legacy request cannot be represented without changing its semantics.

Native handler signatures must remain unchanged. A seller's explicit legacy implementation must take precedence over the facade, and facade dispatch must not recurse between legacy and compact handlers.

Scope and acceptance

• Design and implement an explicit server-side lifecycle facade for get_products -> list_products and create_media_buy -> buy_products. Keep it separate from the buyer coordinator in feat(media-buy): add a negotiated 3.x catalog purchase helper #1146, but reuse shared loss, continuation, replay, and version primitives where their semantics match.
• Treat the raw legacy request as authoritative. Preserve eligibility, account, selection, pricing, and identity constraints. Never reinterpret an eligibility predicate as delivery targeting or silently broaden a product result.
• Translate discovery only when every requested constraint is representable. Where compact offer filters cannot express a legacy predicate (including the sub-country coverage gap tracked by adcp#7403), dispatch to a retained native legacy implementation when configured or fail closed with a structured compatibility result.
• Bind a legacy purchase to durable discovery evidence sufficient for the compact purchase: seller/account/principal, selected product/package, served protocol, feed/catalog version, pricing version when required, accepted losses, and expiry. Do not fabricate feed or pricing versions.
• Make purchase redemption atomic and idempotent across retries and concurrent requests. Do not implement compatibility as a buy-then-sync compensating saga. Define crash/restart behavior and provide a pluggable durable store plus an in-memory test implementation.
• Advertise legacy capabilities only when the facade is enabled and its prerequisites are satisfied. Preserve native legacy handlers and compact handlers as independently callable protocol operations.
• Add behavioral tests for established 3.0/3.1 buyers against a compact-backed 3.2 seller, including successful discovery/purchase, unrepresentable filters, stale or mismatched discovery evidence, replay, concurrent redemption, restart recovery, native-handler precedence, and omitted/explicit version metadata.
• Run the applicable reverse-compatibility cases from the protocol repository's products-only-brief-compatibility vectors. Keep routing assertions, field-preservation assertions, response-schema validation, and completed-workflow assertions distinct.
• Add an upgrade guide showing how an existing seller moves its canonical implementation from get_products / create_media_buy to list_products / buy_products, how to enable the facade, what remains application-owned, and which requests must still be rejected or handled natively.
• Expose SDK-local fixtures/entry points needed by adcp#7439 to exercise the Python facade through real client/server helpers and validate the produced responses. The cross-language schema-driven harness itself remains owned by adcp#7439.

Non-goals

• Reimplementing the buyer-side negotiated workflow from feat(media-buy): add a negotiated 3.x catalog purchase helper #1146.
• Claiming that handler registration alone provides compatibility.
• Closing compact-schema expressiveness gaps such as adcp#7403 inside the SDK.
• Translating every proposal, refinement, control, or reporting operation in the first slice. Extend the same facade architecture after list -> buy is proven.
• Treating a schema-valid error or successful route as evidence of a completed purchase.

Coordination

• Audit and compatibility contract: adcp#7420
• Cross-language response-conformance evidence: adcp#7439
• Python buyer coordinator: feat(media-buy): add a negotiated 3.x catalog purchase helper #1146
• Go reverse-facade and durable-backend tracker: adcp-go#482

This issue completes the Python half of the two-direction compatibility model; it does not by itself establish full Python/Go/TypeScript parity. That claim requires the release-pinned conformance evidence tracked by adcp#7439.

[bokelley]

Triage

Classification: Feature request — server-side lifecycle compatibility facade
Bucket(s): handlers, middleware (neither label exists in this repo; gap noted)
Status: ready-for-human

What the experts said:

• ad-tech-protocol-expert: Protocol model is correct; existing LegacyPurchaseCoordinator covers the atomicity requirement; non-breaking only if the facade is strictly opt-in (not auto-installed into the dispatch table). The predicate-representability mapping (legacy filter → compact offer filter) needs a canonical reference before implementation — adcp#7420 is the only cited source and it is not yet merged.
• dx-expert: Core scope (facade + durable store + behavioral tests) is tightly coupled and appropriate as one unit; acceptance criteria 9–10 (upgrade guide, cross-language SDK fixtures for adcp#7439) are separable and should become explicit follow-on issues to reduce schedule risk.
• code-reviewer: ~70% of the work already exists in src/adcp/compat/purchase_continuation.py (coordinator, store Protocol, in-memory impl, CAS chain). Net-new is the dispatch shim in decisioning/dispatch.py. Key design blocker: IdempotencyStore.wrap and LegacyPurchaseCoordinator.claim are independent key-scoping systems — concurrent calls on the same idempotency key can double-execute. One must own "already executed" semantics for facade-routed calls.

My take: Direction is architecturally sound and unblocked on external specs (adcp#7439 is a downstream output, not a prerequisite). Implementation is ready to begin after two design decisions are made: (1) how to reconcile IdempotencyStore / LegacyPurchaseCoordinator key ownership for facade-routed calls, and (2) whether the upgrade guide and cross-language fixture criteria ship with the facade or as follow-on issues.

Asking @bokelley to confirm the IdempotencyStore ownership decision and authorize the scope split before work begins.

---

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

---

Generated by Claude Code