feat(rag): stream grounded RAG answers over SSE with source citations

Phase 03 (Story: Chat RAG Answer — happy path):
- app/rag/retriever.py: top-k cosine search + parent-doc selection with
  per-doc dedupe and BOR_MAX_CONTEXT_CHARS cap ([…truncated…] marker)
- app/rag/prompts.py: locked persona + HIGH/DEFLECT prompt builders
- app/rag/llm.py: LLMError + chat_stream (turbo, temp 0.4, max 700, stream)
- app/api/chat.py: POST /api/chat SSE — delta* then done{deflected,
  sources, suggestions}; query_log row + PLAN §9 per-turn log line;
  structured error event on mid-stream failure, JSON 503 when DB down
- frontend: SSE reader, live bubble streaming, source chips -> /sources.html,
  red role=alert banner, Send button state that always recovers
- fix(scaffold): [hidden] { display: none !important } — .kb-banner's
  display:flex was overriding the hidden attribute (banner always visible)
- tests: unit (retriever/prompts/sse/llm) + integration (real Postgres RAG
  turn, query_log, error + 503 paths, mid-turn failures) + Playwright story
  suite (grounded answer, log row, raw SSE shape); smoke placeholder test
  replaced with the real never-stale-button contract

tests/e2e/test_chat_rag.py

