types: 66 silent name collisions in adcp.types / _generated.py — adopters can't safely migrate off generated_poc

[KonstantinMirin]

Problem

consolidate_exports.py flattens all generated_poc/ types into _generated.py using first-seen-wins (alphabetical sort). When multiple JSON schemas define a type with the same name, one class silently shadows the others. adcp.types.__init__.py re-exports from _generated, so from adcp.types import X may resolve to a different class than the adopter had from their deep generated_poc import.

The migration guide and codemod tell adopters "import from adcp.types (stable public API) instead", but for 66 type names this advice silently swaps the underlying class.

Concrete examples (verified with is identity checks)

Symbol	adcp.types resolves to	Adopter likely needs	Fields match?
Brand	protocol.get_adcp_capabilities_response	brand (identity, with names, logos, etc.)	No — 5 vs 80+ fields
Creative	creative.get_creative_delivery_response	creative.list_creatives_response	No — 6 vs 17+ fields
Account	core.account	account.sync_accounts_request OR sync_accounts_response (3 different classes)	No
Sort	core.tasks_list_request	creative.list_creatives_request	No
Authentication	account.sync_governance_request	core.push_notification_config	No
Unit	enums.dimension_unit	core.duration	No
MediaBuy	core.media_buy	protocol.get_adcp_capabilities_response (for capabilities)	No
GovernanceAgent	account.sync_governance_request	core.account	No
CreditLimit	account.sync_accounts_response	core.account	No

Full list: 66 different-shape collisions across non-bundled modules. Only 5 names are in known_collisions; the remaining 61 are unhandled.

Impact on adopters

salesagent (first production adopter) has 85 generated_poc deep imports across 43 files. Following the migration guide, we attempted to rewrite all of them to adcp.types. The result:

• ~40% were safe (class identity preserved)
• ~60% silently swapped classes — code compiled, ruff passed, but mypy caught type mismatches for some; others would have been silent runtime bugs
• The GENERATED_POC_SYMBOL_MAP in the codemod only covers 8 symbols; lines 148-157 of v3_to_v4.py acknowledge the problem for CreditLimit/Setup/GovernanceAgent but defer resolution

The current workaround (documented in extending-types.md via #644) is to import from the specific submodule. This is correct but means the migration guide's primary advice is unsafe for most types.

Proposed fix

Step 1: Make collisions loud (safety net)

In consolidate_exports.py, add a collision_resolution dict. Any collision not in known_collisions or collision_resolution fails the build. This prevents new silent collisions and forces explicit decisions on existing ones. ~50 lines.

Step 2: Add semantic aliases to aliases.py

For the 66 colliding names, add disambiguated aliases that adopters can import safely:

# aliases.py additions
from adcp.types.generated_poc.brand import Brand as BrandIdentity
from adcp.types.generated_poc.creative.list_creatives_response import Creative as ListingCreative
from adcp.types.generated_poc.creative.get_creative_delivery_response import Creative as DeliveryCreative
from adcp.types.generated_poc.creative.sync_creatives_response import Creative as SyncCreativeResult
# ... etc.

This can be done incrementally — start with the high-impact names above and expand as adopters report needs.

Step 3: Expand the codemod's per-symbol map

Add source-module metadata to GENERATED_POC_SYMBOL_MAP so --auto-apply can generate precise rewrites instead of the generic "import from adcp.types" hint.

Relation to existing work

• fix(types): codegen multi-emission of Creative/Package/etc. breaks Sequence covariant override on required response fields #642 (closed as "not actionable on SDK side") — this proposes the actionable SDK-side fix
• feat(types): cross-class entity overrides on response schemas — Protocol bounds or Generic response types #710 (SchemaVariant) — solves the mypy noise but not the silent-swap problem
• spec: rename context-specific schema variants (Creative, Package, MediaBuy, Deployment, Geo*Exclude*) to disambiguate adcp#4347 (spec-level rename, milestoned to 4.0) — the long-term fix; this issue is the SDK-side mitigation until that lands

[bokelley]

Triage

Classification: Bug
Bucket(s): client, validation (neither label exists in this repo — flagging gap in run summary)
Status: ready-to-implement

What the experts said:

• code-reviewer: Step 1 build guard is sound; aliases.py additions are in the permitted import-layer set; all three steps are non-breaking; verify v3_to_v4.py line numbers against current main before submitting (nit).
• dx-expert: Three blockers confirmed — (1) silent class substitution breaks the migration contract, (2) consolidate_exports.py logs warnings but never fails the build so collisions grow silently over time, (3) codemod covers only 8 symbols and explicitly defers CreditLimit/Setup/GovernanceAgent, so --auto-apply emits the dangerous "import from adcp.types" hint for the 53 remaining names.

My take: The diagnosis is verified — only 5 of 66 collisions are in known_collisions; the remaining 61 silently resolve by alphabetical sort order, making the migration guide's primary advice unsafe for ~60% of types. All three proposed steps are non-breaking (additive build guard, new alias exports, expanded codemod map), and the layering contract in CLAUDE.md permits aliases.py to import directly from generated_poc/.

Implementation scope:

• Step 1 — Build guard (scripts/consolidate_exports.py): Add a collision_resolution dict alongside known_collisions. Any collision name not in either dict raises a ValueError (not just a print) so make regenerate-schemas hard-fails. Populate the dict by running the script locally and triaging each of the 61 outstanding names.
• Step 2 — Semantic aliases (src/adcp/types/aliases.py): For each of the 66 collision names, add a disambiguated export using a {ContextHint}{BaseName} convention (e.g., BrandIdentity, ListingCreative, DeliveryCreative, SyncCreativeResult, CapabilitiesMediaBuy). Start with the 9 high-impact names in the issue body and expand. Add a new tests/test_collision_aliases.py that performs is-identity checks on each new alias. Run mypy src/ and pytest tests/test_import_layering.py after changes.
• Step 3 — Codemod (src/adcp/migrate/v3_to_v4.py or equivalent): Expand GENERATED_POC_SYMBOL_MAP with source-module metadata for all 66 names so --auto-apply emits precise rewrites rather than the generic "import from adcp.types" hint. Verify the file path and current line numbers against main before patching.
• Non-breaking rationale: All changes are additive — no public symbol removed or renamed, no function signature changed, no default value altered. Existing code that already imports from adcp.types continues to resolve identically (the build guard only affects the codegen script, not the runtime package).

---

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

---

Generated by Claude Code