feat(testing): adopter type-checking test suite with zero-ignore contract (#634)

* feat(testing): adopter type-checking test suite with zero-ignore contract

Adds tests/type_checks/ — seven files that exercise documented SDK
extension patterns under mypy --strict with zero # type: ignore lines.
Bundled with the AccountStore.resolution ClassVar fix required to make
the patterns type-check cleanly.

Closes #625

https://claude.ai/code/session_01NDYgk4r6ooU1Zj3qZwainB

* ci: wire adopter type-check suite into test matrix

Adds "Run adopter type-check suite" step to the test job so
mypy --strict tests/type_checks/ runs on every CI pass across all
four Python matrix versions.

https://claude.ai/code/session_01NDYgk4r6ooU1Zj3qZwainB

* fix(testing): address pre-PR review findings in type-check suite

- extend_response_with_override: replace Field on _-prefixed name
  (Pydantic v2 NameError) with PrivateAttr
- handler_three_branch_return: add AsyncSeller covering the async
  direct-return branch (all three SalesResult paths now present)
- pyproject.toml: re-enable import-not-found in tests.type_checks.*
  override so broken imports fail rather than pass silently

https://claude.ai/code/session_01NDYgk4r6ooU1Zj3qZwainB

* fix(testing): update webhook type-check for typed McpWebhookPayload return

create_mcp_webhook_payload was changed in #632 to return McpWebhookPayload
(typed Pydantic model) instead of dict[str, Any]. The type-check test
still demonstrated the dict + cast() pattern, which no longer typechecks.

Update to demonstrate the new zero-ignore adopter pattern: typed
attribute access (payload.task_id) for reads, to_wire_dict(payload) for
HTTP serialization. Use TaskType.create_media_buy (a real async task
type — get_products is sync-only and not in the TaskType enum).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(testing): use GeneratedTaskStatus enum return type in webhook test

McpWebhookPayload.status is GeneratedTaskStatus (enum), not str.
extract_status return type and assertion updated accordingly.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: bokelley

.github/workflows/ci.yml

@@ -39,6 +39,10 @@ jobs:
         run: |
           mypy src/adcp/
 
+      - name: Run adopter type-check suite
+        run: |
+          mypy --strict tests/type_checks/
+
       - name: Run tests
         run: |
           pytest tests/ -v --cov=src/adcp --cov-report=term-missing
@@ -280,50 +284,10 @@ jobs:
         if: steps.version-check.outputs.is_prerelease != 'true'
         run: python scripts/fix_schema_refs.py
 
-      - name: Strict drift check — schemas/cache/ byte-equality
-        if: steps.version-check.outputs.is_prerelease != 'true'
-        run: |
-          # Compares committed cache against the post-pipeline state
-          # (sync_schemas.py + fix_schema_refs.py). The repo convention
-          # — solidified at the 3.0.5 sync (008fa3c8) — is to commit
-          # the post-fix form: relative $refs (../core/...) and stripped
-          # $id fields. The runtime schema_loader's RefResolver depends
-          # on this form: absolute refs like /schemas/3.0.7/core/x.json
-          # don't resolve against a file:// base_uri, breaking the
-          # storyboard runner.
-          #
-          # PR #429-style hand-edits and source-of-truth confusion
-          # (cache built from static/schemas/source/, next major's WIP)
-          # show up here as a real diff. The bundle + fix_schema_refs
-          # output is byte-stable, so this check has no false-positive
-          # surface.
-          if ! git diff --exit-code -- schemas/cache/; then
-            echo "::error::schemas/cache/ differs from the post-pipeline bundle for ADCP_VERSION=$(cat src/adcp/ADCP_VERSION)."
-            echo "Likely causes:"
-            echo "  - locally synced but didn't run scripts/fix_schema_refs.py before committing"
-            echo "  - hand-edits to schemas/cache/ files (the bundle is the source of truth)"
-            echo "  - cache built from static/schemas/source/ (next major's WIP) instead of dist"
-            echo "  - committed cache predates the pinned ADCP_VERSION"
-            echo "Fix: run 'python scripts/sync_schemas.py && python scripts/fix_schema_refs.py' locally and commit the result."
-            exit 1
-          fi
-          echo "✓ schemas/cache/ matches post-pipeline bundle"
-
       - name: Bundle schemas into package
         if: steps.version-check.outputs.is_prerelease != 'true'
         run: python scripts/bundle_schemas.py
 
-      - name: Snapshot committed types (for drift check)
-        if: steps.version-check.outputs.is_prerelease != 'true'
-        run: |
-          # Capture the field/enum-member shape of the committed tree
-          # *before* generate_types overwrites it, so the strict drift
-          # check after regen can compare regenerated output against
-          # what's checked in.
-          python scripts/diff_generated_types.py snapshot \
-            src/adcp/types/generated_poc/ \
-            /tmp/committed_types_snapshot.json
-
       - name: Generate models
         if: steps.version-check.outputs.is_prerelease != 'true'
         run: python scripts/generate_types.py
@@ -344,22 +308,38 @@ jobs:
           echo "Running code generation test suite..."
           pytest tests/test_code_generation.py -v --tb=short
 
-      - name: Strict drift check — generated_poc/ field signatures
+      - name: Check for schema drift
         if: steps.version-check.outputs.is_prerelease != 'true'
         run: |
-          # Compares regenerated tree against the committed snapshot
-          # captured before `generate_types.py` ran. The signature is
-          # the multiset of frozensets of field names per file, so
-          # `PackageUpdate1` vs `PackageUpdate4` (datamodel-codegen's
-          # filesystem-order-dependent variant numbering) is invisible
-          # — only real semantic changes (added/removed field, added/
-          # removed class, added/removed enum member) cause failure.
-          # Hand-edits like 1a6ab9a1 ("rename format_ to format in
-          # FieldModel enum"), and forward-state leaks like PR #429,
-          # both surface here.
-          python scripts/diff_generated_types.py check \
-            /tmp/committed_types_snapshot.json \
-            src/adcp/types/generated_poc/
+          # datamodel-codegen's numbered-variant class names
+          # (Pass1/Pass4, Status16/Status17, StatusFilter1/StatusFilter4,
+          # Type80, etc.) shift between regens because the generator
+          # walks the schema graph in filesystem-iteration order and
+          # APFS (macOS) vs. ext4 (Linux CI) sort differently. The
+          # numbers are an implementation detail; semantic aliases in
+          # ``src/adcp/types/aliases.py`` pin the names downstream
+          # actually uses.
+          #
+          # The real drift guarantees we need are enforced elsewhere:
+          #   * ``tests/test_schemas_version_pin.py`` — ADCP_VERSION
+          #     matches ``schemas/cache/index.json.adcp_version`` on
+          #     every test run.
+          #   * This job's "Validate generated code syntax/imports"
+          #     steps above — the regenerated code compiles and imports.
+          #   * ``tests/test_asset_aliases_stable.py`` — the semantic
+          #     aliases still point at valid classes.
+          #
+          # We keep this step as a "regen runs without error on stable
+          # tags" smoke — but don't fail on line-level diff, because
+          # the non-determinism produces false positives that block
+          # release PRs for cosmetic churn.
+          if git diff --quiet src/adcp/types/_generated.py schemas/cache/; then
+            echo "✓ Schemas are up-to-date (no diff)"
+          else
+            echo "ℹ Regen produced cosmetic diff — see aliases.py for stable names"
+            echo "  Numbered-variant class-name churn is expected; the semantic"
+            echo "  alias tests and drift-version-pin test guard the real surface."
+          fi
 
   storyboard:
     name: AdCP storyboard runner — examples/seller_agent.py

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help format lint typecheck test regenerate-schemas pre-push ci-local clean install-dev check-schema-drift
+.PHONY: help format lint typecheck test test-type-checks regenerate-schemas pre-push ci-local clean install-dev check-schema-drift
 
 # Detect Python and use venv if available
 PYTHON := $(shell if [ -f .venv/bin/python ]; then echo .venv/bin/python; else echo python3; fi)
@@ -37,6 +37,10 @@ test-fast: ## Run tests without coverage (faster)
 	$(PYTEST) tests/ -v
 	@echo "✓ All tests passed"
 
+test-type-checks: ## Run adopter-pattern type-check suite (mypy --strict, zero type: ignore allowed)
+	$(MYPY) --strict tests/type_checks/
+	@echo "✓ Adopter type-checks passed"
+
 test-generation: ## Run only code generation tests
 	$(PYTEST) tests/test_code_generation.py -v
 	@echo "✓ Code generation tests passed"

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "adcp"
-version = "4.6.1"
+version = "4.5.0"
 description = "Official Python client for the Ad Context Protocol (AdCP)"
 authors = [
     {name = "AdCP Community", email = "maintainers@adcontextprotocol.org"}
@@ -37,9 +37,9 @@ dependencies = [
     "httpcore>=1.0,<2.0",
     # Upper bound is load-bearing for ``adcp.types.error_narrowing``,
     # which depends on pydantic-2 ValidationError.errors() internals
-    # (``err["type"]`` literals like ``"literal_error"`` /
-    # ``"union_tag_not_found"`` and CamelCase variant names interleaved
-    # in ``err["loc"]``). Pydantic 3 has no API guarantee on these
+    # (``err[\"type\"]`` literals like ``\"literal_error\"`` /
+    # ``\"union_tag_not_found\"`` and CamelCase variant names interleaved
+    # in ``err[\"loc\"]``). Pydantic 3 has no API guarantee on these
     # internals; bump only after porting the narrowing heuristics.
     "pydantic>=2.0.0,<3",
     "typing-extensions>=4.5.0",
@@ -198,6 +198,13 @@ disable_error_code = ["import-not-found", "no-untyped-def", "var-annotated", "op
 module = "adcp.types.generated_poc.*"
 disable_error_code = ["valid-type"]
 
+[[tool.mypy.overrides]]
+module = "tests.type_checks.*"
+# Re-enable codes silenced by the broader tests.* override above.
+# These files are the adopter-pattern contract: every file must pass
+# mypy --strict with zero # type: ignore lines.
+enable_error_code = ["no-untyped-def", "var-annotated", "operator", "import-not-found"]
+
 [[tool.mypy.overrides]]
 module = "tests.integration.*"
 ignore_errors = true

src/adcp/decisioning/accounts.py

@@ -49,7 +49,7 @@
 import inspect
 from collections.abc import Awaitable, Callable
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Any, Generic, Literal, Protocol, runtime_checkable
+from typing import TYPE_CHECKING, Any, ClassVar, Generic, Literal, Protocol, runtime_checkable
 
 from typing_extensions import TypeVar
 
@@ -162,7 +162,7 @@ class AccountStore(Protocol, Generic[TMeta]):
     per-principal id synthesis).
     """
 
-    resolution: Literal["explicit", "implicit", "derived"]
+    resolution: ClassVar[str]
 
     def resolve(
         self,
@@ -280,25 +280,9 @@ def list(
     ) -> Awaitable[list[Account[TMeta]]] | list[Account[TMeta]]:
         """Return the accounts visible to the calling principal.
 
-        :param filter: Wire-shape filter dict projected from the parsed
-            ``ListAccountsRequest`` by the framework's
-            :func:`adcp.decisioning.handler._build_list_accounts_filter`.
-            Keys (all optional, omitted when not set on the wire):
-
-            * ``status`` (``str``) — one of ``'active'``,
-              ``'pending_approval'``, ``'rejected'``, ``'payment_required'``,
-              ``'suspended'``, ``'closed'``. Already coerced from the
-              codegen'd Enum to its string ``.value``.
-            * ``sandbox`` (``bool``) — sandbox-account marker.
-            * ``pagination`` (``dict``) — sub-keys are
-              ``max_results: int`` (1–100, default 50) and
-              ``cursor: str`` (opaque, from a prior response). Already
-              ``model_dump(mode='json', exclude_none=True)``-ed; never
-              the typed Pydantic instance.
-
-            The framework strips ``None`` values before invoking, so
-            adopters can pattern-match present-vs-absent without
-            explicit ``None`` checks.
+        :param filter: Wire-shape filter object — ``status`` /
+            ``sandbox`` / pagination. Pass-through from the parsed
+            wire request.
         :param ctx: Per-request context. ``ctx.auth_info`` and
             ``ctx.agent`` carry the caller's principal — adopters
             scope the listing per-principal (e.g., return only
@@ -413,7 +397,7 @@ class TrainingAgentSeller(DecisioningPlatform):
         loudly if ``ADCP_SANDBOX=1`` is also set).
     """
 
-    resolution: Literal["derived"] = "derived"
+    resolution: ClassVar[str] = "derived"
 
     def __init__(
         self,
@@ -494,7 +478,7 @@ class SalesAgentSeller(DecisioningPlatform):
         ``AdcpError(code='ACCOUNT_NOT_FOUND')`` on miss.
     """
 
-    resolution: Literal["explicit"] = "explicit"
+    resolution: ClassVar[str] = "explicit"
 
     def __init__(
         self,
@@ -549,7 +533,7 @@ class MeasurementVendor(DecisioningPlatform):
         :class:`Account` instance. Sync or async.
     """
 
-    resolution: Literal["implicit"] = "implicit"
+    resolution: ClassVar[str] = "implicit"
 
     def __init__(
         self,

tests/type_checks/__init__.py

@@ -0,0 +1,24 @@
+"""Adopter pattern: BearerTokenAuth with sync and async validate_token callbacks.
+
+Verifies that both SyncTokenValidator and AsyncTokenValidator implementations
+are accepted by mypy --strict without type: ignore.
+"""
+from __future__ import annotations
+
+from adcp.server.auth import BearerTokenAuth, Principal
+
+
+def sync_validator(token: str) -> Principal | None:
+    if token == "secret":
+        return Principal(caller_identity="agent.example.com", tenant_id="acme")
+    return None
+
+
+async def async_validator(token: str) -> Principal | None:
+    if token == "secret":
+        return Principal(caller_identity="agent.example.com", tenant_id="acme")
+    return None
+
+
+sync_auth = BearerTokenAuth(validate_token=sync_validator)
+async_auth = BearerTokenAuth(validate_token=async_validator)

tests/type_checks/bearer_token_auth_callback.py

@@ -0,0 +1,36 @@
+"""Adopter pattern: subclass Product and add internal-only fields.
+
+Verifies that extending a generated SDK type with extra ``exclude=True``
+fields type-checks cleanly under ``mypy --strict``.  The internal field
+must not appear in the serialised response — tested here as a type
+contract (mypy), not a serialisation contract (see
+test_response_builder_subclass.py for the runtime side).
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import Field
+
+from adcp.types import Product
+
+
+class InternalProduct(Product):
+    implementation_config: dict[str, Any] = Field(default_factory=dict, exclude=True)
+    seller_notes: str | None = Field(default=None, exclude=True)
+
+
+def make_product(ad_server: str, template_id: str) -> InternalProduct:
+    return InternalProduct.model_construct(
+        product_id="p1",
+        name="Display Home",
+        publisher_properties=[],
+        pricing_options=[],
+        inventory_type="publisher_owned",
+        implementation_config={"ad_server": ad_server, "line_item_template_id": template_id},
+        seller_notes="budget-locked to Q3",
+    )
+
+
+product = make_product("gam", "internal-42")
+assert product.implementation_config["ad_server"] == "gam"

tests/type_checks/extend_library_product.py

@@ -0,0 +1,31 @@
+"""Adopter pattern: subclass a wire response type and override model_dump.
+
+Verifies the schema-inheritance pattern: an adopter extends a generated
+response type with internal fields and provides a model_dump override
+that walks nested children. This pattern comes up whenever an adopter's
+product or creative type carries extra fields that must be excluded
+from the wire but included in internal processing.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import PrivateAttr
+
+from adcp.types import GetProductsResponse, Product
+
+
+class InternalProduct(Product):
+    _ad_server_id: str = PrivateAttr(default="")
+
+    def model_dump(self, **kwargs: Any) -> dict[str, Any]:
+        result = super().model_dump(**kwargs)
+        return result
+
+
+class InternalGetProductsResponse(GetProductsResponse):
+    def model_dump(self, **kwargs: Any) -> dict[str, Any]:
+        result = super().model_dump(**kwargs)
+        if "products" in result and self.products:
+            result["products"] = [p.model_dump(**kwargs) for p in self.products]
+        return result