feat(mcp)!: migrate catalog call sites to typed cache + decommission CatalogCache (#472 Phase D)

Phase D of the cache-unification effort. Migrates ~33 catalog read
call sites from the legacy ``CatalogCache`` to ``TypedCacheEngine``
via the ``CatalogQueries`` adapter (``services.typed_cache.catalog``)
and decommissions the legacy modules.

Source migration:
- Foundation tools: ``items``, ``inventory``, ``customers``,
  ``reference``, ``reporting``, ``orders``, ``manufacturing_orders``,
  ``sales_orders``, ``purchase_orders``, ``stock_transfers`` all
  call ``services.typed_cache.catalog.*(Cached*Class, ...)`` instead
  of ``services.cache.*(EntityType, ...)``. Dict access (``v["sku"]``)
  flips to attribute access (``v.sku``) with an ``_attr`` helper
  bridging dict / attrs / SQLModel call shapes in helper paths that
  may receive either a cache row or an API-fallback attrs model.
- Decorator ``@cache_read`` keys off the ``Cached*`` SQLModel class
  (e.g. ``CachedVariant``) instead of an ``EntityType`` enum value;
  fans out to typed-cache sync helpers only. Legacy ``@cache_write``
  / ``mark_dirty`` mechanism removed — typed cache pulls incremental
  deltas via ``updated_at_min`` on every ``@cache_read``-decorated
  call, so explicit invalidation is no longer needed.
- ``resolve_entity_name`` takes a ``Cached*`` class plus the
  ``CatalogQueries`` adapter; tolerates both rows and dicts during
  the transition.
- ``Services`` dataclass: ``cache`` field removed; only ``client``
  and ``typed_cache`` remain. Lifespan in ``server.py`` initializes
  only the typed cache.
- ``services.typed_cache.catalog`` is now the only catalog read
  path; the inline negative-lookup cache in reporting tightened to
  ``if variant_id not in variant_cache`` so ``None`` stays a valid
  cached negative result.

Decommission:
- Delete ``katana_mcp/cache.py`` (~870 LOC) and ``katana_mcp/cache_sync.py``.
- Delete ``tests/test_cache.py`` and ``tests/test_cache_sync.py``.
- ``EntityType`` enum disappears with ``cache.py``.

Soft-state filter opt-ins on direct-lookup paths:
- ``get_by_id`` / ``get_by_sku`` callers that need to surface
  archived or soft-deleted rows for inspection (e.g. ``check_inventory``
  on an archived SKU, ``modify_*`` flows resolving a tombstoned entity)
  pass ``include_archived=True`` / ``include_deleted=True`` explicitly,
  matching the legacy cache's "show every row regardless of soft-state"
  semantics for direct lookups. The search-list paths
  (``smart_search`` / ``search_fuzzy`` / ``get_all``) keep the
  adapter's filtered defaults — the papercut fix from #472 Phase B.

Tests:
- ``conftest.create_mock_context`` exposes the six ``CatalogQueries``
  methods on ``lifespan_ctx.typed_cache.catalog``; legacy
  ``lifespan_ctx.cache`` removed.
- All ~13 mock test files migrated. Mock helpers accept ``**_kw`` to
  swallow the adapter's ``include_archived`` / ``include_deleted``
  kwargs. ``CachedCustomer`` / ``CachedSupplier`` / ``CachedLocation``
  / ``CachedVariant`` factories replace dict-shaped fixtures.

Docs:
- ADR-0018 status flipped — the "follow-up epic" is complete; the
  dual-cache rollout section is now historical.
- ``architecture.md`` cache section rewritten for the single-cache
  reality; "Adding a new tool" checklist updated to direct
  contributors at ``@cache_read(CachedEntity)``.
- CLAUDE.md "Known Pitfalls" updated — the cache-ID uniqueness note
  no longer points at the retired ``CatalogCache``; the soft-state
  flags note now describes the ``CatalogQueries`` adapter wiring.

BREAKING CHANGE: ``Services.cache`` field removed.
``katana_mcp.cache`` and ``katana_mcp.cache_sync`` modules removed.
``EntityType`` enum removed. Third-party consumers of
``katana_mcp_server`` that touched any of these will need to migrate
to ``services.typed_cache.catalog`` and the ``Cached*`` SQLModel
classes from ``katana_public_api_client.models_pydantic._generated``.

Closes #472.

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

Author: dougborg

CLAUDE.md

@@ -163,13 +163,15 @@ Common mistakes to avoid:
   soft-deleted. Two MCP-side conventions surface this; keep them symmetric:
 
   - **Query-param flags** for opting into surfacing soft-state rows. **Default
-    `False`.** Items use `include_archived` (`search_items`, catalog cache); the
-    canonical wiring (landed in #526) is `cache.py`'s denormalized
-    `entity_index.is_archived` column populated during sync, plus the
-    `idx.is_archived = 0` predicate in `cache.search` / `search_fuzzy`. Transactional
+    `False`.** Items use `include_archived` (`search_items`, catalog cache); after #472
+    Phase D the canonical wiring is the typed cache's `CatalogQueries` adapter —
+    `parent_archived_at` is denormalized onto `CachedVariant` at sync time (via the
+    variant `attrs_postprocess` hook in `typed_cache/sync.py`) and the adapter's default
+    `include_archived=False` / `include_deleted=False` filters push the
+    `archived_at IS NULL` / `deleted_at IS NULL` predicates down to SQL. Transactional
     entities use `include_deleted` on `list_purchase_orders` / `list_sales_orders` /
-    `list_manufacturing_orders` / `list_stock_adjustments`, filtering at the typed-cache
-    query layer.
+    `list_manufacturing_orders` / `list_stock_adjustments`, filtering at the same
+    typed-cache query layer.
   - **Response-side derived booleans**: every response model that exposes `archived_at`
     / `deleted_at` should also expose a convenience `is_archived` / `is_deleted` bool
     derived from `<timestamp> is not None`, saving callers from the timestamp/null
@@ -243,18 +245,18 @@ Common mistakes to avoid:
   `.claude/worktrees/` as off-limits for destructive operations.
 
 - **Cache IDs are not globally unique — never merge cross-entity maps by numeric ID
-  alone** - The legacy `CatalogCache` (`katana_mcp/cache.py`) — and `services.cache` by
-  extension — keys rows by `(entity_type, id)`, so a product with `id=42` and a material
-  with `id=42` are both legal. When enriching a list of variants with parent context (or
-  any other cross-entity batch fetch), keep separate per-type maps (`products`,
-  `materials`) and select based on which ID the variant carries (`v.product_id` vs
-  `v.material_id`). Merging into a single dict via `{**products, **materials}`
-  mis-attaches parents on collision — Python dict-unpack iterates left-to-right and
-  later keys win, so the material entry silently overwrites the product entry on shared
-  IDs. The bug is symmetric in practice: every product variant whose ID also exists as a
-  material ID looks up the material's data instead (and vice versa if you reorder the
-  unpack). Caught in #542 (variant card redesign) by Copilot review; regression test
-  pins the case in
+  alone** - The typed cache stores each entity type in its own table (`product`,
+  `material`, `supplier`, ...), so a product with `id=42` and a material with `id=42`
+  are both legal. When enriching a list of variants with parent context (or any other
+  cross-entity batch fetch), keep separate per-type maps (`products`, `materials`) and
+  select based on which ID the variant carries (`v.product_id` vs `v.material_id`).
+  Merging into a single dict via `{**products, **materials}` mis-attaches parents on
+  collision — Python dict-unpack iterates left-to-right and later keys win, so the
+  material entry silently overwrites the product entry on shared IDs. The bug is
+  symmetric in practice: every product variant whose ID also exists as a material ID
+  looks up the material's data instead (and vice versa if you reorder the unpack).
+  Caught in #542 (variant card redesign) by Copilot review; regression test pins the
+  case in
   `test_items.py::test_enrich_variants_keeps_product_and_material_maps_separate`.
 
 - **First push of a feature branch — use `HEAD:refs/heads/<name>`, not bare branch

katana_mcp_server/docs/adr/0018-sqlmodel-typed-cache.md

@@ -6,6 +6,14 @@ Accepted
 
 Date: 2026-04-23
 
+**Update (2026-05-11, #472 Phase D):** the "follow-up epic" called out below — unifying
+the catalog tier under `TypedCacheEngine` and retiring `CatalogCache` — is **complete**.
+`katana_mcp.cache` and `katana_mcp.cache_sync` are removed; the typed cache now backs
+both transactional and catalog reads via the `CatalogQueries` adapter
+(`services.typed_cache.catalog`). The "dual-cache coexistence during rollout" section
+below describes a transient state that no longer exists. The "Scope 2" question
+(replacing the attrs API transport) remains open.
+
 ## Context
 
 Analytical workflows over Katana data were making large numbers of sequential API calls

katana_mcp_server/docs/architecture.md

@@ -31,9 +31,10 @@ calls with its own retry / rate-limit logic.
 │  Services / dependencies (services/dependencies.py)        │
 │   get_services(context) → KatanaClient + caches            │
 ├────────────────────────────────────────────────────────────┤
-│  Caches (two, by design — see ADR-0018)                    │
-│   CatalogCache (cache.py)       — reference entities       │
-│   TypedCacheEngine (typed_cache/) — transactional entities │
+│  Cache (unified — see ADR-0018 + #472 Phase D)             │
+│   TypedCacheEngine (typed_cache/)                          │
+│   - catalog tier   — variants/products/materials/...       │
+│   - transactional  — sales/manufacturing/purchase orders   │
 ├────────────────────────────────────────────────────────────┤
 │  KatanaClient (katana_public_api_client)                   │
 │   - transport-layer resilience                             │
@@ -82,15 +83,15 @@ sync when tool surface changes.
 
 ### Cache-aware decorators
 
-`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.
+`tools/decorators.py` provides `@cache_read(CachedVariant, CachedProduct, ...)`.
+`cache_read` triggers an incremental sync of the named typed-cache entities before
+invoking the tool. Tool implementations stay focused on business logic; sync
+orchestration lives in the decorator.
+
+Cache invalidation after writes is **implicit**: the typed cache pulls incremental
+deltas via `updated_at_min` on every `@cache_read`-decorated call, so a freshly-created
+or modified entity is picked up automatically by the next read. The legacy `cache_write`
+/ `mark_dirty` mechanism was retired alongside `CatalogCache` (#472 Phase D).
 
 ## Resources
 
@@ -116,37 +117,36 @@ from katana_mcp.services import get_services
 
 services = get_services(context)
 client = services.client            # KatanaClient
-catalog_cache = services.cache      # CatalogCache
 typed_cache = services.typed_cache  # TypedCacheEngine
+catalog = services.typed_cache.catalog  # CatalogQueries adapter
 ```
 
 Lifespan management (engine open/close, client cleanup) is handled by `server.py`.
 
-## Caches
-
-The MCP server runs **two** complementary caches. They serve different needs and both
-are permanent — neither is a temporary stepping stone toward the other
-([ADR-0018](adr/0018-sqlmodel-typed-cache.md)).
+## Cache
 
-### CatalogCache (`katana_mcp/cache.py`, `cache_sync.py`)
-
-A generic SQLite + FTS5 store for the 10 reference entity types: variants, products,
-materials, services, suppliers, customers, locations, tax rates, operators, factories.
-Every row projects into a three-text-column `entity_index` (name, description, code) for
-cheap full-text search across heterogeneous types. Powers `search_items` and
-`get_variant_details`-style lookup tools.
+The MCP server runs a single SQLModel-backed cache covering both catalog and
+transactional tiers (see [ADR-0018](adr/0018-sqlmodel-typed-cache.md) for the original
+typed-cache architecture and #472 Phase D for the catalog unification).
 
 ### TypedCacheEngine (`katana_mcp/typed_cache/`)
 
-SQLModel-backed per-entity tables for transactional types: sales orders, manufacturing
-orders, purchase orders, stock adjustments, stock transfers, manufacturing-order recipe
-rows. Each entity has its own table with proper FK relationships and JSON columns;
-nested rows (sales-order rows, MO recipe rows, …) become child tables with FKs back to
-the parent.
+SQLModel-backed per-entity tables for every cached type. Each entity has its own table
+with proper FK relationships and JSON columns; nested rows (sales-order rows, MO recipe
+rows, ...) become child tables with FKs back to the parent.
+
+**Catalog tier** (11 entity types): variants, products, materials, services, suppliers,
+customers, locations, tax rates, operators, factories, additional costs. Search via
+per-entity FTS5 sidecar tables (`<entity>_fts`) wired through a `CatalogQueries` adapter
+exposed at `services.typed_cache.catalog`. The adapter provides typed `get_by_id` /
+`get_by_sku` / `get_many_by_ids` / `get_all` / `smart_search` / `search_fuzzy` methods
+that return `Cached*` SQLModel instances directly (not dict shims), with default
+`include_archived=False` / `include_deleted=False` filters.
 
-The transactional types' filter shape (status enums, date ranges, customer/ supplier
-IDs, variant-id-via-rows) and 30+-field schemas don't fit `CatalogCache`'s
-three-text-column projection — hence the dedicated typed store.
+**Transactional tier** (10 entity types counting child rows): sales orders,
+manufacturing orders (+ recipe rows), purchase orders (+ rows), stock adjustments (+
+rows), stock transfers (+ rows). Searched via SQL `WHERE` clauses; no FTS sidecar —
+these tables don't carry free-text fields.
 
 ### EntitySpec — the generic sync driver
 
@@ -213,9 +213,13 @@ 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(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. **If the tool reads from cache,** add `@cache_read(CachedEntity, ...)` keyed by the
+   typed-cache `Cached*` SQLModel class (e.g. `CachedVariant`, `CachedProduct`).
+   Mutating tools do **not** need an explicit invalidation decorator — the typed cache
+   pulls incremental deltas via `updated_at_min` on every `@cache_read`-decorated call,
+   so a freshly-created or modified entity is picked up by the next read. The legacy
+   `@cache_write` / `mark_dirty` mechanism was retired with `CatalogCache` (#472 Phase
+   D).
 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.