@@ -0,0 +1,170 @@
+"""Phase 03 E2E (Playwright): the happy-path RAG chat turn.
+
+Story: ``.agent/user_stories/chat-rag-answer.md``
+Run in isolation (DB must be up: ``podman compose up -d db``):
+
+    uv run pytest tests/e2e/test_chat_rag.py -v --no-cov
+
+Seeding reuses the real importer against ``tests/fixtures/docs/`` with the
+deterministic mock embeddings (same pattern as the phase 02 story suite);
+the mock LLM answers on-topic questions by quoting the question and the
+document context, so the UI assertions are fully deterministic.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+from pathlib import Path
+from threading import Thread
+from typing import Any
+
+import httpx
+from playwright.sync_api import Page, expect
+from sqlalchemy import select, text
+
+from app.config import Settings
+from app.db import SessionLocal
+from app.models import QueryLog
+from app.rag.importer import ImportSummary, import_sources
+from app.rag.llm import LLMClient
+
+REPO = Path(__file__).resolve().parents[2]
+FIXTURES = REPO / "tests" / "fixtures" / "docs"
+QUESTION = "How is my Kubernetes cluster set up?"
+MOCK_ANSWER_MARKER = "Deterministic mock answer for E2E"
+
+
+async def _import_fixtures(mock_port: int) -> ImportSummary:
+    kwargs: dict[str, Any] = {"_env_file": None, "llm_base_url": f"http://127.0.0.1:{mock_port}/v1"}
+    settings = Settings(**kwargs)  # pyright: ignore[reportCallIssue]
+    return await import_sources([FIXTURES], LLMClient(settings))
+
+
+def _run_in_thread(coro: Any) -> Any:
+    """Run a coroutine on a worker thread.
+
+    Playwright's sync API keeps an asyncio loop running on the test thread,
+    so ``asyncio.run`` cannot be called directly from a test body.
+    """
+    box: dict[str, Any] = {}
+
+    def runner() -> None:
+        try:
+            box["value"] = asyncio.run(coro)
+        except BaseException as e:  # noqa: BLE001 — re-raised on the test thread
+            box["error"] = e
+
+    t = Thread(target=runner)
+    t.start()
+    t.join()
+    if "error" in box:
+        raise box["error"]
+    return box["value"]
+
+
+def _reset_db(mock_port: int, seed: bool) -> ImportSummary | None:
+    """Truncate the KB (and query log), then optionally re-import fixtures."""
+    with SessionLocal() as db:
+        db.execute(text("TRUNCATE chunks, documents, query_log"))
+        db.commit()
+    if not seed:
+        return None
+    return _run_in_thread(_import_fixtures(mock_port))
+
+
+def test_on_topic_question_streams_grounded_answer(
+    page: Page, app_url: str, mock_llm: int, db_ready: None
+) -> None:
+    summary = _reset_db(mock_llm, seed=True)
+    assert summary is not None and summary.added == 3
+    page.set_default_timeout(30_000)
+    page.goto(app_url)
+
+    # Healthy KB: the offline banner must stay hidden.
+    expect(page.locator("#kb-banner")).to_be_hidden()
+
+    page.fill("#message-input", QUESTION)
+    page.click("#send-btn")
+
+    # User bubble (right, brand) shows the question.
+    expect(page.locator(".msg.user .bubble")).to_contain_text(QUESTION)
+
+    # Brain bubble streams in: the mock quotes the question and ends with a
+    # deterministic marker — waiting on the marker proves content arrived.
+    bubble = page.locator(".msg.brain .bubble")
+    bubble.first.wait_for(state="visible", timeout=30_000)
+    expect(bubble.first).to_contain_text(QUESTION, timeout=30_000)
+    expect(bubble.first).to_contain_text(MOCK_ANSWER_MARKER, timeout=30_000)
+
+    # Grounded: a kubernetes.md source chip renders under the bubble
+    # (top-N docs can add more chips; the question's doc must be among them).
+    chip = page.locator(".msg.brain .source-chip", has_text="kubernetes.md")
+    expect(chip).to_have_count(1)
+    expect(chip.first).to_contain_text("kubernetes.md")
+    expect(chip.first).to_have_attribute("href", "/sources.html")
+
+    # Button recovers: enabled + "Send" (never stale).
+    expect(page.locator("#send-btn")).to_be_enabled()
+    expect(page.locator("#send-label")).to_have_text("Send")
+
+
+def test_chat_logs_query(page: Page, app_url: str, mock_llm: int, db_ready: None) -> None:
+    _reset_db(mock_llm, seed=True)
+    page.set_default_timeout(30_000)
+    page.goto(app_url)
+    page.fill("#message-input", QUESTION)
+    page.click("#send-btn")
+    expect(
+        page.locator(".msg.brain .source-chip", has_text="kubernetes.md")
+    ).to_have_count(1, timeout=30_000)
+
+    # App still healthy after the turn.
+    r = httpx.get(f"{app_url}/api/health", timeout=5)
+    assert r.status_code == 200
+    body = r.json()
+    assert body["status"] == "ok" and body["db"] == "up"
+
+    # Durable record: exactly one query_log row for the turn.
+    with SessionLocal() as db:
+        rows = db.scalars(select(QueryLog)).all()
+    assert len(rows) == 1
+    row = rows[0]
+    assert row.question == QUESTION
+    assert row.deflected is False
+    assert row.top_score > 0.0
+    assert row.chunk_hits >= 1
+    assert "docs/homelab/kubernetes.md" in row.sources
+    assert row.latency_ms >= 0
+
+
+def test_sse_stream_shape(app_url: str, mock_llm: int, db_ready: None) -> None:
+    """Raw transport contract (PLAN §4): delta events, then one done."""
+    _reset_db(mock_llm, seed=True)
+
+    frames: list[dict[str, Any]] = []
+    with httpx.stream(
+        "POST", f"{app_url}/api/chat", json={"message": QUESTION}, timeout=60.0
+    ) as r:
+        assert r.status_code == 200
+        assert r.headers["content-type"].startswith("text/event-stream")
+        buf = ""
+        for part in r.iter_text():
+            buf += part
+            while "\n\n" in buf:
+                frame, buf = buf.split("\n\n", 1)
+                if frame.strip().startswith("data:"):
+                    frames.append(json.loads(frame.strip().removeprefix("data:").strip()))
+    assert buf.strip() == ""  # stream ends cleanly on a frame boundary
+
+    deltas = [f for f in frames if f.get("type") == "delta"]
+    assert len(deltas) >= 2, "answer must arrive as multiple deltas (streamed)"
+    assert all(d.get("text") for d in deltas)
+    assert "".join(d["text"] for d in deltas)  # non-empty answer
+
+    done = [f for f in frames if f.get("type") == "done"]
+    assert len(done) == 1
+    assert frames[-1]["type"] == "done"  # done is the final event
+    assert done[0]["deflected"] is False
+    assert done[0]["suggestions"] == []
+    assert done[0]["sources"], "done must carry the cited sources"
+    assert any(s["path"] == "homelab/kubernetes.md" for s in done[0]["sources"])

tests/e2e/test_smoke.py

@@ -1,12 +1,10 @@
-"""Phase 01 smoke E2E: the app boots, serves the local frontend, and the
-placeholder chat round-trips without a stale button.
+"""Phase 01 smoke E2E: the app boots, serves the local frontend, and a chat
+round-trip never leaves a stale button (answer or error banner, both fine).
 
 Run:  uv run pytest tests/e2e/test_smoke.py -v
 """
 from __future__ import annotations
 
-import re
-
 import httpx
 from playwright.sync_api import Page, expect
 
@@ -27,19 +25,21 @@ def test_index_page_loads_locally(page: Page, app_url: str) -> None:
     assert 'href="http' not in html.replace('href="http://www.w3.org', "")
 
 
-def test_placeholder_chat_roundtrip(page: Page, app_url: str) -> None:
+def test_chat_roundtrip_never_stale_button(page: Page, app_url: str) -> None:
     page.goto(app_url)
     page.locator("#message-input").fill("hello brain")
     page.locator("#send-btn").click()
 
-    # User bubble appears, then the Brain placeholder answer arrives.
+    # User bubble appears first.
     page.locator(".msg.user .bubble").first.wait_for(state="visible", timeout=10_000)
-    brain_bubble = page.locator(".msg.brain .bubble").first
-    brain_bubble.wait_for(state="visible", timeout=10_000)
-    # to_have_text retries until the async fetch resolves (no stale read).
-    expect(brain_bubble).to_have_text(re.compile("neurons"), timeout=10_000)
+    # Then either a streamed Brain answer (DB up) or an error banner
+    # (DB down) — but the turn must always complete.
+    page.wait_for_selector(
+        ".msg.brain .bubble, #kb-banner.is-error",
+        state="visible",
+        timeout=20_000,
+    )
 
     # Button is never left stuck: back to "Send" and enabled.
-    btn = page.locator("#send-btn")
-    assert btn.is_enabled()
-    assert "Send" in btn.inner_text()
+    expect(page.locator("#send-btn")).to_be_enabled(timeout=10_000)
+    expect(page.locator("#send-label")).to_have_text("Send", timeout=10_000)

tests/integration/test_api.py

@@ -34,16 +34,6 @@ def test_styles_and_js_served(client) -> None:
     assert client.get("/assets/app.js").status_code == 200
 
 
-def test_chat_placeholder_roundtrip(client) -> None:
-    r = client.post("/api/chat", json={"message": "hello brain"})
-    assert r.status_code == 200
-    data = r.json()
-    assert data["ok"] is True
-    assert "neurons" in data["answer"]
-    assert data["deflected"] is False
-    assert data["sources"] == []
-
-
 def test_chat_requires_message(client) -> None:
     r = client.post("/api/chat", json={"message": ""})
     assert r.status_code == 422

tests/integration/test_chat_api.py

@@ -0,0 +1,276 @@
+"""Integration: POST /api/chat — the RAG turn end-to-end.
+
+Real Postgres (compose) seeded from ``tests/fixtures/docs/`` through the
+real importer; the LLM client is a deterministic in-process fake
+(token-overlap embeddings, canned streamed answer), so no network is
+needed and the cosine ordering is meaningful: the Kubernetes question
+retrieves the Kubernetes document.
+
+Requires:  podman compose up -d db
+"""
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import math
+import re
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any
+
+import pytest
+from fastapi.testclient import TestClient
+from sqlalchemy import func, select, text
+
+from app.api import chat as chat_api
+from app.config import Settings, get_settings
+from app.main import app as fastapi_app
+from app.models import Chunk, QueryLog
+from app.rag.importer import import_sources
+from app.rag.llm import EmbeddingError, LLMError
+
+FIXTURES = Path(__file__).resolve().parents[1] / "fixtures" / "docs"
+QUESTION = "How is my Kubernetes cluster set up?"
+DIM = 768
+_TOKEN_RE = re.compile(r"[a-z0-9]+")
+
+
+def _token_vec(text: str) -> list[float]:
+    """Bag-of-words unit vector — same algorithm as the E2E mock, so the
+    cosine behaviour here matches what the story E2E sees."""
+    vec = [0.0] * DIM
+    for tok in _TOKEN_RE.findall(text.lower()):
+        vec[int(hashlib.md5(tok.encode()).hexdigest(), 16) % DIM] += 1.0
+    norm = math.sqrt(sum(v * v for v in vec)) or 1.0
+    return [v / norm for v in vec]
+
+
+class FakeRagLLM:
+    """Duck-typed :class:`app.rag.llm.LLMClient` stand-in for the chat path."""
+
+    def __init__(
+        self,
+        answer: str = "Hey — you've got this! Talos, Cilium, three nodes. 🧠",
+        embed_error: Exception | None = None,
+        stream_error: Exception | None = None,
+        fail_mid_stream: bool = False,
+    ) -> None:
+        self.settings = Settings(_env_file=None)  # pyright: ignore[reportCallIssue]
+        self.embed_batches = 0
+        self.answer = answer
+        self.embed_error = embed_error
+        self.stream_error = stream_error
+        self.fail_mid_stream = fail_mid_stream
+        self.question_embeds: list[str] = []
+        self.seen_messages: list[list[dict[str, str]]] = []
+
+    async def embed(self, texts: list[str]) -> list[list[float]]:
+        self.embed_batches += 1
+        return [_token_vec(t) for t in texts]
+
+    async def embed_one(self, text: str) -> list[float]:
+        if self.embed_error is not None:
+            raise self.embed_error
+        self.question_embeds.append(text)
+        return _token_vec(text)
+
+    async def chat_stream(self, messages: list[dict[str, str]]):
+        self.seen_messages.append(messages)
+        if self.stream_error is not None:
+            raise self.stream_error
+        if self.fail_mid_stream:
+            yield "partial "
+            raise LLMError("mid-stream dropout")
+        for i in range(0, len(self.answer), 12):
+            yield self.answer[i : i + 12]
+
+
+@pytest.fixture()
+def seeded_kb(db) -> Iterator[FakeRagLLM]:
+    """Fresh Postgres with the fixture docs imported (real pipeline)."""
+    db.execute(text("TRUNCATE chunks, documents, query_log"))
+    db.commit()
+    llm = FakeRagLLM()
+    summary = asyncio.run(import_sources([FIXTURES], llm, session=db))
+    assert summary.added == 3
+    yield llm
+    db.execute(text("TRUNCATE chunks, documents, query_log"))
+    db.commit()
+
+
+def _stream_chat(client: TestClient, message: str) -> tuple[int, str, list[dict[str, Any]]]:
+    with client.stream("POST", "/api/chat", json={"message": message}) as r:
+        assert r.status_code == 200
+        assert r.headers["content-type"].startswith("text/event-stream")
+        buf = ""
+        frames: list[dict[str, Any]] = []
+        for part in r.iter_text():
+            buf += part
+            while "\n\n" in buf:
+                frame, buf = buf.split("\n\n", 1)
+                frame = frame.strip()
+                if frame.startswith("data:"):
+                    frames.append(json.loads(frame.removeprefix("data:").strip()))
+        assert buf.strip() == "", "stream must end on a frame boundary"
+    return r.status_code, r.headers["content-type"], frames
+
+
+def test_chat_streams_deltas_then_done_with_sources(client, db, seeded_kb: FakeRagLLM) -> None:
+    fastapi_app.dependency_overrides[chat_api.get_llm] = lambda: seeded_kb
+    try:
+        _, _, frames = _stream_chat(client, QUESTION)
+    finally:
+        fastapi_app.dependency_overrides.clear()
+
+    deltas = [f for f in frames if f.get("type") == "delta"]
+    assert len(deltas) >= 2  # genuinely streamed
+    assert "".join(d["text"] for d in deltas) == seeded_kb.answer
+    assert not any(f.get("type") == "error" for f in frames)
+
+    done = [f for f in frames if f.get("type") == "done"]
+    assert len(done) == 1
+    assert frames[-1]["type"] == "done"  # done is the final event
+    assert done[0]["deflected"] is False
+    assert done[0]["suggestions"] == []
+    sources = done[0]["sources"]
+    assert sources, "done must carry the cited sources"
+    assert sources[0]["path"] == "homelab/kubernetes.md"
+    assert sources[0]["source"] == "docs"
+    assert sources[0]["title"] == "Kubernetes Homelab Cluster"
+
+    # The LLM received the locked HIGH prompt with the FULL document text.
+    (system, user) = seeded_kb.seen_messages[0][0], seeded_kb.seen_messages[0][1]
+    assert user["content"] == QUESTION
+    assert "<relevance>HIGH</relevance>" in system["content"]
+    assert "DEFLECT_MODE" not in system["content"]
+    assert "<documents>" in system["content"]
+    assert "Talos Linux" in system["content"]  # full doc, not just the chunk
+    assert "HONESTY GATE" in system["content"]
+
+
+def test_chat_writes_query_log_row(client, db, seeded_kb: FakeRagLLM) -> None:
+    fastapi_app.dependency_overrides[chat_api.get_llm] = lambda: seeded_kb
+    try:
+        _stream_chat(client, QUESTION)
+    finally:
+        fastapi_app.dependency_overrides.clear()
+
+    rows = db.scalars(select(QueryLog)).all()
+    assert len(rows) == 1
+    row = rows[0]
+    assert row.question == QUESTION
+    assert row.deflected is False
+    total_chunks = db.scalar(select(func.count()).select_from(Chunk))
+    assert row.chunk_hits == min(get_settings().top_k_chunks, total_chunks)
+    assert row.top_score > 0.0  # genuine token-overlap cosine, best hit
+    assert row.top_score <= 1.0
+    assert "docs/homelab/kubernetes.md" in row.sources
+    assert row.latency_ms >= 0
+
+
+def test_chat_empty_kb_streams_empty_sources(client, db) -> None:
+    db.execute(text("TRUNCATE chunks, documents, query_log"))
+    db.commit()
+    llm = FakeRagLLM()
+    fastapi_app.dependency_overrides[chat_api.get_llm] = lambda: llm
+    try:
+        _, _, frames = _stream_chat(client, QUESTION)
+    finally:
+        fastapi_app.dependency_overrides.clear()
+
+    done = frames[-1]
+    assert done["type"] == "done"
+    assert done["deflected"] is False
+    assert done["sources"] == []
+    row = db.scalars(select(QueryLog)).one()
+    assert row.top_score == 0.0
+    assert row.chunk_hits == 0
+    assert row.sources == ""
+
+
+def test_chat_embed_failure_yields_error_event(client, db, seeded_kb: FakeRagLLM) -> None:
+    broken = FakeRagLLM(embed_error=EmbeddingError("embeddings endpoint down"))
+    fastapi_app.dependency_overrides[chat_api.get_llm] = lambda: broken
+    try:
+        _, _, frames = _stream_chat(client, QUESTION)
+    finally:
+        fastapi_app.dependency_overrides.clear()
+
+    assert len(frames) == 1
+    assert frames[0]["type"] == "error"
+    assert "embedding" in frames[0]["detail"]
+    assert db.scalars(select(QueryLog)).all() == []
+
+
+def test_chat_mid_stream_failure_yields_error_after_partial_deltas(client, db) -> None:
+    broken = FakeRagLLM(fail_mid_stream=True)
+    fastapi_app.dependency_overrides[chat_api.get_llm] = lambda: broken
+    try:
+        _, _, frames = _stream_chat(client, QUESTION)
+    finally:
+        fastapi_app.dependency_overrides.clear()
+
+    assert [f["type"] for f in frames] == ["delta", "error"]
+    assert "dropped the connection" in frames[1]["detail"]
+    # No done event, no log row for a turn that never completed.
+    assert db.scalars(select(QueryLog)).all() == []
+
+
+def test_chat_db_down_returns_503_json(client, monkeypatch) -> None:
+    monkeypatch.setattr(chat_api, "db_available", lambda: False)
+    r = client.post("/api/chat", json={"message": "hello"})
+    assert r.status_code == 503
+    assert "offline" in r.json()["detail"]
+
+
+def test_chat_retrieval_failure_yields_error_event(client, db, seeded_kb, monkeypatch) -> None:
+    def boom(*_a: Any, **_k: Any) -> Any:
+        raise RuntimeError("db exploded")
+
+    monkeypatch.setattr(chat_api, "retrieve", boom)
+    fastapi_app.dependency_overrides[chat_api.get_llm] = lambda: seeded_kb
+    try:
+        _, _, frames = _stream_chat(client, QUESTION)
+    finally:
+        fastapi_app.dependency_overrides.clear()
+
+    assert [f["type"] for f in frames] == ["error"]
+    assert "offline mid-question" in frames[0]["detail"]
+    assert db.scalars(select(QueryLog)).all() == []
+
+
+class _BrokenCommitSession:
+    """Pass-through session whose ``commit()`` raises (query_log failure)."""
+
+    def __init__(self, real: Any) -> None:
+        self._real = real
+
+    def commit(self) -> None:
+        raise RuntimeError("query_log commit failed")
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._real, name)
+
+
+def test_chat_query_log_failure_still_sends_done(client, db, seeded_kb: FakeRagLLM) -> None:
+    from app.db import SessionLocal
+
+    def broken_db():
+        real = SessionLocal()
+        try:
+            yield _BrokenCommitSession(real)
+        finally:
+            real.close()
+
+    fastapi_app.dependency_overrides[chat_api.get_db] = broken_db
+    fastapi_app.dependency_overrides[chat_api.get_llm] = lambda: seeded_kb
+    try:
+        _, _, frames = _stream_chat(client, QUESTION)
+    finally:
+        fastapi_app.dependency_overrides.clear()
+
+    # The answer (and the done event) went out despite the log-row failure.
+    assert [f["type"] for f in frames if f["type"] == "delta"]
+    assert frames[-1]["type"] == "done"
+    assert frames[-1]["deflected"] is False

tests/unit/test_llm_client.py

@@ -10,12 +10,13 @@ from __future__ import annotations
 
 import asyncio
 import json
+from types import SimpleNamespace
 from typing import Any
 
 import pytest
 
 from app.config import Settings
-from app.rag.llm import EmbeddingDimensionError, EmbeddingError, LLMClient
+from app.rag.llm import EmbeddingDimensionError, EmbeddingError, LLMClient, LLMError
 
 
 def _settings(**kwargs: Any) -> Settings:
@@ -230,3 +231,98 @@ def test_single_oversized_text_fails_actionably() -> None:
     with pytest.raises(EmbeddingError, match="token cap"):
         asyncio.run(llm.embed(["x" * 3000]))
     assert llm.embed_batches == 0
+
+
+# ---------- chat streaming (phase 03) ----------
+
+
+def _chunk(content: str | None = "text", empty: bool = False):
+    """One fake ChatCompletionChunk (``choices[].delta.content`` shape)."""
+    if empty:
+        return SimpleNamespace(choices=[])
+    return SimpleNamespace(choices=[SimpleNamespace(delta=SimpleNamespace(content=content))])
+
+
+class _FakeChatStream:
+    def __init__(self, chunks: list) -> None:
+        self._chunks = list(chunks)
+
+    def __aiter__(self):
+        self._i = 0
+        return self
+
+    async def __anext__(self):
+        if self._i >= len(self._chunks):
+            raise StopAsyncIteration
+        chunk = self._chunks[self._i]
+        self._i += 1
+        return chunk
+
+
+class _FakeCompletions:
+    def __init__(self, chunks: list | None = None, fail: Exception | None = None) -> None:
+        self.chunks = chunks or []
+        self.fail = fail
+        self.kwargs: dict | None = None
+
+    async def create(self, **kwargs) -> _FakeChatStream:
+        self.kwargs = kwargs
+        if self.fail is not None:
+            raise self.fail
+        return _FakeChatStream(self.chunks)
+
+
+def _make_stream_client(
+    chunks: list | None = None, fail: Exception | None = None
+) -> tuple[LLMClient, _FakeCompletions]:
+    completions = _FakeCompletions(chunks, fail)
+    fake_openai = SimpleNamespace(chat=SimpleNamespace(completions=completions))
+    llm = LLMClient(_settings())
+    llm._client = fake_openai  # pyright: ignore[reportAttributeAccessIssue]
+    return llm, completions
+
+
+async def _collect(llm: LLMClient, messages: list[dict[str, str]]) -> list[str]:
+    return [p async for p in llm.chat_stream(messages)]
+
+
+def test_chat_stream_yields_deltas_in_order() -> None:
+    llm, completions = _make_stream_client(
+        [_chunk("Hey "), _chunk("you've "), _chunk("got this! 🧠")]
+    )
+    pieces = asyncio.run(_collect(llm, [{"role": "user", "content": "q"}]))
+    assert pieces == ["Hey ", "you've ", "got this! 🧠"]
+
+
+def test_chat_stream_uses_locked_generation_params() -> None:
+    llm, completions = _make_stream_client([_chunk("x")])
+    messages = [{"role": "system", "content": "s"}, {"role": "user", "content": "u"}]
+    asyncio.run(_collect(llm, messages))
+    assert completions.kwargs is not None
+    assert completions.kwargs["model"] == "turbo"
+    assert completions.kwargs["stream"] is True
+    assert completions.kwargs["temperature"] == 0.4
+    assert completions.kwargs["max_tokens"] == 700
+    assert completions.kwargs["messages"] == messages
+
+
+def test_chat_stream_skips_empty_deltas_and_choiceless_chunks() -> None:
+    llm, _ = _make_stream_client([_chunk("a"), _chunk(empty=True), _chunk(None), _chunk("b")])
+    assert asyncio.run(_collect(llm, [{"role": "user", "content": "q"}])) == ["a", "b"]
+
+
+def test_chat_stream_wraps_failures_as_llm_error() -> None:
+    llm, _ = _make_stream_client(fail=RuntimeError("connection reset by peer"))
+
+    async def drain() -> None:
+        async for _ in llm.chat_stream([{"role": "user", "content": "q"}]):
+            pass
+
+    with pytest.raises(LLMError, match="connection reset by peer"):
+        asyncio.run(drain())
+
+
+def test_chat_stream_llm_error_passes_through_unwrapped() -> None:
+    llm, _ = _make_stream_client(fail=LLMError("already wrapped"))
+    with pytest.raises(LLMError, match="already wrapped"):
+        asyncio.run(_collect(llm, [{"role": "user", "content": "q"}]))

tests/unit/test_prompts.py

@@ -0,0 +1,88 @@
+"""Unit: locked persona prompt builder (PLAN §6 verbatim + both modes)."""
+from __future__ import annotations
+
+import uuid
+
+import pytest
+
+from app.models import Document
+from app.rag.prompts import PERSONA, _base, build_deflect_prompt, build_high_prompt
+
+
+def _doc(path: str, content: str, title: str) -> Document:
+    return Document(
+        id=uuid.uuid4(),
+        source="Homelab",
+        path=path,
+        full_path=f"/tmp/{path}",
+        title=title,
+        content=content,
+        content_hash="0" * 64,
+    )
+
+
+def test_persona_rules_present_verbatim() -> None:
+    for fragment in (
+        'You are "Brain of Reese" — the digital brain of Reese, a self-hoster and',
+        'optimistic about the user\'s ability to do things ("you\'ve got this")',
+        "Answer ONLY from the provided document context. Cite which document(s)",
+        "you used, by path.",
+        "Be concrete: names, versions, ports, hosts, schedules",
+        'HONESTY GATE: if <relevance> is "LOW", you must NOT pretend to know',
+        'Start your answer with a variant of: "I haven\'t done anything like that."',
+        "Then offer 2-3 alternative questions about things you DO have notes on.",
+        "Never invent facts, hosts, or steps that are not in the context.",
+        "Keep answers tight: short paragraphs, bullets where helpful.",
+    ):
+        assert fragment in PERSONA
+
+
+def test_high_prompt_carries_relevance_marker_and_full_documents() -> None:
+    doc = _doc("kubernetes.md", "Talos Linux on three nodes.", "Kubernetes Homelab Cluster")
+    prompt = build_high_prompt([doc])
+    assert "<relevance>HIGH</relevance>" in prompt
+    assert "DEFLECT_MODE" not in prompt
+    assert "<documents>" in prompt and "</documents>" in prompt
+    assert 'path="kubernetes.md"' in prompt
+    assert "Talos Linux on three nodes." in prompt
+    assert "HONESTY GATE" in prompt  # persona intact
+
+
+def test_high_prompt_lists_multiple_documents_in_order() -> None:
+    a = _doc("a.md", "CONTENT_A", "Title A")
+    b = _doc("b.md", "CONTENT_B", "Title B")
+    prompt = build_high_prompt([a, b])
+    assert prompt.index("CONTENT_A") < prompt.index("CONTENT_B")
+    assert 'title="Title B"' in prompt
+
+
+def test_high_prompt_without_documents_stays_honest() -> None:
+    prompt = build_high_prompt([])
+    assert "<documents>" in prompt
+    assert "do not invent specifics" in prompt
+
+
+def test_low_prompt_has_deflect_mode_and_titles_only() -> None:
+    titles = ["Kubernetes Homelab Cluster", "Backup Strategy"]
+    prompt = build_deflect_prompt(titles)
+    assert "<relevance>LOW</relevance>" in prompt
+    assert "DEFLECT_MODE" in prompt  # marker the E2E mock keys on
+    assert "- Kubernetes Homelab Cluster" in prompt
+    assert "- Backup Strategy" in prompt
+
+
+def test_low_prompt_never_contains_document_content() -> None:
+    secret = "SECRET_DOCUMENT_CONTENT_12345"
+    prompt = build_deflect_prompt(["Some Title"])
+    assert secret not in prompt
+    assert "<documents>" not in prompt
+    assert "HONESTY GATE" in prompt  # the LOW rule is what the model must follow
+
+
+def test_low_prompt_with_no_titles() -> None:
+    assert "nothing close at all" in build_deflect_prompt([])
+
+
+def test_relevance_placeholder_rejected_for_garbage() -> None:
+    with pytest.raises(ValueError, match="HIGH or LOW"):
+        _base("MEDIUM")

