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/handlers/supplier.py

@@ -2,6 +2,7 @@
 import logging
 
 from app import drafts as draft_store
+from app import observability as obs
 from app.api.client import ApiError
 from app.drafts import (
     KIND_SUPPLIER, merge_supplier_patch, new_supplier_payload, supplier_missing,
@@ -13,7 +14,8 @@ from app.texts import ERR_GENERIC, esc, supplier_committed_report, supplier_revi
 logger = logging.getLogger("bot.supplier")
 
 
-async def handle_entities(ctx, chat_id, user, patch: dict, source: str | None) -> None:
+async def handle_entities(ctx, chat_id, user, patch: dict, source: str | None,
+                          trace_id: str | None = None) -> None:
     draft = await draft_store.get_active(chat_id, KIND_SUPPLIER)
     if draft is not None:
         payload = draft.payload
@@ -22,15 +24,18 @@ async def handle_entities(ctx, chat_id, user, patch: dict, source: str | None) -
         payload = new_supplier_payload()
         merge_supplier_patch(payload, patch)
         draft = await draft_store.create(chat_id, KIND_SUPPLIER, payload, source=source)
-    await resolve_payload(ctx, payload)
+    await obs.link_draft(trace_id, draft.id, draft.kind)
+    await resolve_payload(ctx, payload, trace_id)
     await draft_store.save_payload(draft, missing={"fields": supplier_missing(payload)})
-    await render(ctx, chat_id, draft, fresh=draft.review_message_id is None)
+    await render(ctx, chat_id, draft, fresh=draft.review_message_id is None, trace_id=trace_id)
 
 
-async def resolve_payload(ctx, payload: dict) -> None:
+async def resolve_payload(ctx, payload: dict, trace_id: str | None = None) -> None:
     options = payload.setdefault("options", {})
     if not payload.get("category_id") and payload.get("category_name"):
         res = await safe_resolve(ctx.resolver, "category", payload["category_name"])
+        await obs.log_resolution(trace_id, "category", payload["category_name"], res.status,
+                                 [{"id": c.id, "name": c.name} for c in (res.candidates or [])[:4]])
         if res.resolved:
             payload["category_id"] = res.candidates[0].id
             payload["category_name"] = res.candidates[0].name
@@ -58,7 +63,7 @@ def _keyboard(payload: dict, draft_id: str) -> dict:
     return simple_review_keyboard(draft_id, KIND_SUPPLIER, rows)
 
 
-async def render(ctx, chat_id, draft, fresh: bool = True) -> None:
+async def render(ctx, chat_id, draft, fresh: bool = True, trace_id: str | None = None) -> None:
     payload = draft.payload
     missing = supplier_missing(payload)
     text = supplier_review_text(payload, missing)
@@ -71,11 +76,14 @@ async def render(ctx, chat_id, draft, fresh: bool = True) -> None:
     else:
         await ctx.edit(chat_id, draft.review_message_id, text, reply_markup=keyboard)
         await draft_store.save_payload(draft, missing={"fields": missing})
+    await obs.event(trace_id or await obs.latest_trace_for_draft(draft.id), "draft.render",
+                    payload={"fresh": fresh, "missing": [m.get("key") for m in missing if not m.get("ok")]})
 
 
-async def commit(ctx, chat_id, user, draft) -> None:
+async def commit(ctx, chat_id, user, draft, trace_id: str | None = None) -> None:
     payload = draft.payload
-    await resolve_payload(ctx, payload)
+    trace_id = trace_id or await obs.latest_trace_for_draft(draft.id)
+    await resolve_payload(ctx, payload, trace_id)
     missing = {m["key"]: m["ok"] for m in supplier_missing(payload)}
     problems = [label for key, label, ok in [
         ("name", "نام تأمین‌کننده", missing.get("name")),
@@ -99,5 +107,8 @@ async def commit(ctx, chat_id, user, draft) -> None:
         await ctx.send(chat_id, ERR_GENERIC.format(detail=esc(exc.message)))
         return
     await draft_store.set_status(draft.id, "committed")
+    await obs.event(trace_id, "draft.commit", payload={"kind": "supplier",
+                                                       "supplier_id": (created or {}).get("id")})
+    await obs.set_trace_status(trace_id, "committed")
     ctx.resolver.invalidate("suppliers")
     await ctx.send(chat_id, supplier_committed_report(created))