refactor: composition root in lifespan, break core↔services cycle, shared data layer

The gateway was the composition root, device registry, inbound-call
policy, and call-operations service in one class, with core↔services
circular imports papered over by function-local imports, wiring done
by assigning private attributes, and MCP tools duplicating REST query
logic against their own sessions.

Composition:
- main.py's lifespan now builds every service and wires them by
  constructor/registration. gateway.from_config() is gone; core/ no
  longer imports services/ anywhere — the cycle is dead.
- Inbound-call policy moved to ReceptionistService.on_inbound_call
  (routing evaluation, reject/answer, screening dispatch); wired as
  the engine's on_incoming_call by the lifespan. Receptionist deps
  (tts/transcription/recording/routing) are constructor-injected —
  no more gateway._tts reach-through or importing hold_slayer's
  private _get_llm (now services.llm_client.get_llm, shared).
- Hold-slayer launch goes through a mode-handler registry
  (register_mode_handler); the gateway no longer knows the service's
  type. CallManager takes on_call_ended in its constructor.
- build_sip_engine() is a pure function taking explicit callbacks.
- api/routing.py uses the routing service from app.state via a
  proper dependency instead of gateway._routing.

Shared data layer:
- db.session_scope() is the one session convention (get_db wraps it).
- services/call_persistence.py gains the query/write functions and
  the single StoredCallFlow→CallFlow mapper; api/call_flows.py,
  api/call_history.py, and the six DB-touching MCP tools are thin
  wrappers over them — the two surfaces can't drift.
- legs_for_call() replaces the three private _call_legs scans
  (gateway transfer/hangup, REST dtmf, MCP dtmf).

7 new tests (mode-handler launch, on_call_ended hook, receptionist
inbound answer/reject, call-flow CRUD round-trip and history routes
against real SQLite through the shared layer). aiosqlite added to dev
deps for that.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

services/call_persistence.py

@@ -1,25 +1,168 @@
 """
-Call Persistence — Writes completed calls and their transcript chunks
-to the database when CallManager.end_call() fires.
+Call Persistence — the data-access layer for calls and call flows.
+
+Holds the on-hangup persistence hook plus the query/write functions
+that both the REST handlers and the MCP tools call, so the two
+surfaces can't drift. Every function takes an AsyncSession; callers
+own the transaction (get_db for REST, session_scope for MCP/services).
 """
 
 import logging
 import uuid
 from datetime import datetime
 
-from db.database import CallRecord, TranscriptChunk, get_session_factory
+from sqlalchemy import desc, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from db.database import (
+    CallRecord,
+    RecordingRecord,
+    StoredCallFlow,
+    TranscriptChunk,
+    session_scope,
+)
 from models.call import ActiveCall, CallStatus
+from models.call_flow import CallFlow, CallFlowStep
 
 logger = logging.getLogger(__name__)
 
 
+def flow_to_model(row: StoredCallFlow) -> CallFlow:
+    """The one StoredCallFlow-row → CallFlow-model mapping."""
+    return CallFlow(
+        id=row.id,
+        name=row.name,
+        phone_number=row.phone_number,
+        description=row.description or "",
+        steps=[CallFlowStep(**s) for s in (row.steps or [])],
+        tags=row.tags or [],
+        notes=row.notes,
+        avg_hold_time=row.avg_hold_time,
+        success_rate=row.success_rate,
+        last_used=row.last_used,
+        times_used=row.times_used or 0,
+    )
+
+
+# ================================================================
+# Call flows
+# ================================================================
+
+async def get_flow(session: AsyncSession, flow_id: str) -> StoredCallFlow | None:
+    result = await session.execute(
+        select(StoredCallFlow).where(StoredCallFlow.id == flow_id)
+    )
+    return result.scalar_one_or_none()
+
+
+async def get_flow_by_number(
+    session: AsyncSession, phone_number: str
+) -> StoredCallFlow | None:
+    result = await session.execute(
+        select(StoredCallFlow).where(StoredCallFlow.phone_number == phone_number)
+    )
+    return result.scalar_one_or_none()
+
+
+async def list_flows(session: AsyncSession) -> list[StoredCallFlow]:
+    result = await session.execute(select(StoredCallFlow))
+    return list(result.scalars().all())
+
+
+async def create_flow(
+    session: AsyncSession,
+    flow_id: str,
+    name: str,
+    phone_number: str,
+    steps: list[dict],
+    description: str | None = None,
+    tags: list[str] | None = None,
+    notes: str | None = None,
+) -> StoredCallFlow:
+    row = StoredCallFlow(
+        id=flow_id,
+        name=name,
+        phone_number=phone_number,
+        description=description,
+        steps=steps,
+        tags=tags,
+        notes=notes,
+        last_verified=datetime.now(),
+    )
+    session.add(row)
+    await session.flush()
+    return row
+
+
+# ================================================================
+# Call history / records
+# ================================================================
+
+async def get_record(session: AsyncSession, call_id: str) -> CallRecord | None:
+    result = await session.execute(
+        select(CallRecord).where(CallRecord.id == call_id)
+    )
+    return result.scalar_one_or_none()
+
+
+async def search_history(
+    session: AsyncSession,
+    number: str | None = None,
+    number_contains: str | None = None,
+    intent_contains: str | None = None,
+    status: str | None = None,
+    since: datetime | None = None,
+    until: datetime | None = None,
+    limit: int = 50,
+    offset: int = 0,
+) -> list[CallRecord]:
+    stmt = select(CallRecord).order_by(desc(CallRecord.started_at))
+    if number:
+        stmt = stmt.where(CallRecord.remote_number == number)
+    if number_contains:
+        stmt = stmt.where(CallRecord.remote_number.contains(number_contains))
+    if intent_contains:
+        stmt = stmt.where(CallRecord.intent.icontains(intent_contains))
+    if status:
+        stmt = stmt.where(CallRecord.status == status)
+    if since:
+        stmt = stmt.where(CallRecord.started_at >= since)
+    if until:
+        stmt = stmt.where(CallRecord.started_at <= until)
+    result = await session.execute(stmt.offset(offset).limit(limit))
+    return list(result.scalars().all())
+
+
+async def get_transcript_chunks(
+    session: AsyncSession, call_id: str
+) -> list[TranscriptChunk]:
+    result = await session.execute(
+        select(TranscriptChunk)
+        .where(TranscriptChunk.call_id == call_id)
+        .order_by(TranscriptChunk.seq)
+    )
+    return list(result.scalars().all())
+
+
+async def latest_recording(
+    session: AsyncSession, call_id: str
+) -> RecordingRecord | None:
+    result = await session.execute(
+        select(RecordingRecord)
+        .where(RecordingRecord.call_id == call_id)
+        .order_by(desc(RecordingRecord.started_at))
+    )
+    return result.scalars().first()
+
+
 async def persist_call_on_end(call: ActiveCall, final_status: CallStatus) -> None:
     """Insert a CallRecord and any transcript chunks for `call`.
 
-    Wired into CallManager via _on_call_ended in gateway.start().
+    Wired into CallManager as its on_call_ended hook by the
+    composition root in main.py.
     """
     try:
-        async with get_session_factory()() as session:
+        async with session_scope() as session:
             record = CallRecord(
                 id=call.id,
                 direction=call.direction,
@@ -64,7 +207,5 @@ async def persist_call_on_end(call: ActiveCall, final_status: CallStatus) -> Non
                     speaker=speaker,
                     text=payload,
                 ))
-
-            await session.commit()
     except Exception as e:
         logger.warning(f"Could not persist call {call.id}: {e}")