types: provide a version-scoped Pydantic extension surface

[bokelley]

Problem

#1048 adds valuable generated .pyi stubs for version-scoped models, but it
intentionally leaves their runtime implementation as
RootModel[dict[str, Any]]. The module documentation explicitly says that
subclassing to add Pydantic fields is unsupported and recommends composing
adopter state beside the boundary model.

That leaves the extension half of #1046 unresolved for seller frameworks whose
public schemas extend SDK schemas with excluded internal fields:

from adcp.types.v31 import ListCreativesRequest
from pydantic import Field

class SellerListCreativesRequest(ListCreativesRequest):
    internal_tenant_id: str = Field(exclude=True)

On 8.0.0b4 (and with #1048's unchanged RootModel runtime), class definition
fails with:

NameError: Unexpected field with name 'internal_tenant_id'; only 'root' is
allowed as a field of a RootModel

Static stubs make direct construction and attribute access pleasant for type
checkers, but they do not provide runtime Pydantic fields or nested Pydantic
models. Composition beside the boundary object does not replace an extension
model at transport/business-logic boundaries where one validated model must
carry both protocol and excluded internal state.

The practical result for a 3.1 seller is that it must still inherit the
unversioned 3.2-generated classes and patch the version delta locally. Our SDK
8 migration currently has to:

• remove assignment_projection and assignment_limit during 3.1
  ListCreativesRequest serialization; and
• add a validator restoring the 3.1-required PackageRequest.budget.

That is exactly the semantic drift the version-scoped surface should let an
adopter avoid.

Requested extension surface

Please provide a supported way to define a normal Pydantic model that extends
one pinned protocol version. Full isolated per-version runtime codegen is one
valid implementation, but the API shape is open.

Acceptance criteria:

1. An adopter can add an exclude=True internal field to a 3.1 request or
   response without converting through an untyped root dictionary.
2. Protocol fields appear in runtime model_fields, not only in .pyi.
3. Nested protocol objects retain typed Pydantic runtime values where the
   normal generated surface provides them.
4. The extended model emits the pinned version's JSON Schema and wire shape;
   excluded adopter fields never serialize.
5. The 3.1 extension does not admit 3.2-only creative assignment fields and
   keeps package budget required.
6. The solution has a stable public import/factory path and does not require
   generated_poc imports.

Relationship to #1046 and #1048

This is the explicitly deferred runtime-extension portion of #1046. The stubs
in #1048 are useful and should remain; this asks for the complementary runtime
Pydantic extension seam needed by schema-extending adopters.

[bokelley]

Triage

Classification: Feature request
Bucket(s): client (types surface — src/adcp/types/versioned.py; no matching repo label for this bucket)
Status: ready-to-implement

What the experts said:

• code-reviewer: Factory approach is feasible and non-breaking as a new additive export; critical detail is using pydantic.create_model() not bare type() for the BaseModel subclass; criterion 3 (nested typed runtime models) requires explicit depth scoping before implementation.
• dx-expert: Option A (make_versioned_base("3.1", "ListCreativesRequest")) is the clear ergonomic winner; recommend scoping criterion 3 to top-level fields for v1 to ship a useful feature without runtime surprises, with fully-recursive nested models as a follow-up.

My take: Both experts agree this is well-scoped and non-breaking — a factory that produces a real BaseModel subclass with bundled-schema validation and a canonical model_json_schema() override, alongside the existing VersionedSchemaModel surface. One clarification is needed before implementation: does criterion 3 ("nested protocol objects retain typed Pydantic runtime values") mean top-level fields only, or fully recursive nested model generation?

Implementation scope:

• Add make_versioned_base(version: str, model_name: str) -> type[BaseModel] to src/adcp/types/versioned.py using pydantic.create_model(), drawing fields from _object_shapes(), adding a model_validator that runs the bundled JSON Schema check, and overriding model_json_schema() / __get_pydantic_json_schema__ to return the canonical bundled schema.
• Re-export from adcp.types.versioned public API (criterion 6); no generated_poc imports needed.
• Tests: Field(exclude=True) subclassing, model_fields against a known 3.1/3.2 delta field, model_json_schema() round-trip, and confirm 3.1 rejects assignment_projection/assignment_limit.
• Non-breaking: schema_model_for_version / VersionedSchemaModel surface left unchanged.

---

Triaged by Claude Code.

---

Generated by Claude Code