types: make version-scoped models typed and composable

[bokelley]

Problem

SDK 8.0.0b4 now provides version-scoped validation models under
adcp.types.v30, v31, and v32, which fixes the wire-validation and MCP
schema-selection half of #1036. The Python model surface remains opaque,
however: each versioned request/response is a RootModel[dict[str, Any]]
rather than a typed, composable Pydantic model.

from adcp.types import ListCreativesRequest as CurrentListCreativesRequest
from adcp.types.v31 import ListCreativesRequest as V31ListCreativesRequest

assert "assignment_projection" in CurrentListCreativesRequest.model_fields
assert set(V31ListCreativesRequest.model_fields) == {"root"}
assert V31ListCreativesRequest.model_fields["root"].annotation == dict[str, Any]

This means a 3.1 adopter can validate a completed dictionary, but cannot use
the version-scoped model as its normal application type:

• no typed constructor or IDE/mypy support for fields;
• no request.account, request.filters, etc.;
• no typed nested values;
• no supported inheritance point for adopter-only fields or validators;
• no version-scoped nested models to use in application schemas.

The last point matters for seller frameworks. Our schemas extend SDK models
and add internal fields with exclude=True. With b4, the only usable parent is
the unversioned (currently 3.2) generated model, so a 3.1 server still inherits
3.2-only fields and requiredness. We then have to patch 3.1 semantics locally
(for example, reject assignment_projection / assignment_limit and restore
required package budgets) even though the SDK has the correct 3.1 bundle.

Requested public surface

Please make version-scoped types usable as normal typed Pydantic application
models, not validation envelopes. Any implementation shape is fine if it
provides these properties:

1. v31.ListCreativesRequest exposes its 3.1 fields with precise annotations
   and requiredness.
2. Nested types needed to compose or extend a versioned request/response have
   a stable, collision-safe public import path.
3. Adopters can subclass a versioned type and add excluded internal fields or
   validators without converting to/from an untyped root dictionary.
4. Runtime validation continues to use the pinned schema bundle.
5. Tests cover the known 3.1/3.2 deltas: creative assignment fields and
   PackageRequest.budget requiredness.

If fully generated per-version Pydantic trees are intentionally out of scope,
please expose another supported typed composition/inheritance API and document
that adcp.types.v3x is a boundary validator only.

Relationship to #1036

This is a follow-up, not a request to undo its work. Version-pinned dispatch
and MCP schemas now behave correctly. The remaining gap is Python type safety
and composability for adopters implementing a version-pinned server.

[bokelley]

Triage

Classification: Feature request
Bucket(s): client, validation
Status: ready-to-implement

What the experts said:

• code-reviewer: Option C (generated TypedDict stubs) is viable; full per-version codegen (A) is risky — variant-numbering churn documented in CLAUDE.md would multiply across every version tree; dynamic BaseModel construction (B) is risky because type() calls are opaque to mypy/IDEs and creates dual-validator divergence between Pydantic and jsonschema.
• dx-expert: TypedDict/Protocol stubs (C) score 4/5 — matches the boto3/sqlalchemy-stubs pattern; fixes mypy + autocompletion without touching the runtime validation path PR feat(protocol)!: stabilize multi-version SDK 8 beta #1038 established; Pydantic subclassing with exclude=True would remain unsupported and should be explicitly documented with a workaround pattern.
• ad-tech-protocol-expert: versioned models must be fully independent types, not subtypes of the unversioned surface (inheriting from the 3.2-derived class would let assignment_projection/assignment_limit pass mypy on a 3.1 instance); JSON Schema should remain the single validation authority; per-version codegen into isolated directories is architecturally correct if each version's numbering is isolated from the others.

My take: Experts converge on the near-term path: generated .pyi stubs for each versioned module (Option C) fix requirements 1, 2, 4, and 5 without touching the runtime validation path. Requirement 3 (Pydantic subclassing with exclude=True) is architecturally unsolvable without full per-version codegen (Option A), which carries real churn risk and warrants a separate decision.

Implementation scope:

• Option C — near-term, non-breaking: Generate .pyi stub files for src/adcp/types/v30.pyi, v31.pyi, v32.pyi from each version's bundled JSON Schema properties and required arrays. Add a script (scripts/generate_versioned_stubs.py) or extend scripts/bundle_schemas.py to produce stubs in the same pass that produces the schema bundles. Each stub should expose the top-level request/response model names (e.g., v31.ListCreativesRequest, v31.PackageRequest) with precise field annotations and Required/NotRequired from each version's required array — deriving them from the schema rather than hand-authoring them avoids drift. Validate stubs in CI alongside generated-code validation. Add tests/test_version_scoped_models.py coverage asserting that v31.ListCreativesRequest.__annotations__ reflects 3.1 fields and that the stub is visible to mypy (via tests/type_checks/). Add a docstring to each v3x module noting that the type surface is boundary-validator-only and Pydantic subclassing is not supported (with a compose-don't-inherit workaround).
• Option A — longer-term, if subclassing is required: Per-version isolated codegen under src/adcp/types/generated_poc/v31/, generated_poc/v32/, with their own alias and eager layers and exemptions in tests/test_import_layering.py. Each version's directory is independent, so 3.1 schema reordering does not shift 3.2 class numbering. This resolves requirement 3 but requires an explicit team decision given the CLAUDE.md churn caveat.
• Files touched (Option C only): scripts/generate_versioned_stubs.py (new) or scripts/bundle_schemas.py, src/adcp/types/v30.pyi, v31.pyi, v32.pyi (new), tests/test_version_scoped_models.py, tests/type_checks/test_versioned_types.py (new).
• Required checks: mypy src/ (stub resolution), pytest tests/test_version_scoped_models.py tests/type_checks/, ruff check ., black --check .
• Non-breaking: All changes are additive — .pyi stubs are type-checker-only artifacts and VersionedSchemaModel runtime is unchanged. adcp.types.__init__ surface unchanged.

---

Triaged by Claude Code. Session: https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}

---

Generated by Claude Code