Skip to content

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

73.8 KB
Raw Blame
"""Tests for the Mastery Path tools — the seam between the chat-loop tutor and
the engine. They drive the full loop the tutor uses: build a path, read the
gate, pose + grade questions, assess qualitative objectives, with the active
path id injected server-side (never by the model)."""

from __future__ import annotations

import json

import pytest

from deeptutor.learning.models import InteractionStatus, PendingQuestion
from deeptutor.learning.storage import LearningStore
from deeptutor.services.session.sqlite_store import SQLiteSessionStore
from deeptutor.tools.mastery_tool import (
    MasteryAssessTool,
    MasteryBuildTool,
    MasteryGradeTool,
    MasteryLeaveTool,
    MasteryPathsTool,
    MasteryQuizTool,
    MasterySkipQuestionTool,
    MasteryStatusTool,
    MasterySwitchTool,
)


def tool_payload(result):
    """A tool's structured payload, wherever that tool carries it.

    ``mastery_quiz`` now poses the question itself, so its body is prose for
    the tutor and its payload rides in metadata. Every other tool still
    returns it as JSON content.
    """
    payload = (result.metadata or {}).get("mastery_quiz")
    return payload if isinstance(payload, dict) else json.loads(result.content)


def posed_card(result):
    """The learner-facing card ``mastery_quiz`` put in front of them."""
    return (result.metadata or {}).get("mastery_question")


@pytest.fixture
def path_id(tmp_path, monkeypatch):
    """Point the LearningStore at a temp workspace and yield a stable path id."""
    monkeypatch.setattr(LearningStore, "__init__", _store_init_factory(tmp_path))
    from deeptutor.learning import semantic_assessment

    async def judge(_config, items):
        verdicts = {}
        for item in items:
            if (item.get("expected_answer"), item["answer"]) in {("4", "5"), ("0", "1")}:
                result = "incorrect"
            elif item["answer"] == "XOR is exclusive or.":
                result = "correct"
            else:
                raise AssertionError(f"Add an explicit offline assessment case: {item!r}")
            verdicts[item["question_id"]] = semantic_assessment.Verdict(
                result=result, confidence=0.99, feedback="Checked the supplied explanation."
            )
        return verdicts

    monkeypatch.setattr(semantic_assessment, "judge_answers", judge)
    return "test_path"


@pytest.fixture
def session_store(tmp_path, monkeypatch):
    store = SQLiteSessionStore(db_path=tmp_path / "chat.db")
    monkeypatch.setattr("deeptutor.services.session.get_sqlite_session_store", lambda: store)
    return store


def _store_init_factory(root):
    def _init(self, root_arg=None):  # mirrors LearningStore.__init__ signature
        from pathlib import Path

        self._root = Path(root) / "learning"
        self._root.mkdir(parents=True, exist_ok=True)

    return _init


async def _build_basic(path_id):
    build = MasteryBuildTool()
    return await build.execute(
        _mastery_path_id=path_id,
        mode="replace",
        modules=[
            {
                "name": "Module 1",
                "knowledge_points": [
                    {"name": "Truth tables", "type": "memory"},
                    {"name": "Why XOR matters", "type": "concept"},
                ],
            }
        ],
    )


# ── naming ──────────────────────────────────────────────────────────────────


@pytest.mark.asyncio
async def test_build_names_the_path_and_a_rebuild_keeps_that_name(path_id):
    """A rebuild replaces the map, never the identity.

    Before paths had names, the display name was the first module's — so
    rebuilding renamed the course out from under the learner, and the tutor
    could no longer find "the quadratics path" they asked to switch back to.
    """
    build = MasteryBuildTool()
    first = await build.execute(
        _mastery_path_id=path_id,
        path_name="一元二次方程基础",
        modules=[{"name": "模块一:定义", "knowledge_points": [{"name": "标准形式"}]}],
    )
    assert json.loads(first.content)["path_name"] == "一元二次方程基础"

    rebuilt = await build.execute(
        _mastery_path_id=path_id,
        mode="replace",
        path_name="配方法",
        modules=[{"name": "模块一:配方法", "knowledge_points": [{"name": "配方法解方程"}]}],
    )
    payload = json.loads(rebuilt.content)
    assert payload["path_name"] == "一元二次方程基础"
    assert payload["map"]["modules"][0]["name"] == "模块一:配方法"
    assert LearningStore().load(path_id).name == "一元二次方程基础"


@pytest.mark.asyncio
async def test_build_without_a_name_still_reports_the_derived_one(path_id):
    result = await MasteryBuildTool().execute(
        _mastery_path_id=path_id,
        modules=[{"name": "Module 1", "knowledge_points": [{"name": "Truth tables"}]}],
    )
    assert json.loads(result.content)["path_name"] == "Module 1"
    assert LearningStore().load(path_id).name == ""


@pytest.mark.asyncio
async def test_paths_listing_shows_the_stable_name(path_id):
    """What the tutor matches against when the learner names a path."""
    await MasteryBuildTool().execute(
        _mastery_path_id=path_id,
        path_name="Quadratics",
        modules=[{"name": "Module 1", "knowledge_points": [{"name": "Standard form"}]}],
    )
    await MasteryBuildTool().execute(
        _mastery_path_id=path_id,
        mode="replace",
        modules=[{"name": "Completing the square", "knowledge_points": [{"name": "Method"}]}],
    )

    payload = json.loads((await MasteryPathsTool().execute(_mastery_path_id=path_id)).content)
    assert [p["name"] for p in payload["paths"]] == ["Quadratics"]


# ── build ───────────────────────────────────────────────────────────────────


@pytest.mark.asyncio
async def test_build_creates_path(path_id):
    result = await _build_basic(path_id)
    assert result.success
    payload = json.loads(result.content)
    assert payload["knowledge_points_added"] == 2
    assert payload["map"]["counts"]["total"] == 2


@pytest.mark.asyncio
async def test_build_rejects_empty_modules(path_id):
    result = await MasteryBuildTool().execute(_mastery_path_id=path_id, modules=[])
    assert result.success is False


@pytest.mark.asyncio
async def test_build_append_keeps_existing(path_id):
    await _build_basic(path_id)
    result = await MasteryBuildTool().execute(
        _mastery_path_id=path_id,
        mode="append",
        modules=[
            {"name": "Module 2", "knowledge_points": [{"name": "Adders", "type": "procedure"}]}
        ],
    )
    payload = json.loads(result.content)
    assert payload["map"]["counts"]["total"] == 3  # 2 existing + 1 appended


@pytest.mark.asyncio
async def test_build_unknown_type_defaults_to_concept(path_id):
    result = await MasteryBuildTool().execute(
        _mastery_path_id=path_id,
        modules=[{"name": "M", "knowledge_points": [{"name": "Thing", "type": "nonsense"}]}],
    )
    kp = json.loads(result.content)["map"]["modules"][0]["knowledge_points"][0]
    assert kp["type"] == "concept"


# ── status ───────────────────────────────────────────────────────────────────


@pytest.mark.asyncio
async def test_status_empty_path_asks_for_build(path_id):
    payload = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    assert payload["status"] == "empty"


@pytest.mark.asyncio
async def test_status_points_at_first_objective(path_id):
    await _build_basic(path_id)
    payload = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    assert payload["status"] == "active"
    assert payload["next"]["action"] == "probe"
    assert payload["next"]["knowledge_point_type"] == "memory"


@pytest.mark.asyncio
async def test_no_path_id_fails_closed():
    result = await MasteryStatusTool().execute(_mastery_path_id="")
    assert result.success is False


# ── quiz + grade: the deterministic objective gate ───────────────────────────


@pytest.mark.asyncio
async def test_quiz_then_grade_drives_memory_gate(path_id):
    await _build_basic(path_id)
    status = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    kp_id = status["next"]["knowledge_point_id"]

    quiz, grade = MasteryQuizTool(), MasteryGradeTool()
    mastered = False
    for _ in range(3):
        await quiz.execute(
            _mastery_path_id=path_id,
            knowledge_point_id=kp_id,
            question="2+2?",
            expected_answer="4",
            question_type="short",
        )
        result = json.loads((await grade.execute(_mastery_path_id=path_id, answer="4")).content)
        assert result["is_correct"] is True
        mastered = result["mastered"]
    # 0.5 -> 0.8 -> 1.0 ≥ 0.9: mastered only after the third correct answer.
    assert mastered is True


