feat(testing): adopter type-checking test suite — verify extension patterns are clean under strict mypy

[bokelley]

Problem

The SDK itself runs mypy --strict (pyproject.toml [tool.mypy] strict = true) and ships type-check tests under tests/test_*_types.py. Those tests validate the SDK's internal types — they don't validate that adopter extension patterns type-check cleanly under the same strictness.

This means: the SDK can be internally strict-clean while still forcing every adopter who follows the recommended patterns to carry # type: ignore comments. We do — ~50 of them across our schema package, and a handful of [arg-type] / [attr-defined] ignores at SDK call sites. Each one is "the docs told me to do this; mypy disagrees; I shrug and silence it."

Without an adopter-pattern test suite, regressions can ship silently — the SDK passes its own tests, but downstream mypy --strict runs go from "100 ignores" to "150 ignores" between releases and nobody notices.

What the JS SDK has

@adcp/sdk (TypeScript) has dedicated *.type-checks.ts files alongside its runtime tests:

• src/lib/server/adcp-server.type-checks.ts
• src/lib/server/decisioning.type-checks.ts
• src/lib/server/decisioning.type-checks.ts

These exercise extension patterns under TypeScript's strict mode, with the test passing iff the file compiles. tsc-equivalent CI gate.

Proposed SDK shape

A tests/type_checks/ directory of small, self-contained Python files that:

1. Exercise documented adopter patterns (extend LibraryProduct, override model_dump, return CreateMediaBuySubmittedResponse | CreateMediaBuySuccessResponse | CreateMediaBuyErrorResponse from a handler, construct BearerTokenAuth(validate_token=...) callbacks, etc.).
2. Are run through mypy --strict as a CI gate.
3. Have zero # type: ignore lines — that's the contract. If a pattern needs an ignore, the pattern is broken.

tests/type_checks/
├── extend_library_product.py        # subclass + add internal field
├── extend_response_with_override.py # the pattern in #620
├── handler_three_branch_return.py   # PlatformHandler.create_media_buy union
├── bearer_token_auth_callback.py    # BearerTokenAuth(validate_token=...)
├── webhook_payload_construction.py  # create_mcp_webhook_payload usage
├── lazy_platform_router_factory.py  # async factory signature
└── nested_model_dump_subclass.py    # the pattern in #615

CI step (Makefile target):

test-type-checks:
	mypy --strict tests/type_checks/

How adopters contribute

Adopters who hit a strictness wall can submit a failing tests/type_checks/<my_pattern>.py as a reproducer. The SDK either:

1. Fixes the typing so the pattern is clean (becomes part of CI), or
2. Documents that the pattern requires a specific cast(...) / explicit annotation (and adds the documented form to the test).

Either outcome is better than "shrug and silence" — the gap becomes visible.

Why this matters

Type ergonomics compound over time. If the SDK ships v5.0 and we discover at upgrade time that 30 new type: ignore lines are required, that's a high-friction migration. With an adopter-pattern test suite, those would surface during SDK PR review, not during downstream upgrades.

Concrete examples this would have caught (or made trivially diagnosable):

• The extract_webhook_result_data typing mismatch (Type-annotation fixes for webhook helpers #598) — return-type test would have failed.
• The create_mcp_webhook_payload dict return type (feat(webhooks): create_mcp_webhook_payload should return McpWebhookPayload #607) — same.
• The _resolve_params_pydantic_model base-class resolution bug (_resolve_params_pydantic_model resolves base-class annotation, breaking subclass-extended request validation #596) — extension-pattern test would have failed.

We can contribute the initial test files based on patterns we've already validated in production. Happy to send a draft PR if you like the shape.

Related

• feat(types): nested model_dump() resolution in response models #615 — nested model_dump() overrides
• chore(main): release 5.0.0 #620 — schema inheritance type: ignore[assignment]
• Internal: SDK already runs mypy --strict on its own code; this proposes extending the strictness contract to adopter patterns.

[bokelley]

Triage

Bucket: test-infrastructure / type-safety gate
Decision: Execute PR — non-breaking, experts converged, implementation verified locally.

Draft PR: #634 (claude/issue-625-adopter-type-checks)

What the PR does

Seven tests/type_checks/ files covering every documented adopter extension pattern under mypy --strict with zero # type: ignore lines:

• extend_library_product.py — Product subclassing with internal excluded fields
• handler_three_branch_return.py — all three SalesResult[T] return paths (sync value, async value, TaskHandoff)
• bearer_token_auth_callback.py — BearerTokenAuth sync + async validator
• nested_model_dump_subclass.py — model_dump override adding internal keys
• extend_response_with_override.py — GetProductsResponse subclass with PrivateAttr + nested model_dump walk
• webhook_payload_construction.py — create_mcp_webhook_payload + cast() zero-ignore pattern
• lazy_platform_router_factory.py — LazyPlatformRouter with async factory

Bundled SDK fix

AccountStore.resolution Protocol attribute widened from Literal["explicit","implicit","derived"] to ClassVar[str]. Root cause: mypy's strict invariance for ClassVar in Protocol matching — ClassVar[Literal["derived"]] does not satisfy ClassVar[Literal["explicit","implicit","derived"]]. Runtime discriminant string values unchanged.

CI gate

Run adopter type-check suite step added to the test matrix job (all four Python versions, 3.10–3.13). pyproject.toml override for tests.type_checks.* re-enables the four error codes suppressed by the broader tests.* glob.

Pre-PR review findings addressed

Two parallel expert passes (code-reviewer + dx-expert) ran on the diff. All blockers resolved before opening:

• Pydantic v2 NameError on _-prefixed Field → replaced with PrivateAttr
• Missing async create_media_buy branch → AsyncSeller class added
• import-not-found not re-enabled → added to enable_error_code list
• CI step missing → wired into test matrix

---

Generated by Claude Code