test(server): rewrite spec_compat tests against public API (#657)

Closes #653. The previous tests in tests/test_spec_compat_hooks.py
reached into private helpers (_hook_get_products, _make_sync_creatives_hook,
_coerce_asset, _infer_asset_type) and asserted on internal shapes, which
hid a class of bugs the public surface would expose.

Changes:

- All tests now exercise spec_compat_hooks() and the returned dict only.
  No private imports.
- Add four model_validate() proofs that hook output is actually 4.4-valid:
  one for get_products (buying_mode default), three for sync_creatives
  (format_id wrap, asset_type inference, image→url demotion). Failure
  here means the hook is producing dicts that pass our internal asserts
  but fail at the dispatcher boundary.
- Expand the create_tool_caller integration suite from one buying_mode
  smoke test to four end-to-end paths: get_products default, sync_creatives
  format_id wrap, asset_type inference, image→url demotion.
- spec_compat_hooks(exclude={...}) now emits a UserWarning for unknown
  hook names (typos like "sync_creative" used to silently leave the hook
  active). Document the behaviour in the factory's exclude= section.

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

Author: bokelley

src/adcp/server/spec_compat.py

@@ -30,6 +30,7 @@
 
 from __future__ import annotations
 
+import warnings
 from collections.abc import Callable, Collection
 from typing import Any, TypeAlias
 
@@ -44,6 +45,13 @@
 creative-format registries.
 """
 
+_VALID_HOOK_NAMES: frozenset[str] = frozenset({"get_products", "sync_creatives"})
+"""Tool names ``spec_compat_hooks()`` returns hooks for.
+
+Exposed for ``exclude=`` validation — a typo like ``exclude={"sync_creative"}``
+emits a :class:`UserWarning` instead of silently leaving the hook active.
+"""
+
 # Exact set of asset_type discriminator values the spec defines.
 # Used by the asset_type inference heuristic — only exact key matches count.
 _KNOWN_ASSET_TYPES: frozenset[str] = frozenset(
@@ -119,9 +127,7 @@ def _coerce_asset(asset_key: str, asset: dict[str, Any]) -> dict[str, Any]:
     # Only fires when url is present — if url is also absent the asset is
     # structurally unusable either way; leave it for schema validation to
     # report rather than silently changing the type to something equally invalid.
-    if asset.get("asset_type") == "image" and not (
-        "width" in asset and "height" in asset
-    ):
+    if asset.get("asset_type") == "image" and not ("width" in asset and "height" in asset):
         if "url" in asset:
             asset = {k: v for k, v in asset.items() if k not in ("width", "height")}
             asset = {**asset, "asset_type": "url"}
@@ -217,10 +223,11 @@ def spec_compat_hooks(
         only one callable per tool name.
 
     Args:
-        exclude: Tool names to exclude from the returned dict. Members that
-            are not valid hook names are silently ignored. Example:
-            ``exclude={"sync_creatives"}`` returns only the ``get_products``
-            hook.
+        exclude: Tool names to exclude from the returned dict. Names not in
+            :data:`_VALID_HOOK_NAMES` raise a :class:`UserWarning` (a typo
+            like ``exclude={"sync_creative"}`` would otherwise silently leave
+            the hook active). Example: ``exclude={"sync_creatives"}`` returns
+            only the ``get_products`` hook.
         creative_agent_url: Registry URL injected when wrapping a bare
             ``format_id`` string.  Defaults to
             ``CANONICAL_CREATIVE_AGENT_URL``.  Override for private
@@ -231,6 +238,16 @@ def spec_compat_hooks(
         ``serve(pre_validation_hooks=...)``.
     """
     excluded: frozenset[str] = frozenset(exclude) if exclude else frozenset()
+    unknown = excluded - _VALID_HOOK_NAMES
+    if unknown:
+        warnings.warn(
+            "spec_compat_hooks(exclude=...) received unknown hook name(s): "
+            f"{sorted(unknown)}. Valid names: {sorted(_VALID_HOOK_NAMES)}. "
+            "Typos here are silent — verify the name matches the tool you "
+            "intended to opt out.",
+            UserWarning,
+            stacklevel=2,
+        )
     hooks: PreValidationHooks = {}
 
     if "get_products" not in excluded: