feat(mcp): rewire @cache_read decorator to Cached* class keys (#472 Phase C)

The @cache_read decorator now keys off the typed-cache Cached* row classes
(CachedVariant, CachedProduct, ...) instead of the legacy EntityType
StrEnum. Each registered class maps to a small wrapper that fans out to
BOTH the legacy cache_sync.ensure_<entity>_synced(services) AND the typed
typed_cache.ensure_<entity>_synced(client, typed_cache) helpers via
asyncio.gather, so tool bodies see fresh data on either path during the
Phase C → Phase D transition.

The 11 catalog @cache_read(EntityType.X) call sites in
tools/foundation/{customers,inventory,items,reference,reporting}.py shift
to @cache_read(CachedX). Tool bodies that still call
services.cache.<method>(EntityType.X, ...) are untouched — Phase D will
migrate them onto services.typed_cache.catalog.* and remove the legacy
cache.

Tests that mock decorators._sync_fns (test_inventory, test_items,
test_customers, test_reference, integration/test_error_scenarios) flip
their dict keys from EntityType to Cached* classes. test_reporting's
{}-returning patch is unaffected.

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

Author: dougborg

katana_mcp_server/docs/architecture.md

@@ -82,12 +82,15 @@ sync when tool surface changes.
 
 ### Cache-aware decorators
 
-`tools/decorators.py` provides `@cache_read("entity")` and
-`@cache_write("entity_a", "entity_b")` decorators. `cache_read` triggers an incremental
-sync of the named entity before invoking the tool; `cache_write` invalidates the listed
-entities after a mutating call so the next list/get returns fresh data. Tool
-implementations stay focused on business logic; sync orchestration lives in the
-decorator.
+`tools/decorators.py` provides `@cache_read(CachedVariant, ...)` and
+`@cache_write("entity_a", "entity_b")` decorators. `cache_read` keys off the typed-cache
+`Cached*` row class (e.g. `CachedVariant`, `CachedProduct`) and triggers an incremental
+sync of the named entity before invoking the tool. During the #472 unification rollout
+(Phase C) the decorator fans each sync out to BOTH the legacy `CatalogCache` helper and
+the typed-cache helper so tool bodies see fresh data on either path; Phase D drops the
+legacy half. `cache_write` invalidates the listed entities after a mutating call so the
+next list/get returns fresh data. Tool implementations stay focused on business logic;
+sync orchestration lives in the decorator.
 
 ## Resources
 
@@ -210,9 +213,9 @@ bugs at the client/generator layer").
    integration; use elicitation for any state-changing operation.
 1. **Follow ADR-0019** for naming (`<entity>_<field>s` for batch list filters, singular
    for `get_*`) and the docstring opening sentence.
-1. **If the tool reads from cache,** add `@cache_read("entity")`. If it writes, add
-   `@cache_write("entity_a", "entity_b")` listing every entity whose cache should be
-   invalidated.
+1. **If the tool reads from cache,** add `@cache_read(CachedEntity)` keyed by the typed
+   `Cached*` row class. If it writes, add `@cache_write("entity_a", "entity_b")` listing
+   every entity whose cache should be invalidated.
 1. **For new transactional list tools backed by typed cache:** add an `EntitySpec`
    literal in `typed_cache/sync.py` and a thin `ensure_<entity>_synced` wrapper. The
    `Cached<Entity>` row class is auto-generated from the spec by the next regen.

katana_mcp_server/src/katana_mcp/tools/decorators.py

@@ -5,7 +5,7 @@
 
 Usage::
 
-    @cache_read("variant")
+    @cache_read(CachedVariant)
     async def _search_items_impl(request, context):
         services = get_services(context)
         return await services.cache.smart_search("variant", request.query)
@@ -15,65 +15,124 @@ async def _search_items_impl(request, context):
     async def _create_item_impl(request, context):
         services = get_services(context)
         return await services.client.products.create(...)
+
+The ``cache_read`` decorator now keys off the typed-cache ``Cached*``
+classes (``CachedVariant``, ``CachedProduct``, …) instead of the legacy
+``EntityType`` enum. During the #472 unification rollout the decorator
+runs **both** the legacy ``cache_sync.ensure_*_synced`` helper and the
+typed ``typed_cache.ensure_*_synced`` helper for each registered class
+so tool bodies see fresh data on either path. Phase D drops the legacy
+half along with the call sites that read from ``services.cache``.
 """
 
 from __future__ import annotations
 
-from collections.abc import Callable
+import asyncio
+from collections.abc import Awaitable, Callable
 from functools import wraps
-from typing import Any, cast
+from typing import TYPE_CHECKING, Any, cast
 
-from katana_mcp.cache import EntityType
 from katana_mcp.services import get_services
 
-# Lazy-initialized cache of sync functions (avoids circular imports)
-_sync_fns: dict[str, Any] | None = None
-
-
-def _get_sync_fns() -> dict[str, Any]:
-    """Get the entity-type → sync function mapping (initialized once)."""
+if TYPE_CHECKING:
+    from sqlmodel import SQLModel
+
+    from katana_mcp.services.dependencies import Services
+
+
+# Lazy-initialized cache of sync functions (avoids circular imports).
+# Keys are typed-cache ``Cached*`` classes; values are async wrappers
+# that fan out to the legacy ``cache_sync.ensure_*_synced(services)``
+# AND the typed ``typed_cache.ensure_*_synced(client, typed_cache)``
+# helpers (#472 Phase C). Phase D drops the legacy half.
+_sync_fns: dict[type[SQLModel], Callable[[Services], Awaitable[None]]] | None = None
+
+# (Cached* class, ensure-helper stem) — both ``cache_sync`` and ``typed_cache``
+# expose ``ensure_<stem>_synced``, differing only in argument shape (legacy
+# takes ``services``; typed takes ``client, cache``). The dual wrapper in
+# ``_get_sync_fns`` resolves the stem against both modules.
+_DUAL_SYNC_REGISTRY: tuple[tuple[str, str], ...] = (
+    ("CachedVariant", "variants"),
+    ("CachedProduct", "products"),
+    ("CachedMaterial", "materials"),
+    ("CachedService", "services"),
+    ("CachedSupplier", "suppliers"),
+    ("CachedCustomer", "customers"),
+    ("CachedLocation", "locations"),
+    ("CachedTaxRate", "tax_rates"),
+    ("CachedOperator", "operators"),
+    ("CachedFactory", "factory"),
+    ("CachedAdditionalCost", "additional_costs"),
+)
+
+
+def _get_sync_fns() -> dict[type[SQLModel], Callable[[Services], Awaitable[None]]]:
+    """Get the ``Cached*`` class → dual-sync wrapper mapping (initialized once).
+
+    Each wrapper runs the legacy ``cache_sync.ensure_<stem>_synced(services)``
+    and the typed ``typed_cache.ensure_<stem>_synced(client, typed_cache)``
+    concurrently via ``asyncio.gather`` so both caches stay populated during
+    the Phase C → Phase D transition without serializing two API fetches.
+    The registry is tiny on purpose — Phase D removes the legacy half.
+    """
     global _sync_fns  # noqa: PLW0603
     if _sync_fns is None:
-        from katana_mcp.cache_sync import (
-            ensure_additional_costs_synced,
-            ensure_customers_synced,
-            ensure_factory_synced,
-            ensure_locations_synced,
-            ensure_materials_synced,
-            ensure_operators_synced,
-            ensure_products_synced,
-            ensure_services_synced,
-            ensure_suppliers_synced,
-            ensure_tax_rates_synced,
-            ensure_variants_synced,
-        )
+        from katana_mcp import cache_sync, typed_cache
+        from katana_public_api_client.models_pydantic import _generated as cached_models
+
+        def _dual(
+            legacy: Callable[[Services], Awaitable[None]],
+            typed: Callable[..., Awaitable[None]],
+        ) -> Callable[[Services], Awaitable[None]]:
+            async def _wrapped(services: Services) -> None:
+                await asyncio.gather(
+                    legacy(services),
+                    typed(services.client, services.typed_cache),
+                )
+
+            return _wrapped
 
         _sync_fns = {
-            EntityType.VARIANT: ensure_variants_synced,
-            EntityType.PRODUCT: ensure_products_synced,
-            EntityType.MATERIAL: ensure_materials_synced,
-            EntityType.SERVICE: ensure_services_synced,
-            EntityType.SUPPLIER: ensure_suppliers_synced,
-            EntityType.CUSTOMER: ensure_customers_synced,
-            EntityType.LOCATION: ensure_locations_synced,
-            EntityType.TAX_RATE: ensure_tax_rates_synced,
-            EntityType.OPERATOR: ensure_operators_synced,
-            EntityType.FACTORY: ensure_factory_synced,
-            EntityType.ADDITIONAL_COST: ensure_additional_costs_synced,
+            getattr(cached_models, cls_name): _dual(
+                getattr(cache_sync, f"ensure_{stem}_synced"),
+                getattr(typed_cache, f"ensure_{stem}_synced"),
+            )
+            for cls_name, stem in _DUAL_SYNC_REGISTRY
         }
     return _sync_fns
 
 
-def cache_read(*entity_types: str) -> Callable:
-    """Sync cache for entity types before executing the tool.
+def cache_read(*entity_classes: type[SQLModel]) -> Callable:
+    """Sync cache for the given typed ``Cached*`` classes before running the tool.
 
-    Calls ``ensure_{type}_synced(services)`` for each entity type before
-    running the decorated function. The function receives a context with
-    a guaranteed-fresh cache.
+    For each class the decorator looks up the registered sync wrapper in
+    ``_get_sync_fns()`` and awaits it. Each wrapper currently fans out to
+    BOTH the legacy ``CatalogCache`` sync helper AND the typed-cache
+    ``ensure_*_synced`` helper so tool bodies see fresh data on either
+    path during the #472 unification rollout. Phase D drops the legacy
+    half along with the ``services.cache`` call sites.
+
+    Unknown classes raise ``ValueError`` at decoration time so a typo
+    fails at import, not silently as a stale-cache read at first call.
 
     Args:
-        *entity_types: Entity type names to sync (e.g., "variant", "product").
+        *entity_classes: Typed ``Cached*`` classes to sync (e.g.,
+            ``CachedVariant``, ``CachedProduct``).
     """
+    # Fail fast at decoration time so a typo blows up at import, not as
+    # a silent stale-cache read on the first request. Tests that swap
+    # ``decorators._sync_fns`` in autouse fixtures still get the live
+    # mocks at call time — the wrapper re-resolves through
+    # ``_get_sync_fns()``.
+    registered = _get_sync_fns()
+    unknown = [cls for cls in entity_classes if cls not in registered]
+    if unknown:
+        names = ", ".join(cls.__name__ for cls in unknown)
+        known = ", ".join(sorted(c.__name__ for c in registered))
+        raise ValueError(
+            f"@cache_read: unregistered Cached* class(es): {names}. "
+            f"Registered classes: {known}."
+        )
 
     def decorator[F: Callable[..., Any]](fn: F) -> F:
         @wraps(fn)
@@ -82,11 +141,9 @@ async def wrapper(*args: Any, **kwargs: Any) -> Any:
             services = get_services(context)
 
             sync_fns = _get_sync_fns()
-            for et in entity_types:
-                # EntityType is a StrEnum — normalize to ensure dict lookup works
-                key = EntityType(et) if not isinstance(et, EntityType) else et
-                sync_fn = sync_fns.get(key)
-                if sync_fn:
+            for cls in entity_classes:
+                sync_fn = sync_fns.get(cls)
+                if sync_fn is not None:
                     await sync_fn(services)
 
             return await fn(*args, **kwargs)

katana_mcp_server/src/katana_mcp/tools/foundation/customers.py

@@ -20,6 +20,7 @@
 from katana_mcp.tools.tool_result_utils import make_simple_result
 from katana_mcp.unpack import Unpack, unpack_pydantic_params
 from katana_mcp.web_urls import katana_web_url
+from katana_public_api_client.models_pydantic._generated import CachedCustomer
 
 # ============================================================================
 # Tool 1: search_customers
@@ -74,7 +75,7 @@ def _customer_from_dict(d: dict) -> CustomerInfo:
     )
 
 
