Skip to content

[types] Canonical public models must compose with bundled models #1101

Closed

Description

@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.

Activity

  1. added
    bugSomething isn't working
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Aug 29, 2026
  2. bokelley commented on Aug 29, 2026

    @bokelley
    ContributorAuthor

    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): 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.
    • 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

  3. added and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Aug 29, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions