Skip to content

Project native postal capabilities to legacy fused shape for AdCP 3.0 callers #951

Closed

Description

@bokelley

Summary

Python servers built on adcp should have a shared/version-aware projection for postal-area capability declarations in get_adcp_capabilities.

AdCP 3.1 introduces native country-keyed postal support:

{
  "media_buy": {
    "execution": {
      "targeting": {
        "geo_postal_areas": {
          "US": ["zip"]
        }
      }
    }
  }
}

AdCP 3.0 clients and current 3.0 JS SDK validation expect the deprecated fused boolean shape:

{
  "media_buy": {
    "execution": {
      "targeting": {
        "geo_postal_areas": {
          "us_zip": true
        }
      }
    }
  }
}

ESA had to add a local compatibility shim in scope3data/embedded-sales-agent#9: keep the router's native 3.1 DecisioningCapabilities as the source of truth, but downgrade geo_postal_areas to the legacy fused shape for no-version / 3.0* capability callers. Explicit 3.1* callers keep the native country-keyed shape.

Why this should be upstream

This is protocol-version response projection, not seller/GAM-specific business logic. Each seller should still decide which postal systems it can honor, but the Python SDK should own how a DecisioningCapabilities object is serialized for a 3.0 vs 3.1 caller.

Without SDK-level projection, every Python seller that declares native postal capabilities has to rediscover and duplicate the downgrade mapping:

  • ("US", "zip") -> "us_zip"
  • ("US", "zip_plus_four") -> "us_zip_plus_four"
  • etc.

Expected behavior

  • A server may define capabilities internally using the native 3.1 GeoPostalAreas country-keyed model.
  • get_adcp_capabilities for no-version / 3.0* callers projects representable postal support to deprecated fused booleans.
  • get_adcp_capabilities for explicit 3.1* callers emits the native country-keyed shape.
  • The projection should not invent support: it should only transform systems present in the server-provided capability object.
  • Non-representable native 3.1 systems should either be omitted from the 3.0 projection or fail loudly, depending on the SDK's existing compatibility policy.

ESA workaround reference

ESA PR: https://github.com/scope3data/embedded-sales-agent/pull/9

Local workaround behavior added there:

  • base/native: GeoPostalAreas(US=["zip"]) serializes as {"US": ["zip"]}
  • legacy 3.0/no-version projection: {"us_zip": true}
  • explicit 3.1 projection: keeps {"US": ["zip"]}

Related JS SDK note

The JS SDK's current 3.1 dist-tag (@adcp/sdk@adcp-3.1, currently 9.0.0-beta.29) appears to accept/normalize both native country-keyed postal capability maps and deprecated fused booleans. The gap here is specifically the Python SDK/server-side projection for callers that still negotiate/assume AdCP 3.0.

Activity

  1. added
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Jun 14, 2026
  2. bokelley commented on Jun 14, 2026

    @bokelley
    ContributorAuthor

    Triage

    Classification: Feature request
    Bucket(s): handlers (get_adcp_capabilities response projection)
    Status: ready-to-implement
    Milestone: omitted (no version named in issue)

    What the experts said:

    • ad-tech-protocol-expert: Protocol-correct — the spec permits conditional emission of legacy boolean aliases for version-negotiated traffic; the "3.0" default for unnegotiated traffic in validation/envelope.py means the version gate is already drawn correctly. Systems with no 3.0 equivalent (BR cep, IN pin, ZA postal_code) should be silently omitted, not rejected. Additive behavior change for native-field adopters calling 3.0 clients must be called out in release notes.
    • code-reviewer: The native→legacy translation path (e.g. US: ["zip", "zip_plus_four"] → us_zip: True, us_zip_plus_four: True) is non-trivial and must be fully implemented and tested before merge. Projection helper belongs in src/adcp/types/projections.py, not inline in the 1780-line handler. Import must be from adcp.types (not generated_poc/ directly) to comply with layering contract.
    • dx-expert: Strong positive — always-on is the correct default (zero API surface change for sellers), as opting in would create a "broken by default until you find the flag" anti-pattern. Migration story for ESA-style manual shims is documentation only (no runtime warning needed).

    My take: All three experts converge. The change is additive — it corrects currently broken output (3.0 callers receiving unparseable native format) and is a no-op for adopters using only legacy boolean fields or no postal capabilities. Non-breaking by the SDK's own definition; the behavior change for native-field adopters is a correctness fix, not a regression.

    Implementation scope:

    • src/adcp/types/projections.py — new helper project_geo_postal_areas(value: GeoPostalAreas, version: str | None) -> dict. For version >= "3.1": emit native country-keyed fields only. For "3.0" / None: translate native fields to legacy boolean aliases using LegacyPostalCodeSystem as the authoritative mapping (US/["zip"] → us_zip=True, US/["zip_plus_four"] → us_zip_plus_four=True, etc.); silently omit 3.1-only systems (BR, IN, ZA) with no legacy counterpart. Import GeoPostalAreas from adcp.types (not generated_poc/).
    • src/adcp/decisioning/handler.py — in the get_adcp_capabilities path (around lines 1719–1720 where model_dump(mode="json", exclude_none=True) fires), call project_geo_postal_areas on the geo_postal_areas field before dict insertion, keyed on ctx.resolved_adcp_version.
    • tests/test_decisioning_capabilities_projection.py — add six test cases: (1) native fields → native output for 3.1 callers; (2) native fields → legacy boolean output for 3.0 callers (the translation path); (3) legacy boolean fields only → legacy output for 3.0 callers (no change); (4) legacy boolean fields only → native output for 3.1 callers (reverse translation); (5) None version falls back to 3.0 behavior; (6) no postal capabilities → field absent regardless of version.
    • Docstrings — DecisioningCapabilities note that geo_postal_areas is auto-projected for pre-3.1 callers; get_adcp_capabilities_for_request note that manual postal projection is no longer needed and the override fires before auto-projection.
    • Changelog — note additive behavior change: adopters declaring native 3.1 postal fields will now see the projected legacy shape on 3.0 caller responses rather than a dropped/empty block.
    • Required checks: pytest tests/test_decisioning_capabilities_projection.py, mypy src/, ruff check ., black --check .

    Triaged by Claude Code. Session: https://claude.ai/code/session_01Vxi4CpoyXKDw9SLq1SCj4G


    Generated by Claude Code

  3. added
    enhancementNew feature or request
    and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Jun 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions