feat: scaffold Brain of Reese — FastAPI RAG chat over Postgres 17 + pgvector

Foundation (phase 01, verified):
- FastAPI app: /api/health, /api/suggestions, /api/chat (placeholder),
  static frontend served locally (no CDN)
- Postgres 17 + pgvector via db/Containerfile + compose.yaml
  (podman compose up -d db), Alembic initial migration (documents,
  chunks with vector(768), query_log)
- LLM client targeting https://aipi.reeseapps.com/v1 (turbo/embed);
  scripts/llm_probe.py verified models + 768-dim embeddings live
- Conditional debugpy: imported only when DEBUGPY=1 (attach on demand,
  :5678); logging config for clean single-line logs
- Frontend shell: mobile-first chat + Sources pages, tokens, a11y baselines
- Tests: 24 unit+integration (99% coverage on app/), ruff + pyright clean,
  Playwright smoke E2E (3 tests) against a deterministic mock LLM
- Planning: .agent/PLAN.md (architecture + LOCKED decisions), AGENTS.md,
  6 user stories, 7 phase files (one story / one phase / one Playwright
  suite each)

tests/conftest.py

@@ -0,0 +1,12 @@
+"""Shared fixtures for unit + integration tests."""
+from __future__ import annotations
+
+import pytest
+from fastapi.testclient import TestClient
+
+from app.main import app as fastapi_app
+
+
+@pytest.fixture()
+def client() -> TestClient:
+    return TestClient(fastapi_app)

tests/e2e/__init__.py

@@ -0,0 +1 @@
+"""E2E test package."""

tests/e2e/conftest.py

@@ -0,0 +1,126 @@
+"""Playwright E2E fixtures (shared by every story's test file).
+
+Each user story in ``.agent/user_stories/`` gets its own isolated E2E test
+file; this conftest provides the shared environment:
+
+* ``mock_llm``   — deterministic OpenAI-compatible server (see mock_llm.py).
+                    Set ``E2E_REAL_LLM=1`` to point at the real aipi endpoint
+                    instead (requires an imported knowledge base).
+* ``app_server`` — the real FastAPI app under test (uvicorn subprocess).
+* ``browser``/``page`` — headless Chromium pointed at the app.
+
+Prerequisite for story tests that touch the database:
+    podman compose up -d db
+"""
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import time
+from collections.abc import Iterator
+from pathlib import Path
+
+import httpx
+import pytest
+from playwright.sync_api import Browser, Page, sync_playwright
+
+REPO = Path(__file__).resolve().parents[2]
+APP_PORT = int(os.environ.get("E2E_APP_PORT", "8123"))
+MOCK_PORT = int(os.environ.get("E2E_MOCK_PORT", "8901"))
+APP_URL = f"http://127.0.0.1:{APP_PORT}"
+USE_REAL_LLM = os.environ.get("E2E_REAL_LLM") == "1"
+
+
+def _wait_http(url: str, timeout: float = 40.0) -> None:
+    deadline = time.monotonic() + timeout
+    last_err = "unknown"
+    while time.monotonic() < deadline:
+        try:
+            httpx.get(url, timeout=2.0)
+            return
+        except Exception as e:  # noqa: BLE001 — retry until deadline
+            last_err = str(e)
+            time.sleep(0.5)
+    raise RuntimeError(f"server at {url} did not come up: {last_err}")
+
+
+@pytest.fixture(scope="session")
+def mock_llm() -> Iterator[int]:
+    """Deterministic OpenAI-compatible LLM (chat + embeddings)."""
+    if USE_REAL_LLM:
+        yield 0
+        return
+    env = dict(os.environ)
+    env.pop("DEBUGPY", None)
+    proc = subprocess.Popen(
+        [sys.executable, "-m", "uvicorn", "tests.e2e.mock_llm:app",
+         "--host", "127.0.0.1", "--port", str(MOCK_PORT), "--log-level", "warning"],
+        cwd=REPO,
+        env=env,
+    )
+    try:
+        _wait_http(f"http://127.0.0.1:{MOCK_PORT}/v1/models")
+        yield MOCK_PORT
+    finally:
+        proc.terminate()
+        try:
+            proc.wait(timeout=10)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+
+
+@pytest.fixture(scope="session")
+def app_server(mock_llm: int) -> Iterator[str]:
+    """The real app under test."""
+    env = dict(os.environ)
+    env.pop("DEBUGPY", None)
+    env["BOR_ENVIRONMENT"] = "e2e"
+    env["BOR_STATIC_DIR"] = str(REPO / "frontend")
+    env["BOR_LLM_BASE_URL"] = (
+        "https://aipi.reeseapps.com/v1"
+        if USE_REAL_LLM
+        else f"http://127.0.0.1:{mock_llm}/v1"
+    )
+    env.setdefault("BOR_DATABASE_URL", "postgresql+psycopg://reese:reese@localhost:5432/brain_of_reese")
+    proc = subprocess.Popen(
+        [sys.executable, "-m", "uvicorn", "app.main:app",
+         "--host", "127.0.0.1", "--port", str(APP_PORT), "--log-level", "warning"],
+        cwd=REPO,
+        env=env,
+    )
+    try:
+        _wait_http(f"{APP_URL}/api/health")
+        yield APP_URL
+    finally:
+        proc.terminate()
+        try:
+            proc.wait(timeout=10)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+
+
+@pytest.fixture(scope="session")
+def app_url(app_server: str) -> str:
+    return app_server
+
+
+@pytest.fixture()
+def db_ready(app_url: str) -> None:
+    """Skip a test with clear instructions when Postgres is not running."""
+    body = httpx.get(f"{app_url}/api/health", timeout=5).json()
+    if body["db"] != "up":
+        pytest.skip("Postgres not reachable — run `podman compose up -d db` first")
+
+
+@pytest.fixture(scope="session")
+def browser() -> Iterator[Browser]:
+    with sync_playwright() as p:
+        yield p.chromium.launch(headless=True)
+
+
+@pytest.fixture()
+def page(browser: Browser) -> Iterator[Page]:
+    pg = browser.new_page(viewport={"width": 1280, "height": 800})
+    yield pg
+    pg.close()

tests/e2e/mock_llm.py

@@ -0,0 +1,174 @@
+"""Deterministic OpenAI-compatible mock for E2E tests (aipi stand-in).
+
+Implements just enough of the aipi surface:
+
+* ``GET  /v1/models``
+* ``POST /v1/embeddings`` — real bag-of-words vectors (768-dim, L2-normed).
+  Because similarity is *genuine token overlap*, the relevance threshold
+  behaves the same way it will in production: related questions score high,
+  unrelated ones score low and trigger honest deflection.
+* ``POST /v1/chat/completions`` — streaming (SSE) or not. The content keys
+  off markers in the system prompt:
+  - ``DEFLECT_MODE``  -> honest "I haven't done anything like that" answer
+  - otherwise         -> upbeat answer quoting the provided document context
+  - user message containing ``pretend to think slowly`` -> 3s warm-up delay
+    (used by the loading-feedback story).
+"""
+from __future__ import annotations
+
+import hashlib
+import math
+import re
+import time
+import uuid
+from typing import Any
+
+from fastapi import FastAPI
+from fastapi.responses import StreamingResponse
+
+app = FastAPI()
+
+DIM = 768
+TOKEN_RE = re.compile(r"[a-z0-9]+")
+
+
+def embed_text(text: str) -> list[float]:
+    vec = [0.0] * DIM
+    for tok in TOKEN_RE.findall(text.lower()):
+        idx = int(hashlib.md5(tok.encode()).hexdigest(), 16) % DIM
+        vec[idx] += 1.0
+    norm = math.sqrt(sum(v * v for v in vec)) or 1.0
+    return [v / norm for v in vec]
+
+
+def _messages(body: dict[str, Any]) -> list[dict[str, str]]:
+    return body.get("messages", [])
+
+
+def _system(body: dict[str, Any]) -> str:
+    return " ".join(m.get("content", "") for m in _messages(body) if m.get("role") == "system")
+
+
+def _user(body: dict[str, Any]) -> str:
+    parts = [m.get("content", "") for m in _messages(body) if m.get("role") == "user"]
+    return parts[-1] if parts else ""
+
+
+def _context(body: dict[str, Any]) -> str:
+    """The document context is the longest system/user message in practice."""
+    msgs = _messages(body)
+    return max((m.get("content", "") for m in msgs), key=len)
+
+
+def compose_answer(body: dict[str, Any]) -> str:
+    system = _system(body)
+    user = _user(body)
+    if "DEFLECT_MODE" in system:
+        return (
+            "Ah — I haven't done anything like that, so I don't want to make stuff up! "
+            "You're thinking bigger than my notes for a second. Try asking about "
+            "kubernetes, backups, or deploying a new service — I know those inside out. "
+            "You've got this!"
+        )
+    ctx = _context(body)
+    snippet = ctx[:220].replace("\n", " ").strip()
+    return (
+        f"Great question — you've absolutely got this! Here's what my notes say about "
+        f"“{user.strip()[:80]}”: {snippet}… That's the gist from the docs; happy to "
+        "dig into any of it. (Deterministic mock answer for E2E.)"
+    )
+
+
+@app.get("/v1/models")
+def models() -> dict[str, Any]:
+    return {
+        "object": "list",
+        "data": [
+            {"id": "turbo", "object": "model"},
+            {"id": "embed", "object": "model"},
+            {"id": "lite", "object": "model"},
+        ],
+    }
+
+
+@app.post("/v1/embeddings")
+def embeddings(body: dict[str, Any]) -> dict[str, Any]:
+    raw = body.get("input")
+    if isinstance(raw, str):
+        raw = [raw]
+    inputs: list[Any] = list(raw) if isinstance(raw, list) else []
+    data = [
+        {"object": "embedding", "index": i, "embedding": embed_text(t)}
+        for i, t in enumerate(inputs)
+    ]
+    return {
+        "object": "list",
+        "data": data,
+        "model": body.get("model", "embed"),
+        "usage": {"prompt_tokens": 8, "total_tokens": 8},
+    }
+
+
+def _sse_stream(answer: str, delay: float) -> Any:
+    model = "turbo"
+    chunk_id = f"chatcmpl-{uuid.uuid4()}"
+    if delay:
+        time.sleep(delay)
+    for piece in re.findall(r".{1,12}", answer, re.S):
+        payload = {
+            "id": chunk_id,
+            "object": "chat.completion.chunk",
+            "created": int(time.time()),
+            "model": model,
+            "choices": [{"index": 0, "delta": {"content": piece}, "finish_reason": None}],
+        }
+        yield f"data: {json_dumps(payload)}\n\n"
+        time.sleep(0.02)
+    yield (
+        "data: "
+        + json_dumps(
+            {
+                "id": chunk_id,
+                "object": "chat.completion.chunk",
+                "created": int(time.time()),
+                "model": model,
+                "choices": [{"index": 0, "delta": {}, "finish_reason": "stop"}],
+            }
+        )
+        + "\n\n"
+    )
+    yield "data: [DONE]\n\n"
+
+
+def json_dumps(obj: dict[str, Any]) -> str:
+    import json
+
+    return json.dumps(obj)
+
+
+@app.post("/v1/chat/completions")
+def chat_completions(body: dict[str, Any]) -> Any:
+    answer = compose_answer(body)
+    delay = 3.0 if "pretend to think slowly" in _user(body) else 0.0
+
+    if not body.get("stream"):
+        return {
+            "id": f"chatcmpl-{uuid.uuid4()}",
+            "object": "chat.completion",
+            "created": int(time.time()),
+            "model": body.get("model", "turbo"),
+            "choices": [
+                {
+                    "index": 0,
+                    "message": {"role": "assistant", "content": answer},
+                    "finish_reason": "stop",
+                }
+            ],
+            "usage": {"prompt_tokens": 100, "completion_tokens": 50, "total_tokens": 150},
+        }
+
+    return StreamingResponse(
+        _sse_stream(answer, delay),
+        media_type="text/event-stream",
+        headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
+    )

tests/e2e/test_smoke.py

@@ -0,0 +1,45 @@
+"""Phase 01 smoke E2E: the app boots, serves the local frontend, and the
+placeholder chat round-trips without a stale button.
+
+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
+
+
+def test_health_endpoint(app_url: str) -> None:
+    r = httpx.get(f"{app_url}/api/health", timeout=5)
+    assert r.status_code == 200
+    assert r.json()["status"] == "ok"
+
+
+def test_index_page_loads_locally(page: Page, app_url: str) -> None:
+    page.goto(app_url)
+    assert page.title() == "Brain of Reese"
+    assert page.locator(".brand").is_visible()
+    # No external (CDN) resources in the document.
+    html = page.content()
+    assert 'src="http' not in html
+    assert 'href="http' not in html.replace('href="http://www.w3.org', "")
+
+
+def test_placeholder_chat_roundtrip(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.
+    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)
+
+    # 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()

tests/fixtures/docs/deployments/new-service.md

@@ -0,0 +1,13 @@
+# Deploying a New Service
+
+## Steps
+1. Fork the `template/` repository.
+2. Add a cloud-init snippet for provisioning the host.
+3. Wire up the reverse proxy (Traefik) with a `reeseapps.com` label.
+4. Run the Ansible play: `ansible-playbook sites.yaml -l newhost`.
+
+## Domains
+All public services live under `*.reeseapps.com`.
+
+## DNS
+Managed by the ddns updater; new subdomains appear within an hour.

tests/fixtures/docs/homelab/backups.md

@@ -0,0 +1,14 @@
+# Backup Strategy
+
+## Philosophy
+3-2-1 rule: three copies, two media types, one offsite.
+
+## Tooling
+BorgBase for offsite backups. Restic for local nightly snapshots, orchestrated via Ansible.
+
+## Schedule
+- Nightly 02:00 — restic local snapshots
+- Weekly Sunday 03:00 — borg offsite push
+
+## Restore
+Restores are documented per-service in each deployment README. Test a restore quarterly.

tests/fixtures/docs/homelab/kubernetes.md

@@ -0,0 +1,16 @@
+# Kubernetes Homelab Cluster
+
+## Overview
+The cluster runs Talos Linux on three nodes: two workers (i5-8500, 32GB) and one control plane.
+
+## Networking
+Cilium handles networking and the L4/L7 proxy. Ingress is served via the Cilium Gateway API.
+
+## Storage
+Local-path-provisioner provides scratch storage. Longhorn is intentionally not used.
+
+## Notable Workloads
+- Gitea (source control)
+- ntfy (push notifications)
+- Homepage (dashboard)
+- Uptime Kuma (monitoring)

tests/integration/test_api.py

@@ -0,0 +1,49 @@
+"""Integration tests: HTTP API surface (no database required)."""
+from __future__ import annotations
+
+
+def test_health_reports_ok(client) -> None:
+    r = client.get("/api/health")
+    assert r.status_code == 200
+    body = r.json()
+    assert body["status"] == "ok"
+    assert body["db"] in {"up", "down"}
+    assert body["version"]
+
+
+def test_suggestions_returns_list(client) -> None:
+    r = client.get("/api/suggestions")
+    assert r.status_code == 200
+    suggestions = r.json()["suggestions"]
+    assert isinstance(suggestions, list)
+    assert all(isinstance(s, str) and s for s in suggestions)
+
+
+def test_index_html_served_locally(client) -> None:
+    """No-CDN check: the page is served by FastAPI and references only
+    same-origin assets (no https:// script/link tags)."""
+    r = client.get("/")
+    assert r.status_code == 200
+    assert "Brain of Reese" in r.text
+    assert 'src="https://' not in r.text
+    assert 'href="https://' not in r.text
+
+
+def test_styles_and_js_served(client) -> None:
+    assert client.get("/assets/styles.css").status_code == 200
+    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/unit/test_config.py

@@ -0,0 +1,42 @@
+"""Unit tests: settings defaults & env overrides."""
+from __future__ import annotations
+
+from typing import Any
+
+from app.config import Settings
+
+
+def _settings(**kwargs: Any) -> Settings:
+    """Build Settings without reading a .env file (deterministic tests)."""
+    kwargs.setdefault("_env_file", None)
+    return Settings(**kwargs)  # pyright: ignore[reportCallIssue]  (kwarg exists at runtime)
+
+
+def test_defaults_match_locked_decisions() -> None:
+    s = _settings()
+    assert s.llm_chat_model == "turbo"
+    assert s.llm_embed_model == "embed"
+    assert s.embedding_dim == 768
+    assert s.llm_base_url.endswith("/v1")
+    assert 0 < s.relevance_threshold < 1
+    assert s.top_k_chunks >= 1
+    assert s.top_n_docs >= 1
+    assert len(s.suggestions) >= 3
+
+
+def test_env_override(monkeypatch) -> None:
+    monkeypatch.setenv("BOR_RELEVANCE_THRESHOLD", "0.42")
+    monkeypatch.setenv("BOR_LLM_CHAT_MODEL", "juggernaut")
+    s = _settings()
+    assert s.relevance_threshold == 0.42
+    assert s.llm_chat_model == "juggernaut"
+
+
+def test_effective_api_key_fallback(monkeypatch) -> None:
+    monkeypatch.delenv("AIPI_KEY", raising=False)
+    s = _settings()
+    assert s.effective_api_key == "not-needed"
+
+    monkeypatch.setenv("AIPI_KEY", "sk-from-env")
+    s2 = _settings()
+    assert s2.effective_api_key == "sk-from-env"

tests/unit/test_db.py

@@ -0,0 +1,56 @@
+"""Unit tests: engine/session helpers (no live database required).
+
+Creating a SQLAlchemy engine/session is lazy — no connection opens until the
+first query — so these run anywhere.
+"""
+from __future__ import annotations
+
+from sqlalchemy import Engine
+from sqlalchemy.orm import Session
+
+from app import db as app_db
+
+
+def test_engine_and_session_factory_are_lazy() -> None:
+    assert isinstance(app_db.engine, Engine)
+    session = app_db.SessionLocal()
+    try:
+        assert isinstance(session, Session)
+    finally:
+        session.close()
+
+
+def test_get_db_yields_session_and_closes_generator() -> None:
+    gen = app_db.get_db()
+    session = next(gen)
+    assert isinstance(session, Session)
+    session.close()
+    gen.close()  # exercises the finally: db.close()
+
+
+def test_db_available_true_on_select_one(monkeypatch) -> None:
+    class _FakeConn:
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *exc: object) -> None:
+            return None
+
+        def execute(self, _stmt: object) -> None:
+            return None
+
+    class _FakeEngine:
+        def connect(self) -> _FakeConn:
+            return _FakeConn()
+
+    monkeypatch.setattr(app_db, "engine", _FakeEngine())
+    assert app_db.db_available() is True
+
+
+def test_db_available_false_on_error(monkeypatch) -> None:
+    class _BrokenEngine:
+        def connect(self) -> object:
+            raise ConnectionError("db is down")
+
+    monkeypatch.setattr(app_db, "engine", _BrokenEngine())
+    assert app_db.db_available() is False

tests/unit/test_debugging.py

@@ -0,0 +1,60 @@
+"""Unit tests: conditional debugpy gating (PLAN anchor A14).
+
+Rules under test:
+* DEBUGPY unset or 0 -> configure_debugging() is False, debugpy NOT imported.
+* DEBUGPY=1          -> configure_debugging() is True, listener on DEBUGPY_PORT.
+"""
+from __future__ import annotations
+
+import socket
+import sys
+
+import pytest
+
+import app.core.debugging as dbg
+
+
+@pytest.fixture()
+def free_port() -> int:
+    with socket.socket() as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+def test_disabled_by_default(monkeypatch) -> None:
+    monkeypatch.delenv("DEBUGPY", raising=False)
+    monkeypatch.delenv("DEBUGPY_PORT", raising=False)
+    sys.modules.pop("debugpy", None)
+    assert dbg.configure_debugging() is False
+    assert "debugpy" not in sys.modules  # zero overhead: never imported
+
+
+def test_explicit_zero(monkeypatch) -> None:
+    monkeypatch.setenv("DEBUGPY", "0")
+    sys.modules.pop("debugpy", None)
+    assert dbg.configure_debugging() is False
+    assert "debugpy" not in sys.modules
+
+
+def test_invalid_value_treated_as_disabled(monkeypatch) -> None:
+    monkeypatch.setenv("DEBUGPY", "yes-please")
+    assert dbg.configure_debugging() is False
+
+
+def test_enabled_starts_listener(monkeypatch, free_port) -> None:
+    monkeypatch.setenv("DEBUGPY", "1")
+    monkeypatch.setenv("DEBUGPY_PORT", str(free_port))
+    try:
+        assert dbg.configure_debugging() is True
+        assert "debugpy" in sys.modules
+    finally:
+        dbg.shutdown_debugpy()
+
+
+def test_port_falls_back_on_invalid_value(monkeypatch) -> None:
+    monkeypatch.setenv("DEBUGPY_PORT", "not-a-port")
+    assert dbg._port() == 5678
+
+
+def test_shutdown_is_idempotent_when_disabled() -> None:
+    dbg.shutdown_debugpy()  # no listener → no-op, no error

