feat(observability): phase-1 silent pipeline recorder + phase-0 Jev validation

Phase 0 — Jev validated with the real key (5 Persian scenarios, api.typesafe.ai): stale project name «منشیانه»->«منشانه» conf 0.73 (ambiguity band), STT spelling variants «مصطفوی/مستفدی/مسطفی»->«بازرگانی مصطفوی» conf 0.93, exact «دفتر» 0.88, proper _none rejection for «کاغذ A4» 0.92, and two mentions in ONE request (0.77/0.64). Exact model version to pin: jev-1.13.0. Latency 0.7-1.1s per field request; ~450-650 in / 64-133 out tokens.

Phase 1 — Observability (DB-only, zero extra LLM tokens, nothing is ever deleted):

- new tables bot_traces + bot_trace_events (idempotent DDL in db_init.py; ORM in models.py)

- new app/observability.py: _jsonable (UUID/datetime/Decimal/set/enum/dataclass-safe), trace_start, event, log_resolution, link_draft, latest_trace_for_draft, set_trace_status, span() context manager, save_voice (Path.mkdir parents+exist_ok, day folders)

- capture points wired: input.text; input.voice (+voice persisted under OBS_VOICE_DIR); stt.run + per-provider stt.result (success AND failure, latency, model); nlu.request + nlu.result with prompt_hash/prompt_version; entities.extracted; routing.decision (difflib baseline for the phase-6 A/B); ambiguity.sent; ambiguity.user_choice (buttons + free-text reply path); user_choice.pick; draft.render; draft.edit (wizard-side edits detected by the sync loop); draft.commit (quote/supplier/material/project + trace status/quote id); draft.cancel

- compose: persistent ./bot/data:/srv/bot/data volume; bot/.gitignore: data/ (runtime data never committed, never deleted)

- tests: bot/tools/test_observability.py -> 8/8 pass (jsonable cases, trace lifecycle, JSONB round-trip, draft linking, status update, save_voice day-folder mkdir, span task). Verified live: voice file lands on the host volume and is gitignored; rows + files persist across bot restart.

bot/app/nlu.py

@@ -4,12 +4,14 @@ One chat/completions call per message with JSON-mode output. The prompt embeds
 the current draft summary so the model can decide between "start a new
 activity" and "refine the open draft" (update_draft with a partial patch).
 """
+import hashlib
 import json
 import logging
 import re
 
 import httpx
 
+from app import observability as obs
 from app.config import Settings
 
 logger = logging.getLogger("bot.nlu")
@@ -143,7 +145,8 @@ def _extract_json(raw: str) -> dict | None:
         return None
 
 
-async def understand(settings: Settings, text: str | list[dict], draft_summary: str | None = None) -> dict:
+async def understand(settings: Settings, text: str | list[dict], draft_summary: str | None = None,
+                     trace_id: str | None = None) -> dict:
     """Return {"consensus_text": ..., "intent": ..., "patch": {...}, "confidence": ...}; never raises."""
     fallback = {"consensus_text": "", "intent": "unknown", "patch": {}, "confidence": 0.0}
     if not settings.AI_BASE_URL or not settings.AI_API_KEY:
@@ -172,6 +175,17 @@ async def understand(settings: Settings, text: str | list[dict], draft_summary:
 
     fallback["consensus_text"] = first_text
 
+    system_prompt = _build_system_prompt(draft_summary)
+    prompt_hash = hashlib.sha256(
+        f"{settings.OBS_PROMPT_VERSION}|{system_prompt}".encode()
+    ).hexdigest()[:16]
+    await obs.event(trace_id, "nlu.request", model=settings.LLM_MODEL, payload={
+        "is_multi": isinstance(text, list),
+        "content": user_content[:2000],
+        "prompt_hash": prompt_hash,
+        "prompt_version": settings.OBS_PROMPT_VERSION,
+    })
+
     try:
         async with httpx.AsyncClient(timeout=settings.LLM_TIMEOUT_SECONDS) as client:
             resp = await client.post(
@@ -180,7 +194,7 @@ async def understand(settings: Settings, text: str | list[dict], draft_summary:
                 json={
                     "model": settings.LLM_MODEL,
                     "messages": [
-                        {"role": "system", "content": _build_system_prompt(draft_summary)},
+                        {"role": "system", "content": system_prompt},
                         {"role": "user", "content": user_content},
                     ],
                     "temperature": 0.1,
@@ -189,16 +203,28 @@ async def understand(settings: Settings, text: str | list[dict], draft_summary:
             )
         if resp.status_code != 200:
             logger.error("LLM HTTP %s: %s", resp.status_code, resp.text[:300])
+            await obs.event(trace_id, "nlu.result", ok=False, model=settings.LLM_MODEL,
+                            payload={"error": f"HTTP {resp.status_code}", "body": resp.text[:300]})
             return fallback
         content = ((resp.json() or {}).get("choices") or [{}])[0].get("message", {}).get("content", "")
         parsed = _extract_json(content)
         if not parsed or parsed.get("intent") not in INTENTS:
             logger.warning("unparseable LLM output: %r", content[:200])
+            await obs.event(trace_id, "nlu.result", ok=False, model=settings.LLM_MODEL,
+                            payload={"error": "unparseable", "raw": content[:500]})
             return fallback
         parsed.setdefault("patch", {})
         if not parsed.get("consensus_text"):
             parsed["consensus_text"] = first_text
+        await obs.event(trace_id, "nlu.result", ok=True, model=settings.LLM_MODEL, payload={
+            "intent": parsed.get("intent"),
+            "confidence": parsed.get("confidence"),
+            "patch": parsed.get("patch"),
+            "consensus_text": parsed.get("consensus_text"),
+        })
         return parsed
     except (httpx.HTTPError, json.JSONDecodeError, KeyError, TypeError):
         logger.exception("NLU failure")
+        await obs.event(trace_id, "nlu.result", ok=False, model=settings.LLM_MODEL,
+                        payload={"error": "exception"})
         return fallback