Add canonical creative format compatibility helpers

[bokelley]

Context

While validating bokelley/salesagent#631 end-to-end, we found that legacy creative format IDs are upgraded by the SDK/schema layer, but implementations still need a reliable way to compare upgraded legacy IDs with structured canonical format refs.

Example failure mode:

• client sends legacy display_300x250
• SDK/model validation upgrades this to canonical display_image with width/height
• implementation code still compares exact (agent_url, id) tuples
• display_image no longer matches a product/creative format that originated as display_300x250 unless every implementation reimplements canonical matching correctly

Proposed SDK work

Expose documented helpers for common format compatibility checks, for example:

• upgrade_legacy_format_id(value) -> FormatId (already effectively present in some surfaces)
• canonical_format_matches(a, b) -> bool for equivalence after legacy upgrade
• canonical_format_satisfies(requested, supported) -> bool for product/capability gating

The important distinction is that product gating is stricter than equivalence: if the supported/product format declares width, height, or duration_ms, the requested creative format should also declare and match that value. A broad supported format can accept a more specific request, but an under-specified request should not silently match a fixed-size/fixed-duration product.

Acceptance criteria

• SDK exposes a helper or documented pattern for legacy-to-canonical format comparison.
• Tests cover at least display_300x250 vs structured display_image width=300 height=250.
• Tests cover the stricter product-gating case: requested display_image with no dimensions does not satisfy supported display_image width=300 height=250.
• Docs/comments make clear which helper is for equivalence and which is for capability satisfaction.

Discovered in

• fix: Add media buy revision concurrency controls bokelley/salesagent#631

[bokelley]

Triage

Classification: Feature request
Bucket(s): client (label absent from repo — noted in run summary)
Status: ready-to-implement

What the experts said:

• code-reviewer: Non-breaking and additive; upgrade_legacy_format_id is under-specified — bare strings carry no agent_url; canonical_format_satisfies needs a fresh {width,height,duration_ms} exact-match, check_narrows() has inverted semantics and gives wrong answers; (requested, supported) arg order reads backwards.
• dx-expert: matches/satisfies naming is a correctness hazard — direction not encoded; rename to formats_are_equivalent / format_is_supported; find_declaration_by_v1_format_id's None path needs a pointer or adopters won't find these helpers.

My take: The failure mode is real and the helpers belong in adcp.canonical_formats. Resolve two questions first: (1) does upgrade_legacy_format_id accept bare strings or FormatId | dict only (bare strings lack agent_url)?; (2) apply the renames above before coding.

Implementation scope:

• New src/adcp/canonical_formats/compat_helpers.py; re-export from __init__.py + __all__; update tests/test_canonical_formats_public_api.py
• formats_are_equivalent(a, b): delegate to _canonicalize_agent_url() from format_options.py — no independent URL normalization
• format_is_supported(requested, supported): fresh exact-match over {width,height,duration_ms} in supported.params — check_narrows() is semantically inverted for this check
• Add discovery pointer in find_declaration_by_v1_format_id docstring for unexpected None returns (may indicate a legacy id was upgraded)
• Tests: display_300x250 ↔ display_image(300,250) equivalence; display_image() does NOT satisfy display_image(300,250) (product gating)

---

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

---

Generated by Claude Code