feat(mcp): extend rebuild_cache to cover catalog entity types

`force_resync` already handles every key in `ENTITY_SPECS` (16 total)
— but the `CacheEntityType` literal on `RebuildCacheRequest`
restricted callers to the 5 transactional ones. Catalog entities
(variants, products, materials, services, customers, suppliers,
locations, tax rates, operators, factories, additional costs) couldn't
be rebuilt through the tool even though the underlying capability
existed. This came up while verifying the #669 location regression
— "delete the cache file" was the only documented escape hatch for
catalog drift.

Extend the literal to cover all 16 entity types. Also pin the
literal-vs-`ENTITY_SPECS` consistency with a test that loops over
every entity in `ENTITY_SPECS` and asserts the request validator
accepts it — adding a new entity to the typed cache without
extending the literal would otherwise silently exclude it from the
tool. Smoke-test `location` end-to-end (phantom-cleanup happy path)
to prove the catalog tier actually works through the tool, not just
through `force_resync` directly.

Update the tool docstring, the request-field description, and the
help-resource entries so callers see the expanded set in tool
introspection and host-rendered docs.

Refs #659

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

Author: dougborg

katana_mcp_server/src/katana_mcp/resources/help.py

@@ -85,7 +85,7 @@
 - **list_additional_costs** - List or fuzzy-search the additional-cost catalog (freight, duties, handling). Use for `additional_cost_id` on `modify_purchase_order`. Supports `query`, `limit`, `format`.
 
 ### Cache Administration
-- **rebuild_cache** - Force-rebuild the local typed cache for one or more transactional entity types (PO, SO, MO, stock adjustment, stock transfer). Truncates the cache table(s), clears the sync watermark, and re-fetches from Katana. Use when the cache has phantom rows (entities present locally but missing from Katana). Destructive; preview/apply.
+- **rebuild_cache** - Force-rebuild the local typed cache for one or more cached entity types. Covers transactional entities (PO, SO, MO, stock adjustment, stock transfer) and catalog entities (variant, product, material, service, customer, supplier, location, tax_rate, operator, factory, additional_cost). Truncates the cache table(s), clears the sync watermark, and re-fetches from Katana. Use when the cache has phantom rows (entities present locally but missing from Katana). Destructive; preview/apply.
 
 ## Safety Pattern
 
@@ -1820,7 +1820,7 @@
 ## Cache Administration Tools
 
 ### rebuild_cache
-Force-rebuild the local typed cache for one or more transactional entity types.
+Force-rebuild the local typed cache for one or more cached entity types.
 The steady-state sync path upserts via `session.merge` and never deletes — soft-
 deletes from Katana are folded in correctly because the tombstone surfaces in
 the next `updated_at_min` delta, but rows that left Katana without a tombstone
@@ -1837,8 +1837,11 @@
 
 **Parameters:**
 - `entity_types` (required, min length 1): list of entity types to rebuild.
-  Allowed values: `purchase_order`, `sales_order`, `manufacturing_order`,
-  `stock_adjustment`, `stock_transfer`.
+  Allowed values cover transactional entities (`purchase_order`, `sales_order`,
+  `manufacturing_order`, `stock_adjustment`, `stock_transfer`) and catalog
+  entities (`variant`, `product`, `material`, `service`, `customer`,
+  `supplier`, `location`, `tax_rate`, `operator`, `factory`,
+  `additional_cost`).
 - `preview` (optional, default true): true = report current row counts and
   last-synced timestamps without modifying anything; false = perform the
   destructive rebuild.

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

@@ -3,9 +3,9 @@
 Operational utilities for the typed cache (``katana_mcp.typed_cache``).
 
 Currently provides ``rebuild_cache``: a destructive force-resync that
-truncates the cache tables for a set of transactional entity types,
-clears their ``SyncState`` watermarks, and re-fetches the live state
-from Katana — atomically under the entity's sync lock so concurrent
+truncates the cache tables for a set of cached entity types, clears
+their ``SyncState`` watermarks, and re-fetches the live state from
+Katana — atomically under the entity's sync lock so concurrent
 ``list_*`` tools never see the empty intermediate state.
 
 Why this exists: the steady-state sync path upserts via
@@ -17,6 +17,12 @@
 ``list_*`` tools filter ``deleted_at IS NULL``, but phantom rows that
 never received a soft-delete bump still leak. Rebuild is the manual
 escape hatch.
