adcp.types.CreativeAsset resolves to a different type at runtime than under mypy

[bokelley]

Summary

In adcp==6.6.0, the public adcp.types.CreativeAsset symbol has incompatible runtime and static meanings. Runtime resolves it to the legacy CreativeAsset1 branch, while mypy resolves it to the generated CreativeAsset root union over CreativeAsset1 | CreativeAsset2.

This makes code that type-checks against the 3.1+ format_kind branch fail or become impossible when it uses the public runtime symbol.

Reproduction

Python 3.12, adcp==6.6.0:

from typing import get_args, get_origin
from adcp.types import CreativeAsset

print(CreativeAsset)
print(get_origin(CreativeAsset), get_args(CreativeAsset))

Runtime output:

<class 'adcp.types.generated_poc.core.creative_asset.CreativeAsset1'>
None ()

For the same import, mypy 2.3.1 reports:

Revealed type is "def (root: CreativeAsset1 | CreativeAsset2) -> CreativeAsset"

The generated module does define the root union, but _generated.py then deliberately replaces the public runtime binding for subclassing compatibility:

CreativeAssetUnion = CreativeAsset
CreativeAsset = CreativeAsset1  # type: ignore[misc,assignment]

Because the reassignment is ignored statically, the TYPE_CHECKING re-export and runtime lazy re-export disagree.

Impact

A downstream request DTO can subclass or construct CreativeAsset believing it represents both schema branches, while runtime actually fixes it to the legacy branch that requires format_id. The spec-legal format_kind branch is represented by CreativeAsset2 and is unavailable through that public name.

Expected

The public symbol should mean the same thing at runtime and under static analysis. Either:

1. export the root union as CreativeAsset and give the concrete compatibility class a separate explicit name, or
2. type CreativeAsset as CreativeAsset1 and document/use CreativeAssetUnion for the schema union.

SDK 7's canonical CreativeAsset plus explicit LegacyCreativeAsset surface provides a clearer migration seam, but the 6.6.0 mismatch should at least be documented and covered by a runtime/static alias regression test if a 6.x patch is not planned.

Affected version

• Confirmed: 6.6.0
• SDK 7 uses the canonical creative boundary for unqualified CreativeAsset; its explicit LegacyCreativeAsset imports the generated root model, so this exact mismatch does not appear to apply there.

[bokelley]

Triage

Classification: Bug (confirmed in 6.6.0; already fixed in current main)
Bucket(s): client (public type export surface — no matching label in repo; noted here)
Status: ready-to-implement
Milestone: (omitted — fix already shipped in main; remaining work is test coverage)

What the experts said:

• code-reviewer: The specific CreativeAsset runtime/static split is gone in 8.0.0b14. _eager.py line 891 binds CreativeAsset = _canonical_creative.CreativeAsset — a straight assignment, no type: ignore, pointing to a concrete CanonicalBoundaryModel subclass built by _canonical_clone. No union, no rebind. However, _generated.py lines 3744–3753 still use the identical # type: ignore[misc,assignment] rebind for AuthorizedAgents (six-step chain) and Transport — producing the same static/runtime split for those names today.
• dx-expert: (analysis pending; will update if material new information arrives)

My take: The reported mismatch is fixed in current main via the canonical creative boundary (canonical_creative.py). The outstanding work is a regression test to prevent recurrence, plus a decision on AuthorizedAgents/Transport which exhibit the same footgun pattern. Both items are non-breaking.

Implementation scope:

• Add tests/test_creative_asset_regression.py:

  from adcp.types.canonical_creative import CanonicalBoundaryModel
  import adcp, adcp.types
  from pydantic import BaseModel
  
  def test_creative_asset_is_concrete_canonical_class() -> None:
      cls = adcp.types.CreativeAsset
      assert isinstance(cls, type), "CreativeAsset must be a class, not a union"
      assert issubclass(cls, CanonicalBoundaryModel)
      assert issubclass(cls, BaseModel)
      assert cls.__name__ == "CreativeAsset"
      assert cls is not adcp.types.LegacyCreativeAsset
      assert adcp.CreativeAsset is adcp.types.CreativeAsset
      assert "format_id" in cls.model_fields
      assert "format_kind" in cls.model_fields
      assert cls.model_fields["format_kind"].is_required()

• Separately (or in the same PR if reviewer prefers): replace # type: ignore[misc,assignment] rebinds for AuthorizedAgents/Transport in _generated.py lines 3744–3753 with accurate TypeAlias annotations, or document why the static/runtime split is intentional for those names.
• Required checks: pytest tests/test_creative_asset_regression.py, mypy src/, ruff check ., black --check .
• Non-breaking rationale: test-only addition for primary scope; TypeAlias annotation changes are internal (_generated.py is not a public import path per CLAUDE.md).

Note: a 6.x backport is out of scope — main is at 8.0.0b14 and the fix has been in place since SDK 7.

Note: no client bucket label exists in this repo — flagging for maintainer to create if desired.

---

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

---

Generated by Claude Code