feat(decisioning): built-in helpers for buyer-side request-shape parameters on get_products (parent tracker)

[bokelley]

Motivation

get_products carries a number of request-shape parameters that are buyer-facing protocol concerns, not seller business logic: fields projection, pagination, property_list, time_budget, refine, plus the cross-tool implementation_config plumbing on create_media_buy. Every adopter writes substantively the same code to handle them. The framework should ship these as capability-gated helpers — same pattern as the F12 sync-completion webhook auto-emit (src/adcp/decisioning/webhook_emit.py): adopter declares the capability, framework intercepts at the right seam, business logic stays focused on inventory.

Brian's framing: "this is one of the many things we can do to help the user not have to build all these utilities."

Reference: salesagent today

Salesagent (src/core/tools/products.py:94-142) inlines its own filter_products_by_property_list / should_include_product_for_property_list. It does NOT handle fields, pagination, time_budget, or refine at all — those just pass through. implementation_config lookup runs inline in media_buy_create.py:2425-2466. Every adopter will rebuild the property-list helper; no adopter currently has the others.

Reference: SDK today

adcp.decisioning.handler.MediaBuyHandler.get_products (src/adcp/decisioning/handler.py:1015-1033) is a pure pass-through to _invoke_platform_method — no pre/post-processing, no capability gate, no projection. SalesPlatform.get_products (src/adcp/decisioning/specialisms/sales.py:105-119) hands the raw GetProductsRequest to the adopter and expects the raw GetProductsResponse back.

The auto-emit pattern (src/adcp/decisioning/webhook_emit.py) shows what "framework intercepts at the seam" looks like in this codebase — that's the reference design for every child issue.

Children (parallelizable — pick up in any order)

• feat(decisioning): built-in fields projection on get_products responses #492 — feat(decisioning): built-in fields projection on get_products responses — pure post-filter, no capability gate
• feat(decisioning): cursor-based pagination helper for list responses #493 — feat(decisioning): cursor-based pagination helper for list responses — opaque-cursor codec + framework_pagination capability
• feat(decisioning): property_list resolver + intersection helper for get_products #494 — feat(decisioning): property_list resolver + intersection helper for get_products — capability property_list_filtering (already wire-defined)
• feat(decisioning): time_budget deadline wrapper + incomplete projection on get_products #495 — feat(decisioning): time_budget deadline wrapper + incomplete projection on get_products — universal, IncrementalGetProducts opt-in for partial results
• feat(decisioning): refine[] flow scaffold for get_products (position-matched echo) #496 — feat(decisioning): refine[] flow scaffold for get_products (position-matched echo) — buying_mode='refine' + position-matched refinement_applied[] echo
• feat(decisioning): implementation_config lookup helper for create_media_buy #497 — feat(decisioning): implementation_config lookup helper for create_media_buy — ProductConfigStore protocol, scoped to create_media_buy first

Each child is independently scoped — no cross-dependency. They can land in any order.

Cross-references

• Migration doc: docs: salesagent → adcp Python SDK migration guide #489
• Auto-emit reference pattern: src/adcp/decisioning/webhook_emit.py
• Wire request: src/adcp/types/generated_poc/bundled/media_buy/get_products_request.py
• Wire response: src/adcp/types/generated_poc/bundled/media_buy/get_products_response.py
• Capabilities: src/adcp/types/generated_poc/core/media_buy_features.py (property_list_filtering already wire-defined)
• Salesagent reference: /src/core/tools/products.py, /src/core/tools/media_buy_create.py:2431-2466

Out of scope for this tracker

• Dynamic-product assembly from signals (salesagent has it, but no AdCP wire shape exists — speculative)
• Key-value targeting threading product → create_media_buy (salesagent-internal, no wire shape)
• Migration guide edits (handled in docs: salesagent → adcp Python SDK migration guide #489)
• Catalog/collection filter helper — same shape as property_list, but the adoption signal is weaker (salesagent doesn't implement it either). File a follow-up if a second adopter requests it.

[bokelley]

All six children landed:

• feat(decisioning): built-in fields projection on get_products responses #492 — fields projection → feat(decisioning): built-in fields projection on get_products responses #503
• feat(decisioning): cursor-based pagination helper for list responses #493 — pagination helper → feat(decisioning): cursor-based pagination helper for list responses #499
• feat(decisioning): property_list resolver + intersection helper for get_products #494 — property_list resolver → feat(decisioning): property_list resolver + intersection helper for get_products #500
• feat(decisioning): time_budget deadline wrapper + incomplete projection on get_products #495 — time_budget wrapper → feat(decisioning): time_budget deadline wrapper + incomplete projection on get_products #501
• feat(decisioning): refine[] flow scaffold for get_products (position-matched echo) #496 — refine[] scaffold → feat(decisioning): refine[] flow scaffold for get_products (#496) #505
• feat(decisioning): implementation_config lookup helper for create_media_buy #497 — implementation_config lookup → feat(decisioning): ProductConfigStore lookup helper for create_media_buy #498

Out-of-scope items (dynamic-product assembly, key-value targeting, catalog/collection filter, migration-doc edits) remain deferred per the tracker body.