Checkpoint frontend UI/UX overhaul and ingestion embed benchmark work

apps/ai-service/adapters/postgres.py

@@ -22,6 +22,19 @@ class RetrievalTrace:
 
 
 class PostgresTraceRepository:
+    """Opens a new connection per call — no pooling (F-09: a real pool, with
+    startup-time lifecycle, is a further improvement not made here).
+
+    `connect_timeout` matters more than it looks: found live 2026-08-06 that
+    an unreachable Postgres (packets dropped, not actively refused) makes a
+    bare `psycopg.connect()` hang on the OS-level TCP timeout — tens of
+    seconds, not immediate — which defeats a caller's try/except fail-open
+    around `save()` just as effectively as no try/except at all, since the
+    exception it's waiting for never arrives in time. `routers/rag.py`
+    wraps `save()` to keep a trace outage from failing an already-computed
+    answer; this bounds how long that protection can take to kick in.
+    """
+
     def __init__(self, dsn: str) -> None:
         self._dsn = dsn
 
@@ -29,7 +42,7 @@ class PostgresTraceRepository:
         import psycopg
 
         statement = migration_path.read_text(encoding="utf-8")
-        with psycopg.connect(self._dsn) as connection:
+        with psycopg.connect(self._dsn, connect_timeout=5) as connection:
             connection.execute(statement)
 
     def save(
@@ -46,7 +59,7 @@ class PostgresTraceRepository:
         import psycopg
 
         trace_id = str(uuid.uuid4())
-        with psycopg.connect(self._dsn) as connection:
+        with psycopg.connect(self._dsn, connect_timeout=5) as connection:
             connection.execute(
                 """
                 INSERT INTO rag_retrieval_trace (
@@ -64,7 +77,7 @@ class PostgresTraceRepository:
     def get(self, trace_id: str) -> RetrievalTrace | None:
         import psycopg
 
-        with psycopg.connect(self._dsn) as connection:
+        with psycopg.connect(self._dsn, connect_timeout=5) as connection:
             row = connection.execute(
                 """
                 SELECT trace_id::text, query_text, subject_scope, query_intent,