Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

test(api): add contract tests for upload guards, quiz judge, reading progress, notebook and memory routers (#1709)

evan188199-tech0a2c31673732
diff --git a/tests/api/routers/test_quiz_judge_unit.py b/tests/api/routers/test_quiz_judge_unit.py
new file mode 100644
index 000000000..7517003fb
--- /dev/null
+++ b/tests/api/routers/test_quiz_judge_unit.py
@@ -0,0 +1,897 @@
+"""Unit tests for the quiz-judge WebSocket router.
+
+``deeptutor/api/routers/quiz_judge.py`` previously had little line coverage:
+judge prompt assembly, image mime handling, and the WS
+judging loop (including disconnect cleanup) were essentially untested.
+
+The LLM is mocked at ``quiz_judge.llm_stream`` — no real provider call is
+ever made. The socket is exercised two ways:
+
+* through Starlette's ``TestClient`` for the protocol frames a real client
+ sees (started / text / done / error), and
+* through a fake WebSocket for deterministic ordering of the disconnect
+ and cleanup paths (``TestClient`` cannot control exactly when the send
+ side breaks mid-stream).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+from types import SimpleNamespace
+from unittest.mock import MagicMock
+
+from fastapi import FastAPI, WebSocketDisconnect
+from fastapi.testclient import TestClient
+import pytest
+
+from deeptutor.api.routers import auth, quiz_judge
+from deeptutor.api.routers.quiz_judge import (
+ _JUDGE_SYSTEM_PROMPTS,
+ SUPPORTED_JUDGE_LANGUAGES,
+ _build_judge_user_prompt,
+ _build_multimodal_user_content,
+ _guess_image_mime,
+)
+
+_WS_TOKEN = object()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _judge_payload(**overrides) -> dict:
+ payload = {
+ "question": "What is 2+2?",
+ "question_type": "short_answer",
+ "options": None,
+ "correct_answer": "4",
+ "explanation": "2+2 equals 4.",
+ "user_answer": "4",
+ "language": "en",
+ }
+ payload.update(overrides)
+ return payload
+
+
+class _ScriptedStream:
+ """Drop-in replacement for ``quiz_judge.llm_stream``.
+
+ Records every call and replays scripted chunks. ``endless=True`` keeps
+ yielding (with a consumed counter) so a disconnect test can prove the
+ handler stopped pulling from the stream. ``exc`` is raised after the
+ chunks are exhausted.
+ """
+
+ def __init__(self, chunks=(), *, exc: Exception | None = None, endless: bool = False):
+ self.chunks = list(chunks)
+ self.exc = exc
+ self.endless = endless
+ self.calls: list[dict] = []
+ self.consumed = 0
+
+ async def __call__(self, *, prompt: str, system_prompt: str, **kwargs):
+ self.calls.append({"prompt": prompt, "system_prompt": system_prompt, **kwargs})
+ if self.endless:
+ while True:
+ self.consumed += 1
+ yield "chunk"
+ for chunk in self.chunks:
+ self.consumed += 1
+ yield chunk
+ if self.exc is not None:
+ raise self.exc
+
+
+class _FakeJudgeSocket:
+ """Minimal WebSocket stand-in with scriptable failure points."""
+
+ def __init__(self, payload: dict | None, *, ok_sends: int = 10, close_raises: bool = False):
+ self._payload = payload
+ self._ok_sends = ok_sends
+ self._close_raises = close_raises
+ self.sent: list[dict] = []
+ self.accepted = False
+ self.closed = False
+
+ async def accept(self) -> None:
+ self.accepted = True
+
+ async def receive_json(self) -> dict:
+ if self._payload is None:
+ raise WebSocketDisconnect(code=1000)
+ return self._payload
+
+ async def send_json(self, payload: dict) -> None:
+ if len(self.sent) >= self._ok_sends:
+ raise WebSocketDisconnect(code=1001)
+ self.sent.append(payload)
+
+ async def close(self) -> None:
+ if self._close_raises:
+ raise RuntimeError("socket already closed")
+ self.closed = True
+
+
+class _InvalidJsonSocket(_FakeJudgeSocket):
+ """receive_json fails the way a malformed text frame does."""
+
+ async def receive_json(self) -> dict:
+ raise ValueError("Expecting value")
+
+
+def _raising_reset(monkeypatch) -> MagicMock:
+ from deeptutor.multi_user import context
+
+ spy = MagicMock(side_effect=RuntimeError("reset boom"))
+ monkeypatch.setattr(context, "reset_current_user", spy)
+ return spy
+
+
+def reset_spy(monkeypatch) -> MagicMock:
+ """Spy on the user-context cleanup the handler must run on exit."""
+ from deeptutor.multi_user import context
+
+ spy = MagicMock()
+ monkeypatch.setattr(context, "reset_current_user", spy)
+ return spy
+
+
+def ws_token(monkeypatch):
+ """Bypass WS auth with a non-None token so cleanup paths activate."""
+
+ async def allow(_websocket):
+ return _WS_TOKEN
+
+ monkeypatch.setattr(auth, "ws_require_auth", allow)
+ return _WS_TOKEN
+
+
+def fake_attachment_store(monkeypatch) -> MagicMock:
+ from deeptutor.services import storage
+
+ store = MagicMock()
+ store.resolve_path = MagicMock(return_value=None)
+ monkeypatch.setattr(storage, "get_attachment_store", lambda: store)
+ return store
+
+
+def llm_vision(monkeypatch):
+ """Pin the LLM binding/model and vision capability deterministically."""
+ from deeptutor.services.llm import capabilities
+ from deeptutor.services.llm import config as llm_config_mod
+
+ def _install(supports: bool) -> None:
+ monkeypatch.setattr(
+ llm_config_mod,
+ "get_llm_config",
+ lambda: SimpleNamespace(binding="openai", model="gpt-4o-mini"),
+ )
+ monkeypatch.setattr(capabilities, "supports_vision", lambda binding, model=None: supports)
+
+ return _install
+
+
+def _judge_client(monkeypatch, stream: _ScriptedStream) -> TestClient:
+ monkeypatch.setattr(quiz_judge, "llm_stream", stream)
+ app = FastAPI()
+ app.include_router(quiz_judge.router, prefix="/ws")
+ return TestClient(app)
+
+
+# ---------------------------------------------------------------------------
+# Prompt assembly (pure functions)
+# ---------------------------------------------------------------------------
+
+
+class TestGuessImageMime:
+ @pytest.mark.parametrize(
+ "filename,expected",
+ [
+ (None, "image/png"),
+ ("", "image/png"),
+ ("photo.png", "image/png"),
+ ("photo.PNG", "image/png"),
+ ("photo.jpg", "image/jpeg"),
+ ("photo.JPEG", "image/jpeg"),
+ ("anim.gif", "image/gif"),
+ ("pic.webp", "image/webp"),
+ ("noext", "image/png"),
+ ("weird.tiff", "image/png"),
+ ("a.b.jpg", "image/jpeg"),
+ ],
+ )
+ def test_common_filenames(self, filename, expected):
+ assert _guess_image_mime(filename) == expected
+
+
+class TestBuildJudgeUserPrompt:
+ def test_zh_prompt_carries_question_options_answer_explanation_and_image_note(self):
+ prompt = _build_judge_user_prompt(
+ language="zh",
+ question="地球绕太阳一圈需要多久?",
+ question_type="single_choice",
+ options={"A": "一天", "B": "一年", "C": "一个月"},
+ correct_answer="B",
+ explanation="地球公转周期约365天。",
+ user_answer="B",
+ has_image=True,
+ image_count=1,
+ )
+ assert "题目类型:single_choice" in prompt
+ assert "题干:\n地球绕太阳一圈需要多久?" in prompt
+ assert "选项:" in prompt
+ assert " A. 一天" in prompt
+ assert " B. 一年" in prompt
+ assert "参考答案:\nB" in prompt
+ assert "参考解析:\n地球公转周期约365天。" in prompt
+ assert "学习者作答:\nB" in prompt
+ assert "一张图片" in prompt
+ assert prompt.endswith("请针对该学习者的具体作答给出 AI 评判。")
+
+ def test_zh_prompt_reports_multi_image_count(self):
+ prompt = _build_judge_user_prompt(
+ language="zh",
+ question="证明勾股定理",
+ question_type="proof",
+ options=None,
+ correct_answer="见参考",
+ explanation="多种证法均可",
+ user_answer="如图所示",
+ has_image=True,
+ image_count=3,
+ )
+ assert "另附了 3 张图片" in prompt
+
+ def test_zh_prompt_without_optional_fields_omits_them(self):
+ prompt = _build_judge_user_prompt(
+ language="zh",
+ question="1+1=?",
+ question_type="",
+ options=None,
+ correct_answer="",
+ explanation="",
+ user_answer="2",
+ has_image=False,
+ image_count=0,
+ )
+ assert "题目类型:unknown" in prompt
+ assert "选项" not in prompt
+ assert "参考答案" not in prompt
+ assert "参考解析" not in prompt
+ assert "图片" not in prompt
+
+ def test_image_only_answer_gets_zh_placeholder(self):
+ prompt = _build_judge_user_prompt(
+ language="zh",
+ question="画出示意图",
+ question_type="drawing",
+ options=None,
+ correct_answer="任意合理示意",
+ explanation="",
+ user_answer=" ",
+ has_image=True,
+ image_count=1,
+ )
+ assert "(仅提交了图片,无文字作答)" in prompt
+
+ def test_en_prompt_carries_question_answer_and_unknown_type(self):
+ prompt = _build_judge_user_prompt(
+ language="en",
+ question="What is 2+2?",
+ question_type="",
+ options=None,
+ correct_answer="4",
+ explanation="2+2 equals 4.",
+ user_answer="4",
+ has_image=False,
+ image_count=0,
+ )
+ assert "Question type: unknown" in prompt
+ assert "Question:\nWhat is 2+2?" in prompt
+ assert "Reference answer:\n4" in prompt
+ assert "Reference explanation:\n2+2 equals 4." in prompt
+ assert "Learner's answer:\n4" in prompt
+ assert "attached" not in prompt
+
+ def test_en_prompt_renders_options_and_multi_image_note(self):
+ prompt = _build_judge_user_prompt(
+ language="en",
+ question="Pick the primes",
+ question_type="multi_choice",
+ options={"A": "2", "B": "4", "C": "5"},
+ correct_answer="A and C",
+ explanation="2 and 5 are prime.",
+ user_answer="A",
+ has_image=True,
+ image_count=2,
+ )
+ assert "Options:" in prompt
+ assert " A. 2" in prompt
+ assert " B. 4" in prompt
+ assert "The learner attached 2 images" in prompt
+
+ def test_image_only_answer_gets_en_placeholder(self):
+ prompt = _build_judge_user_prompt(
+ language="en",
+ question="Sketch the graph",
+ question_type="drawing",
+ options=None,
+ correct_answer="any correct sketch",
+ explanation="",
+ user_answer="",
+ has_image=True,
+ image_count=1,
+ )
+ assert "(only an image was submitted, no typed answer)" in prompt
+ assert "attached an image as part of the answer" in prompt
+
+ def test_unrenderable_options_are_dropped_not_fatal(self):
+ class _BadOptions(dict):
+ def items(self):
+ raise TypeError("unrenderable")
+
+ prompt = _build_judge_user_prompt(
+ language="en",
+ question="Q",
+ question_type="t",
+ options=_BadOptions(A="a"),
+ correct_answer="a",
+ explanation="",
+ user_answer="a",
+ has_image=False,
+ image_count=0,
+ )
+ assert "Options:" not in prompt
+ assert "Question:\nQ" in prompt
+
+
+# ---------------------------------------------------------------------------
+# Multimodal content builder
+# ---------------------------------------------------------------------------
+
+
+class TestBuildMultimodalUserContent:
+ def test_text_part_comes_first_and_base64_becomes_data_url(self, fake_attachment_store):
+ content = asyncio.run(
+ _build_multimodal_user_content(
+ text="judge this",
+ image_records=[
+ {"base64": "QUJD", "url": "", "filename": "a.jpg", "mime_type": "image/jpeg"},
+ ],
+ )
+ )
+ assert content[0] == {"type": "text", "text": "judge this"}
+ assert content[1] == {
+ "type": "image_url",
+ "image_url": {"url": "data:image/jpeg;base64,QUJD"},
+ }
+
+ def test_url_only_record_is_passed_through(self, fake_attachment_store):
+ content = asyncio.run(
+ _build_multimodal_user_content(
+ text="t",
+ image_records=[
+ {"base64": "", "url": "https://cdn.example.com/x.png", "filename": "x.png"},
+ ],
+ )
+ )
+ # mime missing → guessed from filename; url cannot be resolved → passed through
+ assert content[1] == {
+ "type": "image_url",
+ "image_url": {"url": "https://cdn.example.com/x.png"},
+ }
+
+ def test_local_attachment_url_is_resolved_to_base64(self, fake_attachment_store, tmp_path):
+ blob = tmp_path / "photo.jpg"
+ blob.write_bytes(b"\xff\xd8jpeg-bytes")
+ fake_attachment_store.resolve_path.return_value = blob
+
+ content = asyncio.run(
+ _build_multimodal_user_content(
+ text="t",
+ image_records=[
+ {
+ "base64": "",
+ "url": "/api/attachments/s%201/att%202/photo.jpg",
+ "filename": "photo.jpg",
+ },
+ ],
+ )
+ )
+ fake_attachment_store.resolve_path.assert_called_once_with(
+ session_id="s 1", attachment_id="att 2", filename="photo.jpg"
+ )
+ expected_b64 = base64.b64encode(b"\xff\xd8jpeg-bytes").decode("ascii")
+ assert content[1]["image_url"]["url"] == f"data:image/jpeg;base64,{expected_b64}"
+
+ def test_unresolvable_attachment_url_falls_back_to_url(self, fake_attachment_store):
+ content = asyncio.run(
+ _build_multimodal_user_content(
+ text="t",
+ image_records=[
+ {
+ "base64": "",
+ "url": "/api/attachments/s/a/missing.png",
+ "filename": "missing.png",
+ },
+ ],
+ )
+ )
+ assert content[1] == {
+ "type": "image_url",
+ "image_url": {"url": "/api/attachments/s/a/missing.png"},
+ }
+
+ def test_resolution_failure_is_swallowed_and_url_kept(self, fake_attachment_store):
+ fake_attachment_store.resolve_path.side_effect = OSError("disk on fire")
+ content = asyncio.run(
+ _build_multimodal_user_content(
+ text="t",
+ image_records=[
+ {"base64": "", "url": "/api/attachments/s/a/x.png", "filename": "x.png"},
+ ],
+ )
+ )
+ assert content[1] == {
+ "type": "image_url",
+ "image_url": {"url": "/api/attachments/s/a/x.png"},
+ }
+
+ def test_record_without_payload_is_skipped(self, fake_attachment_store):
+ content = asyncio.run(
+ _build_multimodal_user_content(
+ text="t",
+ image_records=[{"base64": "", "url": "", "filename": "empty.png"}],
+ )
+ )
+ assert content == [{"type": "text", "text": "t"}]
+
+
+# ---------------------------------------------------------------------------
+# WebSocket protocol (TestClient)
+# ---------------------------------------------------------------------------
+
+
+class TestJudgeVerdicts:
+ """The three judgment outcomes a learner can receive, end to end."""
+
+ @pytest.mark.parametrize(
+ "scenario,answer,verdict_chunks",
+ [
+ (
+ "correct",
+ "4",
+ ["✅ Correct — 4 is right.", " 2+2 equals 4, well done."],
+ ),
+ (
+ "wrong",
+ "5",
+ ["❌ Incorrect — 5 is not 2+2.", " The sum is 4."],
+ ),
+ (
+ "multi_answer",
+ "A",
+ ["⚠️ Partially correct — A is prime but C also is.", " Both A and C were valid."],
+ ),
+ ],
+ )
+ def test_verdict_chunks_are_streamed_then_done(
+ self, ws_token, reset_spy, monkeypatch, scenario, answer, verdict_chunks
+ ):
+ stream = _ScriptedStream(verdict_chunks)
+ client = _judge_client(monkeypatch, stream)
+ payload = _judge_payload(user_answer=answer)
+ if scenario == "multi_answer":
+ payload.update(
+ question="Pick the primes",
+ question_type="multi_choice",
+ options={"A": "2", "B": "4", "C": "5"},
+ correct_answer="A and C",
+ explanation="2 and 5 are prime.",
+ )
+
+ with client.websocket_connect("/ws/questions/judge") as ws:
+ ws.send_json(payload)
+ assert ws.receive_json() == {"type": "started"}
+ assert ws.receive_json() == {"type": "text", "content": verdict_chunks[0]}
+ assert ws.receive_json() == {"type": "text", "content": verdict_chunks[1]}
+ assert ws.receive_json() == {"type": "done"}
+
+ assert len(stream.calls) == 1
+ call = stream.calls[0]
+ assert call["system_prompt"] == _JUDGE_SYSTEM_PROMPTS["en"]
+ assert call["prompt"].startswith("Question type:")
+ assert "Learner's answer:\n" + answer in call["prompt"]
+ if scenario == "multi_answer":
+ assert "Options:" in call["prompt"]
+ assert "Reference answer:\nA and C" in call["prompt"]
+ reset_spy.assert_called_once_with(ws_token)
+
+ def test_empty_llm_chunks_are_not_relayed(self, ws_token, reset_spy, monkeypatch):
+ stream = _ScriptedStream(["", "real text", ""])
+ client = _judge_client(monkeypatch, stream)
+ with client.websocket_connect("/ws/questions/judge") as ws:
+ ws.send_json(_judge_payload())
+ assert ws.receive_json() == {"type": "started"}
+ assert ws.receive_json() == {"type": "text", "content": "real text"}
+ assert ws.receive_json() == {"type": "done"}
+
+
+class TestJudgeRequestValidation:
+ def test_missing_question_is_rejected_without_llm_call(self, ws_token, reset_spy, monkeypatch):
+ stream = _ScriptedStream(["never called"])
+ client = _judge_client(monkeypatch, stream)
+ with client.websocket_connect("/ws/questions/judge") as ws:
+ ws.send_json(_judge_payload(question=" "))
+ frame = ws.receive_json()
+ assert frame == {"type": "error", "content": "Question is required"}
+ assert stream.calls == []
+ reset_spy.assert_called_once_with(ws_token)
+
+ def test_invalid_json_request_is_reported(self, ws_token, reset_spy, monkeypatch):
+ stream = _ScriptedStream(["never called"])
+ client = _judge_client(monkeypatch, stream)
+ with client.websocket_connect("/ws/questions/judge") as ws:
+ ws.send_text("{not json")
+ frame = ws.receive_json()
+ assert frame["type"] == "error"
+ assert frame["content"].startswith("Invalid request:")
+ assert stream.calls == []
+ reset_spy.assert_called_once_with(ws_token)
+
+ def test_answerless_submission_is_rejected(self, ws_token, reset_spy, monkeypatch):
+ stream = _ScriptedStream(["never called"])
+ client = _judge_client(monkeypatch, stream)
+ with client.websocket_connect("/ws/questions/judge") as ws:
+ ws.send_json(_judge_payload(user_answer=" "))
+ frame = ws.receive_json()
+ assert frame == {
+ "type": "error",
+ "content": "No answer to judge — submit a typed answer or attach an image.",
+ }
+ assert stream.calls == []
+ reset_spy.assert_called_once_with(ws_token)
+
+
+class TestJudgeLanguage:
+ def test_supported_language_is_used_directly(self, ws_token, reset_spy, monkeypatch):
+ def _unexpected(*_args, **_kwargs):
+ raise AssertionError(
+ "get_response_language must not be consulted for supported languages"
+ )
+
+ monkeypatch.setattr(quiz_judge, "get_response_language", _unexpected)
+ stream = _ScriptedStream(["добре"])
+ client = _judge_client(monkeypatch, stream)
+ with client.websocket_connect("/ws/questions/judge") as ws:
+ ws.send_json(_judge_payload(language="uk"))
+ assert ws.receive_json() == {"type": "started"}
+ assert ws.receive_json() == {"type": "text", "content": "добре"}
+ assert ws.receive_json() == {"type": "done"}
+ assert stream.calls[0]["system_prompt"] == _JUDGE_SYSTEM_PROMPTS["uk"]
+
+ def test_unsupported_language_falls_back_to_interface_language(
+ self, ws_token, reset_spy, monkeypatch
+ ):
+ monkeypatch.setattr(quiz_judge, "get_response_language", lambda *, default: "de")
+ stream = _ScriptedStream(["gut"])
+ client = _judge_client(monkeypatch, stream)
+ with client.websocket_connect("/ws/questions/judge") as ws:
+ ws.send_json(_judge_payload(language="klingon"))
+ assert ws.receive_json() == {"type": "started"}
+ assert ws.receive_json() == {"type": "text", "content": "gut"}
+ assert ws.receive_json() == {"type": "done"}
+ assert stream.calls[0]["system_prompt"] == _JUDGE_SYSTEM_PROMPTS["de"]
+
+ def test_unsupported_interface_language_falls_back_to_english(
+ self, ws_token, reset_spy, monkeypatch
+ ):
+ monkeypatch.setattr(quiz_judge, "get_response_language", lambda *, default: "klingon")
+ stream = _ScriptedStream(["ok"])
+ client = _judge_client(monkeypatch, stream)
+ with client.websocket_connect("/ws/questions/judge") as ws:
+ ws.send_json(_judge_payload(language=""))
+ assert ws.receive_json() == {"type": "started"}
+ assert ws.receive_json() == {"type": "text", "content": "ok"}
+ assert ws.receive_json() == {"type": "done"}
+ assert stream.calls[0]["system_prompt"] == _JUDGE_SYSTEM_PROMPTS["en"]
+
+ def test_supported_languages_mirror_available_prompts(self):
+ assert SUPPORTED_JUDGE_LANGUAGES == frozenset(_JUDGE_SYSTEM_PROMPTS)
+ assert {"zh", "en", "de", "uk"} <= SUPPORTED_JUDGE_LANGUAGES
+
+
+class TestJudgeImages:
+ def test_vision_model_receives_multimodal_messages_with_image_mimes(
+ self, ws_token, reset_spy, monkeypatch, fake_attachment_store, llm_vision
+ ):
+ llm_vision(supports=True)
+ stream = _ScriptedStream(["looking at your sketch"])
+ client = _judge_client(monkeypatch, stream)
+ payload = _judge_payload(
+ user_answer="",
+ user_answer_images=[
+ {"base64": "data:image/jpeg;base64,QUJD", "filename": "work.jpg"},
+ {
+ "url": "https://cdn.example.com/sketch.webp",
+ "filename": "sketch.webp",
+ "mime_type": "image/webp",
+ },
+ "not-a-dict", # junk entries are skipped
+ {"filename": "no-payload.png"}, # neither base64 nor url → skipped
+ ],
+ )
+
+ with client.websocket_connect("/ws/questions/judge") as ws:
+ ws.send_json(payload)
+ assert ws.receive_json() == {"type": "started"}
+ assert ws.receive_json() == {"type": "text", "content": "looking at your sketch"}
+ assert ws.receive_json() == {"type": "done"}
+
+ call = stream.calls[0]
+ messages = call["messages"]
+ assert messages[0] == {"role": "system", "content": _JUDGE_SYSTEM_PROMPTS["en"]}
+ user_content = messages[1]["content"]
+ assert user_content[0]["type"] == "text"
+ assert "(only an image was submitted, no typed answer)" in user_content[0]["text"]
+ # data: prefix stripped, mime preserved from the record / guessed from filename
+ assert user_content[1] == {
+ "type": "image_url",
+ "image_url": {"url": "data:image/jpeg;base64,QUJD"},
+ }
+ assert user_content[2] == {
+ "type": "image_url",
+ "image_url": {"url": "https://cdn.example.com/sketch.webp"},
+ }
+ assert len(user_content) == 3
+ assert "The learner attached 2 images" in call["prompt"]
+ reset_spy.assert_called_once_with(ws_token)
+
+ def test_non_vision_model_judges_the_typed_answer_text_only(
+ self, ws_token, reset_spy, monkeypatch, fake_attachment_store, llm_vision
+ ):
+ llm_vision(supports=False)
+ stream = _ScriptedStream(["text-only feedback"])
+ client = _judge_client(monkeypatch, stream)
+ payload = _judge_payload(
+ user_answer="my written reasoning",
+ user_answer_images=[
+ {"base64": "QUJD", "filename": "work.jpg", "mime_type": "image/jpeg"}
+ ],
+ )
+
+ with client.websocket_connect("/ws/questions/judge") as ws:
+ ws.send_json(payload)
+ assert ws.receive_json() == {"type": "started"}
+ assert ws.receive_json() == {"type": "text", "content": "text-only feedback"}
+ assert ws.receive_json() == {"type": "done"}
+
+ call = stream.calls[0]
+ assert "messages" not in call
+ assert "my written reasoning" in call["prompt"]
+ assert "attached an image" in call["prompt"]
+ reset_spy.assert_called_once_with(ws_token)
+
+ def test_legacy_single_image_form_is_normalized(
+ self, ws_token, reset_spy, monkeypatch, fake_attachment_store, llm_vision
+ ):
+ llm_vision(supports=True)
+ stream = _ScriptedStream(["ok"])
+ client = _judge_client(monkeypatch, stream)
+ payload = _judge_payload(
+ user_answer_image="data:image/png;base64,QUJD", image_filename="scan.png"
+ )
+
+ with client.websocket_connect("/ws/questions/judge") as ws:
+ ws.send_json(payload)
+ assert ws.receive_json() == {"type": "started"}
+ assert ws.receive_json() == {"type": "text", "content": "ok"}
+ assert ws.receive_json() == {"type": "done"}
+
+ user_content = stream.calls[0]["messages"][1]["content"]
+ assert user_content[1] == {
+ "type": "image_url",
+ "image_url": {"url": "data:image/png;base64,QUJD"},
+ }
+ assert "attached an image" in stream.calls[0]["prompt"]
+
+ def test_malformed_data_url_entries_are_dropped(
+ self, ws_token, reset_spy, monkeypatch, fake_attachment_store, llm_vision
+ ):
+ llm_vision(supports=True)
+ stream = _ScriptedStream(["ok"])
+ client = _judge_client(monkeypatch, stream)
+ # "data:" with no comma — the payload split fails, the entry is dropped
+ payload = _judge_payload(
+ user_answer="typed answer",
+ user_answer_images=[{"base64": "data:image/png;base64-no-comma", "filename": "x.png"}],
+ )
+
+ with client.websocket_connect("/ws/questions/judge") as ws:
+ ws.send_json(payload)
+ assert ws.receive_json() == {"type": "started"}
+ assert ws.receive_json() == {"type": "text", "content": "ok"}
+ assert ws.receive_json() == {"type": "done"}
+
+ assert "messages" not in stream.calls[0]
+ assert "attached an image" not in stream.calls[0]["prompt"]
+
+ def test_legacy_data_url_without_payload_part_is_dropped(
+ self, ws_token, reset_spy, monkeypatch
+ ):
+ stream = _ScriptedStream(["fine"])
+ client = _judge_client(monkeypatch, stream)
+ payload = _judge_payload(
+ user_answer="written answer",
+ user_answer_image="data:image/png;base64,", # empty payload after the comma
+ )
+ with client.websocket_connect("/ws/questions/judge") as ws:
+ ws.send_json(payload)
+ assert ws.receive_json() == {"type": "started"}
+ assert ws.receive_json() == {"type": "text", "content": "fine"}
+ assert ws.receive_json() == {"type": "done"}
+ # "data:...," splits to an empty payload — falsy, treated as no image
+ assert "messages" not in stream.calls[0]
+ assert "attached an image" not in stream.calls[0]["prompt"]
+
+ def test_legacy_malformed_data_url_is_dropped(self, ws_token, reset_spy, monkeypatch):
+ stream = _ScriptedStream(["fine"])
+ client = _judge_client(monkeypatch, stream)
+ payload = _judge_payload(
+ user_answer="written answer",
+ user_answer_image="data:image/png;base64-no-comma", # split fails → dropped
+ )
+ with client.websocket_connect("/ws/questions/judge") as ws:
+ ws.send_json(payload)
+ assert ws.receive_json() == {"type": "started"}
+ assert ws.receive_json() == {"type": "text", "content": "fine"}
+ assert ws.receive_json() == {"type": "done"}
+ assert "messages" not in stream.calls[0]
+ assert "attached an image" not in stream.calls[0]["prompt"]
+
+
+# ---------------------------------------------------------------------------
+# Failure & cleanup paths (fake WebSocket — deterministic ordering)
+# ---------------------------------------------------------------------------
+
+
+class TestJudgeDisconnectAndCleanup:
+ def test_client_disconnect_mid_stream_stops_pulling_and_cleans_up(
+ self, ws_token, reset_spy, monkeypatch
+ ):
+ stream = _ScriptedStream(endless=True)
+ monkeypatch.setattr(quiz_judge, "llm_stream", stream)
+ socket = _FakeJudgeSocket(_judge_payload(), ok_sends=3)
+
+ asyncio.run(quiz_judge.websocket_quiz_judge(socket))
+
+ # started + 2 text frames delivered; the 3rd chunk's send fails → break
+ assert [frame["type"] for frame in socket.sent] == ["started", "text", "text"]
+ assert stream.consumed == 3
+ assert socket.accepted is True
+ assert socket.closed is True
+ reset_spy.assert_called_once_with(ws_token)
+
+ def test_stream_timeout_is_reported_as_error_and_socket_closed(
+ self, ws_token, reset_spy, monkeypatch
+ ):
+ stream = _ScriptedStream(["partial"], exc=TimeoutError())
+ monkeypatch.setattr(quiz_judge, "llm_stream", stream)
+ socket = _FakeJudgeSocket(_judge_payload())
+
+ asyncio.run(quiz_judge.websocket_quiz_judge(socket))
+
+ assert socket.sent[-1] == {
+ "type": "error",
+ "content": "AI judge timed out. Please try again.",
+ }
+ assert socket.sent[0] == {"type": "started"}
+ assert socket.closed is True
+ reset_spy.assert_called_once_with(ws_token)
+
+ def test_stream_failure_is_reported_as_error_frame(self, ws_token, reset_spy, monkeypatch):
+ stream = _ScriptedStream([], exc=RuntimeError("judge backend exploded"))
+ monkeypatch.setattr(quiz_judge, "llm_stream", stream)
+ socket = _FakeJudgeSocket(_judge_payload())
+
+ asyncio.run(quiz_judge.websocket_quiz_judge(socket))
+
+ assert socket.sent[0] == {"type": "started"}
+ assert socket.sent[-1] == {"type": "error", "content": "judge backend exploded"}
+ assert socket.closed is True
+ reset_spy.assert_called_once_with(ws_token)
+
+ def test_stream_disconnect_error_ends_the_judge_quietly(self, ws_token, reset_spy, monkeypatch):
+ stream = _ScriptedStream(["partial"], exc=WebSocketDisconnect(code=1001))
+ monkeypatch.setattr(quiz_judge, "llm_stream", stream)
+ socket = _FakeJudgeSocket(_judge_payload())
+
+ asyncio.run(quiz_judge.websocket_quiz_judge(socket))
+
+ # the mid-stream disconnect is not an error for the learner — just ends
+ assert socket.sent == [
+ {"type": "started"},
+ {"type": "text", "content": "partial"},
+ ]
+ assert socket.closed is True
+ reset_spy.assert_called_once_with(ws_token)
+
+ def test_cleanup_failures_during_happy_path_are_swallowed(self, ws_token, monkeypatch):
+ raising_reset = _raising_reset(monkeypatch)
+ stream = _ScriptedStream(["fine"])
+ monkeypatch.setattr(quiz_judge, "llm_stream", stream)
+ socket = _FakeJudgeSocket(_judge_payload(), close_raises=True)
+
+ asyncio.run(quiz_judge.websocket_quiz_judge(socket))
+
+ assert socket.sent[-1] == {"type": "done"}
+ raising_reset.assert_called_once_with(ws_token)
+
+ def test_missing_question_cleanup_failures_are_swallowed(self, ws_token, monkeypatch):
+ raising_reset = _raising_reset(monkeypatch)
+ stream = _ScriptedStream(["never called"])
+ monkeypatch.setattr(quiz_judge, "llm_stream", stream)
+ socket = _FakeJudgeSocket(_judge_payload(question=" "), close_raises=True)
+
+ asyncio.run(quiz_judge.websocket_quiz_judge(socket))
+
+ assert socket.sent == [{"type": "error", "content": "Question is required"}]
+ raising_reset.assert_called_once_with(ws_token)
+
+ def test_invalid_json_cleanup_failures_are_swallowed(self, ws_token, monkeypatch):
+ raising_reset = _raising_reset(monkeypatch)
+ stream = _ScriptedStream(["never called"])
+ monkeypatch.setattr(quiz_judge, "llm_stream", stream)
+ socket = _InvalidJsonSocket(None, close_raises=True)
+
+ asyncio.run(quiz_judge.websocket_quiz_judge(socket))
+
+ assert len(socket.sent) == 1
+ assert socket.sent[0]["type"] == "error"
+ assert socket.sent[0]["content"].startswith("Invalid request:")
+ raising_reset.assert_called_once_with(ws_token)
+
+ def test_answerless_cleanup_failures_are_swallowed(self, ws_token, monkeypatch):
+ raising_reset = _raising_reset(monkeypatch)
+ stream = _ScriptedStream(["never called"])
+ monkeypatch.setattr(quiz_judge, "llm_stream", stream)
+ socket = _FakeJudgeSocket(_judge_payload(user_answer=" "), close_raises=True)
+
+ asyncio.run(quiz_judge.websocket_quiz_judge(socket))
+
+ assert socket.sent[0]["type"] == "error"
+ assert socket.sent[0]["content"].startswith("No answer to judge")
+ raising_reset.assert_called_once_with(ws_token)
+
+ def test_failed_ws_auth_returns_without_accepting(self, monkeypatch, reset_spy):
+ async def deny(_websocket):
+ return auth.ws_auth_failed
+
+ monkeypatch.setattr(auth, "ws_require_auth", deny)
+ socket = _FakeJudgeSocket(_judge_payload())
+
+ asyncio.run(quiz_judge.websocket_quiz_judge(socket))
+
+ assert socket.accepted is False
+ assert socket.sent == []
+ assert socket.closed is False
+ reset_spy.assert_not_called()
+
+ def test_disconnect_before_request_returns_without_llm_call(
+ self, ws_token, monkeypatch, reset_spy
+ ):
+ stream = _ScriptedStream(["never called"])
+ monkeypatch.setattr(quiz_judge, "llm_stream", stream)
+ socket = _FakeJudgeSocket(None) # receive_json raises WebSocketDisconnect
+
+ asyncio.run(quiz_judge.websocket_quiz_judge(socket))
+
+ assert socket.sent == []
+ assert stream.calls == []
diff --git a/tests/api/routers/test_reading_progress.py b/tests/api/routers/test_reading_progress.py
new file mode 100644
index 000000000..e2580337c
--- /dev/null
+++ b/tests/api/routers/test_reading_progress.py
@@ -0,0 +1,241 @@
+"""Contract tests for the Immersive Reading progress API.
+
+These pin the durability contract of the position and bookmark endpoints —
+the two routes a reader trusts to survive a reload. A lost or corrupted
+progress write is invisible until a user opens the book on another device,
+so the suite drives a real :class:`~deeptutor.reading.store.ReadingStore`
+through the real ASGI routes and asserts on persisted state, not just on
+response bodies:
+
+1. save → retrieve round-trip returns exactly what was saved;
+2. saving the same position or bookmark twice converges (idempotent);
+3. malformed payloads are rejected with 4xx and persist nothing;
+4. a failed save (out-of-range locator) leaves the previous state intact.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+import pytest
+
+pytest.importorskip("fastapi")
+
+from deeptutor.api.routers import reading
+from deeptutor.learning.storage import LearningStore
+from deeptutor.reading import ReadingStore
+from deeptutor.services.path_service import PathService
+
+MATERIAL_ID = "a1b2c3d4e5f6"
+UNIT_COUNT = 3
+
+SAVED_POSITION = {"locator": 2, "source_anchor": "epubcfi(/6/4)", "percentage": 0.75}
+POSITION_BASE = f"/api/reading/materials/{MATERIAL_ID}/position"
+BOOKMARK_BASE = f"/api/reading/materials/{MATERIAL_ID}/bookmarks"
+
+
+def client(monkeypatch, tmp_path: Path):
+ monkeypatch.setenv("DEEPTUTOR_HOME", str(tmp_path))
+ PathService.reset_instance()
+ app = FastAPI()
+ app.include_router(reading.router, prefix="/api/reading")
+ with TestClient(app) as test_client:
+ yield test_client
+ PathService.reset_instance()
+
+
+def material(client: TestClient) -> str:
+ """A real three-unit material in the store the router will resolve."""
+ ReadingStore().ingest_units(
+ MATERIAL_ID,
+ filename="progress.md",
+ units=[f"Section {index} body text." for index in range(1, UNIT_COUNT + 1)],
+ unit="section",
+ title="Progress fixture",
+ )
+ return MATERIAL_ID
+
+
+def _positions_dir() -> Path:
+ return ReadingStore().root / MATERIAL_ID / "positions"
+
+
+def test_position_defaults_to_first_locator_before_any_save(
+ client: TestClient, material: str
+) -> None:
+ response = client.get(POSITION_BASE)
+
+ assert response.status_code == 200
+ body = response.json()
+ assert body["locator"] == 1
+ assert body["source_anchor"] == ""
+ assert body["percentage"] == 0.0
+ assert body["updated_at"] > 0
+
+
+def test_saved_position_roundtrips_through_get(client: TestClient, material: str) -> None:
+ saved = client.put(POSITION_BASE, json=SAVED_POSITION)
+ assert saved.status_code == 200
+ saved_body = saved.json()
+ assert saved_body["updated_at"] > 0
+
+ fetched = client.get(POSITION_BASE)
+
+ assert fetched.status_code == 200
+ body = fetched.json()
+ for key, value in SAVED_POSITION.items():
+ assert body[key] == value, f"round-trip lost {key}"
+
+
+def test_duplicate_save_of_the_same_position_is_idempotent(
+ client: TestClient, material: str
+) -> None:
+ first = client.put(POSITION_BASE, json=SAVED_POSITION)
+ second = client.put(POSITION_BASE, json=SAVED_POSITION)
+
+ assert first.status_code == second.status_code == 200
+ assert second.json()["updated_at"] >= first.json()["updated_at"]
+
+ body = client.get(POSITION_BASE).json()
+ for key, value in SAVED_POSITION.items():
+ assert body[key] == value
+
+ state_files = sorted(_positions_dir().glob("*.json"))
+ assert len(state_files) == 1, f"expected one position file, found {state_files}"
+ on_disk = json.loads(state_files[0].read_text())
+ for key, value in SAVED_POSITION.items():
+ assert on_disk[key] == value
+
+ records = LearningStore().list_reading_records()
+ assert len(records.progress) == 1
+ assert records.progress[0].material_id == material
+ assert records.progress[0].latest_locator == SAVED_POSITION["locator"]
+
+
+def test_re_save_with_a_new_locator_overwrites_the_previous_state(
+ client: TestClient, material: str
+) -> None:
+ assert client.put(POSITION_BASE, json={"locator": 2, "percentage": 0.5}).status_code == 200
+
+ moved = client.put(POSITION_BASE, json={"locator": 3, "percentage": 0.9})
+ assert moved.status_code == 200
+
+ body = client.get(POSITION_BASE).json()
+ assert body["locator"] == 3
+ assert body["percentage"] == 0.9
+ assert len(list(_positions_dir().glob("*.json"))) == 1
+
+
+def test_failed_save_out_of_range_locator_keeps_previous_state(
+ client: TestClient, material: str
+) -> None:
+ assert client.put(POSITION_BASE, json={"locator": 2, "percentage": 0.5}).status_code == 200
+
+ response = client.put(POSITION_BASE, json={"locator": UNIT_COUNT + 1, "percentage": 0.9})
+
+ assert response.status_code == 400
+ body = client.get(POSITION_BASE).json()
+ assert body["locator"] == 2
+ assert body["percentage"] == 0.5
+
+
+def test_position_routes_404_for_an_unknown_material(client: TestClient) -> None:
+ missing = "/api/reading/materials/0123456789abcdef/position"
+
+ assert client.get(missing).status_code == 404
+ assert client.put(missing, json={"locator": 1}).status_code == 404
+
+
+ "payload",
+ [
+ {"locator": 0},
+ {"locator": 2, "percentage": 1.5},
+ {"locator": 2, "percentage": -0.25},
+ {"locator": 2, "source_anchor": "x" * 4097},
+ {"locator": "second"},
+ {},
+ ],
+)
+def test_invalid_position_payloads_are_rejected_with_4xx(
+ client: TestClient, material: str, payload: dict
+) -> None:
+ response = client.put(POSITION_BASE, json=payload)
+
+ assert 400 <= response.status_code < 500
+ body = client.get(POSITION_BASE).json()
+ assert body["locator"] == 1, "a rejected save must persist nothing"
+
+
+def test_bookmark_roundtrip_lists_in_reading_order(client: TestClient, material: str) -> None:
+ kept = client.post(BOOKMARK_BASE, json={"locator": 3, "label": "Ending"})
+ assert kept.status_code == 200
+ assert kept.json()["bookmark_id"].startswith("bm_")
+
+ first_page = client.post(
+ BOOKMARK_BASE,
+ json={"locator": 1, "label": "Opening", "source_anchor": "anchor-1"},
+ )
+ assert first_page.status_code == 200
+
+ rows = client.get(BOOKMARK_BASE).json()["bookmarks"]
+
+ assert [row["locator"] for row in rows] == [1, 3]
+ assert rows[0]["label"] == "Opening"
+ assert rows[0]["source_anchor"] == "anchor-1"
+ assert rows[1]["label"] == "Ending"
+
+
+def test_duplicate_bookmark_of_the_same_locator_is_idempotent(
+ client: TestClient, material: str
+) -> None:
+ first = client.post(BOOKMARK_BASE, json={"locator": 2, "label": "Kept"})
+ second = client.post(BOOKMARK_BASE, json={"locator": 2, "label": "Kept again"})
+
+ assert first.status_code == second.status_code == 200
+ assert second.json()["bookmark_id"] == first.json()["bookmark_id"]
+
+ rows = client.get(BOOKMARK_BASE).json()["bookmarks"]
+ assert len(rows) == 1
+ assert rows[0]["label"] == "Kept", "the second save must not overwrite the first"
+
+
+def test_delete_bookmark_removes_exactly_one_place(client: TestClient, material: str) -> None:
+ created = client.post(BOOKMARK_BASE, json={"locator": 2}).json()
+
+ removed = client.delete(f"{BOOKMARK_BASE}/{created['bookmark_id']}")
+ assert removed.status_code == 200
+ assert client.get(BOOKMARK_BASE).json()["bookmarks"] == []
+
+ again = client.delete(f"{BOOKMARK_BASE}/{created['bookmark_id']}")
+ assert again.status_code == 404
+
+
+def test_bookmark_routes_404_for_an_unknown_material(client: TestClient) -> None:
+ missing = "/api/reading/materials/0123456789abcdef/bookmarks"
+
+ assert client.get(missing).status_code == 404
+ assert client.post(missing, json={"locator": 1}).status_code == 404
+
+
+ "payload",
+ [
+ {"locator": 0},
+ {"locator": UNIT_COUNT + 1},
+ {"locator": 2, "label": "x" * 201},
+ {"locator": 2, "source_anchor": "x" * 4097},
+ ],
+)
+def test_invalid_bookmark_payloads_are_rejected_with_4xx(
+ client: TestClient, material: str, payload: dict
+) -> None:
+ response = client.post(BOOKMARK_BASE, json=payload)
+
+ assert 400 <= response.status_code < 500
+ assert client.get(BOOKMARK_BASE).json()["bookmarks"] == []
diff --git a/tests/api/test_knowledge_upload_guards.py b/tests/api/test_knowledge_upload_guards.py
new file mode 100644
index 000000000..c0ff13869
--- /dev/null
+++ b/tests/api/test_knowledge_upload_guards.py
@@ -0,0 +1,388 @@
+"""Contract tests for the KB upload/delete route guards.
+
+``deeptutor/api/routers/knowledge.py`` is the data-integrity entry point for
+knowledge bases; the happy paths were covered but the guard rails were not.
+Three contracts are locked here, matching the coverage-gap evidence card:
+
+1. a rejected upload batch fails with 4xx and leaves nothing behind — no
+ staged files under ``raw/``, no queued task, no status flip;
+2. task IDs are idempotent per logical task key (a retried dispatch reuses
+ its ID) while two accepted uploads never share one;
+3. deleting a raw document (or a whole KB) keeps the file listing, the
+ indexed-hash metadata and the disk consistent.
+
+No product code is changed by this file.
+"""
+
+from __future__ import annotations
+
+import importlib
+import io
+import json
+from pathlib import Path
+
+import pytest
+
+pytest.importorskip("fastapi")
+from fastapi import FastAPI, UploadFile
+from fastapi.testclient import TestClient
+
+from deeptutor.api.utils.task_id_manager import TaskIDManager
+from deeptutor.utils.document_validator import DocumentValidator
+
+try:
+ knowledge_router_module = importlib.import_module("deeptutor.api.routers.knowledge")
+ router = knowledge_router_module.router
+except Exception: # pragma: no cover - optional heavy imports in lightweight envs
+ knowledge_router_module = None
+ router = None
+
+pytestmark = pytest.mark.skipif(
+ router is None, reason="deeptutor.api.routers.knowledge could not be imported"
+)
+
+
[email protected](autouse=True)
+def _disable_pocketbase(monkeypatch):
+ monkeypatch.setattr("deeptutor.services.pocketbase_client.is_pocketbase_enabled", lambda: False)
+
+
+def _build_app() -> FastAPI:
+ app = FastAPI()
+ app.include_router(router, prefix="/api")
+ return app
+
+
+def _real_manager(monkeypatch, tmp_path: Path):
+ """A real ``KnowledgeBaseManager`` on a throwaway base dir.
+
+ The delete/listing contracts below are about actual disk and config
+ consistency, so the real manager is used instead of a fake.
+ """
+ from deeptutor.knowledge.manager import KnowledgeBaseManager
+
+ manager = KnowledgeBaseManager(base_dir=str(tmp_path / "kbs"))
+ monkeypatch.setattr(knowledge_router_module, "get_kb_manager", lambda: manager)
+ return manager
+
+
+def _seed_kb(
+ manager,
+ name: str = "kb",
+ *,
+ files: dict[str, str] | None = None,
+ file_hashes: dict[str, str] | None = None,
+) -> Path:
+ """Create a ready llamaindex KB with raw files and indexed hashes."""
+ kb_dir = manager.base_dir / name
+ raw_dir = kb_dir / "raw"
+ raw_dir.mkdir(parents=True, exist_ok=True)
+ for rel_name, content in (files or {}).items():
+ target = raw_dir / rel_name
+ target.parent.mkdir(parents=True, exist_ok=True)
+ target.write_text(content, encoding="utf-8")
+
+ manager.config.setdefault("knowledge_bases", {})[name] = {
+ "path": name,
+ "rag_provider": "llamaindex",
+ "status": "ready",
+ }
+ manager._save_config()
+
+ metadata: dict = {"rag_provider": "llamaindex", "needs_reindex": False}
+ if file_hashes is not None:
+ metadata["file_hashes"] = dict(file_hashes)
+ (kb_dir / "metadata.json").write_text(json.dumps(metadata), encoding="utf-8")
+ return kb_dir
+
+
+def _upload(filename: str, payload: bytes) -> list[tuple[str, tuple[str, bytes, str]]]:
+ return [("files", (filename, payload, "application/octet-stream"))]
+
+
+def _staged_files(raw_dir: Path) -> list[Path]:
+ """Files left under ``raw/`` after a request (empty raw dir is fine)."""
+ if not raw_dir.exists():
+ return []
+ return [path for path in raw_dir.rglob("*") if path.is_file()]
+
+
+class _DispatchRecorder:
+ def __init__(self) -> None:
+ self.calls: list[dict] = []
+
+ async def __call__(self, *args, **kwargs):
+ self.calls.append(kwargs)
+ return None
+
+
+def _install_dispatch_recorder(monkeypatch) -> _DispatchRecorder:
+ recorder = _DispatchRecorder()
+ monkeypatch.setattr(knowledge_router_module, "run_upload_processing_task", recorder)
+ return recorder
+
+
+# ---------------------------------------------------------------------------
+# 1. Rejected upload batches leave nothing behind
+# ---------------------------------------------------------------------------
+
+
+def test_upload_rejects_unsupported_extension_without_side_effects(
+ monkeypatch, tmp_path: Path
+) -> None:
+ manager = _real_manager(monkeypatch, tmp_path)
+ _seed_kb(manager, files={})
+ recorder = _install_dispatch_recorder(monkeypatch)
+
+ with TestClient(_build_app()) as client:
+ response = client.post(
+ "/api/knowledge-bases/kb/upload",
+ files=_upload("payload.unsupported", b"binary"),
+ )
+
+ assert response.status_code == 400
+ assert "unsupported file type" in response.json()["detail"].lower()
+ # Nothing staged on disk, no task dispatched, no status flip.
+ assert _staged_files(manager.base_dir / "kb" / "raw") == []
+ assert recorder.calls == []
+ entry = json.loads((manager.base_dir / "kb_config.json").read_text(encoding="utf-8"))[
+ "knowledge_bases"
+ ]["kb"]
+ assert entry["status"] == "ready"
+ assert not entry.get("progress")
+
+
+def test_upload_rejects_oversize_file_without_side_effects(monkeypatch, tmp_path: Path) -> None:
+ manager = _real_manager(monkeypatch, tmp_path)
+ _seed_kb(manager, files={})
+ recorder = _install_dispatch_recorder(monkeypatch)
+ monkeypatch.setattr(DocumentValidator, "MAX_FILE_SIZE", 32)
+
+ with TestClient(_build_app()) as client:
+ response = client.post(
+ "/api/knowledge-bases/kb/upload", files=_upload("big.txt", b"x" * 100)
+ )
+
+ assert response.status_code == 400
+ assert "too large" in response.json()["detail"].lower()
+ assert _staged_files(manager.base_dir / "kb" / "raw") == []
+ assert recorder.calls == []
+ entry = json.loads((manager.base_dir / "kb_config.json").read_text(encoding="utf-8"))[
+ "knowledge_bases"
+ ]["kb"]
+ assert entry["status"] == "ready"
+
+
+def test_upload_rejects_duplicate_names_within_one_batch(monkeypatch, tmp_path: Path) -> None:
+ manager = _real_manager(monkeypatch, tmp_path)
+ _seed_kb(manager, files={})
+ recorder = _install_dispatch_recorder(monkeypatch)
+
+ with TestClient(_build_app()) as client:
+ response = client.post(
+ "/api/knowledge-bases/kb/upload",
+ files=[*_upload("notes.txt", b"one"), *_upload("notes.txt", b"two")],
+ )
+
+ assert response.status_code == 400
+ assert "duplicate filename" in response.json()["detail"].lower()
+ assert _staged_files(manager.base_dir / "kb" / "raw") == []
+ assert recorder.calls == []
+
+
+def test_upload_rejects_provider_mismatch_with_kb(monkeypatch, tmp_path: Path) -> None:
+ manager = _real_manager(monkeypatch, tmp_path)
+ _seed_kb(manager, files={})
+ recorder = _install_dispatch_recorder(monkeypatch)
+
+ with TestClient(_build_app()) as client:
+ response = client.post(
+ "/api/knowledge-bases/kb/upload",
+ data={"rag_provider": "pageindex"},
+ files=_upload("demo.txt", b"hello"),
+ )
+
+ assert response.status_code == 400
+ assert "does not match kb provider" in response.json()["detail"].lower()
+ assert recorder.calls == []
+
+
+def test_rejected_batch_member_rolls_back_earlier_writes(tmp_path: Path) -> None:
+ """A failure on any member unlinks the files already written (unit level).
+
+ The route-level batch pre-validation catches most of these earlier; this
+ exercises the rollback inside ``_save_uploaded_files`` itself.
+ """
+ raw = tmp_path / "raw"
+ raw.mkdir()
+ batch = [
+ UploadFile(filename="ok.txt", file=io.BytesIO(b"hello")),
+ UploadFile(filename="bad.exe", file=io.BytesIO(b"binary")),
+ ]
+
+ with pytest.raises(knowledge_router_module.HTTPException) as exc_info:
+ knowledge_router_module._save_uploaded_files(batch, raw, allowed_extensions={".txt"})
+
+ assert exc_info.value.status_code == 400
+ assert not any(raw.rglob("*")) # ok.txt was written, then rolled back
+
+
+def test_mid_write_size_limit_removes_the_partial_file(monkeypatch, tmp_path: Path) -> None:
+ """A stream whose size cannot be probed is bounded while it is written."""
+
+ class _SizeOpaqueStream(io.BytesIO):
+ def tell(self): # size probe fails -> validation skips the size check
+ raise OSError("position unavailable")
+
+ monkeypatch.setattr(DocumentValidator, "MAX_FILE_SIZE", 16)
+ raw = tmp_path / "raw"
+ raw.mkdir()
+ upload = UploadFile(filename="huge.txt", file=_SizeOpaqueStream(b"x" * 100))
+
+ with pytest.raises(knowledge_router_module.HTTPException) as exc_info:
+ knowledge_router_module._save_uploaded_files([upload], raw, allowed_extensions={".txt"})
+
+ assert exc_info.value.status_code == 400
+ assert "exceeds maximum size" in exc_info.value.detail.lower()
+ assert not any(raw.rglob("*")) # the partial file was unlinked, not staged
+
+
+# ---------------------------------------------------------------------------
+# 2. Task ID idempotency
+# ---------------------------------------------------------------------------
+
+
+def _fresh_task_manager():
+ manager = TaskIDManager()
+ manager._task_ids = {}
+ manager._task_metadata = {}
+ return manager
+
+
+def test_duplicate_task_key_maps_to_the_same_task_id() -> None:
+ manager = _fresh_task_manager()
+
+ first = manager.generate_task_id("kb_upload", "kb-upload-key")
+ second = manager.generate_task_id("kb_upload", "kb-upload-key")
+
+ assert first == second # a retried dispatch reuses its task
+ assert list(manager._task_metadata) == [first]
+ assert manager.get_task_metadata(first)["status"] == "running"
+
+ other = manager.generate_task_id("kb_upload", "kb-upload-other")
+ assert other != first
+
+
+def test_build_unique_task_id_never_collides_for_distinct_uploads(
+ monkeypatch,
+) -> None:
+ fresh = _fresh_task_manager()
+ monkeypatch.setattr(TaskIDManager, "get_instance", classmethod(lambda cls: fresh))
+
+ first = knowledge_router_module._build_unique_task_id("kb_upload", "kb-a")
+ second = knowledge_router_module._build_unique_task_id("kb_upload", "kb-a")
+
+ assert first != second # two accepted uploads never share a task
+ assert first.startswith("kb_upload_") and second.startswith("kb_upload_")
+ assert set(fresh._task_metadata) == {first, second}
+
+
+def test_two_uploads_dispatch_two_distinct_tasks(monkeypatch, tmp_path: Path) -> None:
+ manager = _real_manager(monkeypatch, tmp_path)
+ _seed_kb(manager, files={})
+ recorder = _install_dispatch_recorder(monkeypatch)
+ fresh = _fresh_task_manager()
+ monkeypatch.setattr(TaskIDManager, "get_instance", classmethod(lambda cls: fresh))
+
+ with TestClient(_build_app()) as client:
+ first = client.post("/api/knowledge-bases/kb/upload", files=_upload("one.txt", b"one"))
+ second = client.post("/api/knowledge-bases/kb/upload", files=_upload("two.txt", b"two"))
+
+ assert first.status_code == 200
+ assert second.status_code == 200
+ first_task = first.json()["task_id"]
+ second_task = second.json()["task_id"]
+ assert first_task != second_task
+ assert first_task.startswith("kb_upload_")
+
+ # Both uploads queued exactly one background task, each with its own ID.
+ assert len(recorder.calls) == 2
+ assert {call["task_id"] for call in recorder.calls} == {first_task, second_task}
+
+ # The queued status points at the task that was actually dispatched.
+ entry = json.loads((manager.base_dir / "kb_config.json").read_text(encoding="utf-8"))[
+ "knowledge_bases"
+ ]["kb"]
+ assert entry["status"] == "processing"
+ assert entry["progress"]["task_id"] == second_task
+
+
+# ---------------------------------------------------------------------------
+# 3. Delete keeps listing, metadata and disk consistent
+# ---------------------------------------------------------------------------
+
+
+def test_delete_raw_file_updates_listing_metadata_and_disk(monkeypatch, tmp_path: Path) -> None:
+ manager = _real_manager(monkeypatch, tmp_path)
+ kb_dir = _seed_kb(
+ manager,
+ files={"notes.txt": "hello", "docs/paper.md": "# paper"},
+ file_hashes={"notes.txt": "h-notes", "docs/paper.md": "h-paper"},
+ )
+
+ with TestClient(_build_app()) as client:
+ listing_before = client.get("/api/knowledge-bases/kb/files").json()["files"]
+ removal = client.delete("/api/knowledge-bases/kb/files/notes.txt")
+ listing_after = client.get("/api/knowledge-bases/kb/files").json()["files"]
+ repeat = client.delete("/api/knowledge-bases/kb/files/notes.txt")
+
+ assert {entry["name"] for entry in listing_before} == {
+ "notes.txt",
+ "docs",
+ "docs/paper.md",
+ }
+ assert removal.status_code == 200
+ assert removal.json() == {"status": "ok", "path": "notes.txt", "was_indexed": True}
+
+ # Listing no longer shows the file…
+ assert {entry["name"] for entry in listing_after} == {"docs", "docs/paper.md"}
+ # …the disk copy is gone while siblings survive…
+ assert not (kb_dir / "raw" / "notes.txt").exists()
+ assert (kb_dir / "raw" / "docs" / "paper.md").read_text(encoding="utf-8") == "# paper"
+ # …and the indexed-hash record was dropped with it.
+ metadata = json.loads((kb_dir / "metadata.json").read_text(encoding="utf-8"))
+ assert metadata["file_hashes"] == {"docs/paper.md": "h-paper"}
+
+ assert repeat.status_code == 404
+ assert repeat.json()["detail"] == "File not found"
+
+
+def test_delete_whole_kb_updates_listing_and_disk(monkeypatch, tmp_path: Path) -> None:
+ manager = _real_manager(monkeypatch, tmp_path)
+ kb_dir = _seed_kb(manager, files={"notes.txt": "hello"})
+ second_dir = _seed_kb(manager, "kb-two", files={"extra.md": "x"})
+
+ with TestClient(_build_app()) as client:
+ names_before = {item["name"] for item in client.get("/api/knowledge-bases").json()}
+ path_route = client.delete("/api/knowledge-bases/kb")
+ repeat = client.delete("/api/knowledge-bases/kb")
+ body_route = client.post("/api/knowledge-bases/delete", json={"name": "kb-two"})
+ listing = client.get("/api/knowledge-bases").json()
+
+ assert names_before == {"kb", "kb-two"}
+ assert path_route.status_code == 200
+ assert path_route.json()["message"] == "Knowledge base 'kb' deleted successfully"
+ assert repeat.status_code == 404
+ assert body_route.status_code == 200
+ assert body_route.json()["message"] == "Knowledge base 'kb-two' deleted successfully"
+
+ # Both the config listing and the directories on disk are empty afterwards.
+ assert listing == []
+ assert not kb_dir.exists()
+ assert not second_dir.exists()
+ assert (
+ json.loads((manager.base_dir / "kb_config.json").read_text(encoding="utf-8"))[
+ "knowledge_bases"
+ ]
+ == {}
+ )
diff --git a/tests/api/test_memory_router_contract.py b/tests/api/test_memory_router_contract.py
new file mode 100644
index 000000000..acb13a8d3
--- /dev/null
+++ b/tests/api/test_memory_router_contract.py
@@ -0,0 +1,571 @@
+"""Memory workbench router contract tests (deeptutor/api/routers/memory.py).
+
+Covers the three contract groups the workbench UI relies on:
+
+1. GET shapes — overview / doc / lines / settings / trace / snapshot / backup.
+2. Edit + delete round-trips — PUT /doc, DELETE entry, apply ops, PUT settings,
+ trace clearing all read back consistently through the same API.
+3. 4xx surfaces — bad layer, unknown surface/slot, missing entries, invalid
+ run requests, bad trace days.
+
+Everything is isolated per test: ``paths.memory_root`` is redirected to
+``tmp_path``, the settings ``ConfigManager`` is replaced with an in-memory
+fake (a real PUT would otherwise write the developer's ``main.yaml``), the
+snapshot workspace adapters are stubbed, and the run-manager singleton is
+reset on both sides of every test so no consolidator run can leak in or out.
+Consolidator runs are never driven for real — the LLM runner is stubbed.
+"""
+
+from __future__ import annotations
+
+import importlib
+import json
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+pytest.importorskip("fastapi")
+
+FastAPI = pytest.importorskip("fastapi").FastAPI
+TestClient = pytest.importorskip("fastapi.testclient").TestClient
+
+memory_router = importlib.import_module("deeptutor.api.routers.memory").router
+memory_router_mod = importlib.import_module("deeptutor.api.routers.memory")
+paths_mod = importlib.import_module("deeptutor.services.memory.paths")
+document_mod = importlib.import_module("deeptutor.services.memory.document")
+settings_mod = importlib.import_module("deeptutor.services.memory.settings")
+snap_adapters_mod = importlib.import_module("deeptutor.services.memory.snapshot.adapters")
+snapshot_store = importlib.import_module("deeptutor.services.memory.snapshot.store")
+runs_mod = importlib.import_module("deeptutor.services.memory.consolidator.runs")
+
+ENTRY_ID = "m_01HZK1ABCDEFGHJKMNPQRSTVWX"
+OTHER_ENTRY_ID = "m_01HZK1BCDEFGHJKMNPQRSTVWXY"
+
+
+def _make_doc(surface: str, *entries: tuple[str, str]) -> str:
+ """Serialize an L2 doc with the given (id, text) entries under 'Themes'."""
+ doc = document_mod.Document(
+ title=f"{surface} memory",
+ sections=[
+ (
+ "Themes",
+ [
+ document_mod.Entry(
+ id=entry_id,
+ section="Themes",
+ text=text,
+ refs=[f"{surface}:r{index}"],
+ )
+ for index, (entry_id, text) in enumerate(entries)
+ ],
+ ),
+ ],
+ )
+ return document_mod.serialize(doc)
+
+
+def _seed_l2(tmp_path: Path, surface: str, *entries: tuple[str, str]) -> Path:
+ path = tmp_path / "L2" / f"{surface}.md"
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text(_make_doc(surface, *entries), encoding="utf-8")
+ return path
+
+
+def _write_trace(root: Path, surface: str, day: str, events: list[dict]) -> Path:
+ trace_dir = root / "trace" / surface
+ trace_dir.mkdir(parents=True, exist_ok=True)
+ path = trace_dir / f"{day}.jsonl"
+ path.write_text(
+ "".join(json.dumps(event, ensure_ascii=False) + "\n" for event in events),
+ encoding="utf-8",
+ )
+ return path
+
+
+def _trace_event(day: str, index: int) -> dict[str, Any]:
+ return {
+ "id": f"chat:{day}-{index}",
+ "ts": f"{day}T0{index}:00:00+00:00",
+ "surface": "chat",
+ "kind": "note",
+ "payload": {"text": f"event-{index}"},
+ }
+
+
+class _FakeConfigManager:
+ """In-memory stand-in for ConfigManager — instances share class state."""
+
+ _state: dict[str, Any] = {}
+
+ def __init__(self, *args: Any, **kwargs: Any) -> None:
+ self._config = _FakeConfigManager._state
+
+ def load_config(self, force_reload: bool = False) -> dict[str, Any]:
+ return json.loads(json.dumps(self._config))
+
+ def save_config(self, config: dict[str, Any]) -> bool:
+ for key, value in config.items():
+ if isinstance(value, dict) and isinstance(self._config.get(key), dict):
+ self._config[key].update(json.loads(json.dumps(value)))
+ else:
+ self._config[key] = json.loads(json.dumps(value))
+ return True
+
+
+def mem_root(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+ monkeypatch.setattr(paths_mod, "memory_root", lambda: tmp_path)
+ (tmp_path / "L2").mkdir()
+ (tmp_path / "L3").mkdir()
+ return tmp_path
+
+
+def client(mem_root: Path, monkeypatch: pytest.MonkeyPatch) -> TestClient:
+ runs_mod.reset_run_manager_for_tests()
+ app = FastAPI()
+ app.include_router(memory_router, prefix="/api/memory")
+ try:
+ yield TestClient(app)
+ finally:
+ runs_mod.reset_run_manager_for_tests()
+
+
+def isolated_settings(monkeypatch: pytest.MonkeyPatch) -> type[_FakeConfigManager]:
+ _FakeConfigManager._state = {}
+ monkeypatch.setattr(settings_mod, "ConfigManager", _FakeConfigManager)
+ return _FakeConfigManager
+
+
+def snapshot_adapters(monkeypatch: pytest.MonkeyPatch):
+ stamps = [
+ snap_adapters_mod.EntityStamp(
+ id="e1", label="Notebook entry", fingerprint="fp2", ts="2026-10-02T00:00:00Z"
+ )
+ ]
+ entities = [
+ snap_adapters_mod.Entity(
+ id="e1",
+ label="Notebook entry",
+ ts="2026-10-02T00:00:00Z",
+ content="body",
+ fingerprint="fp2",
+ )
+ ]
+ monkeypatch.setattr(snap_adapters_mod, "read_entities", lambda surface: list(entities))
+ monkeypatch.setattr(snap_adapters_mod, "read_stamps", lambda surface: list(stamps))
+ return snap_adapters_mod
+
+
+# ── ① GET return shapes ──────────────────────────────────────────────────
+
+
+def test_overview_returns_all_docs_and_backups(client: TestClient, mem_root: Path) -> None:
+ _seed_l2(mem_root, "chat", (ENTRY_ID, "some fact"))
+ backup = mem_root / "backup" / "20260101T000000Z"
+ backup.mkdir(parents=True)
+ (backup / "L2").mkdir()
+
+ res = client.get("/api/memory/overview")
+ assert res.status_code == 200
+ body = res.json()
+ assert set(body) == {"docs", "backups"}
+ assert body["backups"] == ["20260101T000000Z"]
+
+ docs = body["docs"]
+ assert len(docs) == len(paths_mod.SURFACES) + len(paths_mod.L3_SLOTS)
+ l2_rows = [row for row in docs if row["layer"] == "L2"]
+ l3_rows = [row for row in docs if row["layer"] == "L3"]
+ assert {row["key"] for row in l2_rows} == set(paths_mod.SURFACES)
+ assert {row["key"] for row in l3_rows} == set(paths_mod.L3_SLOTS)
+ for row in docs:
+ assert set(row) == {"layer", "key", "exists", "updated_at", "entry_count", "backlog"}
+
+ chat_row = next(row for row in l2_rows if row["key"] == "chat")
+ assert chat_row["exists"] is True
+ assert chat_row["entry_count"] == 1
+ assert chat_row["updated_at"] is not None
+ missing_row = next(row for row in l2_rows if row["key"] == "quiz")
+ assert missing_row["exists"] is False
+ assert missing_row["updated_at"] is None
+ assert missing_row["entry_count"] == 0
+
+
+def test_get_doc_returns_raw_content_or_empty(client: TestClient, mem_root: Path) -> None:
+ _seed_l2(mem_root, "chat", (ENTRY_ID, "seeded fact"))
+
+ res = client.get("/api/memory/doc/L2/chat")
+ assert res.status_code == 200
+ body = res.json()
+ assert body == {
+ "layer": "L2",
+ "key": "chat",
+ "content": _make_doc("chat", (ENTRY_ID, "seeded fact")),
+ }
+
+ missing = client.get("/api/memory/doc/L3/profile")
+ assert missing.status_code == 200
+ assert missing.json() == {"layer": "L3", "key": "profile", "content": ""}
+
+
+def test_get_doc_lines_returns_numbered_view(client: TestClient, mem_root: Path) -> None:
+ _seed_l2(mem_root, "chat", (ENTRY_ID, "line view fact"))
+
+ res = client.get("/api/memory/doc/L2/chat/lines")
+ assert res.status_code == 200
+ body = res.json()
+ assert body["layer"] == "L2"
+ assert body["key"] == "chat"
+ assert isinstance(body["lines"], list) and body["lines"]
+ for line in body["lines"]:
+ assert set(line) == {"number", "kind", "text", "entry_id", "section"}
+ assert any(line["entry_id"] == ENTRY_ID for line in body["lines"])
+
+
+def test_get_settings_returns_full_schema(
+ client: TestClient, isolated_settings: type[_FakeConfigManager]
+) -> None:
+ res = client.get("/api/memory/settings")
+ assert res.status_code == 200
+ body = res.json()
+ assert set(body) == {"update", "audit", "dedup", "merge", "chunking", "reference"}
+ assert body["update"] == {"l2_budget": 20, "l3_budget": 10}
+ assert body["dedup"] == {"iterations": 3, "auto_after_update": True}
+
+
+def test_trace_returns_events_with_pagination(client: TestClient, mem_root: Path) -> None:
+ _write_trace(
+ mem_root,
+ "chat",
+ "2026-10-02",
+ [_trace_event("2026-10-02", 1), _trace_event("2026-10-02", 2)],
+ )
+
+ res = client.get("/api/memory/trace/chat", params={"limit": 1, "offset": 1})
+ assert res.status_code == 200
+ body = res.json()
+ assert body["surface"] == "chat"
+ assert body["offset"] == 1
+ assert body["limit"] == 1
+ assert [event["payload"]["text"] for event in body["events"]] == ["event-2"]
+ for event in body["events"]:
+ assert set(event) == {"id", "ts", "surface", "kind", "payload", "session_id", "turn_id"}
+
+
+def test_snapshot_get_returns_entities_and_pending(
+ client: TestClient, mem_root: Path, snapshot_adapters
+) -> None:
+ snapshot_store.save_state(
+ "chat",
+ fingerprints={"e1": "fp1"},
+ labels={"e1": "Notebook entry"},
+ last_refresh="2026-10-01T00:00:00Z",
+ )
+
+ res = client.get("/api/memory/snapshot/chat")
+ assert res.status_code == 200
+ body = res.json()
+ assert body["surface"] == "chat"
+ assert [entity["id"] for entity in body["entities"]] == ["e1"]
+ assert body["last_refresh"] == "2026-10-01T00:00:00Z"
+ assert len(body["pending_changes"]) == 1
+ change = body["pending_changes"][0]
+ assert change["entity_id"] == "e1"
+ assert change["kind"] == "modified"
+
+
+def test_backup_listing_shape(client: TestClient, mem_root: Path) -> None:
+ empty = client.get("/api/memory/backup")
+ assert empty.status_code == 200
+ assert empty.json() == {"backups": []}
+
+ backup = mem_root / "backup" / "20260101T000000Z"
+ backup.mkdir(parents=True)
+ (backup / "PROFILE.md").write_text("archived", encoding="utf-8")
+
+ res = client.get("/api/memory/backup")
+ assert res.status_code == 200
+ assert res.json() == {"backups": [{"name": "20260101T000000Z", "files": ["PROFILE.md"]}]}
+
+
+# ── ② Edit / delete then read consistency ────────────────────────────────
+
+
+def test_put_doc_then_get_roundtrip(client: TestClient) -> None:
+ content = "---\ntitle: chat memory\n---\n\n# Themes\n\n- hand edited fact\n"
+ res = client.put("/api/memory/doc/L2/chat", json={"content": content})
+ assert res.status_code == 200
+ assert res.json() == {"layer": "L2", "key": "chat", "saved": True}
+
+ follow_up = client.get("/api/memory/doc/L2/chat")
+ assert follow_up.status_code == 200
+ assert follow_up.json()["content"] == content
+
+
+def test_delete_entry_then_read_consistent(client: TestClient, mem_root: Path) -> None:
+ _seed_l2(
+ mem_root,
+ "chat",
+ (ENTRY_ID, "doomed fact"),
+ (OTHER_ENTRY_ID, "surviving fact"),
+ )
+
+ res = client.delete(f"/api/memory/doc/L2/chat/entry/{ENTRY_ID}")
+ assert res.status_code == 200
+ assert res.json() == {"layer": "L2", "key": "chat", "deleted": ENTRY_ID}
+
+ content = client.get("/api/memory/doc/L2/chat").json()["content"]
+ assert "doomed fact" not in content
+ assert "surviving fact" in content
+
+ again = client.delete(f"/api/memory/doc/L2/chat/entry/{ENTRY_ID}")
+ assert again.status_code == 404
+ assert again.json()["detail"] == "entry not found"
+
+
+def test_apply_ops_adds_entry_to_doc(client: TestClient) -> None:
+ res = client.post(
+ "/api/memory/doc/L2/chat/apply",
+ json={
+ "ops": [
+ {
+ "op": "add",
+ "section": "Themes",
+ "text": "applied fact",
+ "refs": ["chat:r0"],
+ }
+ ]
+ },
+ )
+ assert res.status_code == 200
+ body = res.json()
+ assert body["accepted"] is True
+ assert body["reason"] == ""
+ assert len(body["results"]) == 1
+ assert body["results"][0]["status"] == "applied"
+ assert body["results"][0]["entry_id"].startswith("m_")
+
+ content = client.get("/api/memory/doc/L2/chat").json()["content"]
+ assert "applied fact" in content
+
+ empty = client.post("/api/memory/doc/L2/chat/apply", json={"ops": []})
+ assert empty.status_code == 200
+ assert empty.json() == {"accepted": True, "reason": "no ops to apply", "results": []}
+
+
+def test_apply_ops_preferences_is_rejected(client: TestClient) -> None:
+ res = client.post(
+ "/api/memory/doc/L3/preferences/apply",
+ json={"ops": [{"op": "add", "section": "Preferences", "text": "x", "refs": []}]},
+ )
+ assert res.status_code == 405
+
+
+def test_put_settings_roundtrip(
+ client: TestClient, isolated_settings: type[_FakeConfigManager]
+) -> None:
+ res = client.put("/api/memory/settings", json={"update": {"l2_budget": 55}})
+ assert res.status_code == 200
+ body = res.json()
+ assert body["update"]["l2_budget"] == 55
+ # Unspecified fields keep their defaults after the merge.
+ assert body["dedup"]["iterations"] == 3
+ assert isolated_settings._state["memory"]["update"]["l2_budget"] == 55
+
+ follow_up = client.get("/api/memory/settings")
+ assert follow_up.status_code == 200
+ assert follow_up.json()["update"]["l2_budget"] == 55
+
+
+def test_clear_trace_and_clear_day_consistent(client: TestClient, mem_root: Path) -> None:
+ _write_trace(mem_root, "chat", "2026-10-01", [_trace_event("2026-10-01", 1)])
+ _write_trace(mem_root, "chat", "2026-10-02", [_trace_event("2026-10-02", 1)])
+
+ res = client.delete("/api/memory/trace/chat/day/2026-10-01")
+ assert res.status_code == 200
+ assert res.json() == {"surface": "chat", "day": "2026-10-01", "deleted": True}
+ assert not (mem_root / "trace" / "chat" / "2026-10-01.jsonl").exists()
+ assert (mem_root / "trace" / "chat" / "2026-10-02.jsonl").exists()
+
+ clear_all = client.delete("/api/memory/trace/chat")
+ assert clear_all.status_code == 200
+ assert clear_all.json() == {"surface": "chat", "removed_files": 1}
+ assert client.get("/api/memory/trace/chat").json()["events"] == []
+
+
+def test_snapshot_refresh_and_changes_roundtrip(
+ client: TestClient, mem_root: Path, snapshot_adapters
+) -> None:
+ refresh = client.post("/api/memory/snapshot/chat/refresh")
+ assert refresh.status_code == 200
+ body = refresh.json()
+ assert body["surface"] == "chat"
+ assert [change["entity_id"] for change in body["changes"]] == ["e1"]
+ assert body["last_refresh"] is not None
+
+ listed = client.get("/api/memory/snapshot/chat/changes", params={"limit": 10, "offset": 0})
+ assert listed.status_code == 200
+ listed_body = listed.json()
+ assert listed_body["surface"] == "chat"
+ assert listed_body["limit"] == 10
+ assert [change["entity_id"] for change in listed_body["changes"]] == ["e1"]
+
+ cleared = client.delete("/api/memory/snapshot/chat/changes")
+ assert cleared.status_code == 200
+ assert cleared.json() == {"surface": "chat", "cleared": True}
+ assert client.get("/api/memory/snapshot/chat/changes").json()["changes"] == []
+
+
+# ── ③ Invalid params / nonexistent items → 4xx ───────────────────────────
+
+
+def test_doc_invalid_layer_returns_400(client: TestClient) -> None:
+ for method, path in (
+ ("get", "/api/memory/doc/L9/chat"),
+ ("put", "/api/memory/doc/L9/chat"),
+ ("delete", "/api/memory/doc/L9/chat/entry/x"),
+ ("get", "/api/memory/doc/L9/chat/lines"),
+ ):
+ res = getattr(client, method)(
+ path, **({"json": {"content": "x"}} if method == "put" else {})
+ )
+ assert res.status_code == 400, (method, path)
+ assert res.json()["detail"] == "layer must be L2 or L3"
+
+
+def test_doc_unknown_surface_or_slot_returns_404(client: TestClient) -> None:
+ assert client.get("/api/memory/doc/L2/nope").status_code == 404
+ assert client.get("/api/memory/doc/L3/nope").status_code == 404
+ assert client.put("/api/memory/doc/L2/nope", json={"content": "x"}).status_code == 404
+ assert client.delete("/api/memory/doc/L2/nope/entry/x").status_code == 404
+ assert client.get("/api/memory/doc/L2/nope/lines").status_code == 404
+
+
+def test_put_doc_missing_body_returns_422(client: TestClient) -> None:
+ res = client.put("/api/memory/doc/L2/chat", json={})
+ assert res.status_code == 422
+
+
+def test_run_start_invalid_combos(client: TestClient) -> None:
+ bad_layer = client.post(
+ "/api/memory/runs/start",
+ json={"layer": "L1", "key": "chat", "mode": "update"},
+ )
+ assert bad_layer.status_code == 400
+
+ bad_key = client.post(
+ "/api/memory/runs/start",
+ json={"layer": "L2", "key": "nope", "mode": "update"},
+ )
+ assert bad_key.status_code == 404
+
+ preferences = client.post(
+ "/api/memory/runs/start",
+ json={"layer": "L3", "key": "preferences", "mode": "update"},
+ )
+ assert preferences.status_code == 405
+
+ bad_mode = client.post(
+ "/api/memory/runs/start",
+ json={"layer": "L2", "key": "chat", "mode": "explode"},
+ )
+ assert bad_mode.status_code == 422
+
+
+def test_run_unknown_ids(client: TestClient) -> None:
+ assert client.get("/api/memory/runs/unknown").status_code == 404
+ assert client.get("/api/memory/runs/unknown/events").status_code == 404
+ assert client.post("/api/memory/runs/unknown/undo").status_code == 404
+ cancel = client.post("/api/memory/runs/unknown/cancel")
+ assert cancel.status_code == 409
+ assert cancel.json()["detail"] == "not active"
+
+
+def test_list_runs_validation(client: TestClient) -> None:
+ empty = client.get("/api/memory/runs")
+ assert empty.status_code == 200
+ assert empty.json() == {"runs": []}
+
+ assert client.get("/api/memory/runs", params={"layer": "L9"}).status_code == 400
+ assert client.get("/api/memory/runs", params={"layer": "L2", "key": "nope"}).status_code == 404
+
+
+def test_trace_day_invalid_and_missing(client: TestClient) -> None:
+ bad = client.delete("/api/memory/trace/chat/day/not-a-date")
+ assert bad.status_code == 400
+ assert bad.json()["detail"] == "day must be YYYY-MM-DD"
+
+ missing = client.delete("/api/memory/trace/chat/day/2026-10-02")
+ assert missing.status_code == 404
+ assert missing.json()["detail"] == "no trace for that day"
+
+
+def test_snapshot_unknown_surface_returns_404(client: TestClient, snapshot_adapters) -> None:
+ assert client.get("/api/memory/snapshot/nope").status_code == 404
+ assert client.post("/api/memory/snapshot/nope/refresh").status_code == 404
+ assert client.get("/api/memory/snapshot/nope/changes").status_code == 404
+ assert client.delete("/api/memory/snapshot/nope/changes").status_code == 404
+
+
+def test_legacy_mode_endpoint_validation(client: TestClient) -> None:
+ """Legacy streams validate layer/key before any run starts."""
+ assert client.post("/api/memory/doc/L9/chat/update").status_code == 400
+ assert client.post("/api/memory/doc/L2/nope/update").status_code == 404
+ assert client.post("/api/memory/doc/L1/x/audit").status_code == 400
+ assert client.post("/api/memory/doc/L2/nope/dedup").status_code == 404
+
+
+# ── Run lifecycle contract (runner stubbed — no LLM) ─────────────────────
+
+
+def test_run_start_and_completion_contract(
+ client: TestClient, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ async def fake_runner(on_event) -> None: # noqa: ANN001 — matches runner signature
+ await __import__("asyncio").sleep(0)
+
+ monkeypatch.setattr(memory_router_mod, "_runner_for", lambda req: fake_runner)
+
+ res = client.post(
+ "/api/memory/runs/start",
+ json={"layer": "L2", "key": "chat", "mode": "update", "language": "en"},
+ )
+ assert res.status_code == 200
+ started = res.json()
+ assert set(started) == {
+ "id",
+ "layer",
+ "key",
+ "mode",
+ "params",
+ "language",
+ "status",
+ "started_at",
+ "ended_at",
+ "error",
+ "event_count",
+ "undo_count",
+ }
+ assert started["layer"] == "L2"
+ assert started["key"] == "chat"
+ assert started["mode"] == "update"
+ run_id = started["id"]
+
+ fetched = client.get(f"/api/memory/runs/{run_id}")
+ assert fetched.status_code == 200
+ assert fetched.json()["status"] == "done"
+ assert fetched.json()["event_count"] >= 2
+
+ listed = client.get("/api/memory/runs", params={"layer": "L2", "key": "chat"})
+ assert [run["id"] for run in listed.json()["runs"]] == [run_id]
+
+ cancel = client.post(f"/api/memory/runs/{run_id}/cancel")
+ assert cancel.status_code == 409
+ assert cancel.json()["detail"] == "not active"
+
+ undo = client.post(f"/api/memory/runs/{run_id}/undo")
+ assert undo.status_code == 409
+ assert undo.json()["detail"] == "nothing to undo"
diff --git a/tests/api/test_notebook_api_contract.py b/tests/api/test_notebook_api_contract.py
new file mode 100644
index 000000000..5a1638efe
--- /dev/null
+++ b/tests/api/test_notebook_api_contract.py
@@ -0,0 +1,274 @@
+"""Contract tests for the Question Notebook API (issue #1244 ground work).
+
+Pins three contract surfaces of ``POST /api/question-notebook/entries/upsert``
+and the listing filter: AssessmentSource validation, identity dedup, and
+concurrent-write behaviour.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+import httpx
+import pytest
+
+pytest.importorskip("fastapi")
+
+FastAPI = pytest.importorskip("fastapi").FastAPI
+TestClient = pytest.importorskip("fastapi.testclient").TestClient
+notebook_router = pytest.importorskip("deeptutor.api.routers.question_notebook").router
+
+from deeptutor.core.assessment import ASSESSMENT_SOURCES
+from deeptutor.services.session.sqlite_store import SQLiteSessionStore
+
+PREFIX = "/api/question-notebook"
+
+PINNED_SOURCES = {
+ "deep_question",
+ "mastery_path",
+ "immersive_reading",
+ "book",
+ "partner_chat",
+ "import",
+}
+
+
+def _build_app(store: SQLiteSessionStore) -> FastAPI:
+ app = FastAPI()
+ app.include_router(notebook_router, prefix=PREFIX)
+ return app
+
+
+def store(tmp_path: Path, monkeypatch) -> SQLiteSessionStore:
+ instance = SQLiteSessionStore(db_path=tmp_path / "notebook-contract.db")
+ monkeypatch.setattr(
+ "deeptutor.api.routers.question_notebook.get_sqlite_session_store",
+ lambda: instance,
+ )
+ return instance
+
+
+def client(store: SQLiteSessionStore):
+ with TestClient(_build_app(store)) as test_client:
+ yield test_client
+
+
+def session_id(store: SQLiteSessionStore) -> str:
+ return asyncio.run(store.create_session(title="Notebook contract"))["id"]
+
+
+def _conversation_payload(session_id: str, **overrides):
+ payload = {
+ "session_id": session_id,
+ "origin_type": "conversation",
+ "question_id": "q1",
+ "question": "Capital of France?",
+ "user_answer": "A",
+ "correct_answer": "B",
+ "is_correct": False,
+ "source": "deep_question",
+ }
+ payload.update(overrides)
+ return payload
+
+
+def test_assessment_source_catalog_is_pinned() -> None:
+ assert ASSESSMENT_SOURCES == PINNED_SOURCES
+
+
[email protected]("source", sorted(PINNED_SOURCES))
+def test_upsert_accepts_every_valid_source(client, session_id: str, source: str) -> None:
+ response = client.post(
+ f"{PREFIX}/entries/upsert",
+ json=_conversation_payload(session_id, question_id=f"q-{source}", source=source),
+ )
+ assert response.status_code == 200
+ assert response.json()["source"] == source
+
+
[email protected]("source", ["wechat_chat", "partner", "Partner_Chat", "deepquest", ""])
+def test_upsert_rejects_unlisted_source(
+ client, store: SQLiteSessionStore, session_id: str, source: str
+) -> None:
+ response = client.post(
+ f"{PREFIX}/entries/upsert",
+ json=_conversation_payload(session_id, question_id="q-rejected", source=source),
+ )
+ assert response.status_code == 422
+ detail = response.json()["detail"][0]
+ assert detail["type"] == "literal_error"
+ assert detail["loc"] == ["body", "source"]
+ listing = client.get(f"{PREFIX}/entries").json()
+ assert listing["total"] == 0
+
+
+def test_entries_filter_rejects_unlisted_source(client) -> None:
+ response = client.get(f"{PREFIX}/entries", params={"source": "wechat_chat"})
+ assert response.status_code == 422
+
+
+def test_partner_chat_entry_roundtrip_and_filter(client, session_id: str) -> None:
+ created = client.post(
+ f"{PREFIX}/entries/upsert",
+ json=_conversation_payload(
+ session_id,
+ question_id="q-partner",
+ question=" Photographed wrong question ",
+ source="partner_chat",
+ user_answer="42",
+ is_correct=False,
+ result="incorrect",
+ ),
+ )
+ assert created.status_code == 200
+ entry = created.json()
+ assert entry["source"] == "partner_chat"
+ assert entry["user_answer"] == "42"
+ assert entry["is_correct"] is False
+
+ by_id = client.get(f"{PREFIX}/entries/{entry['id']}")
+ assert by_id.status_code == 200
+ assert by_id.json()["source"] == "partner_chat"
+
+ filtered = client.get(f"{PREFIX}/entries", params={"source": "partner_chat"})
+ assert filtered.status_code == 200
+ assert filtered.json()["total"] == 1
+ assert filtered.json()["items"][0]["id"] == entry["id"]
+
+
+def test_upsert_dedupes_identity_and_updates_content(client, session_id: str) -> None:
+ first = client.post(
+ f"{PREFIX}/entries/upsert",
+ json=_conversation_payload(
+ session_id,
+ question_id="q-dup",
+ turn_id="turn-1",
+ user_answer="A",
+ is_correct=True,
+ ),
+ )
+ assert first.status_code == 200
+ assert first.json()["score_trend"] == "new"
+
+ second = client.post(
+ f"{PREFIX}/entries/upsert",
+ json=_conversation_payload(
+ session_id,
+ question_id="q-dup",
+ turn_id="turn-1",
+ user_answer="C",
+ is_correct=False,
+ ),
+ )
+ assert second.status_code == 200
+ assert second.json()["id"] == first.json()["id"]
+ assert second.json()["user_answer"] == "C"
+ assert second.json()["is_correct"] is False
+ assert second.json()["score_trend"] == "declined"
+
+ listing = client.get(f"{PREFIX}/entries").json()
+ assert listing["total"] == 1
+
+
+def test_upsert_identity_is_turn_scoped(client, session_id: str) -> None:
+ for turn_id in ("turn-1", "turn-2"):
+ response = client.post(
+ f"{PREFIX}/entries/upsert",
+ json=_conversation_payload(session_id, question_id="q-turns", turn_id=turn_id),
+ )
+ assert response.status_code == 200
+ listing = client.get(f"{PREFIX}/entries").json()
+ assert listing["total"] == 2
+ assert {item["turn_id"] for item in listing["items"]} == {"turn-1", "turn-2"}
+
+
+def test_upsert_rejects_conversation_origin_ref_mismatch(client, session_id: str) -> None:
+ response = client.post(
+ f"{PREFIX}/entries/upsert",
+ json=_conversation_payload(session_id, origin_ref="not-this-session"),
+ )
+ assert response.status_code == 422
+ assert client.get(f"{PREFIX}/entries").json()["total"] == 0
+
+
+def test_upsert_requires_origin_ref_for_non_conversation(client, session_id: str) -> None:
+ response = client.post(
+ f"{PREFIX}/entries/upsert",
+ json=_conversation_payload(session_id, origin_type="external_import", source="import"),
+ )
+ assert response.status_code == 422
+ assert client.get(f"{PREFIX}/entries").json()["total"] == 0
+
+
+def test_concurrent_identical_upserts_keep_single_row(
+ store: SQLiteSessionStore, session_id: str
+) -> None:
+ app = _build_app(store)
+
+ async def fire() -> list[httpx.Response]:
+ transport = httpx.ASGITransport(app=app)
+ async with httpx.AsyncClient(transport=transport, base_url="http://test") as client:
+
+ async def one(index: int) -> httpx.Response:
+ return await client.post(
+ f"{PREFIX}/entries/upsert",
+ json=_conversation_payload(
+ session_id,
+ question_id="q-race",
+ turn_id="turn-race",
+ user_answer=f"answer-{index}",
+ is_correct=index % 2 == 0,
+ ),
+ )
+
+ return list(await asyncio.gather(*(one(i) for i in range(8))))
+
+ responses = asyncio.run(fire())
+ assert all(r.status_code == 200 for r in responses), [r.status_code for r in responses]
+
+ listing = store_list(store)
+ race_rows = [
+ item
+ for item in listing
+ if item["question_id"] == "q-race" and item["turn_id"] == "turn-race"
+ ]
+ assert len(race_rows) == 1
+ assert race_rows[0]["user_answer"] in {f"answer-{i}" for i in range(8)}
+
+
+def test_concurrent_distinct_turns_create_distinct_rows(
+ store: SQLiteSessionStore, session_id: str
+) -> None:
+ app = _build_app(store)
+
+ async def fire() -> list[httpx.Response]:
+ transport = httpx.ASGITransport(app=app)
+ async with httpx.AsyncClient(transport=transport, base_url="http://test") as client:
+
+ async def one(index: int) -> httpx.Response:
+ return await client.post(
+ f"{PREFIX}/entries/upsert",
+ json=_conversation_payload(
+ session_id,
+ question_id="q-fanout",
+ turn_id=f"turn-{index}",
+ user_answer=f"answer-{index}",
+ ),
+ )
+
+ return list(await asyncio.gather(*(one(i) for i in range(8))))
+
+ responses = asyncio.run(fire())
+ assert all(r.status_code == 200 for r in responses), [r.status_code for r in responses]
+
+ listing = store_list(store)
+ fanout = {item["turn_id"] for item in listing if item["question_id"] == "q-fanout"}
+ assert fanout == {f"turn-{i}" for i in range(8)}
+
+
+def store_list(store: SQLiteSessionStore) -> list[dict]:
+ return asyncio.run(store.list_notebook_entries(limit=200))["items"]