-@cache_read(EntityType.CUSTOMER)
+@cache_read(CachedCustomer)
 async def _search_customers_impl(
     request: SearchCustomersRequest, context: Context
 ) -> SearchCustomersResponse:
@@ -274,7 +275,7 @@ async def _fetch_customer_addresses(
     return result
 
 
-@cache_read(EntityType.CUSTOMER)
+@cache_read(CachedCustomer)
 async def _get_customer_impl(
     request: GetCustomerRequest, context: Context
 ) -> GetCustomerResponse:

katana_mcp_server/src/katana_mcp/tools/foundation/inventory.py

@@ -37,6 +37,7 @@
 from katana_public_api_client.api.stock_adjustment import get_all_stock_adjustments
 from katana_public_api_client.client_types import UNSET, Unset
 from katana_public_api_client.domain.converters import to_unset, unwrap_unset
+from katana_public_api_client.models_pydantic._generated import CachedVariant
 from katana_public_api_client.utils import unwrap_data
 
 logger = get_logger(__name__)
@@ -415,7 +416,7 @@ class LowStockResponse(BaseModel):
     total_count: int
 
 
-@cache_read(EntityType.VARIANT)
+@cache_read(CachedVariant)
 async def _list_low_stock_items_impl(
     request: LowStockRequest, context: Context
 ) -> LowStockResponse:

katana_mcp_server/src/katana_mcp/tools/foundation/items.py

@@ -91,6 +91,12 @@
     UpdateVariantRequestConfigAttributesItem as APIUpdateVariantConfigItem,
     Variant,
 )