@pytest.mark.asyncio
async def test_quiz_on_a_qualitative_objective_says_the_question_cannot_open_it(path_id):
    """Probing a concept with a question is allowed, but never silent.

    ``mastery_assess`` aimed at a quantitative objective is refused outright.
    The mirror direction stays permitted — a question is a fair way to check
    what the learner already knows — so the notice has to carry what the
    refusal would otherwise have said.
    """
    build = json.loads((await _build_basic(path_id)).content)
    points = build["map"]["modules"][0]["knowledge_points"]
    concept_id = next(p["id"] for p in points if p["type"] == "concept")

    result = await MasteryQuizTool().execute(
        _mastery_path_id=path_id,
        knowledge_point_id=concept_id,
        question="Why does XOR matter?",
        expected_answer="it is not linearly separable",
        question_type="short",
    )
    assert "mastery_assess" in result.content

    memory_id = next(p["id"] for p in points if p["type"] == "memory")
    await MasterySkipQuestionTool().execute(_mastery_path_id=path_id)
    quantitative = await MasteryQuizTool().execute(
        _mastery_path_id=path_id,
        knowledge_point_id=memory_id,
        question="2+2?",
        expected_answer="4",
        question_type="short",
    )
    assert "mastery_assess" not in quantitative.content


@pytest.mark.asyncio
async def test_grade_on_a_qualitative_objective_sends_the_tutor_to_assess(path_id):
    """A concept objective cannot be cleared by questions, and grading says so.

    Quiz accuracy lands in ``mastery_levels`` whatever the objective's type,
    but the qualitative gate reads ``qualitative_mastery`` — which only
    ``mastery_assess`` writes. Grading used to answer a correct attempt here by
    telling the tutor to pose the next question, which is an instruction to
    loop forever on an objective no question can clear: the conversation
    narrates progress while the outline rail, correctly, never moves.
    """
    build = json.loads((await _build_basic(path_id)).content)
    points = build["map"]["modules"][0]["knowledge_points"]
    concept_id = next(p["id"] for p in points if p["type"] == "concept")

    quiz, grade = MasteryQuizTool(), MasteryGradeTool()
    for _ in range(3):
        await quiz.execute(
            _mastery_path_id=path_id,
            knowledge_point_id=concept_id,
            question="Why does XOR matter?",
            expected_answer="it is not linearly separable",
            question_type="short",
        )
        payload = json.loads(
            (
                await grade.execute(_mastery_path_id=path_id, answer="it is not linearly separable")
            ).content
        )
        assert payload["is_correct"] is True

    # Three correct answers and the gate is still shut — by design, not by bug.
    assert payload["mastered"] is False
    assert payload["gate"] == "qualitative"
    # Which is only an interpretable reading next to the gate it is read
    # against: on its own, mastery 1.0 against threshold 1.0 says "cleared".
    assert payload["mastery"] == payload["threshold"] == 1.0
    # ``next`` is the path-wide cursor, not a verdict on the objective just
    # graded — here it still points at the untouched memory objective ahead of
    # this one. Which is exactly why the instruction has to carry the way
    # forward for *this* objective itself.
    assert payload["next"]["knowledge_point_id"] != concept_id
    assert "mastery_assess" in payload["instruction"]
    assert "mastery_quiz" not in payload["instruction"]


@pytest.mark.asyncio
async def test_grade_below_a_quantitative_gate_still_asks_for_another_question(path_id):
    """The quantitative branch is unchanged — there, more questions do clear it."""
    await _build_basic(path_id)
    status = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    kp_id = status["next"]["knowledge_point_id"]
    await MasteryQuizTool().execute(
        _mastery_path_id=path_id,
        knowledge_point_id=kp_id,
        question="2+2?",
        expected_answer="4",
        question_type="short",
    )
    payload = json.loads(
        (await MasteryGradeTool().execute(_mastery_path_id=path_id, answer="4")).content
    )
    assert payload["mastered"] is False  # 0.5 is below the 0.9 gate
    assert payload["gate"] == "quantitative"
    assert "mastery_quiz" in payload["instruction"]
    assert "mastery_assess" not in payload["instruction"]


@pytest.mark.asyncio
async def test_grade_without_pending_fails(path_id):
    await _build_basic(path_id)
    result = await MasteryGradeTool().execute(_mastery_path_id=path_id, answer="x")
    assert result.success is False


@pytest.mark.asyncio
async def test_skip_question_unblocks_registration_without_credit(path_id):
    await _build_basic(path_id)
    status = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    kp_id = status["next"]["knowledge_point_id"]
    first = tool_payload(
        (
            await MasteryQuizTool().execute(
                _mastery_path_id=path_id,
                knowledge_point_id=kp_id,
                question="First?",
                expected_answer="right",
            )
        )
    )
    from deeptutor.learning.service import LearningService

    LearningService().record_question_answer(
        path_id,
        "wrong",
        interaction_id=first["question_id"],
    )
    before = LearningStore().load(path_id)
    assert before is not None
    mastery_before = before.mastery_levels.get(kp_id, 0.0)

    result = await MasterySkipQuestionTool().execute(_mastery_path_id=path_id)
    skipped = json.loads(result.content)
    progress = LearningStore().load(path_id)
    abandoned = LearningStore().get_interaction(path_id, first["question_id"])

    assert result.success is True
    assert skipped["skipped"] is True
    assert skipped["question_id"] == first["question_id"]
    assert skipped["next"]["action"] != "answer_pending"
    assert progress is not None
    assert progress.pending_question is None
    assert progress.quiz_attempts == []
    assert progress.mastery_levels.get(kp_id, 0.0) == mastery_before
    assert abandoned is not None
    assert abandoned.status == InteractionStatus.ABANDONED
    assert LearningStore().get_active_interaction(path_id) is None

    replacement = tool_payload(
        (
            await MasteryQuizTool().execute(
                _mastery_path_id=path_id,
                knowledge_point_id=kp_id,
                question="Replacement?",
                expected_answer="right",
            )
        )
    )
    assert replacement["status"] == "registered"
    assert replacement["question_id"] != first["question_id"]


@pytest.mark.asyncio
async def test_skip_question_without_open_question_is_no_op(path_id):
    await _build_basic(path_id)
    before = LearningStore().load(path_id)
    assert before is not None

    result = await MasterySkipQuestionTool().execute(_mastery_path_id=path_id)
    payload = json.loads(result.content)
    after = LearningStore().load(path_id)

    assert result.success is True
    assert payload["skipped"] is False
    assert payload["question_id"] == ""
    assert after is not None
    assert after.version == before.version


@pytest.mark.asyncio
async def test_quiz_unknown_kp_fails(path_id):
    await _build_basic(path_id)
    result = await MasteryQuizTool().execute(
        _mastery_path_id=path_id,
        knowledge_point_id="nope",
        question="?",
        expected_answer="x",
    )
    assert result.success is False


@pytest.mark.asyncio
async def test_wrong_answer_does_not_master(path_id):
    await _build_basic(path_id)
    status = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    kp_id = status["next"]["knowledge_point_id"]
    await MasteryQuizTool().execute(
        _mastery_path_id=path_id, knowledge_point_id=kp_id, question="2+2?", expected_answer="4"
    )
    result = json.loads(
        (await MasteryGradeTool().execute(_mastery_path_id=path_id, answer="5")).content
    )
    assert result["is_correct"] is False
    assert result["mastered"] is False


@pytest.mark.asyncio
async def test_grade_syncs_mastery_attempt_to_question_bank(path_id, session_store):
    session = await session_store.create_session(title="Mastery Session")
    await _build_basic(path_id)
    status = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    kp_id = status["next"]["knowledge_point_id"]
    quiz = tool_payload(
        (
            await MasteryQuizTool().execute(
                _mastery_path_id=path_id,
                knowledge_point_id=kp_id,
                question="2+2?",
                expected_answer="4",
                question_type="short",
            )
        )
    )

    result = json.loads(
        (
            await MasteryGradeTool().execute(
                _mastery_path_id=path_id,
                _session_id=session["id"],
                _turn_id="turn_mastery_1",
                answer="5",
            )
        ).content
    )

    assert result["is_correct"] is False
    wrong_entries = await session_store.list_notebook_entries(is_correct=False)
    assert wrong_entries["total"] == 1
    entry = wrong_entries["items"][0]
    assert entry["session_title"] == "Mastery Session"
    assert entry["turn_id"] == "turn_mastery_1"
    assert entry["question"] == "2+2?"
    assert entry["question_type"] == "short_answer"
    assert entry["user_answer"] == "5"
    assert entry["correct_answer"] == "4"
    assert entry["is_correct"] is False
    assert entry["source"] == "mastery_path"
    assert entry["material_id"] == path_id
    assert entry["section_id"] == kp_id
    assert entry["section_title"] == "Truth tables"
    assert entry["assessment_type"] == "quiz"
    assert entry["result"] == "incorrect"
    assert entry["mastery_path_id"] == path_id
    assert entry["knowledge_point_id"] == kp_id

    # An idempotent retry with a changed model argument must not overwrite the
    # committed learner answer in the auxiliary question bank.
    replay = json.loads(
        (
            await MasteryGradeTool().execute(
                _mastery_path_id=path_id,
                _session_id=session["id"],
                _turn_id="turn_mastery_2",
                question_id=quiz["question_id"],
                answer="4",
            )
        ).content
    )
    assert replay["replayed"] is True
    entries_after_replay = await session_store.list_notebook_entries()
    assert entries_after_replay["total"] == 1
    assert entries_after_replay["items"][0]["user_answer"] == "5"
    assert entries_after_replay["items"][0]["is_correct"] is False


