You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
[types] Canonical public models must compose with bundled models #1101
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.
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): add reliable ledger reconciliation #1095, while item 1 (generator reuse) would conflict with feat(reporting): add 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.
Activity
bokelley commentedon Aug 29, 2026
Triage
Classification: Bug
Bucket(s): client / types layer (no
clientlabel exists in this repo — gap noted)Status: ready-to-implement (items 2 and 3); blocked on #1095 (item 1)
What the experts said:
generated_poc/protocol/andgenerated_poc/bundled/protocol/emit structurally identical but identity-distinct Pydantic classes; the_forward_compat.pyimport-time patch (_patch_model_field+model_rebuild) already has this exact template in use forcanonical_creatives; that pattern is non-breaking for item 3; items 2 and 3 can land independently of feat(reporting): add reliable ledger reconciliation #1095, while item 1 (generator reuse) would conflict with feat(reporting): add reliable ledger reconciliation #1095's generated-file diff and should be sequenced after.ValidationErrorgives 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):
_forward_compat.pymitigation: Extend the existing_patch_model_field+model_rebuild(force=True)pattern to swapMediaBuy.reporting_delivery_methods(and any other bundled fields backed by a locally re-emitted class) to the canonicaladcp.typesexport. Add aRuntimeErrorannotation-shape guard for each newly patched field. File:src/adcp/types/_forward_compat.py.tests/test_composability_invariant.pyasserting that for every public symbol inadcp.types, any class also present undergenerated_poc/bundled/either resolves to the same object or is covered by a known_forward_compat.pypatch entry. Wire it into the existing CI generated-code validation job so regen regressions fail loudly.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
$refidentities) resurfaces on merge.Triaged by Claude Code. Session: https://claude.ai/code
Generated by Claude Code
fix(types): preserve public model composability (#1116)