tests/unit/test_main.py

@@ -0,0 +1,21 @@
+"""Unit tests: app factory edge cases (no live DB needed)."""
+from __future__ import annotations
+
+from fastapi.testclient import TestClient
+
+import app.main as main_mod
+
+
+def test_create_app_warns_and_serves_api_only_without_static_dir(
+    monkeypatch, tmp_path
+) -> None:
+    """If the frontend directory is missing, the API still boots (PLAN §7)."""
+    monkeypatch.setattr(
+        main_mod.settings, "static_dir", str(tmp_path / "definitely-missing")
+    )
+    app2 = main_mod.create_app()
+    client = TestClient(app2)
+    # /api still works…
+    assert client.get("/api/health").status_code == 200
+    # …but the static mount is absent (no index page).
+    assert client.get("/").status_code == 404

tests/unit/test_models.py

@@ -0,0 +1,46 @@
+"""Unit tests: SQLAlchemy models register the pgvector schema on the metadata.
+
+Importing :mod:`app.models` is what Alembic's ``env.py`` and the runtime rely
+on; these tests lock the table/column contract (PLAN §5) without a live DB.
+"""
+from __future__ import annotations
+
+from pgvector.sqlalchemy import Vector
+from sqlalchemy import UniqueConstraint
+
+import app.models  # noqa: F401  (import registers all tables on Base.metadata)
+from app.db import Base
+
+
+def test_all_tables_registered() -> None:
+    tables = Base.metadata.tables
+    assert "documents" in tables
+    assert "chunks" in tables
+    assert "query_log" in tables
+
+
+def test_chunks_embedding_is_vector_768() -> None:
+    chunks = Base.metadata.tables["chunks"]
+    col = chunks.c["embedding"]
+    assert isinstance(col.type, Vector)
+    assert col.type.dim == 768
+    # Embeddings are two-phase: inserted first, embedded later.
+    assert col.nullable is True
+
+
+def test_chunks_reference_documents_cascade() -> None:
+    chunks = Base.metadata.tables["chunks"]
+    fkc = list(chunks.foreign_key_constraints)[0]
+    assert fkc.elements[0].column.table.name == "documents"
+    assert fkc.ondelete == "CASCADE"
+
+
+def test_documents_unique_source_path() -> None:
+    documents = Base.metadata.tables["documents"]
+    uq = [
+        c
+        for c in documents.constraints
+        if isinstance(c, UniqueConstraint)
+        and {col.name for col in c.columns} == {"source", "path"}
+    ]
+    assert uq, "documents must be unique on (source, path) — the upsert key"