@pytest.mark.asyncio
async def test_choice_quiz_rejects_bare_option_labels(path_id):
    await _build_basic(path_id)
    status = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    kp_id = status["next"]["knowledge_point_id"]

    result = await MasteryQuizTool().execute(
        _mastery_path_id=path_id,
        knowledge_point_id=kp_id,
        question="Which order is correct?",
        expected_answer="A",
        question_type="choice",
        options=["A", "B", "C", "D"],
    )

    assert result.success is False
    assert "full option bodies" in result.content


@pytest.mark.asyncio
@pytest.mark.parametrize(
    ("type_kwargs", "expected_answer"),
    [
        ({}, "B"),
        ({"question_type": ""}, "blue"),
    ],
)
async def test_quiz_infers_choice_and_normalizes_expected_answer(
    path_id, type_kwargs, expected_answer
):
    await _build_basic(path_id)
    status = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    kp_id = status["next"]["knowledge_point_id"]

    result = await MasteryQuizTool().execute(
        _mastery_path_id=path_id,
        knowledge_point_id=kp_id,
        question="Pick a colour",
        expected_answer=expected_answer,
        options=["A: red", "B: blue"],
        **type_kwargs,
    )

    assert result.success is True
    pending = LearningStore().load(path_id).pending_question
    assert pending is not None
    assert pending.question_type == "choice"
    # Registration shuffles the options (#1691), so labels are asserted through
    # the bodies they carry instead of the order the model registered.
    assert set(pending.choice_map.values()) == {"red", "blue"}
    assert pending.choice_map[pending.expected_answer] == "blue"


@pytest.mark.asyncio
@pytest.mark.parametrize("question_type", ["short", "open"])
async def test_explicit_non_choice_without_options_is_unchanged(path_id, question_type):
    await _build_basic(path_id)
    status = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    kp_id = status["next"]["knowledge_point_id"]

    result = await MasteryQuizTool().execute(
        _mastery_path_id=path_id,
        knowledge_point_id=kp_id,
        question="Explain it",
        expected_answer="stored as written",
        question_type=question_type,
        options=[],
    )

    assert result.success is True
    pending = LearningStore().load(path_id).pending_question
    assert pending is not None
    assert pending.question_type == question_type
    assert pending.expected_answer == "stored as written"
    assert pending.options == []


@pytest.mark.asyncio
@pytest.mark.parametrize("question_type", ["short", "open"])
async def test_explicit_non_choice_rejects_options(path_id, question_type):
    await _build_basic(path_id)
    status = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    kp_id = status["next"]["knowledge_point_id"]

    result = await MasteryQuizTool().execute(
        _mastery_path_id=path_id,
        knowledge_point_id=kp_id,
        question="Explain it",
        expected_answer="answer",
        question_type=question_type,
        options=["A: first", "B: second"],
    )

    assert result.success is False
    assert "cannot be used" in result.content
    assert LearningStore().load(path_id).pending_question is None


@pytest.mark.asyncio
@pytest.mark.parametrize(
    ("options", "error"),
    [
        ("A: first, B: second", "must be an array"),
        (["A: first", "A: second", "B: third"], "must run A, B, C"),
        (["A: repeated answer", "B: repeated answer"], "same answer"),
        (["A: Repeated   answer", "B: repeated answer"], "same answer"),
        (["A: repeated\nanswer", "B: repeated answer"], "same answer"),
        (["A: Straße", "B: STRASSE"], "same answer"),
        (["A: first", "B: second", "C: first"], "same answer"),
        (["A: first", ""], "non-empty strings"),
    ],
)
async def test_choice_quiz_rejects_malformed_options(path_id, options, error):
    await _build_basic(path_id)
    status = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    kp_id = status["next"]["knowledge_point_id"]

    result = await MasteryQuizTool().execute(
        _mastery_path_id=path_id,
        knowledge_point_id=kp_id,
        question="Pick one",
        expected_answer="A",
        question_type="choice",
        options=options,
    )

    assert result.success is False
    assert error in result.content
    assert LearningStore().load(path_id).pending_question is None


@pytest.mark.asyncio
async def test_choice_quiz_accepts_ask_user_key_names(path_id):
    """``description`` is ask_user's word for the body; models mix them up.

    Rejecting the shape used to cost the learner the question outright: the
    model retried it every round until the budget was gone.
    """
    await _build_basic(path_id)
    status = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    kp_id = status["next"]["knowledge_point_id"]

    result = await MasteryQuizTool().execute(
        _mastery_path_id=path_id,
        knowledge_point_id=kp_id,
        question="How does LangGraph merge that update?",
        expected_answer="B",
        question_type="choice",
        options=[
            {"label": "A: overwrite the old value", "description": "the reducer never ran"},
            {"label": "B: concatenate both lists", "description": "the reducer ran"},
            {"label": "C: raise, the reducer rejects a list", "description": "annotation clash"},
        ],
    )

    assert result.success is True
    pending = LearningStore().load(path_id).pending_question
    assert pending is not None
    # Shuffled registration: assert through bodies, not registration order.
    assert sorted(pending.choice_map.values()) == [
        "concatenate both lists",
        "overwrite the old value",
        "raise, the reducer rejects a list",
    ]
    assert pending.choice_map[pending.expected_answer] == "concatenate both lists"
    card_options = posed_card(result)["options"]
    assert sorted(option["body"] for option in card_options) == [
        "concatenate both lists",
        "overwrite the old value",
        "raise, the reducer rejects a list",
    ]
    assert [option["label"] for option in card_options] == ["A", "B", "C"]


@pytest.mark.asyncio
async def test_choice_quiz_rejoins_bare_labels_sent_with_descriptions(path_id):
    await _build_basic(path_id)
    status = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    kp_id = status["next"]["knowledge_point_id"]

    result = await MasteryQuizTool().execute(
        _mastery_path_id=path_id,
        knowledge_point_id=kp_id,
        question="Pick a colour",
        expected_answer="blue",
        options=[{"label": "A", "description": "red"}, {"label": "B", "description": "blue"}],
    )

    assert result.success is True
    pending = LearningStore().load(path_id).pending_question
    assert pending is not None
    assert pending.question_type == "choice"
    assert set(pending.choice_map.values()) == {"red", "blue"}
    assert pending.choice_map[pending.expected_answer] == "blue"


@pytest.mark.asyncio
async def test_choice_quiz_names_an_option_it_cannot_read(path_id):
    """A rejection has to say which entry was unusable, or the retry repeats it."""
    await _build_basic(path_id)
    status = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    kp_id = status["next"]["knowledge_point_id"]

    result = await MasteryQuizTool().execute(
        _mastery_path_id=path_id,
        knowledge_point_id=kp_id,
        question="Pick one",
        expected_answer="A",
        question_type="choice",
        options=[{"note": "first"}, "B: second"],
    )

    assert result.success is False
    assert "must each be an option" in result.content
    assert "{'note': 'first'}" in result.content
    assert LearningStore().load(path_id).pending_question is None


@pytest.mark.asyncio
async def test_choice_quiz_requires_options_even_when_type_is_explicit(path_id):
    await _build_basic(path_id)
    status = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    kp_id = status["next"]["knowledge_point_id"]

    result = await MasteryQuizTool().execute(
        _mastery_path_id=path_id,
        knowledge_point_id=kp_id,
        question="Pick one",
        expected_answer="A",
        question_type="choice",
        options=[],
    )

    assert result.success is False
    assert "full option bodies" in result.content