tests/unit/test_retriever.py

@@ -0,0 +1,96 @@
+"""Unit: retriever — ordering, dedup, and the context cap (fake rows).
+
+The SQL side of :func:`app.rag.retriever.retrieve` is exercised by the
+chat integration tests against real Postgres; the pure mapping logic in
+:func:`select_documents` is tested here with in-memory rows.
+"""
+from __future__ import annotations
+
+import uuid
+
+from app.models import Document
+from app.rag.retriever import TRUNCATION_MARKER, RetrievedChunk, select_documents
+
+
+def _doc(path: str, content: str, source: str = "Homelab", title: str | None = None) -> Document:
+    return Document(
+        id=uuid.uuid4(),
+        source=source,
+        path=path,
+        full_path=f"/tmp/{path}",
+        title=title or path,
+        content=content,
+        content_hash="0" * 64,
+    )
+
+
+def _chunk(doc: Document, score: float, position: int = 0) -> RetrievedChunk:
+    return RetrievedChunk(
+        chunk_id=uuid.uuid4(),
+        position=position,
+        content=doc.content[:40],
+        score=score,
+        document=doc,
+    )
+
+
+def test_ranks_by_best_chunk_score_not_first_hit() -> None:
+    """A doc whose *later* chunk scores highest must still rank first."""
+    a = _doc("a.md", "A" * 50)
+    b = _doc("b.md", "B" * 50)
+    c = _doc("c.md", "C" * 50)
+    chunks = [
+        _chunk(a, 0.4, position=0),  # a's weak chunk comes first
+        _chunk(b, 0.8),
+        _chunk(a, 0.9, position=2),  # a's best chunk comes last
+        _chunk(c, 0.5),
+    ]
+    docs = select_documents(chunks, n=3, max_chars=10_000)
+    assert [d.path for d in docs] == ["a.md", "b.md", "c.md"]
+
+
+def test_dedups_to_one_document_per_hit_set() -> None:
+    a = _doc("a.md", "A" * 50)
+    chunks = [_chunk(a, 0.2), _chunk(a, 0.7), _chunk(a, 0.5)]
+    docs = select_documents(chunks, n=2, max_chars=10_000)
+    assert len(docs) == 1
+    assert docs[0] is a
+
+
+def test_caps_at_n_documents() -> None:
+    docs_in = [_doc(f"d{i}.md", "X" * 20) for i in range(4)]
+    chunks = [_chunk(d, 0.5 - 0.1 * i) for i, d in enumerate(docs_in)]
+    out = select_documents(chunks, n=2, max_chars=10_000)
+    assert [d.path for d in out] == ["d0.md", "d1.md"]
+
+
+def test_combined_content_capped_with_truncation_marker() -> None:
+    big = _doc("big.md", "B" * 100)
+    small = _doc("small.md", "S" * 100)
+    chunks = [_chunk(big, 0.9), _chunk(small, 0.6)]
+    out = select_documents(chunks, n=2, max_chars=150)
+    # Best doc stays intact; the overflowing one is truncated in place.
+    assert out[0].content == "B" * 100
+    assert out[1].content.endswith(TRUNCATION_MARKER)
+    assert out[1].content.startswith("S")
+    assert len(out[0].content) + len(out[1].content) <= 150
+
+
+def test_single_doc_over_budget_is_truncated_to_budget() -> None:
+    big = _doc("big.md", "Z" * 200)
+    out = select_documents([_chunk(big, 0.9)], n=2, max_chars=50)
+    assert len(out[0].content) == 50
+    assert out[0].content.endswith(TRUNCATION_MARKER)
+
+
+def test_under_budget_no_truncation() -> None:
+    a = _doc("a.md", "A" * 80)
+    b = _doc("b.md", "B" * 60)
+    out = select_documents([_chunk(b, 0.5), _chunk(a, 0.9)], n=2, max_chars=200)
+    assert [d.path for d in out] == ["a.md", "b.md"]
+    assert a.content == "A" * 80 and b.content == "B" * 60
+    assert TRUNCATION_MARKER not in a.content + b.content
+
+
+def test_empty_hits_yield_no_documents() -> None:
+    assert select_documents([], n=2, max_chars=24_000) == []

