feat(decisioning): ProposalManager v1 — Protocol + MockProposalManager forwarder + tenant binding

[bokelley]

Summary

Foundation for the two-platform composition established in the product architecture design doc (#502, docs/proposals/product-architecture.md). Adopters can now wire a separate ProposalManager that handles get_products / refine, while DecisioningPlatform handles create_media_buy and lifecycle. The recipe (typed implementation_config) is the contract between them.

After this PR, the on-ramp for new adopters is: point a MockProposalManager at a running bin/adcp.js mock-server <specialism> and ship a working seller agent with zero adopter code on the proposal side. Real proposal logic lands incrementally as a subclass that replaces mock-served slices.

What this PR ships (v1 scope)

• ProposalManager Protocol — get_products (required) + refine_products (optional, capability-gated). Sync or async, detected via asyncio.iscoroutinefunction. Same convention as SalesPlatform.
• ProposalCapabilities dataclass — sales_specialism: Literal["sales-guaranteed", "sales-non-guaranteed"] + capability flags (refine, dynamic_products, rate_card_pricing, availability_reservations, multi_decisioning).
• Recipe Pydantic base with recipe_kind: str discriminator. Adopter subclasses declare typed fields. v1 treats Product.implementation_config as opaque dict[str, Any] from the framework; adopters who want typed recipes round-trip via model_dump() / model_validate() themselves.
• MockProposalManager — v1 default forwarder. POSTs get_products / refine_products requests to a configured mock_upstream_url (running bin/adcp.js mock-server <specialism>). Symmetric with Phase 2's DecisioningPlatform.upstream_for(ctx) mock-mode pattern. Reuses UpstreamHttpClient.
• Tenant binding — new proposal_manager= kwarg on serve() / create_adcp_server_from_platform(). The dispatcher in PlatformHandler.get_products routes to the wired manager when present; falls through to platform.get_products otherwise.
• Refine routing — buying_mode='refine' + capabilities.refine + refine_products method present → dispatch to refine_products; any condition missing → falls through to get_products.
• Backward-compatible by construction — every existing example keeps working unchanged. ProposalManager is opt-in.
• Tests — tests/test_proposal_manager.py (16 tests).
• Example — examples/hello_proposal_manager.py.

Out of scope (subsequent PRs — flagged in module docstring)

• Session cache for in-flight proposals
• finalize transition handling
• expires_at enforcement
• capability_overlap declaration on Recipe + framework validation
• Recipe persistence + hydration through buy lifecycle
• Per-tenant ProposalManager via PlatformRouter
• MIGRATION.md updates for v3 reference seller (separate doc PR)

Module layout

Picked flat files (proposal_manager.py, recipe.py directly under decisioning/) over a proposal/ submodule. Existing decisioning module is flat; adding a submodule for two files would break local convention.

Dispatcher routing (pseudocode)

# PlatformHandler.get_products(params, context)
if proposal_manager is not None:
    target = proposal_manager
    method_name = self._select_proposal_method(params)
    # _select_proposal_method returns 'refine_products' iff:
    #   - params.buying_mode == 'refine'
    #   - manager.capabilities.refine is True
    #   - hasattr(manager, 'refine_products')
    # otherwise returns 'get_products'
else:
    target = platform              # back-compat fall-through
    method_name = 'get_products'

response = await _invoke_platform_method(target, method_name, params, ctx, ...)
if params.fields:
    response = _project_product_fields(response, params.fields)
return response

Tenant binding

Wired on serve() — a single ProposalManager per serve() call applies to every tenant. Per-tenant managers via PlatformRouter are deferred (flagged in the architecture doc § "Open questions").

Notes during implementation

• The architecture doc's sketch said refine_products(req: RefineProductsRequest, ...). Per the spec, refine is a buying_mode value on GetProductsRequest — there's no separate RefineProductsRequest type. Updated the Protocol to use GetProductsRequest for both methods and route by buying_mode inside the dispatcher.
• AdcpError exposes message via args[0], not .message.
• GetProductsRequest.buying_mode is a generated BuyingMode enum; the dispatcher normalizes via getattr(buying_mode, 'value', buying_mode).

References

• Design doc: docs(proposals): product architecture — layered model + two-platform composition #502 (docs/proposals/product-architecture.md)
• Parent tracker for buyer-side helpers: feat(decisioning): built-in helpers for buyer-side request-shape parameters on get_products (parent tracker) #491
• Phase 2 mock-mode dispatch: feat(decisioning): mock-mode upstream URL routing (Phase 2) #487 (DecisioningPlatform.upstream_for)
• ProductConfigStore pattern: feat(decisioning): ProductConfigStore lookup helper for create_media_buy #498

Test plan

• ruff check on new + modified files clean
• mypy on new + modified files clean
• New tests/test_proposal_manager.py: 16/16 pass
• Full regression: 3718 passed, 32 skipped, 1 xfailed
• examples/hello_proposal_manager.py imports + composes without error

🤖 Generated with Claude Code