@pytest.mark.asyncio
async def test_choice_grade_reads_an_answer_typed_in_the_composer(path_id):
    """The card is not the only way in: a typed answer must grade the same."""
    await _build_basic(path_id)
    status = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    kp_id = status["next"]["knowledge_point_id"]

    await MasteryQuizTool().execute(
        _mastery_path_id=path_id,
        knowledge_point_id=kp_id,
        question="Which is the general form?",
        expected_answer="C",
        question_type="choice",
        options=[
            "A: 3x² - 3x = 2x + 8",
            "B: 3x² - x - 8 = 0",
            "C: 3x² - 5x - 8 = 0",
            "D: 3x² - 5x + 8 = 0",
        ],
    )

    # The shuffle re-labels options, so the typed answer targets whatever
    # label the correct body carries after registration.
    expected_label = LearningStore().load(path_id).pending_question.expected_answer
    grade = await MasteryGradeTool().execute(_mastery_path_id=path_id, answer=f"选{expected_label}")
    assert grade.success is True
    assert json.loads(grade.content)["is_correct"] is True


@pytest.mark.asyncio
async def test_choice_grade_refuses_an_unreadable_answer_instead_of_failing_it(path_id):
    """An answer we cannot map to one option is unreadable, not wrong."""
    await _build_basic(path_id)
    status = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    kp_id = status["next"]["knowledge_point_id"]

    await MasteryQuizTool().execute(
        _mastery_path_id=path_id,
        knowledge_point_id=kp_id,
        question="Which is the general form?",
        expected_answer="A",
        question_type="choice",
        options=["A: 3x² - 5x - 8 = 0", "B: 3x² - 5x + 8 = 0"],
    )

    grade = await MasteryGradeTool().execute(_mastery_path_id=path_id, answer="A or B")
    assert grade.success is False
    assert "NOT graded" in grade.content
    # Nothing was recorded, so the question is still open for a real answer.
    progress = LearningStore().load(path_id)
    assert progress.pending_question is not None
    assert progress.quiz_attempts == []


@pytest.mark.asyncio
async def test_choice_quiz_preserves_bodies_and_normalizes_answer(path_id, session_store):
    session = await session_store.create_session(title="Choice Mastery")
    await _build_basic(path_id)
    status = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    kp_id = status["next"]["knowledge_point_id"]

    quiz = await MasteryQuizTool().execute(
        _mastery_path_id=path_id,
        knowledge_point_id=kp_id,
        question="Where is the stop condition added?",
        expected_answer="Step 6",
        question_type="choice",
        options=[
            "A: Step 2 — write the first tool",
            "B: Step 4 — test one call",
            "C: Step 6 — add the stop condition",
            "D: Step 7 — add another tool",
        ],
    )
    assert quiz.success is True

    # Registration shuffles, so the submission targets the correct body's
    # post-shuffle label and the notebook assertions follow the stored map.
    pending_after_quiz = LearningStore().load(path_id).pending_question
    choice_map = pending_after_quiz.choice_map
    expected_label = pending_after_quiz.expected_answer
    grade = json.loads(
        (
            await MasteryGradeTool().execute(
                _mastery_path_id=path_id,
                _session_id=session["id"],
                _turn_id="turn_choice_1",
                answer=expected_label,
            )
        ).content
    )
    assert grade["is_correct"] is True

    entries = await session_store.list_notebook_entries()
    entry = entries["items"][0]
    assert entry["options"] == choice_map
    assert entry["correct_answer"] == expected_label
    assert entry["user_answer"] == expected_label
    assert entry["is_correct"] is True


@pytest.mark.asyncio
async def test_pending_choice_status_reuses_public_contract_without_answer(path_id):
    await _build_basic(path_id)
    initial = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    kp_id = initial["next"]["knowledge_point_id"]

    result = await MasteryQuizTool().execute(
        _mastery_path_id=path_id,
        knowledge_point_id=kp_id,
        question="Pick a colour",
        expected_answer="blue",
        question_type="choice",
        options=["A: red", "B: blue"],
    )
    registered = tool_payload(result)
    status = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)

    pending = status["next"]["pending_question"]
    assert pending == registered["pending_question"]
    # Posing the question and registering it are the same call: the turn ends
    # on a card derived from what was just persisted.
    card = posed_card(result)
    assert card is not None
    # The card is mastery's own shape on its own key — it no longer doubles as
    # an ask_user payload.
    assert "questions" not in card
    assert card["question_id"] == pending["question_id"]
    assert card["prompt"] == "Pick a colour"
    assert card["allow_free_text"] is True
    card_options = card["options"]
    assert [option["label"] for option in card_options] == ["A", "B"]
    assert sorted(option["body"] for option in card_options) == ["blue", "red"]
    assert card["objective"]["id"] == kp_id
    assert card["attempt"] == 1
    # The answer key never travels to the learner.
    rendered = json.dumps(card, ensure_ascii=False)
    assert "expected_answer" not in rendered
    assert "expected_answer" not in registered
    assert "expected_answer" not in pending


@pytest.mark.asyncio
async def test_choice_grade_accepts_unique_persisted_body(path_id):
    await _build_basic(path_id)
    initial = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    kp_id = initial["next"]["knowledge_point_id"]
    quiz = tool_payload(
        (
            await MasteryQuizTool().execute(
                _mastery_path_id=path_id,
                knowledge_point_id=kp_id,
                question="Pick a colour",
                expected_answer="B",
                question_type="choice",
                options=["A: red", "B: blue"],
            )
        )
    )

    grade = json.loads(
        (
            await MasteryGradeTool().execute(
                _mastery_path_id=path_id,
                question_id=quiz["question_id"],
                answer="blue",
            )
        ).content
    )

    assert grade["is_correct"] is True


@pytest.mark.asyncio
async def test_choice_grade_rejects_stale_question_id_without_clearing_pending(path_id):
    await _build_basic(path_id)
    initial = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    kp_id = initial["next"]["knowledge_point_id"]
    await MasteryQuizTool().execute(
        _mastery_path_id=path_id,
        knowledge_point_id=kp_id,
        question="Pick a colour",
        expected_answer="B",
        question_type="choice",
        options=["A: red", "B: blue"],
    )

    grade = await MasteryGradeTool().execute(
        _mastery_path_id=path_id,
        question_id="stale-question",
        answer="B",
    )

    assert grade.success is False
    assert LearningStore().load(path_id).pending_question is not None


@pytest.mark.asyncio
async def test_choice_grade_keeps_legacy_bare_label_pending_compatible(path_id):
    await _build_basic(path_id)
    progress = LearningStore().load(path_id)
    assert progress is not None
    kp_id = progress.modules[0].knowledge_points[0].id
    progress.pending_question = PendingQuestion(
        question_id="legacy-question",
        knowledge_point_id=kp_id,
        module_id=progress.modules[0].id,
        prompt="Legacy choice",
        question_type="choice",
        expected_answer="B",
        options=["A", "B"],
    )
    LearningStore().save(progress)

    grade = json.loads(
        (
            await MasteryGradeTool().execute(
                _mastery_path_id=path_id,
                question_id="legacy-question",
                answer="B",
            )
        ).content
    )

    assert grade["is_correct"] is True


@pytest.mark.asyncio
async def test_a_repeat_quiz_call_says_it_posed_nothing(path_id):
    """The second call in a round must not read like a fresh question.

    The engine holds one open question per path, so a repeat call re-presents
    the existing card. Reported with the same wording as a new question, a
    model that had already posed one this round could not tell that its extra
    call did nothing — and kept making it.
    """
    await _build_basic(path_id)
    initial = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    kp_id = initial["next"]["knowledge_point_id"]

    posed = await MasteryQuizTool().execute(
        _mastery_path_id=path_id,
        _session_id="session-1",
        _turn_id="turn-1",
        knowledge_point_id=kp_id,
        question="2+2?",
        expected_answer="4",
    )
    repeated = await MasteryQuizTool().execute(
        _mastery_path_id=path_id,
        _session_id="session-1",
        _turn_id="turn-1",
        knowledge_point_id=kp_id,
        question="a different question",
        expected_answer="5",
    )

    assert "on the learner's answer card" in posed.content
    assert "No new question was posed" in repeated.content
    assert "do not call any further tools after mastery_quiz" in repeated.content
    # Both still end the turn: the card is in front of the learner either way.
    assert tool_payload(repeated)["status"] == "already_pending"


