feat(matching): Jev entity matching phases 2-5 (per-field fan-out, variants, candidate ambiguity buttons)

Phase 2 — jev.py client: POST /v1/systemone, PINNED model jev-1.13.0 (drift warning when the response model differs), one retry on 429/5xx, fail-soft (None on any error), usage/latency returned for observability. Config adds TYPESAFE_API_KEY / JEV_* (thresholds 0.85/0.60, 15 questions per field); no daily cap by owner decision. bot/.env is now mounted read-only into the container so the key never enters compose/git.

Phase 3 — matching.py: برون‌گروهی (one request per field, parallel), درون‌گروهی (one choice question per mention sharing the same full candidate list + «_none»), درون‌واریانسی (all STT spellings in one question). Routing: conf>=exact → bind; floor..exact → ambiguity; else/_none → new; missing/failed field → difflib fallback (bug fixed during testing: a failed request used to record 'new' instead of falling back). Resolver gains full cached lists for suppliers/materials (paged) plus brands (API+DB) and specs (EAV values + draft specs). NLU prompt now emits entity_mentions (6 fields) with the voice-variant grouping rule; sanitize_mentions guards the shape. handle_message runs matching only for register_quote/update_draft/add_material behind JEV_ENABLED; jev_map threads into quote/material resolve_payload (Jev hit skips difflib; exact writes ids; ambiguity skips difflib). Spec effect per owner: spelling normalization only (normalize_brand_spec).

Phase 4 — entity-match ambiguity sub-messages: create_ambiguities() builds deduped entries {kind: entity_match, field, variants, candidates, details with Persian percentages}; new keyboards.ambiguity_candidates_keyboard renders one button per candidate + «هیچ‌کدام — ایجاد جدید»; callbacks handle amb⛏️{prefix}:{amb_id}:{idx} (applies the candidate via matching.apply_choice then re-resolves/renders) and amb:new (rejected → auto-create path at commit). Every user choice lands in observability (ambiguity.user_choice with arg+candidates).

Phase 5 — voice variants: NLU groups different STT spellings of one entity into one variants[] (verified live: مصطفوی/مستفدی → one supplier mention); tools/test_matching.py live section (RUN_LIVE=1) exercises real DeepSeek + real Jev without touching Bale.

Tests: test_jev.py 5/5 (mock HTTP: no-key, happy path, 429-retry, 400, exception), test_matching.py 11/11 mock + 3/3 live (real NLU produced 7 mentions with correct fields; real Jev matched «50 کیلویی»→«۵۰ کیلویی» 0.98 and «کیسه» 1.0 and correctly returned new against the emptied catalog); observability regression 8/8.

bot/app/handlers/material.py

@@ -2,6 +2,7 @@
 import logging
 
 from app import drafts as draft_store
+from app import matching
 from app import observability as obs
 from app.api.client import ApiError
 from app.drafts import (
@@ -15,7 +16,8 @@ logger = logging.getLogger("bot.material")
 
 
 async def handle_entities(ctx, chat_id, user, patch: dict, source: str | None,
-                          trace_id: str | None = None) -> None:
+                          trace_id: str | None = None,
+                          jev_map: dict | None = None) -> None:
     draft = await draft_store.get_active(chat_id, KIND_MATERIAL)
     if draft is not None:
         payload = draft.payload
@@ -25,25 +27,36 @@ async def handle_entities(ctx, chat_id, user, patch: dict, source: str | None,
         merge_material_patch(payload, patch)
         draft = await draft_store.create(chat_id, KIND_MATERIAL, payload, source=source)
     await obs.link_draft(trace_id, draft.id, draft.kind)
-    await resolve_payload(ctx, payload, trace_id)
+    await resolve_payload(ctx, payload, trace_id, jev_map)
     await draft_store.save_payload(draft, missing={"fields": material_missing(payload)})
     await render(ctx, chat_id, draft, fresh=draft.review_message_id is None, trace_id=trace_id)
 
 
-async def resolve_payload(ctx, payload: dict, trace_id: str | None = None) -> None:
+async def resolve_payload(ctx, payload: dict, trace_id: str | None = None,
+                          jev_map: dict | None = None) -> None:
     options = payload.setdefault("options", {})
     if not payload.get("canonical_unit_id") and payload.get("unit_name"):
-        res = await safe_resolve(ctx.resolver, "unit", payload["unit_name"])
-        await obs.log_resolution(trace_id, "unit", payload["unit_name"], res.status,
-                                 [{"id": c.id, "name": c.name} for c in (res.candidates or [])[:4]])
-        if res.resolved:
-            payload["canonical_unit_id"] = res.candidates[0].id
-            payload["unit_name"] = res.candidates[0].name
-            options.pop("unit", None)
-        elif res.candidates:
-            options["unit"] = [{"id": c.id, "name": c.name} for c in res.candidates]
+        hit = matching.lookup(jev_map, payload["unit_name"])
+        if hit is not None:
+            if hit["status"] == "exact":
+                payload["canonical_unit_id"] = hit["id"]
+                payload["unit_name"] = hit["name"]
+                options.pop("unit", None)
+            elif hit["status"] == "ambiguity" and hit.get("candidates"):
+                options["unit"] = [{"id": c["id"], "name": c["name"]}
+                                   for c in hit["candidates"][:6]]
         else:
-            options.pop("unit", None)
+            res = await safe_resolve(ctx.resolver, "unit", payload["unit_name"])
+            await obs.log_resolution(trace_id, "unit", payload["unit_name"], res.status,
+                                     [{"id": c.id, "name": c.name} for c in (res.candidates or [])[:4]])
+            if res.resolved:
+                payload["canonical_unit_id"] = res.candidates[0].id
+                payload["unit_name"] = res.candidates[0].name
+                options.pop("unit", None)
+            elif res.candidates:
+                options["unit"] = [{"id": c.id, "name": c.name} for c in res.candidates]
+            else:
+                options.pop("unit", None)
 
 
 async def apply_pick(ctx, chat_id, user, draft, field: str, choice: dict) -> None:
@@ -105,5 +118,5 @@ async def commit(ctx, chat_id, user, draft, trace_id: str | None = None) -> None
     await obs.event(trace_id, "draft.commit", payload={"kind": "material",
                                                        "material_id": (created or {}).get("id")})
     await obs.set_trace_status(trace_id, "committed")
-    ctx.resolver.invalidate("materials")
+    ctx.resolver.invalidate()
     await ctx.send(chat_id, material_committed_report(created))