chore(client): emit Mapped[T] field types on Cached* classes (drop col()/cast() ergonomics tax)

Closes #625-spike-revisit. Generator now wraps every cache-table field's
type in ``Mapped[T]`` so type checkers see ``CachedX.field`` as
``InstrumentedAttribute[T]`` (with ``.in_/.is_/.desc/.ilike``). The
36 ``sqlmodel.col()`` wrappers and 4 ``cast(QueryableAttribute, ...)``
calls landed in #624 are no longer needed and have been removed.

The runtime path is unchanged: a small ``_mapped_shim.py`` module
defines ``Mapped`` as ``sqlalchemy.orm.Mapped`` under ``TYPE_CHECKING``
and as a runtime-identity class (``__class_getitem__`` returns ``T``)
otherwise. So ``Annotated[Mapped[int], Field(...)]`` evaluates to
``Annotated[int, Field(...)]`` at class-definition time — exactly what
SQLModel + pydantic 2.13 want.

The earlier #625 spike concluded "won't do" because the only working
form (``if TYPE_CHECKING / else``) doubled every field declaration.
That spike missed the runtime-identity-shim option, which the
research follow-up surfaced via SQLModel discussion #1016 and
``roman.pt/posts/pydantic-in-sqlalchemy-fields/``.

Generator changes (``scripts/generate_pydantic_models.py``):