@pytest.mark.asyncio
async def test_quiz_strips_options_restated_in_the_question(path_id):
    """A stem that repeats its options would show every choice twice."""
    await _build_basic(path_id)
    initial = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    kp_id = initial["next"]["knowledge_point_id"]

    result = await MasteryQuizTool().execute(
        _mastery_path_id=path_id,
        _session_id="session-1",
        _turn_id="turn-1",
        knowledge_point_id=kp_id,
        question="Which one accumulates? A: plain list B: Annotated with a reducer",
        expected_answer="B",
        options=["A: plain list", "B: Annotated with a reducer"],
    )

    stem = tool_payload(result)["pending_question"]["prompt"]
    assert stem == "Which one accumulates?"
    # The options themselves are untouched; only the duplicate prose is gone.
    card = posed_card(result)
    assert "your question text also listed the options" in result.content
    assert card is not None


@pytest.mark.asyncio
async def test_duplicate_quiz_and_grade_are_idempotent(path_id):
    await _build_basic(path_id)
    initial = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    kp_id = initial["next"]["knowledge_point_id"]

    first_quiz = tool_payload(
        (
            await MasteryQuizTool().execute(
                _mastery_path_id=path_id,
                _session_id="session-1",
                _turn_id="turn-1",
                knowledge_point_id=kp_id,
                question="2+2?",
                expected_answer="4",
            )
        )
    )
    retry_quiz = tool_payload(
        (
            await MasteryQuizTool().execute(
                _mastery_path_id=path_id,
                _session_id="session-1",
                _turn_id="turn-1",
                knowledge_point_id=kp_id,
                question="A model-authored replacement must not win",
                expected_answer="5",
            )
        )
    )
    assert retry_quiz["question_id"] == first_quiz["question_id"]
    assert retry_quiz["pending_question"]["prompt"] == "2+2?"
    assert retry_quiz["status"] == "already_pending"

    first_grade = json.loads(
        (
            await MasteryGradeTool().execute(
                _mastery_path_id=path_id,
                _session_id="session-1",
                _turn_id="turn-1",
                question_id=first_quiz["question_id"],
                answer="4",
            )
        ).content
    )
    retry_grade = json.loads(
        (
            await MasteryGradeTool().execute(
                _mastery_path_id=path_id,
                _session_id="session-1",
                _turn_id="turn-1",
                question_id=first_quiz["question_id"],
                answer="4",
            )
        ).content
    )

    progress = LearningStore().load(path_id)
    interaction = LearningStore().get_interaction(path_id, first_quiz["question_id"])
    assert progress is not None
    assert len(progress.quiz_attempts) == 1
    assert retry_grade["replayed"] is True
    assert retry_grade["path_revision"] == first_grade["path_revision"]
    assert interaction is not None
    assert interaction.status == InteractionStatus.GRADED
    assert LearningStore().get_active_interaction(path_id) is None


@pytest.mark.asyncio
async def test_new_quiz_repairs_stale_legacy_pending_after_grade(path_id):
    await _build_basic(path_id)
    initial = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    kp_id = initial["next"]["knowledge_point_id"]
    first = tool_payload(
        (
            await MasteryQuizTool().execute(
                _mastery_path_id=path_id,
                knowledge_point_id=kp_id,
                question="First?",
                expected_answer="yes",
            )
        )
    )
    await MasteryGradeTool().execute(
        _mastery_path_id=path_id,
        question_id=first["question_id"],
        answer="yes",
    )
    store = LearningStore()
    progress = store.load(path_id)
    graded = store.get_interaction(path_id, first["question_id"])
    assert progress is not None and graded is not None
    progress.pending_question = graded.question
    store.save(progress)

    second_result = await MasteryQuizTool().execute(
        _mastery_path_id=path_id,
        knowledge_point_id=kp_id,
        question="Second?",
        expected_answer="yes",
    )
    second = tool_payload(second_result)

    assert second_result.success is True
    assert second["status"] == "registered"
    assert second["question_id"] != first["question_id"]


@pytest.mark.asyncio
async def test_status_recovers_answered_interaction_without_exposing_answer_key(path_id):
    await _build_basic(path_id)
    initial = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    kp_id = initial["next"]["knowledge_point_id"]
    quiz = tool_payload(
        (
            await MasteryQuizTool().execute(
                _mastery_path_id=path_id,
                knowledge_point_id=kp_id,
                question="2+2?",
                expected_answer="4",
            )
        )
    )
    from deeptutor.learning.service import LearningService

    LearningService().record_question_answer(
        path_id,
        "4",
        interaction_id=quiz["question_id"],
    )

    recovered = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    assert recovered["pending_interaction"] == {
        "question_id": quiz["question_id"],
        "status": "answered",
        "learner_answer": "4",
    }
    assert "expected_answer" not in json.dumps(recovered)

    # The committed learner reply is authoritative even if a later model
    # round accidentally paraphrases or changes the tool argument.
    graded = json.loads(
        (
            await MasteryGradeTool().execute(
                _mastery_path_id=path_id,
                question_id=quiz["question_id"],
                answer="5",
            )
        ).content
    )
    assert graded["is_correct"] is True


@pytest.mark.asyncio
async def test_grade_recovers_unreadable_choice_answer(path_id):
    """An unreadable clarifying commit must not permanently block grading (#1004)."""
    await _build_basic(path_id)
    initial = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    kp_id = initial["next"]["knowledge_point_id"]
    quiz = tool_payload(
        (
            await MasteryQuizTool().execute(
                _mastery_path_id=path_id,
                knowledge_point_id=kp_id,
                question="Compute (2e^{iπ/3})³",
                expected_answer="A",
                options=["A: -8", "B: -6", "C: 8", "D: -2"],
            )
        )
    )
    from deeptutor.learning.service import LearningService

    # Simulate the pre-fix deadlock: clarifying prose already persisted.
    LearningService().record_question_answer(
        path_id,
        "先告诉我三角恒等式是什么?",
        interaction_id=quiz["question_id"],
    )
    stuck = LearningStore().get_interaction(path_id, quiz["question_id"])
    assert stuck is not None
    assert stuck.status == InteractionStatus.ANSWERED

    blocked = await MasteryGradeTool().execute(
        _mastery_path_id=path_id,
        question_id=quiz["question_id"],
        answer="先告诉我三角恒等式是什么?",
    )
    assert blocked.success is False
    assert "NOT graded" in blocked.content

    # The shuffle re-labels options, so the recovery answers with whatever
    # label the correct body ("-8") carries after registration.
    expected_label = LearningStore().load(path_id).pending_question.expected_answer
    recovered = json.loads(
        (
            await MasteryGradeTool().execute(
                _mastery_path_id=path_id,
                question_id=quiz["question_id"],
                answer=expected_label,
            )
        ).content
    )
    assert recovered["is_correct"] is True
    graded = LearningStore().get_interaction(path_id, quiz["question_id"])
    assert graded is not None
    assert graded.status == InteractionStatus.GRADED
    assert graded.user_answer == expected_label


# ── assess: the qualitative gate ─────────────────────────────────────────────


@pytest.mark.asyncio
async def test_assess_passes_concept(path_id):
    await _build_basic(path_id)
    # Drive past the memory objective so status reaches the concept one.
    status = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    mem_kp = status["next"]["knowledge_point_id"]
    for _ in range(3):
        await MasteryQuizTool().execute(
            _mastery_path_id=path_id, knowledge_point_id=mem_kp, question="q", expected_answer="a"
        )
        await MasteryGradeTool().execute(_mastery_path_id=path_id, answer="a")

    status2 = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    concept_kp = status2["next"]["knowledge_point_id"]
    assert status2["next"]["action"] == "probe"
    assert status2["next"]["knowledge_point_type"] == "concept"

    result = json.loads(
        (
            await MasteryAssessTool().execute(
                _mastery_path_id=path_id,
                knowledge_point_id=concept_kp,
                passed=True,
                feedback="ok",
                _learner_message="XOR is exclusive or.",
            )
        ).content
    )
    assert result["mastered"] is True
    assert result["next"]["action"] == "complete"
    progress = LearningStore().load(path_id)
    assert progress is not None
    assert progress.repetition_states[concept_kp].review_count == 1
    assert [task.knowledge_point_id for task in progress.review_queue] == [mem_kp, concept_kp]


