feat(decisioning): ProposalManager v1.5 core primitives — store, recipe, capabilities, lifecycle helpers (#538-impl)

Lands the foundation for v1.5 proposal lifecycle work per
docs/proposals/proposal-manager-v15-design.md (PR #538):

- proposal_store.py: ProposalStore Protocol + InMemoryProposalStore
  reference impl with state-machine guards (DRAFT → COMMITTED → CONSUMED).
  Includes get_by_media_buy_id reverse-index for the single-ledger
  recipe-persistence design (D1, D3). create_dev_proposal_store()
  factory warns on construction. is_durable=False for the in-memory
  ref mirrors TaskRegistry posture.
- recipe.py: CapabilityOverlap dataclass with four typed axes
  (pricing_models, targeting_dimensions, delivery_types, signal_types).
  No extras dict per § D4 — adopters subclass. Recipe gains optional
  capability_overlap field.
- proposal_manager.py: ProposalCapabilities adds finalize +
  expires_at_grace_seconds. ProposalManager Protocol adds
  finalize_proposal returning union (FinalizeProposalSuccess |
  TaskHandoff[FinalizeProposalSuccess]) — single method per § D2,
  matching the create_media_buy precedent. Adds typed
  FinalizeProposalRequest / FinalizeProposalSuccess dataclasses.
  multi_decisioning retained for v1 source-compat but framework no
  longer reads it (Resolutions §6).
- proposal_lifecycle.py: framework intercept seam parallel to
  refine.py / webhook_emit.py. Carries enforce_proposal_expiry (D7),
  validate_capability_overlap (D4 buyer-request gate),
  validate_overlap_subset_of_wire (D4 round-4 drift check),
  detect_finalize_action helper, and structured log emit helpers
  per § Observability (proposal.draft_persisted, proposal.finalized,
  proposal.expired, proposal.consumed).
- platform_router.py: adds proposal_stores= constructor kwarg with
  orphan-key validation + cross-store consistency check (D5). Hard
  error at construction when finalize=True without a wired store —
  the error message names the exact kwarg to add.
- context.py: RequestContext.recipes field typed as Mapping[str, Recipe]
  per § D3.
- tests/test_error_code_conformance.py: PROPOSAL_NOT_FOUND added to
  KNOWN_NON_SPEC_CODES (PROPOSAL_EXPIRED + PROPOSAL_NOT_COMMITTED
  already in canonical 3.0 enum). Cites adcp#4043 spec issue.

Out of this commit (follow-up): full dispatch wiring for finalize
interception in get_products and create_media_buy(proposal_id=...);
unit tests; the v1.5 hello example.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: bokelley

src/adcp/decisioning/__init__.py

@@ -123,12 +123,21 @@ def create_media_buy(
     validate_property_list_config,
 )
 from adcp.decisioning.proposal_manager import (
+    FinalizeProposalRequest,
+    FinalizeProposalSuccess,
     MockProposalManager,
     ProposalCapabilities,
     ProposalManager,
     SalesSpecialism,
 )
-from adcp.decisioning.recipe import Recipe
+from adcp.decisioning.proposal_store import (
+    InMemoryProposalStore,
+    ProposalRecord,
+    ProposalState,
+    ProposalStore,
+    create_dev_proposal_store,
+)
+from adcp.decisioning.recipe import CapabilityOverlap, Recipe
 from adcp.decisioning.refine import (
     RefinementOutcome,
     RefinementStatus,
@@ -331,6 +340,14 @@ def __init__(self, *args: object, **kwargs: object) -> None:
     "Proposal",
     "ProposalCapabilities",
     "ProposalManager",
+    "ProposalRecord",
+    "ProposalState",
+    "ProposalStore",
+    "InMemoryProposalStore",
+    "FinalizeProposalRequest",
+    "FinalizeProposalSuccess",
+    "CapabilityOverlap",
+    "create_dev_proposal_store",
     "PropertyList",
     "PropertyListFetcher",
     "PropertyListReference",

src/adcp/decisioning/context.py

@@ -28,6 +28,7 @@
 from adcp.server.base import ToolContext
 
 if TYPE_CHECKING:
+    from adcp.decisioning.recipe import Recipe
     from adcp.decisioning.registry import (
         BuyerAgent,
         Credential,
@@ -534,6 +535,12 @@ class RequestContext(ToolContext, Generic[TMeta]):
     now: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
     state: StateReader = field(default_factory=_make_default_state_reader)
     resolve: ResourceResolver = field(default_factory=_make_default_resolver)
+    # ``recipes`` — populated by the framework on dispatch paths that
+    # hydrate a proposal (post-finalize ``create_media_buy`` /
+    # ``update_media_buy`` / ``get_media_buy_delivery``). Empty mapping
+    # by default so legacy / non-proposal flows see the v1 shape. See
+    # ``docs/proposals/proposal-manager-v15-design.md`` § D3.
+    recipes: Mapping[str, Recipe] = field(default_factory=dict)
 
     def handoff_to_task(
         self,

src/adcp/decisioning/platform_router.py

@@ -121,6 +121,7 @@
     from adcp.decisioning.accounts import AccountStore
     from adcp.decisioning.context import RequestContext
     from adcp.decisioning.proposal_manager import ProposalManager
+    from adcp.decisioning.proposal_store import ProposalStore
 
 
 # Every specialism Protocol the framework knows about. New Protocol
@@ -325,6 +326,7 @@ def __init__(
         platforms: Mapping[str, DecisioningPlatform],
         capabilities: DecisioningCapabilities,
         proposal_managers: Mapping[str, ProposalManager] | None = None,
+        proposal_stores: Mapping[str, ProposalStore] | None = None,
     ) -> None:
         if not platforms:
             raise ValueError(
@@ -351,6 +353,36 @@ def __init__(
                     f"orphan tenant_id(s): {sorted(orphans)}"
                 )
 
+        # Per-tenant ProposalStore binding (v1.5 § D5). Same orphan
+        # validation; no auto-allocation — finalize-capable managers
+        # without a wired store are a hard error so multi-worker
+        # deployments don't silently lose proposals at the first
+        # worker that didn't see put_draft.
+        self._proposal_stores: dict[str, ProposalStore] = dict(proposal_stores or {})
+        if self._proposal_stores:
+            orphans = set(self._proposal_stores) - set(self._platforms)
+            if orphans:
+                raise ValueError(
+                    f"proposal_stores keys must be a subset of platforms keys; "
+                    f"orphan tenant_id(s): {sorted(orphans)}"
+                )
+
+        # Cross-store consistency check: a tenant declaring
+        # finalize=True needs a wired store. The error message names
+        # the exact kwarg to add — adopters get a 30-second copy-paste
+        # rather than a debugging session at first finalize request.
+        for tenant_id, manager in self._proposal_managers.items():
+            caps = getattr(manager, "capabilities", None)
+            finalize_supported = bool(getattr(caps, "finalize", False))
+            if finalize_supported and tenant_id not in self._proposal_stores:
+                raise ValueError(
+                    f"Tenant {tenant_id!r} wired a ProposalManager declaring "
+                    f"finalize=True, but no ProposalStore was registered for "
+                    f"that tenant. Wire one via "
+                    f"proposal_stores={{{tenant_id!r}: InMemoryProposalStore()}}, "
+                    "or remove the finalize capability."
+                )
+
         self.accounts = accounts
         self.capabilities = capabilities
 
@@ -585,5 +617,17 @@ def proposal_manager_for_tenant(self, tenant_id: str) -> ProposalManager | None:
         """
         return self._proposal_managers.get(tenant_id)
 
+    def proposal_store_for_tenant(self, tenant_id: str) -> ProposalStore | None:
+        """Return the :class:`ProposalStore` for ``tenant_id``, or
+        ``None`` when the tenant has no store wired.
+
+        Tenants without a wired store cannot dispatch finalize / expiry
+        / consume paths — the cross-store consistency check at
+        construction prevents declaring ``finalize=True`` without a
+        store, but tenants running pure-catalog mode with no finalize
+        legitimately have no store.
+        """
+        return self._proposal_stores.get(tenant_id)
+
 
 __all__ = ["PlatformRouter"]