feat(migrate+types): v3->v4 codemod, strict-validation flag, version helpers, subclass test

[bokelley]

Summary

Third of three PRs on salesagent's feedback. Closes the final 4 items. All additive — no breaking changes.

Item	What
#5	python -m adcp.migrate v3-to-v4 — new CLI that rewrites the 9 <Type>Asset → <Type>Content renames and flags usages of removed types (BrandManifest, DeliverTo, Pricing, etc.) + numbered Assets<N> imports + adcp.types.generated_poc imports. Dry-run default, --apply rewrites in place, --json for CI. Exit 1 on flagged findings. No new runtime deps.
#6	ADCP_STRICT_VALIDATION=1 env flag on AdCPBaseModel. Flips extra='forbid' at import time; default stays 'ignore' for forward-compat. Use during spec upgrades to surface silently-dropped renamed fields.
#11	get_adcp_spec_version() + get_adcp_sdk_version() split the ambiguous get_adcp_version() into two named helpers. Old name kept as a spec-version alias.
#4	Subclass passthrough test locks the exclude=True contract through products_response / signals_response / media_buys_response / list_creatives_response so a future _serialize refactor can't silently leak seller internals.

Tested

• +49 new tests across 4 files:
  • tests/test_migrate_v3_to_v4.py (20): renames, word boundaries, removed-type anchors, numbered-Assets flagging, skip-dirs, CLI exit codes, JSON output, apply-rewrites-and-reports, unreadable-file graceful skip.
  • tests/test_response_builder_subclass.py (5): 4 builders × subclass passthrough + mixed-base-and-subclass.
  • tests/test_strict_validation_env.py (17): all truthy/falsy variants, whitespace handling, unset default, model_config wiring.
  • tests/test_version_helpers.py (4): sdk-matches-dunder, spec non-empty, legacy alias, distinct concepts.
• Full suite: 2001 passed, 22 skipped locally (1937 → 2001).
• ruff, mypy clean across 676 source files.

Test plan

• CI green across Python 3.10–3.13
• Review: does the migrate CLI's regex + word-boundary approach suffice, or should it use libcst/ast for safer AST-level rewrites? (Tradeoff: new dep vs. false-positive risk — current approach has tests showing MyAudioAsset / AudioAssetExtra stay untouched.)
• Review: should get_adcp_version emit a DeprecationWarning when called, or is a docstring .. deprecated:: note enough? Current impl is silent-alias to avoid breaking pre-4.1 callers.
• Review: is ADCP_STRICT_VALIDATION resolved at import time the right policy, or should it be per-model / per-call? Import-time is simpler; per-model adds flexibility at the cost of surprising runtime behavior.

Related

Part of triaging feedback from salesagent (primary downstream of adcp.server).

• PR feat(server): AccountAwareToolContext + multi-tenant contract doc #245 (merged): AccountAwareToolContext + multi-tenant contract doc (items chore(main): release 0.1.1 #2, fix: correct tool name in list_creative_formats method #10).
• PR feat(server): middleware parity, auth, A2A parser hook, startup log #246: server middleware/auth/observability parity (items chore(main): release 0.1.0 #1, chore(main): release 0.1.2 #3, revert: restore correct PYPY_API_TOKEN secret name #7, fix: use correct PYPY_API_TOKEN secret for PyPI publishing #8, chore(main): release 1.0.1 #9).
• PR feat(migrate+types): v3->v4 codemod, strict-validation flag, version helpers, subclass test #247 (this): migrate + strict + versions + subclass test (items chore(main): release 1.0.0 #4, feat: complete Python AdCP SDK with typed API and auto-generated types #5, fix: correct PyPI API token secret name #6, chore(main): release 1.0.2 #11).

All 11 feedback items now addressed.

🤖 Generated with Claude Code