feat(decisioning): property_list resolver + intersection helper for get_products

[bokelley]

Motivation

GetProductsRequest.property_list is {agent_url, list_id, auth_token?} — a reference to an externally-managed list of properties the buyer has been authorized to spend on. The seller is expected to fetch the list from the buyer's agent, intersect against each product's publisher_properties, and set property_list_applied: true in the response.

This is directly capability-gated already: RequiredFeatures.property_list_filtering (src/adcp/types/generated_poc/core/media_buy_features.py:18) exists on both buyer-side filter and seller capabilities response. Every adopter that wants to claim this capability writes the same fetch + intersect + flag-echo code. Salesagent already has it inline; the helper should live in the SDK.

Parent tracker: #491.

Current state

Salesagent has the canonical implementation inline:

• src/core/tools/products.py:65-91 — extract_product_property_ids (reads selection_type all/by_id/by_tag)
• src/core/tools/products.py:94-126 — should_include_product_for_property_list (handles property_targeting_allowed permissive vs strict mode)
• src/core/tools/products.py:129-142 — filter_products_by_property_list
• src/core/tools/products.py:404-424 — invocation site (calls resolve_property_list from src/core/property_list_resolver.py:42, then filters, sets the flag implicitly via the wire schema's property_list_applied)

SDK: nothing. MediaBuyHandler.get_products (src/adcp/decisioning/handler.py:1015-1033) doesn't touch property_list. The capability RequiredFeatures.property_list_filtering is wire-defined but the framework doesn't gate on it.

Proposed API

Capability-gated, framework intercepts post-adapter (mirrors auto-emit pattern):

# src/adcp/decisioning/property_list.py (new)

async def resolve_property_list(
    ref: PropertyList,
    *,
    fetcher: PropertyListFetcher,
) -> set[str]:
    \"\"\"Fetch the list from `ref.agent_url` and return the set of allowed
    property_ids. Adopter supplies a `PropertyListFetcher` to plug in
    their HTTP client / auth.\"\"\"

def filter_products_by_property_list(
    products: list[Product],
    allowed_property_ids: set[str],
) -> list[Product]:
    \"\"\"Mirrors salesagent's logic: respects publisher_properties.selection_type
    ('all' = always include, 'by_id' = intersect, 'by_tag' = exclude),
    and respects product.property_targeting_allowed (False = strict subset
    required, True = any intersection suffices).\"\"\"

Capability declaration on DecisioningCapabilities:

caps = DecisioningCapabilities(
    media_buy=MediaBuy(
        execution=Execution(
            features=Features(property_list_filtering=True),
        ),
    ),
)
# When True, framework runs filter post-adapter and sets
# response.property_list_applied = True. When False, framework
# leaves request.property_list untouched and the adopter handles it
# (or ignores it).

Acceptance criteria

• filter_products_by_property_list matches salesagent's three-mode logic (all / strict / permissive) — port the salesagent test suite
• Framework runs the filter only when capability is declared AND req.property_list is present
• Sets response.property_list_applied = True when filter applied
• Adopter-supplied PropertyListFetcher protocol (no hidden HTTP client)
• Fetch failures surface as AdcpError with recovery='transient', mirroring salesagent's behavior
• validate_platform warns when property_list_filtering=True is declared but no fetcher is wired
• Test: product with selection_type='all' always passes
• Test: product with property_targeting_allowed=False requires full subset
• Test: auth_token threaded through to the fetcher

Out of scope

• The list_property_lists / create_property_list task family (already wired in handler at lines 1814-1909)
• Caching the fetched list across requests (out of scope for v1; framework calls fetcher every time)
• Seller-side property-list publishing (separate from the buyer-supplied filter)

Cross-references

• Wire capability: src/adcp/types/generated_poc/core/media_buy_features.py:18 (property_list_filtering)
• Wire request shape: src/adcp/types/generated_poc/bundled/media_buy/get_products_request.py:1178-1191 (PropertyList)
• Wire response flag: src/adcp/types/generated_poc/bundled/media_buy/get_products_response.py:4538-4543 (property_list_applied)
• Salesagent helpers (port these): src/core/tools/products.py:65-142
• Salesagent fetcher: src/core/property_list_resolver.py
• Reference pattern: src/adcp/decisioning/webhook_emit.py
• Parent tracker: feat(decisioning): built-in helpers for buyer-side request-shape parameters on get_products (parent tracker) #491
• Migration guide: docs: salesagent → adcp Python SDK migration guide #489

[bokelley]

Triage complete — draft PR opened

Classification: Execute (non-breaking additive feature, clear spec semantics, mirrors established framework patterns)

Draft PR: #500

---

Expert findings

Protocol expert (ad-tech-protocol-expert)

• Confirmed by_tag selection cannot be matched against property ID lists — correct to always exclude these entries from ID-based filtering
• Confirmed property_targeting_allowed strict/permissive semantics as specified
• Confirmed model_copy(update=…) is the correct Pydantic v2 pattern to avoid aliasing the platform's return value

DX expert (adtech-product-expert / dx-expert)

• Confirmed PropertyListFetcher is NOT redundant with ResourceResolver — ResourceResolver.property_list() returns a wire reference object; PropertyListFetcher.fetch() fetches the list contents from the buyer agent. Different abstraction levels, both required.
• Flagged: validate_property_list_config must be exported publicly from adcp.decisioning so self-managed adopters (who push filtering into their own get_products) can call the boot guard themselves. Fixed.

Code reviewer (code-reviewer)

• Blocker (fixed): {exc} interpolated into the wire AdcpError message was a credential-leak risk — upstream HTTP exception reprs can carry auth_token values from response bodies. Fixed: exception logged server-side via logger.warning, not included in message or details.
• Blocker (fixed): Duplicate getattr chain (platform.capabilities.media_buy.features.property_list_filtering) appeared in both handler.py and serve.py. Fixed by extracting property_list_capability_enabled(platform) helper in property_list.py.

---

What was implemented

• src/adcp/decisioning/property_list.py — new module with PropertyListFetcher, resolve_property_list, filter_products_by_property_list, maybe_apply_property_list_filter, validate_property_list_config, property_list_capability_enabled
• src/adcp/decisioning/handler.py — post-adapter gate wired into get_products shim
• src/adcp/decisioning/serve.py — boot-time validate_property_list_config + property_list_fetcher= param on create_adcp_server_from_platform and serve()
• src/adcp/decisioning/__init__.py — public exports for all new symbols
• tests/test_decisioning_property_list.py — 30 tests; all passing; ruff + mypy clean

One note on the proposed API in the issue: MediaBuy(execution=Execution(features=Features(...))) references Execution.features which doesn't exist on the Execution class. The correct path is MediaBuy(features=Features(property_list_filtering=True)). The PR uses this correct path.

---

Generated by Claude Code