@pytest.mark.asyncio
async def test_assess_rejects_quantitative_type(path_id):
    await _build_basic(path_id)
    status = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    mem_kp = status["next"]["knowledge_point_id"]  # a memory objective
    result = await MasteryAssessTool().execute(
        _mastery_path_id=path_id, knowledge_point_id=mem_kp, passed=True
    )
    assert result.success is False


@pytest.mark.asyncio
async def test_assess_syncs_qualitative_record_to_question_bank(path_id, session_store):
    session = await session_store.create_session(title="Qualitative Session")
    await _build_basic(path_id)
    status = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    mem_kp = status["next"]["knowledge_point_id"]
    for _ in range(3):
        await MasteryQuizTool().execute(
            _mastery_path_id=path_id, knowledge_point_id=mem_kp, question="q", expected_answer="a"
        )
        await MasteryGradeTool().execute(
            _mastery_path_id=path_id,
            _session_id=session["id"],
            _turn_id="turn_mem",
            answer="a",
        )

    status2 = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    concept_kp = status2["next"]["knowledge_point_id"]
    await MasteryAssessTool().execute(
        _mastery_path_id=path_id,
        _session_id=session["id"],
        _turn_id="turn_qual",
        _learner_message="XOR is exclusive or.",
        knowledge_point_id=concept_kp,
        passed=True,
        feedback="XOR is exclusive or.",
    )
    await MasteryAssessTool().execute(
        _mastery_path_id=path_id,
        _session_id=session["id"],
        _turn_id="turn_qual",
        _learner_message="XOR is exclusive or.",
        knowledge_point_id=concept_kp,
        passed=True,
        feedback="XOR is exclusive or.",
    )

    qualitative = await session_store.list_notebook_entries(assessment_type="qualitative")
    assert qualitative["total"] == 1
    entry = qualitative["items"][0]
    assert entry["source"] == "mastery_path"
    assert entry["result"] == "correct"
    assert entry["mastery_path_id"] == path_id
    assert entry["knowledge_point_id"] == concept_kp
    assert entry["question_id"] == f"qual:{concept_kp}"
    assert entry["user_answer"] == "XOR is exclusive or."
    assert entry["quality"] == 1.0
    progress = LearningStore().load(path_id)
    assert progress is not None
    assert progress.repetition_states[concept_kp].review_count == 1
    assert (
        len([item for item in progress.learning_evidence if item.knowledge_point_id == concept_kp])
        == 1
    )


# ── path switching: a conversation is not bound to one path ───────────────


async def _build_named(path_id: str, module_name: str) -> None:
    await MasteryBuildTool().execute(
        _mastery_path_id=path_id,
        mode="replace",
        modules=[
            {
                "name": module_name,
                "knowledge_points": [{"name": f"{module_name} basics", "type": "concept"}],
            }
        ],
    )


@pytest.mark.asyncio
async def test_paths_tool_reports_every_path_and_marks_the_active_one(path_id):
    await _build_named("calculus", "Calculus")
    await _build_named("algebra", "Algebra")

    payload = json.loads((await MasteryPathsTool().execute(_mastery_path_id="algebra")).content)

    assert payload["active_path_id"] == "algebra"
    by_id = {entry["path_id"]: entry for entry in payload["paths"]}
    assert by_id.keys() == {"calculus", "algebra"}
    assert by_id["algebra"]["active"] is True
    assert by_id["calculus"]["active"] is False
    assert by_id["calculus"]["objectives"] == 1
    assert by_id["calculus"]["mastered"] == 0


@pytest.mark.asyncio
async def test_paths_tool_hides_paths_with_nothing_to_teach(path_id):
    await _build_named("calculus", "Calculus")
    # A conversation-owned scratch path exists as soon as a mastery turn runs,
    # long before anyone builds objectives into it.
    with LearningStore().transaction("empty_scratch", create=True):
        pass

    payload = json.loads((await MasteryPathsTool().execute(_mastery_path_id="calculus")).content)

    assert [entry["path_id"] for entry in payload["paths"]] == ["calculus"]


@pytest.mark.asyncio
async def test_switch_rebinds_the_running_turn_and_hands_over_the_lease(path_id, session_store):
    await _build_named("calculus", "Calculus")
    await _build_named("algebra", "Algebra")
    store = LearningStore()
    store.acquire_path_lease("calculus", "session-1", "turn-1")
    bound: list[str] = []

    result = await MasterySwitchTool().execute(
        path_id="algebra",
        _mastery_path_id="calculus",
        _session_id="session-1",
        _turn_id="turn-1",
        _bind_active_path=bound.append,
    )

    assert result.success
    payload = json.loads(result.content)
    assert payload["previous_path_id"] == "calculus"
    assert payload["active_path_id"] == "algebra"
    # The rest of THIS turn must operate on the new path...
    assert bound == ["algebra"]
    # ...and exclusion moves with it, rather than being held on both or neither.
    assert store.get_path_lease("calculus") is None
    assert store.get_path_lease("algebra").turn_id == "turn-1"


@pytest.mark.asyncio
async def test_switch_to_an_unknown_path_changes_nothing(path_id):
    await _build_named("calculus", "Calculus")
    store = LearningStore()
    store.acquire_path_lease("calculus", "session-1", "turn-1")
    bound: list[str] = []

    result = await MasterySwitchTool().execute(
        path_id="not_a_path",
        _mastery_path_id="calculus",
        _session_id="session-1",
        _turn_id="turn-1",
        _bind_active_path=bound.append,
    )

    assert not result.success
    assert "mastery_paths" in result.content
    assert bound == []
    assert store.get_path_lease("calculus").turn_id == "turn-1"


@pytest.mark.asyncio
async def test_switch_into_a_path_busy_elsewhere_keeps_the_current_one(path_id):
    await _build_named("calculus", "Calculus")
    await _build_named("algebra", "Algebra")
    store = LearningStore()
    store.acquire_path_lease("calculus", "session-1", "turn-1")
    store.acquire_path_lease("algebra", "session-2", "turn-2")
    bound: list[str] = []

    result = await MasterySwitchTool().execute(
        path_id="algebra",
        _mastery_path_id="calculus",
        _session_id="session-1",
        _turn_id="turn-1",
        _bind_active_path=bound.append,
    )

    assert not result.success
    assert "another conversation" in result.content
    assert bound == []
    # Rolled back onto the path the learner was already on.
    assert store.get_path_lease("calculus").turn_id == "turn-1"
    assert store.get_path_lease("algebra").turn_id == "turn-2"


@pytest.mark.asyncio
async def test_leave_falls_back_to_the_conversation_scratch_path(path_id, session_store):
    await _build_named("calculus", "Calculus")
    store = LearningStore()
    store.acquire_path_lease("calculus", "session-1", "turn-1")
    bound: list[str] = []

    result = await MasteryLeaveTool().execute(
        _mastery_path_id="calculus",
        _session_id="session-1",
        _turn_id="turn-1",
        _bind_active_path=bound.append,
    )

    assert result.success
    payload = json.loads(result.content)
    assert payload["previous_path_id"] == "calculus"
    assert payload["active_path_id"] == "session-1"
    assert bound == ["session-1"]
    # The course keeps everything and stays resumable.
    assert store.load("calculus") is not None
    assert store.get_path_lease("calculus") is None
    assert store.get_path_lease("session-1").turn_id == "turn-1"


@pytest.mark.asyncio
async def test_leave_makes_the_conversation_own_its_scratch_path(path_id, session_store):
    """Otherwise leaving strews empty orphan paths that nothing cleans up."""
    await _build_named("calculus", "Calculus")
    store = LearningStore()
    store.acquire_path_lease("calculus", "session-1", "turn-1")

    await MasteryLeaveTool().execute(
        _mastery_path_id="calculus",
        _session_id="session-1",
        _turn_id="turn-1",
        _bind_active_path=lambda _path_id: None,
    )
    removed = store.detach_session("session-1", delete_owned_orphans=True)

    assert removed == ["session-1"]
    assert store.exists("session-1") is False
    assert store.exists("calculus") is True