- New pass ``wrap_cache_fields_in_mapped`` runs after every other
  field-rewrite pass (those passes match ``Annotated[T, Field(...)]``
  literally — running this wrap before them would leave them unable
  to find their targets). It does two regex sweeps:
  - ``Annotated[<type>, ...]`` → ``Annotated[Mapped[<type>], ...]``
    (column fields)
  - ``field: <type> = Relationship(...)`` →
    ``field: Mapped[<type>] = Relationship(...)`` (relationship fields,
    matching SQLAlchemy 2.0's canonical shape)
- Operates on both ``Cached*`` siblings *and* the shared entity base
  classes (BaseEntity, UpdatableEntity, DeletableEntity, etc.) since
  ``Cached*`` inherits ``id`` / ``created_at`` / ``updated_at`` /
  ``deleted_at`` / ``archived_at`` from those bases. Wrapping only the
  Cached classes left those inherited fields as bare ``T`` for type
  checkers — and those are the fields most query call sites filter on.
  API classes that share the same bases inherit the wrapping too;
  runtime is unaffected (Mapped → identity), and no API consumer
  relies on class-level access (instance-level access stays as ``T``
  per pydantic's normal field handling).
- Mapped shim import added to cache-table modules and ``base.py``.

Foundation-file cleanup (``katana_mcp_server/.../foundation/*.py``):

- Dropped 36 ``col(CachedX.field)`` wrappers across 6 files
  (inventory, manufacturing_orders, sales_orders, purchase_orders,
  stock_transfers, reporting) — types now resolve correctly without
  the wrapper.
- Dropped 4 ``cast("QueryableAttribute[Any]", CachedX.<rel>)``
  wrappers around ``selectinload`` arguments — relationship fields
  are now ``Mapped[list[X]]`` so ``selectinload(CachedX.<rel>)``
  type-checks natively.
- Removed corresponding unused imports (``col``, ``QueryableAttribute``,
  ``cast``).

Typecheck config (``pyproject.toml``):

- ``ty check`` now also excludes
  ``katana_public_api_client/models_pydantic/_generated/`` (matches
  ``pyrightconfig.json`` exclusions). Ty rejects the trailing
  ``= None`` default on ``Annotated[Mapped[T | None], Field(...)] = None``;
  pyright accepts it. Generated files are auto-emitted, so excluding
  them from in-repo type-checking is consistent with how pyright
  already handles them.

Validation:
- ``uv run poe lint`` clean (ruff + ty + yamllint)
- ``uv run poe check`` clean (full validation)
- ``uv run pyright katana_mcp_server/src/`` 0 errors / 1 documented warning
- All 3,019 tests pass

This is forward-compatible: when SQLModel ships native ``Mapped[T]``
support, the shim becomes redundant and can be deleted in a one-line
PR (the generator output stays the same).

Refs: #625

Author: dougborg

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

@@ -10,7 +10,7 @@
 import json
 import time
 from datetime import datetime
-from typing import Annotated, Any, Literal, cast
+from typing import Annotated, Any, Literal
 
 from fastmcp import Context, FastMCP
 from fastmcp.tools import ToolResult
@@ -1192,7 +1192,7 @@ def _apply_stock_adjustment_filters(
     this function lets the paginated path avoid re-parsing on the COUNT
     query.
     """
-    from sqlmodel import col, exists, select
+    from sqlmodel import exists, select
 
     from katana_public_api_client.models_pydantic._generated import (
         CachedStockAdjustment,
@@ -1202,14 +1202,14 @@ def _apply_stock_adjustment_filters(
     if request.location_id is not None:
         stmt = stmt.where(CachedStockAdjustment.location_id == request.location_id)
     if request.ids is not None:
-        stmt = stmt.where(col(CachedStockAdjustment.id).in_(request.ids))
+        stmt = stmt.where(CachedStockAdjustment.id.in_(request.ids))
     if request.stock_adjustment_number is not None:
         stmt = stmt.where(
             CachedStockAdjustment.stock_adjustment_number
             == request.stock_adjustment_number
         )
     if not request.include_deleted:
-        stmt = stmt.where(col(CachedStockAdjustment.deleted_at).is_(None))
+        stmt = stmt.where(CachedStockAdjustment.deleted_at.is_(None))
 
     # ``variant_id`` is a row-level field — EXISTS subquery scans the
     # indexed FK directly so a match on any row of any adjustment is
@@ -1229,7 +1229,7 @@ def _apply_stock_adjustment_filters(
     if request.reason is not None:
         needle = request.reason.strip()
         if needle:
-            stmt = stmt.where(col(CachedStockAdjustment.reason).ilike(f"%{needle}%"))
+            stmt = stmt.where(CachedStockAdjustment.reason.ilike(f"%{needle}%"))
 
     return apply_date_window_filters(
         stmt,
@@ -1256,8 +1256,8 @@ async def _list_stock_adjustments_impl(
     subquery against the row table so a match on any row is found
     regardless of how many adjustments precede it. See ADR-0018.
     """
-    from sqlalchemy.orm import QueryableAttribute, selectinload
-    from sqlmodel import col, func, select
+    from sqlalchemy.orm import selectinload
+    from sqlmodel import func, select
 
     from katana_mcp.typed_cache import ensure_stock_adjustments_synced
     from katana_public_api_client.models_pydantic._generated import (
@@ -1276,16 +1276,11 @@ async def _list_stock_adjustments_impl(
     # materialization time and we skip the correlated COUNT subquery.
     if request.include_rows:
         stmt = select(CachedStockAdjustment).options(
-            selectinload(
-                cast(
-                    "QueryableAttribute[Any]",
-                    CachedStockAdjustment.stock_adjustment_rows,
-                )
-            )
+            selectinload(CachedStockAdjustment.stock_adjustment_rows)
         )
     else:
         row_count_subq = (
-            select(func.count(col(CachedStockAdjustmentRow.id)))
+            select(func.count(CachedStockAdjustmentRow.id))
             .where(
                 CachedStockAdjustmentRow.stock_adjustment_id == CachedStockAdjustment.id
             )
@@ -1296,8 +1291,8 @@ async def _list_stock_adjustments_impl(
         stmt = select(CachedStockAdjustment, row_count_subq)
     stmt = _apply_stock_adjustment_filters(stmt, request, parsed_dates)
     stmt = stmt.order_by(
-        col(CachedStockAdjustment.created_at).desc(),
-        col(CachedStockAdjustment.id).desc(),
+        CachedStockAdjustment.created_at.desc(),
+        CachedStockAdjustment.id.desc(),
     )
     if request.page is not None:
         stmt = stmt.offset((request.page - 1) * request.limit).limit(request.limit)

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

@@ -1777,27 +1777,24 @@ def _apply_manufacturing_order_filters(
     reflect exactly the same filter set as the data rows. ``parsed_dates``
     must come from :func:`parse_request_dates`.
     """
-    from sqlmodel import col
 
     from katana_public_api_client.models_pydantic._generated import (
         CachedManufacturingOrder,
     )
 
     if request.ids is not None:
-        stmt = stmt.where(col(CachedManufacturingOrder.id).in_(request.ids))
+        stmt = stmt.where(CachedManufacturingOrder.id.in_(request.ids))
     if request.order_no is not None:
         stmt = stmt.where(CachedManufacturingOrder.order_no == request.order_no)
     if request.status is not None:
         stmt = stmt.where(CachedManufacturingOrder.status == request.status)
     if request.location_id is not None:
         stmt = stmt.where(CachedManufacturingOrder.location_id == request.location_id)
     if request.variant_ids is not None:
-        stmt = stmt.where(
-            col(CachedManufacturingOrder.variant_id).in_(request.variant_ids)
-        )
+        stmt = stmt.where(CachedManufacturingOrder.variant_id.in_(request.variant_ids))
     if request.sales_order_ids is not None:
         stmt = stmt.where(
-            col(CachedManufacturingOrder.sales_order_id).in_(request.sales_order_ids)
+            CachedManufacturingOrder.sales_order_id.in_(request.sales_order_ids)
         )
     if request.ingredient_availability is not None:
         stmt = stmt.where(
@@ -1814,7 +1811,7 @@ def _apply_manufacturing_order_filters(
             == request.is_linked_to_sales_order
         )
     if not request.include_deleted:
-        stmt = stmt.where(col(CachedManufacturingOrder.deleted_at).is_(None))
+        stmt = stmt.where(CachedManufacturingOrder.deleted_at.is_(None))
 
     return apply_date_window_filters(
         stmt,
@@ -1842,7 +1839,7 @@ async def _list_manufacturing_orders_impl(
     Filters (including ``production_deadline_*``) translate to indexed
     SQL. See ADR-0018.
     """
-    from sqlmodel import col, func, select
+    from sqlmodel import func, select
 
     from katana_mcp.typed_cache import ensure_manufacturing_orders_synced
     from katana_public_api_client.models_pydantic._generated import (
@@ -1858,8 +1855,8 @@ async def _list_manufacturing_orders_impl(
     stmt = select(CachedManufacturingOrder)
     stmt = _apply_manufacturing_order_filters(stmt, request, parsed_dates)
     stmt = stmt.order_by(
-        col(CachedManufacturingOrder.created_at).desc(),
-        col(CachedManufacturingOrder.id).desc(),
+        CachedManufacturingOrder.created_at.desc(),
+        CachedManufacturingOrder.id.desc(),
     )
     if request.page is not None:
         stmt = stmt.offset((request.page - 1) * request.limit).limit(request.limit)
@@ -2182,7 +2179,7 @@ async def _list_blocking_ingredients_impl(
     hasn't run for, which would otherwise surface as a false-positive
     blocking entry.
     """
-    from sqlmodel import col, select
+    from sqlmodel import select
 
     from katana_mcp.typed_cache import (
         MANUFACTURING_ORDER_RECIPE_ROW_SPEC,
@@ -2264,24 +2261,22 @@ async def _list_blocking_ingredients_impl(
         select(CachedManufacturingOrderRecipeRow, CachedManufacturingOrder)
         .join(
             CachedManufacturingOrder,
-            col(CachedManufacturingOrder.id)
+            CachedManufacturingOrder.id
             == CachedManufacturingOrderRecipeRow.manufacturing_order_id,
         )
-        .where(col(CachedManufacturingOrder.deleted_at).is_(None))
-        .where(col(CachedManufacturingOrderRecipeRow.deleted_at).is_(None))
-        .where(col(CachedManufacturingOrder.status).in_(statuses))
+        .where(CachedManufacturingOrder.deleted_at.is_(None))
+        .where(CachedManufacturingOrderRecipeRow.deleted_at.is_(None))
+        .where(CachedManufacturingOrder.status.in_(statuses))
         .where(
-            col(CachedManufacturingOrderRecipeRow.ingredient_availability).in_(
+            CachedManufacturingOrderRecipeRow.ingredient_availability.in_(
                 list(_BLOCKING_AVAILABILITY)
             )
         )
     )
     if request.mo_ids is not None:
-        stmt = stmt.where(col(CachedManufacturingOrder.id).in_(request.mo_ids))
+        stmt = stmt.where(CachedManufacturingOrder.id.in_(request.mo_ids))
     if request.mo_order_nos is not None:
-        stmt = stmt.where(
-            col(CachedManufacturingOrder.order_no).in_(request.mo_order_nos)
-        )
+        stmt = stmt.where(CachedManufacturingOrder.order_no.in_(request.mo_order_nos))
     if request.location_id is not None:
         stmt = stmt.where(CachedManufacturingOrder.location_id == request.location_id)
     stmt = apply_date_window_filters(

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

@@ -13,7 +13,7 @@
 import asyncio
 from datetime import UTC, datetime
 from enum import StrEnum
-from typing import Annotated, Any, Literal, cast
+from typing import Annotated, Any, Literal
 
 from fastmcp import Context, FastMCP
 from fastmcp.tools import ToolResult
@@ -2013,7 +2013,6 @@ def _apply_purchase_order_filters(
     Shared by the data SELECT and the COUNT SELECT so pagination totals
     reflect exactly the same filter set as the data rows.
     """
-    from sqlmodel import col
 
     from katana_public_api_client.models_pydantic._generated import (
         CachedPurchaseOrder,
@@ -2023,7 +2022,7 @@ def _apply_purchase_order_filters(
     )
 
     if request.ids is not None:
-        stmt = stmt.where(col(CachedPurchaseOrder.id).in_(request.ids))
+        stmt = stmt.where(CachedPurchaseOrder.id.in_(request.ids))
     if request.order_no is not None:
         stmt = stmt.where(CachedPurchaseOrder.order_no == request.order_no)
     if request.entity_type is not None:
@@ -2056,7 +2055,7 @@ def _apply_purchase_order_filters(
     if request.supplier_id is not None:
         stmt = stmt.where(CachedPurchaseOrder.supplier_id == request.supplier_id)
     if not request.include_deleted:
-        stmt = stmt.where(col(CachedPurchaseOrder.deleted_at).is_(None))
+        stmt = stmt.where(CachedPurchaseOrder.deleted_at.is_(None))
 
     return apply_date_window_filters(
         stmt,
@@ -2085,8 +2084,8 @@ async def _list_purchase_orders_impl(
     outsourced-only ``tracking_location_id``) translate to indexed SQL.
     See ADR-0018.
     """
-    from sqlalchemy.orm import QueryableAttribute, selectinload
-    from sqlmodel import col, func, select
+    from sqlalchemy.orm import selectinload
+    from sqlmodel import func, select
 
     from katana_mcp.typed_cache import ensure_purchase_orders_synced
     from katana_public_api_client.models_pydantic._generated import (
@@ -2105,16 +2104,11 @@ async def _list_purchase_orders_impl(
     # time and we skip the correlated COUNT subquery.
     if request.include_rows:
         stmt = select(CachedPurchaseOrder).options(
-            selectinload(
-                cast(
-                    "QueryableAttribute[Any]",
-                    CachedPurchaseOrder.purchase_order_rows,
-                )
-            )
+            selectinload(CachedPurchaseOrder.purchase_order_rows)
         )
     else:
         row_count_subq = (
-            select(func.count(col(CachedPurchaseOrderRow.id)))
+            select(func.count(CachedPurchaseOrderRow.id))
             .where(CachedPurchaseOrderRow.purchase_order_id == CachedPurchaseOrder.id)
             .correlate(CachedPurchaseOrder)
             .scalar_subquery()
@@ -2123,8 +2117,8 @@ async def _list_purchase_orders_impl(
         stmt = select(CachedPurchaseOrder, row_count_subq)
     stmt = _apply_purchase_order_filters(stmt, request, parsed_dates)
     stmt = stmt.order_by(
-        col(CachedPurchaseOrder.created_at).desc(),
-        col(CachedPurchaseOrder.id).desc(),
+        CachedPurchaseOrder.created_at.desc(),
+        CachedPurchaseOrder.id.desc(),
     )
     if request.page is not None:
         stmt = stmt.offset((request.page - 1) * request.limit).limit(request.limit)

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

@@ -793,7 +793,7 @@ async def _fetch_completed_mo_recipe_rows_in_window(
     window datetimes must also be naive UTC — callers are responsible for
     stripping tzinfo before passing.
     """
-    from sqlmodel import col, select
+    from sqlmodel import select
 
     from katana_mcp.typed_cache import ensure_manufacturing_orders_synced
     from katana_public_api_client.models_pydantic._generated import (
@@ -815,13 +815,13 @@ async def _fetch_completed_mo_recipe_rows_in_window(
             select(CachedManufacturingOrderRecipeRow)
             .join(
                 CachedManufacturingOrder,
-                col(CachedManufacturingOrder.id)
+                CachedManufacturingOrder.id
                 == CachedManufacturingOrderRecipeRow.manufacturing_order_id,
             )
             .where(CachedManufacturingOrder.status == ManufacturingOrderStatus.done)
-            .where(col(CachedManufacturingOrder.done_date).is_not(None))
-            .where(col(CachedManufacturingOrder.deleted_at).is_(None))
-            .where(col(CachedManufacturingOrderRecipeRow.deleted_at).is_(None))
+            .where(CachedManufacturingOrder.done_date.is_not(None))
+            .where(CachedManufacturingOrder.deleted_at.is_(None))
+            .where(CachedManufacturingOrderRecipeRow.deleted_at.is_(None))
         )
         row_stmt = apply_date_window_filters(
             row_stmt,

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

@@ -16,7 +16,7 @@
 import asyncio
 from datetime import datetime
 from enum import StrEnum
-from typing import Annotated, Any, Literal, cast
+from typing import Annotated, Any, Literal
 
 from fastmcp import Context, FastMCP
 from fastmcp.tools import ToolResult
@@ -730,7 +730,6 @@ def _apply_sales_order_filters(
     this function lets the paginated path avoid re-parsing on the COUNT
     query.
     """
-    from sqlmodel import col
 
     from katana_public_api_client.models_pydantic._generated import (
         CachedSalesOrder,
@@ -745,7 +744,7 @@ def _apply_sales_order_filters(
     if request.order_no is not None:
         stmt = stmt.where(CachedSalesOrder.order_no == request.order_no)
     if request.ids is not None:
-        stmt = stmt.where(col(CachedSalesOrder.id).in_(request.ids))
+        stmt = stmt.where(CachedSalesOrder.id.in_(request.ids))
     if request.customer_id is not None:
         stmt = stmt.where(CachedSalesOrder.customer_id == request.customer_id)
     if request.location_id is not None:
@@ -767,7 +766,7 @@ def _apply_sales_order_filters(
     if request.currency is not None:
         stmt = stmt.where(CachedSalesOrder.currency == request.currency)
     if not request.include_deleted:
-        stmt = stmt.where(col(CachedSalesOrder.deleted_at).is_(None))
+        stmt = stmt.where(CachedSalesOrder.deleted_at.is_(None))
 
     return apply_date_window_filters(
         stmt,
@@ -795,8 +794,8 @@ async def _list_sales_orders_impl(
     translates request filters into indexed SQL and returns results
     directly. See ADR-0018.
     """
-    from sqlalchemy.orm import QueryableAttribute, selectinload
-    from sqlmodel import col, func, select
+    from sqlalchemy.orm import selectinload
+    from sqlmodel import func, select
 
     from katana_mcp.typed_cache import ensure_sales_orders_synced
     from katana_public_api_client.models_pydantic._generated import (
@@ -815,23 +814,19 @@ async def _list_sales_orders_impl(
     # time and we skip the correlated COUNT subquery entirely.
     if request.include_rows:
         stmt = select(CachedSalesOrder).options(
-            selectinload(
-                cast("QueryableAttribute[Any]", CachedSalesOrder.sales_order_rows)
-            )
+            selectinload(CachedSalesOrder.sales_order_rows)
         )
     else:
         row_count_subq = (
-            select(func.count(col(CachedSalesOrderRow.id)))
+            select(func.count(CachedSalesOrderRow.id))
             .where(CachedSalesOrderRow.sales_order_id == CachedSalesOrder.id)
             .correlate(CachedSalesOrder)
             .scalar_subquery()
             .label("row_count")
         )
         stmt = select(CachedSalesOrder, row_count_subq)
     stmt = _apply_sales_order_filters(stmt, request, parsed_dates)
-    stmt = stmt.order_by(
-        col(CachedSalesOrder.created_at).desc(), col(CachedSalesOrder.id).desc()
-    )
+    stmt = stmt.order_by(CachedSalesOrder.created_at.desc(), CachedSalesOrder.id.desc())
     if request.page is not None:
         stmt = stmt.offset((request.page - 1) * request.limit).limit(request.limit)
     else: