DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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"]