+
+Coverage: every key in ``katana_mcp.typed_cache.ENTITY_SPECS`` is
+addressable — both the transactional entities (PO, SO, MO + recipe
+rows, stock adjustments, stock transfers) and the catalog entities
+(variants, products, materials, services, customers, suppliers,
+locations, tax rates, operators, factories, additional costs).
 """
 
 from __future__ import annotations
@@ -49,11 +55,26 @@
 # pyright ``Literal`` mismatch until added below, catching the drift at
 # review time rather than runtime).
 CacheEntityType = Literal[
+    # Transactional entities — parent + nested/related child rows.
     "purchase_order",
     "sales_order",
     "manufacturing_order",
     "stock_adjustment",
     "stock_transfer",
+    # Catalog entities — flat tables, no inline child rows. ``variant``
+    # carries denormalized parent-archive state; the rest are simple
+    # name/id lookups against the corresponding Katana endpoints.
+    "variant",
+    "product",
+    "material",
+    "service",
+    "customer",
+    "supplier",
+    "location",
+    "tax_rate",
+    "operator",
+    "factory",
+    "additional_cost",
 ]
 
 
@@ -73,7 +94,11 @@ class RebuildCacheRequest(BaseModel):
         description=(
             "Entity types to rebuild. Each entry truncates the cache "
             "table(s) for that entity, clears its sync watermark, and "
-            "re-fetches the live state from Katana."
+            "re-fetches the live state from Katana. Covers transactional "
+            "entities (purchase_order, sales_order, manufacturing_order, "
+            "stock_adjustment, stock_transfer) and catalog entities "
+            "(variant, product, material, service, customer, supplier, "
+            "location, tax_rate, operator, factory, additional_cost)."
         ),
     )
     preview: bool = Field(
@@ -271,7 +296,7 @@ def _format_markdown(response: RebuildCacheResponse) -> str:
 async def rebuild_cache(
     request: Annotated[RebuildCacheRequest, Unpack()], context: Context
 ) -> ToolResult:
-    """Force-rebuild the local typed cache for one or more transactional entity types.
+    """Force-rebuild the local typed cache for one or more cached entity types.
 
     Use this when the local cache has drifted from Katana — the most
     common symptom is "phantom" rows (entities present in the cache
@@ -290,8 +315,16 @@ async def rebuild_cache(
        locks, so concurrent ``list_*`` tools block until the cache is
        repopulated and never see the empty intermediate state.
 
-    **Supported entity types:** ``purchase_order``, ``sales_order``,
-    ``manufacturing_order``, ``stock_adjustment``, ``stock_transfer``.
+    **Supported entity types:**
+
+    - Transactional: ``purchase_order``, ``sales_order``,
+      ``manufacturing_order``, ``stock_adjustment``, ``stock_transfer``
+      (each rebuilds the parent table plus its child/related-spec
+      tables, e.g. PO + PO rows, MO + MO recipe rows).
+    - Catalog: ``variant``, ``product``, ``material``, ``service``,
+      ``customer``, ``supplier``, ``location``, ``tax_rate``,
+      ``operator``, ``factory``, ``additional_cost`` (flat tables,
+      no inline child rows).
 
     **Two-step flow:**
     - ``preview=true`` (default) — reports current row counts and last-

katana_mcp_server/tests/tools/test_cache_admin.py

@@ -563,6 +563,89 @@ async def reader():
         ]
 
 
+# ============================================================================
+# Catalog entity coverage — `rebuild_cache` accepts all 16 keys in
+# `ENTITY_SPECS`, not just the 5 transactional ones it shipped with.
+# Smoke-test one catalog entity end-to-end (location — the headline #669
+# regression source) plus a literal-shape test that pins the full
+# accepted set against `ENTITY_SPECS` so adding a new entity to the
+# typed cache surfaces the missing literal at review time.
+# ============================================================================
+
+
+class TestCatalogEntityRebuild:
+    @pytest.mark.asyncio
+    async def test_rebuild_location_clears_phantom_and_repulls(
+        self, typed_cache_engine
+    ):
+        """End-to-end smoke test for the catalog tier of `rebuild_cache`.
+
+        Exercises one catalog entity (location) through the full
+        `force_resync` path: seed two locations (one of which the live
+        API will omit), patch the API to return only the live one,
+        confirm the phantom is gone after rebuild and that the live row
+        survives. Same shape as the headline transactional test
+        `test_phantom_purchase_order_is_removed_after_rebuild`, just
+        against a flat catalog table.
+        """
+        from katana_public_api_client.models import Location as AttrsLocation
+        from katana_public_api_client.models_pydantic._generated import (
+            CachedLocation,
+        )
+
+        # Seed: one row Katana still has, one phantom Katana doesn't.
+        async with typed_cache_engine.session() as session:
+            session.add(CachedLocation(id=1, name="Main Warehouse"))
+            session.add(CachedLocation(id=999, name="Phantom Warehouse"))
+            await session.commit()
+
+        context = _build_context(typed_cache_engine)
+        live_location = AttrsLocation.from_dict({"id": 1, "name": "Main Warehouse"})
+        live_response = MagicMock()
+        live_response.status_code = 200
+        live_response.parsed = MagicMock(data=[live_location])
+
+        with patch(
+            "katana_mcp.typed_cache.sync.get_all_locations.asyncio_detailed",
+            new=AsyncMock(return_value=live_response),
+        ):
+            response = await _rebuild_cache_impl(
+                RebuildCacheRequest(entity_types=["location"], preview=False),
+                context,
+            )
+
+        assert response.is_preview is False
+        result = response.results[0]
+        assert result.entity_type == "location"
+        assert result.parent_rows_before == 2
+        assert result.parent_rows_after == 1
+        # Catalog entities have no related-spec children, so the only
+        # cleared key is the parent's own watermark.
+        assert result.sync_state_keys_cleared == ["location"]
+
+        async with typed_cache_engine.session() as session:
+            remaining = (await session.exec(select(CachedLocation))).all()
+        ids = {loc.id for loc in remaining}
+        assert ids == {1}, f"Phantom location 999 should be gone, got {ids}"
+
+    def test_request_accepts_all_entity_specs_keys(self):
+        """The `CacheEntityType` literal must stay in lock-step with
+        `ENTITY_SPECS`. Adding a new entity to the typed cache without
+        also extending the `Literal` would silently exclude it from the
+        rebuild_cache tool — tested explicitly so the gap can't ship.
+        """
+        for entity_key in ENTITY_SPECS:
+            # `model_validate` exercises the Literal check at runtime;
+            # success means the key is in the accepted set.
+            req = RebuildCacheRequest.model_validate(
+                {"entity_types": [entity_key], "preview": True}
+            )
+            assert req.entity_types == [entity_key], (
+                f"{entity_key!r} accepted by ENTITY_SPECS but rejected by "
+                f"CacheEntityType — extend the Literal in cache_admin.py."
+            )
+
+
 # ============================================================================
 # Request validation — invalid entity types fail at the request boundary
 # ============================================================================