@pytest.mark.asyncio
async def test_quiz_explanation_reaches_the_question_bank(path_id, session_store):
    """A mastery mistake must be reviewable, not just scored.

    The sync used to hard-code ``explanation`` and ``difficulty`` to empty, so
    every question the mastery path contributed to the bank showed a bare
    right/wrong with nothing saying why.
    """
    await _build_basic(path_id)
    session = await session_store.create_session(title="Mastery Session")
    status = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    kp_id = status["next"]["knowledge_point_id"]

    posed = await MasteryQuizTool().execute(
        _mastery_path_id=path_id,
        knowledge_point_id=kp_id,
        question="What does NAND return for (1, 1)?",
        expected_answer="0",
        question_type="short",
        explanation="NAND is NOT AND, so two true inputs give false.",
        difficulty="medium",
    )
    quiz = tool_payload(posed)

    # The reference explanation is answer-adjacent: it must never ride along
    # on the card the learner is about to answer.
    rendered = json.dumps(posed_card(posed), ensure_ascii=False)
    assert "NOT AND" not in rendered
    assert "NOT AND" not in json.dumps(quiz["pending_question"], ensure_ascii=False)
    # Difficulty is shown, so it has to reach the card.
    assert posed_card(posed)["difficulty"] == "medium"

    await MasteryGradeTool().execute(
        _mastery_path_id=path_id,
        _session_id=session["id"],
        _turn_id="turn_mastery_1",
        question_id=quiz["question_id"],
        answer="1",
    )

    entry = (await session_store.list_notebook_entries())["items"][0]
    assert entry["is_correct"] is False
    assert entry["explanation"] == "NAND is NOT AND, so two true inputs give false."
    assert entry["difficulty"] == "medium"


@pytest.mark.asyncio
async def test_unusable_difficulty_is_dropped_not_rejected(path_id, session_store):
    """A mislabelled difficulty must never cost the learner the question."""
    await _build_basic(path_id)
    session = await session_store.create_session(title="Mastery Session")
    status = json.loads((await MasteryStatusTool().execute(_mastery_path_id=path_id)).content)
    kp_id = status["next"]["knowledge_point_id"]

    quiz = tool_payload(
        (
            await MasteryQuizTool().execute(
                _mastery_path_id=path_id,
                knowledge_point_id=kp_id,
                question="2+2?",
                expected_answer="4",
                question_type="short",
                difficulty="extremely tricky",
            )
        )
    )
    assert quiz["status"] == "registered"

    await MasteryGradeTool().execute(
        _mastery_path_id=path_id,
        _session_id=session["id"],
        _turn_id="turn_mastery_1",
        question_id=quiz["question_id"],
        answer="5",
    )
    entry = (await session_store.list_notebook_entries())["items"][0]
    assert entry["difficulty"] == ""


@pytest.mark.asyncio
async def test_pending_question_without_explanation_still_deserializes(path_id):
    """Paths persisted before the field existed must load unchanged."""
    legacy = PendingQuestion.model_validate(
        {
            "question_id": "q1",
            "knowledge_point_id": "kp1",
            "prompt": "old question",
            "expected_answer": "yes",
        }
    )
    assert legacy.explanation == ""
    assert legacy.difficulty == ""


# ── revising one module's waypoints ─────────────────────────────────────────


async def _build_with_objective(path_id):
    build = MasteryBuildTool()
    return await build.execute(
        _mastery_path_id=path_id,
        path_name="命题逻辑",
        modules=[
            {
                "name": "布尔基础",
                "objective": "读懂一个真值表并判断两个命题是否等价",
                "knowledge_points": [
                    {"name": "真值表", "type": "memory"},
                    {"name": "XOR 的意义", "type": "concept"},
                ],
            }
        ],
    )


@pytest.mark.asyncio
async def test_build_keeps_the_module_objective(path_id):
    """The objective is the contract a revision is later measured against, so
    it has to survive the build that wrote it."""
    payload = json.loads((await _build_with_objective(path_id)).content)
    module = payload["map"]["modules"][0]
    assert module["objective"] == "读懂一个真值表并判断两个命题是否等价"


@pytest.mark.asyncio
async def test_revise_rewrites_a_waypoint_and_resets_only_its_progress(path_id):
    from deeptutor.tools.mastery_tool import MasteryReviseTool

    built = json.loads((await _build_with_objective(path_id)).content)
    module = built["map"]["modules"][0]
    target = module["knowledge_points"][1]

    revised = await MasteryReviseTool().execute(
        _mastery_path_id=path_id,
        module_id=module["id"],
        rewrite=[
            {
                "knowledge_point_id": target["id"],
                "name": "用 XOR 判断两个命题何时等价",
                "type": "procedure",
            }
        ],
    )
    payload = json.loads(revised.content)
    assert payload["status"] == "revised"
    # The promise the revision had to stay inside is echoed back with it.
    assert payload["module_objective"] == "读懂一个真值表并判断两个命题是否等价"
    names = [kp["name"] for kp in payload["knowledge_points"]]
    assert names == ["真值表", "用 XOR 判断两个命题何时等价"]
    # A restated waypoint is a different waypoint: fresh id, progress reset,
    # and the tutor is told so it can say so.
    assert payload["knowledge_points"][1]["id"] != target["id"]
    assert payload["knowledge_points"][1]["type"] == "procedure"
    assert payload["progress_reset"] == ["XOR 的意义"]
    # The untouched waypoint keeps its identity, and so its evidence.
    assert payload["knowledge_points"][0]["id"] == module["knowledge_points"][0]["id"]


@pytest.mark.asyncio
async def test_build_append_resolves_client_refs_to_final_map_ids(path_id):
    from deeptutor.tools.mastery_tool import MasteryBuildTool

    await MasteryBuildTool().execute(
        _mastery_path_id=path_id,
        modules=[{"name": "Foundations", "knowledge_points": [{"name": "Vectors"}]}],
    )

    built = await MasteryBuildTool().execute(
        _mastery_path_id=path_id,
        mode="append",
        modules=[
            {
                "name": "Products",
                "knowledge_points": [
                    {
                        "client_ref": "dot-product",
                        "name": "Dot product",
                        "prerequisite_refs": ["test_path_m0_kp0"],
                    }
                ],
            }
        ],
    )

    assert built.success, built.content
    payload = json.loads(built.content)
    modules = payload["map"]["modules"]
    appended = modules[1]["knowledge_points"][0]
    assert appended["id"] == "test_path_m1_kp0"
    assert appended["prerequisite_ids"] == [modules[0]["knowledge_points"][0]["id"]]


@pytest.mark.asyncio
async def test_revise_rewrites_edges_across_modules(path_id):
    from deeptutor.tools.mastery_tool import MasteryBuildTool, MasteryReviseTool

    await MasteryBuildTool().execute(
        _mastery_path_id=path_id,
        modules=[
            {"name": "Foundations", "knowledge_points": [{"name": "Sets"}]},
            {"name": "Relations", "knowledge_points": [{"name": "Functions"}]},
        ],
    )
    await MasteryBuildTool().execute(
        _mastery_path_id=path_id,
        mode="append",
        modules=[
            {
                "name": "Applications",
                "knowledge_points": [
                    {
                        "name": "Composition",
                        "prerequisite_refs": ["test_path_m0_kp0"],
                    }
                ],
            }
        ],
    )

    revised = await MasteryReviseTool().execute(
        _mastery_path_id=path_id,
        module_id="test_path_m0",
        rewrite=[{"knowledge_point_id": "test_path_m0_kp0", "name": "Sets and subsets"}],
    )

    payload = json.loads(revised.content)
    rewritten = payload["map"]["modules"][0]["knowledge_points"][0]
    dependent = payload["map"]["modules"][2]["knowledge_points"][0]
    assert rewritten["id"] != "test_path_m0_kp0"
    assert dependent["prerequisite_ids"] == [rewritten["id"]]


@pytest.mark.asyncio
async def test_revise_remove_reports_every_dependent_across_modules(path_id):
    from deeptutor.tools.mastery_tool import MasteryBuildTool, MasteryReviseTool

    await MasteryBuildTool().execute(
        _mastery_path_id=path_id,
        modules=[
            {"name": "Foundations", "knowledge_points": [{"name": "Sets"}]},
            {"name": "Relations", "knowledge_points": [{"name": "Functions"}]},
        ],
    )
    await MasteryBuildTool().execute(
        _mastery_path_id=path_id,
        mode="append",
        modules=[
            {
                "name": "Applications",
                "knowledge_points": [
                    {"name": "Composition", "prerequisite_refs": ["test_path_m0_kp0"]},
                    {"name": "Inverses", "prerequisite_refs": ["test_path_m0_kp0"]},
                ],
            }
        ],
    )

    refused = await MasteryReviseTool().execute(
        _mastery_path_id=path_id,
        module_id="test_path_m0",
        remove=["test_path_m0_kp0"],
    )

    assert refused.success is False
    assert "Composition" in refused.content
    assert "Inverses" in refused.content
    assert "Remove or change" in refused.content