+from katana_public_api_client.models_pydantic._generated import (
+    CachedMaterial,
+    CachedProduct,
+    CachedSupplier,
+    CachedVariant,
+)
 
 logger = get_logger(__name__)
 
@@ -177,7 +183,7 @@ def _search_response_to_tool_result(
     return make_tool_result(filtered_response, ui=ui)
 
 
-@cache_read(EntityType.VARIANT)
+@cache_read(CachedVariant)
 async def _search_items_impl(
     request: SearchItemsRequest, context: Context
 ) -> SearchItemsResponse:
@@ -1755,10 +1761,10 @@ def _partition_variant_lookups(
 
 
 @cache_read(
-    EntityType.VARIANT,
-    EntityType.PRODUCT,
-    EntityType.MATERIAL,
-    EntityType.SUPPLIER,
+    CachedVariant,
+    CachedProduct,
+    CachedMaterial,
+    CachedSupplier,
 )
 async def _get_variant_details_impl(
     request: GetVariantDetailsRequest, context: Context

katana_mcp_server/src/katana_mcp/tools/foundation/reference.py

@@ -20,6 +20,13 @@
 from katana_mcp.tools.decorators import cache_read
 from katana_mcp.tools.tool_result_utils import make_simple_result
 from katana_mcp.unpack import Unpack, unpack_pydantic_params
+from katana_public_api_client.models_pydantic._generated import (
+    CachedAdditionalCost,
+    CachedLocation,
+    CachedOperator,
+    CachedSupplier,
+    CachedTaxRate,
+)
 
 # ============================================================================
 # Shared helpers
@@ -140,7 +147,7 @@ def _supplier_summary_from_dict(d: dict[str, Any]) -> SupplierInfo:
     )
 
 
-@cache_read(EntityType.SUPPLIER)
+@cache_read(CachedSupplier)
 async def _list_suppliers_impl(
     request: ListSuppliersRequest, context: Context
 ) -> ListSuppliersResponse:
@@ -230,7 +237,7 @@ def _iso_or_none(value: Any) -> str | None:
     return str(value)
 
 
-@cache_read(EntityType.SUPPLIER)
+@cache_read(CachedSupplier)
 async def _get_supplier_impl(
     request: GetSupplierRequest, context: Context
 ) -> GetSupplierResponse:
@@ -383,7 +390,7 @@ def _location_from_dict(d: dict[str, Any]) -> LocationInfo:
     )
 
 
-@cache_read(EntityType.LOCATION)
+@cache_read(CachedLocation)
 async def _list_locations_impl(
     request: ListLocationsRequest, context: Context
 ) -> ListLocationsResponse:
@@ -482,7 +489,7 @@ def _tax_rate_from_dict(d: dict[str, Any]) -> TaxRateInfo:
     )
 
 
-@cache_read(EntityType.TAX_RATE)
+@cache_read(CachedTaxRate)
 async def _list_tax_rates_impl(
     request: ListTaxRatesRequest, context: Context
 ) -> ListTaxRatesResponse:
@@ -566,7 +573,7 @@ def _operator_from_dict(d: dict[str, Any]) -> OperatorInfo:
     return OperatorInfo(id=d.get("id") or 0, name=d.get("name") or "")
 
 
-@cache_read(EntityType.OPERATOR)
+@cache_read(CachedOperator)
 async def _list_operators_impl(
     request: ListOperatorsRequest, context: Context
 ) -> ListOperatorsResponse:
@@ -641,7 +648,7 @@ def _additional_cost_from_dict(d: dict[str, Any]) -> AdditionalCostInfo:
     return AdditionalCostInfo(id=d.get("id") or 0, name=d.get("name") or "")
 
 
-@cache_read(EntityType.ADDITIONAL_COST)
+@cache_read(CachedAdditionalCost)
 async def _list_additional_costs_impl(
     request: ListAdditionalCostsRequest, context: Context
 ) -> ListAdditionalCostsResponse: