Title: ProposalStore: ship PgProposalStore + framework-level package derivation from allocations · Issue #727 · adcontextprotocol/adcp-client-python · GitHub
Open Graph Title: ProposalStore: ship PgProposalStore + framework-level package derivation from allocations · Issue #727 · adcontextprotocol/adcp-client-python
X Title: ProposalStore: ship PgProposalStore + framework-level package derivation from allocations · Issue #727 · adcontextprotocol/adcp-client-python
Description: Summary Two adopter-side pieces every production seller wires today that belong upstream. Same upstream-vs-local-workaround pattern as #712 (WWW-Authenticate), #714 (replayed: true), and #720 (multi-header auth) — proven productive this ...
Open Graph Description: Summary Two adopter-side pieces every production seller wires today that belong upstream. Same upstream-vs-local-workaround pattern as #712 (WWW-Authenticate), #714 (replayed: true), and #720 (mult...
X Description: Summary Two adopter-side pieces every production seller wires today that belong upstream. Same upstream-vs-local-workaround pattern as #712 (WWW-Authenticate), #714 (replayed: true), and #720 (mult...
Opengraph URL: https://github.com/adcontextprotocol/adcp-client-python/issues/727
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"ProposalStore: ship PgProposalStore + framework-level package derivation from allocations","articleBody":"## Summary\n\nTwo adopter-side pieces every production seller wires today that belong upstream. Same upstream-vs-local-workaround pattern as #712 (WWW-Authenticate), #714 (replayed: true), and #720 (multi-header auth) — proven productive this week (all three shipped in 5.4.0 and adopter code shrunk).\n\n## (1) ``PgProposalStore`` — concrete durable backing\n\nUpstream ships ``adcp.decisioning.InMemoryProposalStore`` (non-durable reference) + the ``ProposalStore`` Protocol. Every production adopter writes the same Postgres-backed implementation:\n\n* The same nine methods (``put_draft`` / ``get`` / ``commit`` / ``try_reserve_consumption`` / ``finalize_consumption`` / ``release_consumption`` / ``mark_consumed`` / ``discard`` / ``get_by_media_buy_id``).\n* The same ``SELECT … FOR UPDATE`` row-lock pattern for the CAS in ``try_reserve_consumption`` (Protocol contract).\n* The same composite primary key shape: ``(tenant_id, proposal_id)`` for multi-tenant scoping; partial unique on ``(tenant_id, media_buy_id) WHERE media_buy_id IS NOT NULL`` for ``get_by_media_buy_id``.\n* The same state-machine guards (``commit`` from non-DRAFT raises INTERNAL_ERROR, ``try_reserve_consumption`` from non-COMMITTED raises PROPOSAL_NOT_COMMITTED, etc.).\n\nThe Prebid salesagent fork shipped this as ``SalesAgentProposalStore`` in [bokelley/salesagent#390](https://github.com/bokelley/salesagent/pull/390) (~430 LOC core + tests). The implementation is mostly mechanical — same shape as ``IdempotencyStore.PgBackend`` adopters get for free.\n\n### Proposed API\n\n```python\nfrom adcp.decisioning.proposal_store import PgProposalStore\nfrom psycopg_pool import AsyncConnectionPool\n\npool = AsyncConnectionPool(DATABASE_URL, ...)\nstore = PgProposalStore(\n pool=pool,\n # Adopter chooses the table name to avoid collisions with existing\n # ``proposal_drafts`` / ``proposals`` tables. Defaults to the canonical\n # name; explicit prefix lets adopters with one Postgres serving multiple\n # adcp instances keep them scoped.\n table_name=\"adcp_proposal_drafts\",\n)\nPgProposalStore.MIGRATION # alembic-compatible upgrade/downgrade strings\n```\n\nSame shape as ``IdempotencyStore.PgBackend`` ships today.\n\n## (2) Framework-level package derivation from proposal allocations\n\nThe framework already:\n\n* Reserves the proposal via ``try_reserve_consumption`` (proposal_dispatch.py:585-588)\n* Hydrates ``ctx.recipes`` (line 607)\n* Documents that \"the spec allows the seller to derive packages from the proposal's allocations\" (line 590-593)\n\nBut then it punts: the seller's ``platform.create_media_buy`` is handed an empty ``req.packages`` and is expected to do the derivation. Every adopter writes essentially the same percentage math:\n\n```python\nfor allocation in proposal_payload[\"allocations\"]:\n pkg_budget = total_budget.amount * (allocation[\"allocation_percentage\"] / 100.0)\n packages.append(PackageRequest(\n product_id=allocation[\"product_id\"],\n budget=pkg_budget,\n pricing_option_id=allocation.get(\"pricing_option_id\"),\n ))\n```\n\nThe salesagent had to ship this seller-side just to pass the ``proposal_finalize/create_media_buy`` storyboard. So will every other seller declaring ``capabilities.refine=True`` or wiring a ProposalStore.\n\n### Proposed API — framework-level auto-injection\n\nIn ``proposal_dispatch.maybe_hydrate_recipes_for_create_media_buy``, after reserving the proposal: if ``req.packages`` is empty AND the proposal has ``allocations[]``, mutate ``req.packages`` to the derived list before dispatching to ``platform.create_media_buy``.\n\nThe seller's adapter sees a normal ``create_media_buy`` with populated packages — never needs to know it came from a proposal. Existing ``packages``-based paths (no ``proposal_id``) unchanged.\n\n### Override hook for non-default strategies\n\nSome sellers will want custom derivation logic — auction pricing options need ``bid_price``, multi-currency proposals need explicit currency, capability-overlap filtering may shape the package count. Expose a method on ``ProposalManager``:\n\n```python\nclass MyProposalManager:\n def derive_packages(\n self,\n proposal_payload: dict,\n total_budget: TotalBudget,\n recipes: Mapping[str, Recipe],\n ) -> list[PackageRequest]:\n \\\"\\\"\\\"Custom derivation. Framework calls this when proposal_id is set\n and req.packages is empty. Default implementation (when this method\n is absent) does even-percentage distribution per allocation.\\\"\\\"\\\"\n```\n\nAdopters with default behavior (even percentage split) leave the method off; the framework falls through to its built-in even-split derivation. ``SalesAgentProposalManager`` and most other minimal adopters delete their custom code; sellers with auction / multi-currency / complex inventory shaping override.\n\n### Standalone helper for sellers that need it\n\nEven if (2) ships, expose ``adcp.decisioning.derive_packages_from_proposal(...)`` as a public helper so adopters with workflows outside ``proposal_dispatch``'s auto-injection path can still call it. Mirror the shape ``IdempotencyStore.wrap`` exposes — auto-applied via decorator, also callable directly.\n\n## Why now\n\nFive days, four PRs (#712, #714, #720, plus the implicit #722/#723 wave), every one collapsed adopter code by 50-500 LOC. The pattern is reliable: defects and patterns in adopter ``decisioning/`` wiring are good candidates for the library. This issue closes two more.\n\n## Related\n\n- bokelley/salesagent#387 — adopter-side ProposalStore wiring tracker (closed when #390 + the upcoming derivation PR land)\n- bokelley/salesagent#390 — ``SalesAgentProposalStore`` PR (collapses to ~10 LOC once PgProposalStore ships upstream)\n- adcp 5.4.0 PRs #722/#724 / #723/#725 — adopter-API surface (factory kwargs + auto_commit_on_put_draft); this issue is the natural next step (concrete backings + auto-derivation)\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)","author":{"url":"https://github.com/bokelley","@type":"Person","name":"bokelley"},"datePublished":"2026-05-13T23:24:49Z","url":"https://github.com/adcontextprotocol/adcp-client-python/issues/727"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:823552ff-3921-0ea8-229a-5252dacdc6c2 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | E0A2:1F7384:C9689E:10B8959:6B00F6E1 |
| html-safe-nonce | 59e3ff4711d0d95f51d8f6b97a615a20b7943a1e308ceffb67f39aa370be0924 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJFMEEyOjFGNzM4NDpDOTY4OUU6MTBCODk1OTo2QjAwRjZFMSIsInZpc2l0b3JfaWQiOiI2MjE0MTI0MzE2NzY2ODI4MjU3IiwicmVnaW9uX2VkZ2UiOiJpYWQiLCJyZWdpb25fcmVuZGVyIjoiaWFkIn0= |
| visitor-hmac | 52676640b3c3c07cd1085fe788acfacef16d214564ce5bee20e3365d335032da |
| hovercard-subject-tag | issue:4441837610 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/adcontextprotocol/adcp-client-python/727/issue_layout |
| twitter:image | https://opengraph.githubassets.com/f70ee62b2ce1756d48235a8aa64bcaac6c4117148f5d0ef4cb152d3f0d98c61f/adcontextprotocol/adcp-client-python/issues/727 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/f70ee62b2ce1756d48235a8aa64bcaac6c4117148f5d0ef4cb152d3f0d98c61f/adcontextprotocol/adcp-client-python/issues/727 |
| og:image:alt | Summary Two adopter-side pieces every production seller wires today that belong upstream. Same upstream-vs-local-workaround pattern as #712 (WWW-Authenticate), #714 (replayed: true), and #720 (mult... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | bokelley |
| hostname | github.com |
| expected-hostname | github.com |
| None | 4ef498cbabcbe3c50befc7a5b743e7072ee770b4daf0e15e54801180d1fa91fc |
| turbo-cache-control | no-preview |
| go-import | github.com/adcontextprotocol/adcp-client-python git https://github.com/adcontextprotocol/adcp-client-python.git |
| octolytics-dimension-user_id | 221690821 |
| octolytics-dimension-user_login | adcontextprotocol |
| octolytics-dimension-repository_id | 1090305973 |
| octolytics-dimension-repository_nwo | adcontextprotocol/adcp-client-python |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 1090305973 |
| octolytics-dimension-repository_network_root_nwo | adcontextprotocol/adcp-client-python |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 9983dd5da06943f833c971dd5b6bc988e2858be5 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width