[types] Canonical public models must compose with bundled models

[bokelley]

Summary

Canonical public models and independently generated bundled models can represent the same wire schema but have different Python class identity. That makes otherwise valid public SDK objects fail when nested into another public SDK model.

Reproduction from reporting integration

ReportingDeliveryCapabilities imported from the canonical public type surface was rejected when supplied to adcp.decisioning.capabilities.MediaBuy.reporting_delivery:

ValidationError: reporting_delivery
Input should be a valid dictionary or instance of ReportingDelivery

Passing capability.model_dump() with identical wire content succeeded. The parent MediaBuy came from the independently generated bundled capabilities schema, which embedded a distinct ReportingDelivery class.

Impact

• The SDK's public models are not reliably composable.
• Users must know when to convert a typed object back to an untyped dictionary.
• Type checkers can approve code that Pydantic rejects at runtime.
• The same defect can recur for any canonical model embedded in a bundled tool/capability schema.

This is a more specific recurrence of the collision/model-surface risks discussed in #911 and #1046.

Expected

• Bundled schema generation should reuse canonical public model identities for $ref targets rather than emitting structurally equivalent private classes.
• Add a generator-level identity/composability test for every canonical model exposed through a bundled capability or tool model.
• At minimum, public wrapper models should override bundled annotations with the canonical public type and preserve wire validation.

#1095 includes the immediate reporting fix and a regression test for MediaBuy.reporting_delivery; the generator-wide invariant remains the desired end state.

[bokelley]

Triage

Classification: Bug
Bucket(s): client / types layer (no client label exists in this repo — gap noted)
Status: ready-to-implement (items 2 and 3); blocked on #1095 (item 1)

What the experts said:

• code-reviewer: Confirmed bug — generated_poc/protocol/ and generated_poc/bundled/protocol/ emit structurally identical but identity-distinct Pydantic classes; the _forward_compat.py import-time patch (_patch_model_field + model_rebuild) already has this exact template in use for canonical_creatives; that pattern is non-breaking for item 3; items 2 and 3 can land independently of feat(reporting): prototype reliable ledger reconciliation #1095, while item 1 (generator reuse) would conflict with feat(reporting): prototype reliable ledger reconciliation #1095's generated-file diff and should be sequenced after.
• dx-expert: Trust-breaking severity — type checkers approve code that Pydantic rejects at runtime, so the generic ValidationError gives no actionable hint; the composability invariant test (item 2) should be prioritized independently as it catches future regen regressions immediately; a targeted error message would materially reduce debugging time.

My take: Items 2 and 3 are additive-only and don't touch generated files — they can land now. Item 1 (generator-level class identity reuse) is blocked on #1095 to avoid a conflict with that draft's 228-file generated diff.

Implementation brief (items 2 + 3):

• Item 3 — _forward_compat.py mitigation: Extend the existing _patch_model_field + model_rebuild(force=True) pattern to swap MediaBuy.reporting_delivery_methods (and any other bundled fields backed by a locally re-emitted class) to the canonical adcp.types export. Add a RuntimeError annotation-shape guard for each newly patched field. File: src/adcp/types/_forward_compat.py.
• Item 2 — Composability invariant test: Add tests/test_composability_invariant.py asserting that for every public symbol in adcp.types, any class also present under generated_poc/bundled/ either resolves to the same object or is covered by a known _forward_compat.py patch entry. Wire it into the existing CI generated-code validation job so regen regressions fail loudly.
• Non-breaking rationale: Both changes are purely additive — a new test file and a patch that only widens what bundled fields accept. No public exports change identity, no signatures change, no default values change.
• Required checks: pytest tests/test_composability_invariant.py tests/test_forward_compat.py, mypy src/adcp/types/_forward_compat.py, ruff check ., black --check ..

Blocked-on: #1095 — item 1 (generator reuse of canonical $ref identities) resurfaces on merge.

---

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

---

Generated by Claude Code