tests/unit/test_sse_events.py

@@ -0,0 +1,48 @@
+"""Unit: SSE frame serialization for POST /api/chat (PLAN §4 contract)."""
+from __future__ import annotations
+
+import json
+
+from app.api.chat import sse_event
+
+
+def _payload(frame: str) -> dict:
+    assert frame.startswith("data: ")
+    assert frame.endswith("\n\n")
+    return json.loads(frame.removeprefix("data: ").strip())
+
+
+def test_delta_frame_serializes_exactly() -> None:
+    frame = sse_event({"type": "delta", "text": "hi"})
+    assert frame == 'data: {"type": "delta", "text": "hi"}\n\n'
+    assert _payload(frame) == {"type": "delta", "text": "hi"}
+
+
+def test_done_frame_carries_full_contract_shape() -> None:
+    payload = {
+        "type": "done",
+        "deflected": False,
+        "sources": [{"source": "Homelab", "path": "kubernetes.md", "title": "K8s"}],
+        "suggestions": [],
+    }
+    assert _payload(sse_event(payload)) == payload
+
+
+def test_error_frame_serializes() -> None:
+    frame = sse_event({"type": "error", "detail": "boom"})
+    assert _payload(frame) == {"type": "error", "detail": "boom"}
+
+
+def test_unicode_survives_roundtrip() -> None:
+    frame = sse_event({"type": "delta", "text": "🧠 café — \"quoted\""})
+    # ensure_ascii=False keeps the frame readable (no \uXXXX escapes).
+    assert "🧠 café" in frame
+    assert _payload(frame)["text"] == "🧠 café — \"quoted\""
+
+
+def test_multi_line_text_stays_one_frame() -> None:
+    """Newlines inside the JSON payload must be escaped so the frame
+    delimiter ``\\n\\n`` remains unambiguous."""
+    frame = sse_event({"type": "delta", "text": "line1\nline2\n\n"})
+    assert frame.count("\n\n") == 1  # only the frame terminator
+    assert _payload(frame)["text"] == "line1\nline2\n\n"