@pytest.mark.asyncio
async def test_revise_relation_omission_inherits_and_empty_clears(path_id):
    from deeptutor.tools.mastery_tool import MasteryBuildTool, MasteryReviseTool

    await MasteryBuildTool().execute(
        _mastery_path_id=path_id,
        modules=[
            {
                "name": "Logic",
                "knowledge_points": [
                    {"client_ref": "truth-tables", "name": "Truth tables"},
                    {
                        "name": "Equivalence",
                        "prerequisite_refs": ["truth-tables"],
                    },
                ],
            }
        ],
    )
    inherited = await MasteryReviseTool().execute(
        _mastery_path_id=path_id,
        module_id="test_path_m0",
        rewrite=[{"knowledge_point_id": "test_path_m0_kp1", "name": "Logical equivalence"}],
    )
    assert inherited.success, inherited.content
    inherited_point = json.loads(inherited.content)["knowledge_points"][1]
    assert inherited_point["prerequisite_ids"] == ["test_path_m0_kp0"]

    cleared = await MasteryReviseTool().execute(
        _mastery_path_id=path_id,
        module_id="test_path_m0",
        rewrite=[
            {
                "knowledge_point_id": inherited_point["id"],
                "name": "Logical equivalence without a required prerequisite",
                "prerequisite_ids": [],
            }
        ],
    )
    cleared_point = json.loads(cleared.content)["knowledge_points"][1]
    assert cleared_point["prerequisite_ids"] == []


@pytest.mark.asyncio
async def test_revise_adds_and_removes_within_one_module(path_id):
    from deeptutor.tools.mastery_tool import MasteryReviseTool

    built = json.loads((await _build_with_objective(path_id)).content)
    module = built["map"]["modules"][0]

    revised = await MasteryReviseTool().execute(
        _mastery_path_id=path_id,
        module_id=module["id"],
        remove=[module["knowledge_points"][0]["id"]],
        add=[{"name": "德摩根定律", "type": "memory"}],
    )
    payload = json.loads(revised.content)
    assert [kp["name"] for kp in payload["knowledge_points"]] == ["XOR 的意义", "德摩根定律"]
    assert payload["progress_reset"] == []


@pytest.mark.asyncio
async def test_revise_refuses_to_erase_a_mastered_waypoint(path_id):
    """Proven work is the one thing a passing dislike must not delete."""
    from deeptutor.tools.mastery_tool import MasteryReviseTool

    built = json.loads((await _build_with_objective(path_id)).content)
    module = built["map"]["modules"][0]
    concept = module["knowledge_points"][1]

    assessed = await MasteryAssessTool().execute(
        _mastery_path_id=path_id,
        knowledge_point_id=concept["id"],
        _learner_message="XOR is exclusive or.",
        passed=True,
        explanation="学习者说清楚了 XOR 与等价的关系。",
    )
    assert json.loads(assessed.content)["mastered"] is True

    refused = await MasteryReviseTool().execute(
        _mastery_path_id=path_id,
        module_id=module["id"],
        rewrite=[{"knowledge_point_id": concept["id"], "name": "换一个说法"}],
    )
    assert refused.success is False
    assert "already mastered" in refused.content
    # …and nothing moved: the waypoint keeps both its id and its pass.
    status = tool_payload(await MasteryStatusTool().execute(_mastery_path_id=path_id))
    survivor = status["map"]["modules"][0]["knowledge_points"][1]
    assert survivor["id"] == concept["id"]
    assert survivor["status"] == "mastered"


@pytest.mark.asyncio
async def test_revise_rejects_an_unknown_module_by_listing_the_real_ones(path_id):
    from deeptutor.tools.mastery_tool import MasteryReviseTool

    await _build_with_objective(path_id)
    result = await MasteryReviseTool().execute(
        _mastery_path_id=path_id,
        module_id="not_a_module",
        remove=["whatever"],
    )
    assert result.success is False
    assert "布尔基础" in result.content


# ── intake: who is learning this goal ───────────────────────────────────────


@pytest.mark.asyncio
async def test_status_asks_for_intake_until_the_learner_has_been_asked(path_id):
    """A goal nobody has been asked about must say so, not quietly design a
    route for an average learner who does not exist."""
    from deeptutor.tools.mastery_tool import MasteryProfileTool

    before = tool_payload(await MasteryStatusTool().execute(_mastery_path_id=path_id))
    assert before["intake_needed"] is True
    assert before["learner_profile"] is None
    assert "how much time" in before["intake_instruction"]

    await MasteryProfileTool().execute(
        _mastery_path_id=path_id,
        prior_knowledge="矩阵乘法会,特征值忘了",
        time_budget="两周,每天晚上一小时",
    )
    after = tool_payload(await MasteryStatusTool().execute(_mastery_path_id=path_id))
    assert after["intake_needed"] is False
    assert after["learner_profile"]["time_budget"] == "两周,每天晚上一小时"


@pytest.mark.asyncio
async def test_the_profile_travels_with_every_status_call_not_just_the_first(path_id):
    """The failure intake exists to prevent is being forgotten by the thirtieth
    knowledge point — so the profile rides on the built path's status too."""
    from deeptutor.tools.mastery_tool import MasteryProfileTool

    await MasteryProfileTool().execute(
        _mastery_path_id=path_id, preferences="中文讲解,术语保留英文"
    )
    await _build_basic(path_id)

    status = tool_payload(await MasteryStatusTool().execute(_mastery_path_id=path_id))
    assert status["status"] == "active"
    assert status["learner_profile"]["preferences"] == "中文讲解,术语保留英文"
    assert status["intake_needed"] is False


@pytest.mark.asyncio
async def test_a_correction_merges_instead_of_wiping_the_other_answers(path_id):
    from deeptutor.tools.mastery_tool import MasteryProfileTool

    profile = MasteryProfileTool()
    await profile.execute(
        _mastery_path_id=path_id,
        prior_knowledge="学过一学期线性代数",
        target_level="能看懂论文里的推导",
        time_budget="一个月",
    )
    # Months later: only the time changed.
    corrected = json.loads(
        (await profile.execute(_mastery_path_id=path_id, time_budget="改成两周")).content
    )
    assert corrected["updated_fields"] == ["time_budget"]
    expected_answers = {
        "prior_knowledge": "学过一学期线性代数",
        "target_level": "能看懂论文里的推导",
        "time_budget": "改成两周",
        "preferences": "",
        "teaching_strategy": "probe_first",
        "notes": "",
    }
    # Advisory teaching projections accompany these durable intake answers.
    assert {key: corrected["learner_profile"][key] for key in expected_answers} == expected_answers


@pytest.mark.asyncio
async def test_teach_first_preference_persists_and_changes_next_step(path_id):
    from deeptutor.tools.mastery_tool import MasteryProfileTool

    profile = MasteryProfileTool()
    selected = await profile.execute(_mastery_path_id=path_id, teaching_strategy="teach_first")
    assert selected.success is True
    await _build_basic(path_id)
    status = tool_payload(await MasteryStatusTool().execute(_mastery_path_id=path_id))
    assert status["learner_profile"]["teaching_strategy"] == "teach_first"
    assert status["next"]["action"] == "teach"

    restored = await profile.execute(_mastery_path_id=path_id, teaching_strategy="probe_first")
    assert restored.success is True
    status = tool_payload(await MasteryStatusTool().execute(_mastery_path_id=path_id))
    assert status["next"]["action"] == "probe"
    invalid = await profile.execute(_mastery_path_id=path_id, teaching_strategy="skip_all")
    assert invalid.success is False


@pytest.mark.asyncio
async def test_resending_an_unchanged_answer_reports_no_new_information(path_id):
    """Re-sending what is already on file must not read back as the learner
    having said something new."""
    from deeptutor.tools.mastery_tool import MasteryProfileTool

    profile = MasteryProfileTool()
    await profile.execute(_mastery_path_id=path_id, target_level="能自己实现一遍")
    again = json.loads(
        (await profile.execute(_mastery_path_id=path_id, target_level="能自己实现一遍")).content
    )
    assert again["updated_fields"] == []


@pytest.mark.asyncio
async def test_an_empty_profile_call_is_refused_with_the_fields_it_wanted(path_id):
    from deeptutor.tools.mastery_tool import MasteryProfileTool

    result = await MasteryProfileTool().execute(_mastery_path_id=path_id)
    assert result.success is False
    assert "time_budget" in result.content