feat(mcp): per-entity PO modify card with field-level diff overlay — #722

Foundation + first migration for the #721 modify-card umbrella. Replaces
the today's ``ActionResult``-shaped modify card (which showed "Update
Header / 2 field(s) changed / Operation #1, Target #2641831" — internal
model abstractions the user can't action on) with a per-entity entry
that mirrors the create-card layout and decorates the changing fields
with ``before → after``.

What lands:

- ``FieldChangeView`` + ``_index_changes_by_field`` + ``_render_field_diff_line``
  — renderer-facing field-diff projection, shared by every future modify
  card. Flattens ``ActionResult.changes`` across all actions into a single
  field-name keyed map so the entity view's render code can do simple
  ``changes.get("expected_arrival_date")`` lookups.

- ``_render_po_entity_view(entity, *, changes=None)`` — the PO entity-view
  body, extracted from the old inlined ``build_po_create_ui`` Tier 2/3
  content. Called by BOTH the create card (``changes=None``) and the new
  modify card. Single source of truth for "what fields show in a PO card";
  the create-modify pair can't drift over time.

- ``build_po_modify_ui`` — the new entrypoint. Handles
  ``modify_purchase_order`` / ``delete_purchase_order`` /
  ``correct_purchase_order`` (verb from ``confirm_tool``). Renders the
  entity view with the diff overlay; the leading ``✗`` glyph + inline
  Muted error line appears only on failed actions (the agreed hybrid
  status approach — card-level header Badge carries the all/most-case
  status, per-field decoration only when it carries information).

- Dispatch in ``_modification.to_tool_result`` — switches on
  ``response.entity_type``. PO routes to the new entrypoint; other
  entities fall through to the legacy ``build_modification_preview_ui`` /
  ``build_modification_result_ui`` pair until their child PRs (#723 SO,
  #724 MO, #725 stock-transfer, #726 item) ship. The legacy builders
  delete once every entity migrates.

Tests:

- ``TestFieldDiffIndex`` — pins ``_index_changes_by_field`` projection
  (multi-action flattening, added/unchanged kinds, failed-action error
  propagation).
- ``TestBuildPOModifyUI`` — smoke + diff-decoration + supplier composite
  diff + failed-action ``✗`` glyph + delete verb + partial-failure
  header badge + ``state.result`` seeding on applied path.
- ``TestPOEntityViewSharedBetweenCreateAndModify`` — pins the dual-call
  contract so a future refactor of ``_render_po_entity_view`` can't
  silently drift the create card away from modify.

What this PR does NOT touch (deferred to follow-ups):

- Line-item / additional-cost adds/removes (the ``add_row`` / ``delete_row``
  / ``add_additional_cost`` operations) — the entity view doesn't yet
  render those rows. The current PO create card doesn't render them
  either, so this is consistent with #728's create-card scope, not a
  regression. Adding the nested-rows section is its own follow-up
  (probably the next PO modify PR or rolled into the SO migration where
  the entity-view component for line-items first matters).
- Other entities (SO, MO, stock_transfer, item) — child PRs #723-#726.

Closes #722
Refs #721

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

Author: dougborg

katana_mcp_server/src/katana_mcp/tools/_modification.py

@@ -554,25 +554,40 @@ def to_tool_result(
 ) -> ToolResult:
     """Build a :class:`ToolResult` with a Prefab UI from a ModificationResponse.
 
-    Preview branch: emits ``build_modification_preview_ui`` with the
-    direct-apply rail (Confirm fires ``tools/call`` directly + iframe
-    pushes the structured result back via ``ui/update-model-context``).
-    Non-preview branch: emits ``build_modification_result_ui`` summarizing
-    each action's terminal status.
-
-    ``confirm_request`` is the original Pydantic request (its ``preview``
-    field flips to ``False`` when the iframe re-issues for apply);
-    ``confirm_tool`` is the registered MCP tool name to re-call. The
-    preview branch wires both into the Confirm-button CallTool; the
-    result branch uses ``confirm_tool`` to derive the title verb so a
-    delete reads "Product Delete" instead of "Product Modification".
+    Dispatches by ``response.entity_type`` to a per-entity builder that
+    handles BOTH preview and applied states (one entrypoint per entity,
+    matching the create-card pattern in #728 and the modify-card design
+    in #721). Each per-entity builder shares its entity-view renderer
+    with its create-card sibling (e.g. ``_render_po_entity_view``) —
+    create cards call it with no diff overlay; modify cards pass the
+    per-field diff lookup built from ``response.actions[*].changes``.
+
+    Entities not yet migrated fall back to ``build_modification_preview_ui``
+    / ``build_modification_result_ui`` — the legacy single-entrypoint pair
+    today's modify/delete/correct tools render through. Removed once
+    every #721 child PR has shipped.
     """
     from katana_mcp.tools.prefab_ui import (
         build_modification_preview_ui,
         build_modification_result_ui,
+        build_po_modify_ui,
     )
 
     response_dict = response.model_dump()
+
+    # Per-entity dispatch — PO migrated in #722; remaining entities
+    # (SO, MO, stock_transfer, item) fall through to the legacy
+    # builders until their respective child PRs land.
+    if response.entity_type == "purchase_order":
+        ui = build_po_modify_ui(
+            response_dict,
+            confirm_request=confirm_request,
+            confirm_tool=confirm_tool,
+        )
+        return make_tool_result(response, ui=ui)
+
+    # Legacy path — preserves today's behavior for not-yet-migrated
+    # entity types so #722 can land without cross-entity test churn.
     if response.is_preview:
         ui = build_modification_preview_ui(
             response_dict,