Skip to content

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

143 KB
Raw Blame
from __future__ import annotations

import logging
import time
from typing import TYPE_CHECKING, Any, Literal
import uuid

from deeptutor.learning.grading import classify_error, grade_answer
from deeptutor.learning.mastery import compute_mastery
from deeptutor.learning.models import (
    DeferredObjective,
    ErrorRecord,
    InteractionStatus,
    KnowledgePoint,
    LearnerMasteryOverride,
    LearnerProfile,
    LearningEvidence,
    LearningModule,
    LearningProgress,
    LearningStage,
    MasteryInteraction,
    PendingOption,
    PendingQuestion,
    QuizAttempt,
    RetryAttempt,
    TopicMetadata,
    TopicSource,
)
from deeptutor.learning.objective_relations import (
    ObjectiveRelationError,
    RelationRefs,
    resolve_relation_refs,
    validate_objective_relations,
)
from deeptutor.learning.storage import LearningStore

if TYPE_CHECKING:
    from deeptutor.learning.scheduler import SpacedRepetitionScheduler


# Long enough for a course title, short enough that a list row stays a row.
# Matches the cap module and objective names already use.
_MAX_PATH_NAME_LEN = 200
#: One intake answer. Free text, but a paragraph is an answer and a chapter is
#: a paste — and the whole profile is injected into every turn's status.
_MAX_PROFILE_FIELD_LEN = 600
#: The intake fields a caller may set. Named here so the tool schema, the REST
#: layer and this merge cannot drift apart.
_LEARNER_PROFILE_FIELDS: tuple[str, ...] = (
    "prior_knowledge",
    "target_level",
    "time_budget",
    "preferences",
    "teaching_strategy",
    "notes",
)


def _source_page_key(source: dict) -> tuple | None:
    """Conservative physical-page identity, shared by native visual/lesson refs."""
    ref = source.get("source_ref") or source.get("ref") or source
    if not isinstance(ref, dict):
        return None
    kb = ref.get("kb_ref") or ref.get("kb_name")
    document = ref.get("document_key") or ref.get("source_path")
    digest = ref.get("source_digest") or ref.get("source_hash")
    page = ref.get("page_index")
    if page is None and type(ref.get("page")) is int:
        page = ref["page"] - 1
    if not kb or not document or not digest or type(page) is not int or page < 0:
        return None
    # Crops do not establish that a nearby printed answer was absent.
    return kb, document, digest, page


def _question_source_pages(question: PendingQuestion) -> set[tuple]:
    sources = question.source_evidence.get("sources", [])
    citations = question.source_evidence.get("assessment_contract", {}).get("citations", [])
    if citations:
        indices = {row.get("index") for row in citations}
        sources = [row for index, row in enumerate(sources) if index in indices]
    return {
        key
        for source in [*sources, *question.visual_context.get("sources", [])]
        if (key := _source_page_key(source)) is not None
    }


def _apply_source_assistance(progress: LearningProgress, question: PendingQuestion) -> None:
    """Attach exposure to this attempt, never to lifelong knowledge of a page.

    Same-turn pre-card display may disclose the question/key. A later receipt
    can assist an already pending question only in its registration session.
    Legacy exposures without native identity are not inferred from history.
    """
    context = question.assistance_context
    session_id, turn_id = context.get("session_id"), context.get("turn_id")
    if not session_id or not turn_id:
        return
    exposed = {
        key
        for source in progress.source_exposures
        if (key := _source_page_key(source)) is not None
        and source.get("session_id") == session_id
        and (source.get("turn_id") == turn_id or source.get("created_at", 0) >= question.created_at)
    }
    pages = _question_source_pages(question)
    # Without a source identity, independence after public source display is
    # unknown. Preserve practice without inventing independent credit.
    if exposed and (not pages or exposed.intersection(pages)):
        question.assistance_used = True


def _question_independent(question: PendingQuestion) -> bool:
    return not (question.assistance_used or question.visual_context.get("hints_used"))


def _objective_fingerprint(kp: KnowledgePoint) -> tuple[str, str]:
    return (str(kp.name or "").strip().casefold(), kp.type.value)


def _unique_fingerprint_map(
    points: list[KnowledgePoint],
) -> dict[tuple[str, str], KnowledgePoint]:
    counts: dict[tuple[str, str], int] = {}
    for kp in points:
        fingerprint = _objective_fingerprint(kp)
        counts[fingerprint] = counts.get(fingerprint, 0) + 1
    return {
        _objective_fingerprint(kp): kp for kp in points if counts[_objective_fingerprint(kp)] == 1
    }


def _reserved_objective_ids(progress: LearningProgress) -> set[str]:
    ids = {kp.id for module in progress.modules for kp in module.knowledge_points}
    ids.update(progress.mastery_levels)
    ids.update(progress.knowledge_types)
    ids.update(progress.qualitative_mastery)
    ids.update(progress.repetition_states)
    ids.update(progress.learner_mastery_overrides)
    ids.update(progress.feynman_retries)
    ids.update(progress.feynman_explanations)
    ids.update(progress.deferred_objectives)
    ids.update(progress.explained_objectives)
    ids.update(attempt.knowledge_point_id for attempt in progress.quiz_attempts)
    ids.update(record.knowledge_point_id for record in progress.error_records)
    ids.update(task.knowledge_point_id for task in progress.review_queue)
    ids.update(event.knowledge_point_id for event in progress.learning_evidence)
    ids.discard("")
    return ids


def _new_objective_id(module_id: str, reserved: set[str]) -> str:
    prefix = f"{module_id}_kp"
    while True:
        candidate = f"{prefix}_{uuid.uuid4().hex[:12]}"
        if candidate not in reserved:
            reserved.add(candidate)
            return candidate


_QUIZ_EVIDENCE_TYPES = ("quiz", "review")
_QUIZ_EVIDENCE_WINDOW = 2.0


def _quiz_evidence_matches_attempt(event: LearningEvidence, attempt: QuizAttempt) -> bool:
    if (
        event.knowledge_point_id != attempt.knowledge_point_id
        or event.assessment_type not in _QUIZ_EVIDENCE_TYPES
    ):
        return False
    if event.question_id:
        return event.question_id == attempt.question_id
    # Legacy evidence predates question linkage. Keep its narrow timestamp
    # match so old paths remain repairable without risking newer linked rows.
    return abs(event.timestamp - attempt.timestamp) <= _QUIZ_EVIDENCE_WINDOW


def _drop_quiz_evidence_for_attempts(
    progress: LearningProgress, attempts: list[QuizAttempt]
) -> None:
    if not attempts:
        return
    unmatched = list(attempts)
    kept: list[LearningEvidence] = []
    for event in progress.learning_evidence:
        match_index = next(
            (
                index
                for index, attempt in enumerate(unmatched)
                if _quiz_evidence_matches_attempt(event, attempt)
            ),
            None,
        )
        if match_index is not None:
            unmatched.pop(match_index)
            continue
        kept.append(event)
    leftover_by_kp: dict[str, int] = {}
    for attempt in unmatched:
        leftover_by_kp[attempt.knowledge_point_id] = (
            leftover_by_kp.get(attempt.knowledge_point_id, 0) + 1
        )
    if leftover_by_kp:
        rebuilt: list[LearningEvidence] = []
        for event in reversed(kept):
            leftover = leftover_by_kp.get(event.knowledge_point_id, 0)
            if leftover and not event.question_id and event.assessment_type in _QUIZ_EVIDENCE_TYPES:
                leftover_by_kp[event.knowledge_point_id] = leftover - 1
                continue
            rebuilt.append(event)
        kept = list(reversed(rebuilt))
    progress.learning_evidence = kept


def _update_quiz_evidence_for_attempts(
    progress: LearningProgress, attempts: list[QuizAttempt]
) -> None:
    if not attempts:
        return
    unmatched = list(attempts)
    for event in progress.learning_evidence:
        match_index = next(
            (
                index
                for index, attempt in enumerate(unmatched)
                if _quiz_evidence_matches_attempt(event, attempt)
            ),
            None,
        )
        if match_index is None:
            continue
        attempt = unmatched.pop(match_index)
        event.result = attempt.result or ("correct" if attempt.is_correct else "incorrect")
        event.quality = {"correct": 1.0, "partial": 0.5, "incorrect": 0.0}[event.result]
        if event.hints_used and attempt.is_correct:
            event.quality = min(event.quality, 0.6)


def assign_objective_identities(
    progress: LearningProgress,
    modules: list[LearningModule],
    *,
    identity_mode: str,
) -> dict[str, list[str] | str]:
    """Rewrite *modules* in place so IDs never inherit unrelated evidence.

    ``semantic`` (full replace) preserves an ID only when ``(name, type)`` is
    unique in both maps. ``explicit`` (targeted revise / topic edits) keeps
    caller-supplied IDs unless the same ID now names different content.
    """
    mode = "semantic" if identity_mode == "semantic" else "explicit"
    old_points = [kp for module in progress.modules for kp in module.knowledge_points]
    old_by_id = {kp.id: kp for kp in old_points}
    old_ids = set(old_by_id)
    reserved = _reserved_objective_ids(progress)
    preserved: list[str] = []
    minted: list[str] = []
    used_old_ids: set[str] = set()

    if mode == "semantic" and old_points:
        old_unique = _unique_fingerprint_map(old_points)
        new_unique = _unique_fingerprint_map(
            [kp for module in modules for kp in module.knowledge_points]
        )
        for module in modules:
            for kp in module.knowledge_points:
                fingerprint = _objective_fingerprint(kp)
                matched = None
                if fingerprint in new_unique and fingerprint in old_unique:
                    candidate = old_unique[fingerprint]
                    if candidate.id not in used_old_ids:
                        matched = candidate
                if matched is not None:
                    kp.id = matched.id
                    used_old_ids.add(matched.id)
                    preserved.append(kp.id)
                elif kp.id not in reserved:
                    reserved.add(kp.id)
                    minted.append(kp.id)
                else:
                    kp.id = _new_objective_id(module.id, reserved)
                    minted.append(kp.id)
                kp.module_id = module.id
    else:
        for module in modules:
            for kp in module.knowledge_points:
                old = old_by_id.get(kp.id)
                if old is not None and _objective_fingerprint(old) == _objective_fingerprint(kp):
                    preserved.append(kp.id)
                    reserved.add(kp.id)
                elif kp.id in reserved:
                    kp.id = _new_objective_id(module.id, reserved)
                    minted.append(kp.id)
                else:
                    reserved.add(kp.id)
                    minted.append(kp.id)
                kp.module_id = module.id

    new_ids = {kp.id for module in modules for kp in module.knowledge_points}
    return {
        "mode": mode,
        "preserved": preserved,
        "minted": minted,
        "dropped": sorted(old_ids - new_ids),
    }


class MasteryInteractionError(RuntimeError):
    """Base error for invalid durable question lifecycle transitions."""


class NoPendingInteractionError(MasteryInteractionError):
    """Raised when grading or resuming without an outstanding question."""


class StaleInteractionError(MasteryInteractionError):
    """Raised when a caller submits an answer for a superseded question."""

    def __init__(self, submitted_id: str, current_id: str) -> None:
        self.submitted_id = submitted_id
        self.current_id = current_id
        super().__init__(
            f"Question {submitted_id!r} is no longer pending; answer {current_id!r} instead"
        )


class LearningService:
    def __init__(self, store: LearningStore | None = None) -> None:
        self._store = store or LearningStore()

    @property
    def store(self) -> LearningStore:
        """Expose the persistence boundary for read-only interaction queries."""
        return self._store

    def get_or_create(self, book_id: str) -> LearningProgress:
        # The store serializes creation under BEGIN IMMEDIATE, so two callers
        # cannot both manufacture revision 1 and race to overwrite one another.
        with self._store.transaction(book_id, create=True) as tx:
            return tx.progress

    def init_modules(self, progress: LearningProgress, modules: list[LearningModule]) -> None:
        """Initialize the runnable module set (replace semantics)."""
        self.replace_modules(progress, modules)

    @staticmethod
    def _resolve_final_relations(
        applied: list[LearningModule],
        submitted: list[LearningModule],
        relation_refs: dict[str, RelationRefs],
        source_aliases: dict[str, str],
        sources: list[TopicSource],
        *,
        existing_modules: list[LearningModule] | None = None,
    ) -> None:
        """Resolve request references after durable objective IDs have been assigned."""
        aliases = {
            point.id: point.id
            for module in existing_modules or []
            for point in module.knowledge_points
        }
        final_refs: dict[str, RelationRefs] = {}
        for submitted_module, final_module in zip(submitted, applied, strict=True):
            for submitted_point, final_point in zip(
                submitted_module.knowledge_points, final_module.knowledge_points, strict=True
            ):
                # An append request may reuse a provisional ID that already belongs
                # to an existing objective. Its client_ref disambiguates the new one.
                if submitted_point.id not in aliases:
                    aliases[submitted_point.id] = final_point.id
                aliases[final_point.id] = final_point.id
                specs = relation_refs.get(submitted_point.id)
                if specs is not None:
                    final_refs[final_point.id] = specs

        for final_id, specs in final_refs.items():
            alias = specs.client_ref.strip()
            if not alias:
                continue
            if alias in aliases and aliases[alias] != final_id:
                raise ObjectiveRelationError(f"Objective reference {alias!r} is ambiguous")
            aliases[alias] = final_id

        resolve_relation_refs(
            applied,
            final_refs,
            prerequisite_aliases=aliases,
            source_aliases=source_aliases,
            sources=sources,
        )

    def replace_modules(self, progress: LearningProgress, modules: list[LearningModule]) -> None:
        """Replace all modules and clean stale KP state."""
        new_kp_ids = {kp.id for m in modules for kp in m.knowledge_points}

        # Clean stale KP state
        for key in list(progress.mastery_levels.keys()):
            if key not in new_kp_ids:
                del progress.mastery_levels[key]
        for key in list(progress.knowledge_types.keys()):
            if key not in new_kp_ids:
                del progress.knowledge_types[key]
        for key in list(progress.qualitative_mastery.keys()):
            if key not in new_kp_ids:
                del progress.qualitative_mastery[key]
        for key in list(progress.repetition_states.keys()):
            if key not in new_kp_ids:
                del progress.repetition_states[key]
        for key in list(progress.learner_mastery_overrides.keys()):
            if key not in new_kp_ids:
                del progress.learner_mastery_overrides[key]
        for key in list(progress.deferred_objectives.keys()):
            if key not in new_kp_ids:
                del progress.deferred_objectives[key]
        for key in list(progress.explained_objectives):
            if key not in new_kp_ids:
                del progress.explained_objectives[key]
        progress.error_records = [
            r for r in progress.error_records if r.knowledge_point_id in new_kp_ids
        ]
        progress.quiz_attempts = [
            attempt
            for attempt in progress.quiz_attempts
            if attempt.knowledge_point_id in new_kp_ids
        ]
        progress.learning_evidence = [
            event for event in progress.learning_evidence if event.knowledge_point_id in new_kp_ids
        ]
        progress.feynman_retries = {
            k: v for k, v in progress.feynman_retries.items() if k in new_kp_ids
        }
        progress.feynman_explanations = {
            k: v for k, v in progress.feynman_explanations.items() if k in new_kp_ids
        }
        progress.review_queue = [
            t for t in progress.review_queue if t.knowledge_point_id in new_kp_ids
        ]
        # Clear global stage failure records — different modules should not share failure counts
        progress.stage_failure_counts = {}
        progress.stage_failure_notes = {}

        # Set new modules
        progress.modules = list(modules)
        for mod in modules:
            for kp in mod.knowledge_points:
                progress.knowledge_types[kp.id] = kp.type

    def advance_stage(self, progress: LearningProgress, next_stage: LearningStage) -> None:
        progress.current_stage = next_stage
        progress.updated_at = time.time()

    def switch_module(self, progress: LearningProgress, module_id: str) -> bool:
        """Point the session at ``module_id`` and reset it to that module's
        first teaching stage (EXPLAIN). Mutates ``progress`` in place and returns
        whether the module exists. The caller is responsible for persisting
        (``save``) — typically *after* cancelling any in-flight turn so the
        turn's teardown cannot overwrite the switch with stale progress.
        """
        found = any(m.id == module_id for m in progress.modules)
        if found:
            progress.current_module_id = module_id
            progress.current_kp_index = 0
            progress.current_stage = LearningStage.EXPLAIN
            progress.updated_at = time.time()
        return found

    def record_quiz_attempt(self, progress: LearningProgress, attempt: QuizAttempt) -> None:
        if not attempt.is_correct and attempt.error_type is not None:
            # Find existing error record for this question + knowledge point.
            existing = None
            for rec in progress.error_records:
                if (
                    rec.question_id == attempt.question_id
                    and rec.knowledge_point_id == attempt.knowledge_point_id
                ):
                    existing = rec
                    break

            if existing is not None:
                existing.retry_history.append(
                    RetryAttempt(
                        timestamp=time.time(),
                        is_correct=False,
                        attempt_number=len(existing.retry_history) + 1,
                    )
                )
                existing.status = "retrying"
            else:
                record = ErrorRecord(
                    id=uuid.uuid4().hex,
                    question_id=attempt.question_id,
                    knowledge_point_id=attempt.knowledge_point_id,
                    module_id=attempt.module_id,
                    error_type=attempt.error_type,
                    self_attribution=attempt.self_attribution,
                    status="active",
                )
                progress.error_records.append(record)

        elif attempt.is_correct:
            # Graduate any active error record for this question + knowledge point.
            for rec in progress.error_records:
                if (
                    rec.question_id == attempt.question_id
                    and rec.knowledge_point_id == attempt.knowledge_point_id
                    and rec.status in ("active", "retrying")
                ):
                    rec.retry_history.append(
                        RetryAttempt(
                            timestamp=time.time(),
                            is_correct=True,
                            attempt_number=len(rec.retry_history) + 1,
                        )
                    )
                    rec.status = "graduated"
                    break

        progress.quiz_attempts.append(attempt)
        progress.updated_at = time.time()

    def calculate_mastery(self, progress: LearningProgress, kp_id: str) -> float:
        """Mastery 0..1 for *kp_id* from its attempt history (policy in mastery.py)."""
        correctness = [
            0.5 if a.result == "partial" else a.is_correct
            for a in progress.quiz_attempts
            if a.knowledge_point_id == kp_id and not a.voided and a.independent
        ]
        return compute_mastery(correctness)

    def update_mastery(self, progress: LearningProgress, kp_id: str, level: float) -> None:
        progress.mastery_levels[kp_id] = level
        progress.updated_at = time.time()

    def grade_and_record(
        self,
        progress: LearningProgress,
        *,
        question_id: str,
        knowledge_point_id: str,
        module_id: str,
        user_answer: str,
        expected_answer: str,
        question_type: str = "short",
        self_attribution: str = "",
        scheduler: SpacedRepetitionScheduler | None = None,
        session_id: str = "",
        turn_id: str = "",
    ) -> bool:
        """Grade one answer and fold it through the full post-answer pipeline.

        record attempt -> recompute mastery -> advance the spaced-repetition
        state -> rebuild the review queue -> persist. This is the single source
        of truth for what happens when a student answers, shared by every
        interactive stage. Grading is fail-closed: with no stored expected
        answer the attempt is recorded wrong, never right.
        """
        is_correct = self._apply_grade(
            progress,
            question_id=question_id,
            knowledge_point_id=knowledge_point_id,
            module_id=module_id,
            user_answer=user_answer,
            expected_answer=expected_answer,
            question_type=question_type,
            self_attribution=self_attribution,
            scheduler=scheduler,
            session_id=session_id,
            turn_id=turn_id,
        )
        self.save(progress)
        return is_correct

    def _apply_grade(
        self,
        progress: LearningProgress,
        *,
        question_id: str,
        knowledge_point_id: str,
        module_id: str,
        user_answer: str,
        expected_answer: str,
        question_type: str,
        self_attribution: str = "",
        scheduler: SpacedRepetitionScheduler | None = None,
        session_id: str = "",
        turn_id: str = "",
        visual_context: dict[str, Any] | None = None,
        assistance_used: bool = False,
        verdict: dict[str, Any] | None = None,
    ) -> bool:
        """Mutate one aggregate with a grade without performing I/O."""
        is_correct = (
            verdict["result"] == "correct"
            if verdict
            else bool(expected_answer) and grade_answer(user_answer, expected_answer, question_type)
        )
        # Capture the active retry before recording this answer graduates it.
        # Past retries on this or another question must not weaken later reviews.
        retrying = any(
            rec.question_id == question_id
            and rec.knowledge_point_id == knowledge_point_id
            and rec.status in ("active", "retrying")
            for rec in progress.error_records
        )
        already_scheduled = knowledge_point_id in progress.repetition_states
        self.record_quiz_attempt(
            progress,
            QuizAttempt(
                question_id=question_id,
                knowledge_point_id=knowledge_point_id,
                module_id=module_id,
                is_correct=is_correct,
                result=verdict["result"] if verdict else ("correct" if is_correct else "incorrect"),
                user_answer=user_answer,
                self_attribution=self_attribution,
                error_type=None
                if is_correct or verdict and verdict["result"] == "partial"
                else classify_error(user_answer),
                independent=not assistance_used and not (visual_context or {}).get("hints_used"),
                visual_context=visual_context or {},
            ),
        )
        evidence = None
        if knowledge_point_id:
            progress.deferred_objectives.pop(knowledge_point_id, None)
            evidence = self._record_quiz_evidence(
                progress,
                knowledge_point_id,
                question_id=question_id,
                is_correct=is_correct,
                retrying=retrying,
                session_id=session_id,
                turn_id=turn_id,
                assessment_type="review" if already_scheduled else "quiz",
            )
            evidence.visual_context = visual_context or {}
            evidence.hints_used = max(
                int((visual_context or {}).get("hints_used") or 0), int(assistance_used)
            )
            if evidence.hints_used and is_correct:
                evidence.quality = min(evidence.quality or 1.0, 0.6)
            if verdict:
                evidence.result = verdict["result"]
                evidence.quality = {"correct": 1.0, "partial": 0.5, "incorrect": 0.0}[
                    verdict["result"]
                ]
                evidence.confidence = verdict.get("confidence")
                evidence.learner_answer = user_answer
                evidence.feedback = verdict.get("feedback", "")
                if evidence.hints_used and is_correct:
                    evidence.quality = min(evidence.quality, 0.6)
            self.update_mastery(
                progress, knowledge_point_id, self.calculate_mastery(progress, knowledge_point_id)
            )
            kp_type = progress.knowledge_types.get(knowledge_point_id)
            if kp_type is not None and scheduler is not None:
                state = progress.repetition_states.get(
                    knowledge_point_id
                ) or scheduler.get_initial_state(
                    kp_type, desired_retention=progress.desired_retention
                )
                progress.repetition_states[knowledge_point_id] = state
                scheduler.schedule_review(state, kp_type, evidence)
                progress.review_queue = scheduler.build_review_queue(progress)
        return is_correct

    def _record_quiz_evidence(
        self,
        progress: LearningProgress,
        kp_id: str,
        *,
        question_id: str = "",
        is_correct: bool,
        retrying: bool = False,
        session_id: str = "",
        turn_id: str = "",
        assessment_type: Literal["quiz", "qualitative", "review"] = "quiz",
    ) -> LearningEvidence:
        attempt_count = sum(
            1
            for attempt in progress.quiz_attempts
            if attempt.knowledge_point_id == kp_id and not attempt.voided
        )
        evidence = LearningEvidence(
            question_id=question_id,
            knowledge_point_id=kp_id,
            assessment_type=assessment_type,
            result="correct" if is_correct else "incorrect",
            quality=(0.6 if retrying else 1.0) if is_correct else 0.0,
            attempt_count=max(1, attempt_count),
            session_id=session_id,
            turn_id=turn_id,
        )
        progress.learning_evidence.append(evidence)
        return evidence

    # ── Loop-driven tutoring helpers ─────────────────────────────────────

    def set_pending_question(self, progress: LearningProgress, pending: PendingQuestion) -> None:
        """Store the question the tutor just posed so its expected answer can
        be graded deterministically on a later turn (never via the model)."""
        for question in pending.questions or [pending]:
            _apply_source_assistance(progress, question)
        progress.pending_question = pending
        progress.updated_at = time.time()
        self.save(progress)

    def clear_pending_question(self, progress: LearningProgress) -> None:
        progress.pending_question = None
        progress.updated_at = time.time()
        self.save(progress)

    def present_sources(
        self,
        book_id: str,
        sources: list[dict],
        purpose: str,
        *,
        session_id: str = "",
        turn_id: str = "",
    ) -> list[dict]:
        """Authorize explicit page display and persist assistance before delivery.

        Called only by the trusted runtime after exact-source retrieval. A
        failed delivery may conservatively leave a receipt; it cannot grant
        independent credit after a possibly delivered answer-bearing page.
        """
        from deeptutor.services.rag.source_pages import SourceRef, public_source, resolve_source

        if purpose not in {"teaching", "reveal"} or not 1 <= len(sources) <= 6:
            raise MasteryInteractionError("Presentation needs one to six exact source pages")
        refs = []
        for source in sources:
            try:
                ref = SourceRef.model_validate(source.get("source_ref"))
            except ValueError as exc:
                raise MasteryInteractionError(
                    "Presentation requires an exact verified source page"
                ) from exc
            resolve_source(ref)
            refs.append(ref)
        rows = [public_source(ref) for ref in refs]
        for row in rows:
            # A full-file link bypasses a page/crop presentation boundary.
            row.pop("url", None)
        pages = {_source_page_key(row) for row in rows}

        def present(tx):
            active = tx.active_interaction() or self._interaction_from_legacy_pending(tx.progress)
            if active:
                final_ids = {
                    row["question_id"]
                    for row in active.result.get("results", [])
                    if row.get("final", True)
                }
                unresolved = [
                    q
                    for q in active.question.questions or [active.question]
                    if q.question_id not in final_ids
                ]
                if purpose == "reveal" and unresolved:
                    raise MasteryInteractionError(
                        "Answer every pending question before revealing source pages"
                    )
                if any(
                    not _question_source_pages(q) or pages.intersection(_question_source_pages(q))
                    for q in unresolved
                ):
                    raise MasteryInteractionError(
                        "This source may disclose a pending answer; resolve the question before presentation"
                    )
            known = {
                (_source_page_key(row), row.get("session_id"), row.get("turn_id"))
                for row in tx.progress.source_exposures
            }
            for row in rows:
                key = (_source_page_key(row), session_id, turn_id)
                if key not in known:
                    tx.progress.source_exposures.append(
                        {
                            "source_ref": row["source_ref"],
                            "purpose": purpose,
                            "session_id": session_id,
                            "turn_id": turn_id,
                            "created_at": time.time(),
                        }
                    )
                    known.add(key)
                    tx.touch()
            return rows

        _, authorized = self._store.mutate(book_id, present)
        return authorized

    @staticmethod
    def _interaction_from_legacy_pending(
        progress: LearningProgress,
        *,
        session_id: str = "",
        turn_id: str = "",
    ) -> MasteryInteraction | None:
        pending = progress.pending_question
        if pending is None:
            return None
        return MasteryInteraction(
            interaction_id=pending.question_id,
            path_id=progress.book_id,
            question=pending,
            status=InteractionStatus.REGISTERED,
            session_id=session_id,
            turn_id=turn_id,
        )

    def register_question(
        self,
        book_id: str,
        pending: PendingQuestion | None,
        *,
        pending_action: str = "retain",
        replace_question_id: str = "",
        resume_question_id: str = "",
        session_id: str = "",
        turn_id: str = "",
    ) -> tuple[LearningProgress, MasteryInteraction, bool]:
        """Atomically register one outstanding question.

        Retrying ``mastery_quiz`` while a question is active returns the
        existing interaction instead of overwriting its expected answer.
        """

        if pending_action not in {"retain", "replace", "resume"}:
            raise MasteryInteractionError("pending_action must be retain, replace or resume")
        if pending_action == "resume":
            if pending is not None or replace_question_id or not resume_question_id:
                raise MasteryInteractionError(
                    "Resume needs only the exact pending parent question_id"
                )
        elif pending is None or resume_question_id:
            raise MasteryInteractionError(
                "A new question contract cannot include resume_question_id"
            )

        def register(tx):
            active = tx.active_interaction()
            if active is None:
                active = self._interaction_from_legacy_pending(
                    tx.progress, session_id=session_id, turn_id=turn_id
                )
                if active is not None:
                    persisted = tx.get_interaction(active.interaction_id)
                    if persisted is not None and persisted.status in {
                        InteractionStatus.GRADED,
                        InteractionStatus.ABANDONED,
                    }:
                        # Repair a legacy aggregate whose compatibility field
                        # survived after the durable interaction completed.
                        tx.progress.pending_question = None
                        tx.touch()
                        active = None
                    elif persisted is not None:
                        active = persisted
                    else:
                        tx.put_interaction(active)
            if pending_action == "resume":
                if active is None or active.interaction_id != resume_question_id:
                    raise StaleInteractionError(
                        resume_question_id, active.interaction_id if active else ""
                    )
                if active.status not in {
                    InteractionStatus.REGISTERED,
                    InteractionStatus.AWAITING_INPUT,
                    InteractionStatus.ANSWERED,
                }:
                    raise MasteryInteractionError(
                        "This question is no longer awaiting input; refresh mastery_status"
                    )
                from deeptutor.learning.lesson_evidence import LessonUnavailable

                graded_ids = {
                    result["question_id"]
                    for result in (active.result or {}).get("results", [])
                    if result.get("final", True)
                }
                reviewed_ids = {
                    result["question_id"] for result in (active.result or {}).get("results", [])
                }
                if set(active.answers) - reviewed_ids:
                    raise MasteryInteractionError(
                        "Grade the committed answers before re-presenting the remaining card"
                    )
                known_ids = {
                    kp.id for module in tx.progress.modules for kp in module.knowledge_points
                }
                try:
                    for question in active.question.questions or [active.question]:
                        if question.question_id in graded_ids:
                            continue
                        if question.knowledge_point_id not in known_ids:
                            raise MasteryInteractionError(
                                "The pending objective changed; refresh mastery_status"
                            )
                        from deeptutor.learning.semantic_assessment import validate_question

                        validate_question(self._store, tx.progress, question)
                except LessonUnavailable as exc:
                    raise MasteryInteractionError(str(exc)) from exc
                return active, False
            if active is not None and pending_action == "retain":
                if bool(pending.questions) != bool(active.question.questions):
                    raise MasteryInteractionError(
                        "An incompatible question is already pending; retain it or explicitly "
                        "replace its question_id before creating a group"
                    )
                if pending.questions and self._group_contract(pending) != self._group_contract(
                    active.question
                ):
                    raise MasteryInteractionError(
                        "A different group is already pending; explicitly replace its question_id"
                    )
                return active, False
            if pending_action == "replace" and (
                active is None or active.interaction_id != replace_question_id
            ):
                raise StaleInteractionError(
                    replace_question_id, active.interaction_id if active else ""
                )

            leaves = pending.questions or [pending]
            known_ids = {kp.id for module in tx.progress.modules for kp in module.knowledge_points}
            for question in leaves:
                if question.knowledge_point_id not in known_ids:
                    raise MasteryInteractionError(
                        f"Unknown objective {question.knowledge_point_id!r}; refresh mastery_status"
                    )
            from deeptutor.learning.lesson_evidence import LessonUnavailable, question_snapshot

            try:
                for question in leaves:
                    if question.source_evidence.get("assessment_contract"):
                        from deeptutor.learning.semantic_assessment import validate_question

                        validate_question(self._store, tx.progress, question)
                    else:
                        question.source_evidence = question_snapshot(
                            self._store, tx.progress, question.knowledge_point_id
                        )
                    question.assistance_context = {"session_id": session_id, "turn_id": turn_id}
                    question.created_at = time.time()
                    _apply_source_assistance(tx.progress, question)
            except LessonUnavailable as exc:
                raise MasteryInteractionError(str(exc)) from exc
            if active is not None:
                active.status = InteractionStatus.ABANDONED
                tx.put_interaction(active)
                tx.emit(
                    "interaction.abandoned",
                    {
                        "interaction_id": active.interaction_id,
                        "reason": "explicit_replacement",
                        "replacement_id": pending.question_id,
                    },
                    session_id=session_id,
                    turn_id=turn_id,
                )

            interaction = MasteryInteraction(
                interaction_id=pending.question_id,
                path_id=book_id,
                question=pending,
                status=InteractionStatus.REGISTERED,
                session_id=session_id,
                turn_id=turn_id,
            )
            tx.progress.pending_question = pending
            for question in leaves:
                tx.progress.deferred_objectives.pop(question.knowledge_point_id, None)
            tx.put_interaction(interaction)
            from deeptutor.learning.pending import public_pending_question

            tx.emit(
                "interaction.registered",
                {
                    "interaction_id": interaction.interaction_id,
                    "knowledge_point_id": pending.knowledge_point_id,
                    "question": public_pending_question(pending).to_dict(),
                },
                session_id=session_id,
                turn_id=turn_id,
            )
            return interaction, True

        progress, result = self._store.mutate(book_id, register)
        interaction, created = result
        return progress, interaction, created

    def mark_question_awaiting(
        self,
        book_id: str,
        *,
        interaction_id: str = "",
        session_id: str = "",
        turn_id: str = "",
    ) -> MasteryInteraction | None:
        """Persist that an interaction card has been presented to the learner."""

        def mark(tx):
            interaction = (
                tx.get_interaction(interaction_id) if interaction_id else tx.active_interaction()
            )
            if interaction is None:
                active = tx.active_interaction()
                if active is not None and interaction_id:
                    raise StaleInteractionError(interaction_id, active.interaction_id)
                interaction = self._interaction_from_legacy_pending(
                    tx.progress, session_id=session_id, turn_id=turn_id
                )
                if interaction is None:
                    return None
                if interaction_id and interaction.interaction_id != interaction_id:
                    raise StaleInteractionError(interaction_id, interaction.interaction_id)
            if interaction.status == InteractionStatus.REGISTERED:
                interaction.status = InteractionStatus.AWAITING_INPUT
                interaction.session_id = session_id or interaction.session_id
                interaction.turn_id = turn_id or interaction.turn_id
                tx.put_interaction(interaction)
                tx.emit(
                    "interaction.awaiting_input",
                    {"interaction_id": interaction.interaction_id},
                    session_id=interaction.session_id,
                    turn_id=interaction.turn_id,
                )
            return interaction

        _, interaction = self._store.mutate(book_id, mark)
        return interaction

    def record_question_answer(
        self,
        book_id: str,
        answer: str,
        *,
        answers: dict[str, str] | None = None,
        interaction_id: str = "",
        session_id: str = "",
        turn_id: str = "",
    ) -> MasteryInteraction | None:
        """Durably record a reply before the LLM gets another reasoning round."""

        def record(tx):
            interaction = (
                tx.get_interaction(interaction_id) if interaction_id else tx.active_interaction()
            )
            if interaction is None:
                active = tx.active_interaction()
                if active is not None and interaction_id:
                    raise StaleInteractionError(interaction_id, active.interaction_id)
                interaction = self._interaction_from_legacy_pending(
                    tx.progress, session_id=session_id, turn_id=turn_id
                )
            if interaction is None:
                return None
            if interaction_id and interaction.interaction_id != interaction_id:
                raise StaleInteractionError(interaction_id, interaction.interaction_id)
            if interaction.question.questions:
                if interaction.status == InteractionStatus.ABANDONED:
                    raise NoPendingInteractionError("The question was abandoned")
                submitted = self._merge_group_answers(interaction, answers)
                if submitted == interaction.answers:
                    return interaction
                interaction.answers = submitted
                complete = len(submitted) == len(interaction.question.questions)
                interaction.status = (
                    InteractionStatus.ANSWERED if complete else InteractionStatus.AWAITING_INPUT
                )
                interaction.session_id = session_id or interaction.session_id
                interaction.turn_id = turn_id or interaction.turn_id
                tx.put_interaction(interaction)
                tx.emit(
                    "interaction.answered" if complete else "interaction.answers_recorded",
                    {"interaction_id": interaction.interaction_id, "complete": complete},
                    session_id=interaction.session_id,
                    turn_id=interaction.turn_id,
                )
                return interaction
            if interaction.status in {
                InteractionStatus.REGISTERED,
                InteractionStatus.AWAITING_INPUT,
            }:
                interaction.status = InteractionStatus.ANSWERED
                interaction.user_answer = str(answer or "")
                interaction.session_id = session_id or interaction.session_id
                interaction.turn_id = turn_id or interaction.turn_id
                tx.put_interaction(interaction)
                tx.emit(
                    "interaction.answered",
                    {"interaction_id": interaction.interaction_id},
                    session_id=interaction.session_id,
                    turn_id=interaction.turn_id,
                )
            elif (
                interaction.status == InteractionStatus.ANSWERED
                and interaction.result.get("final") is False
            ):
                tx.emit(
                    "assessment.revised",
                    {
                        "question_id": interaction.interaction_id,
                        "previous_answer": interaction.user_answer,
                        "previous_result": interaction.result,
                    },
                    session_id=session_id,
                    turn_id=turn_id,
                )
                interaction.user_answer = str(answer or "")
                interaction.session_id = session_id or interaction.session_id
                interaction.turn_id = turn_id or interaction.turn_id
                tx.put_interaction(interaction)
            elif (
                interaction.status == InteractionStatus.ANSWERED
                and interaction.question.question_type == "choice"
            ):
                # Recover from a prior unreadable composer commit (#1004): allow
                # a later readable pick to replace the stalled user_answer.
                from deeptutor.learning.pending import is_readable_choice_answer

                stored = str(interaction.user_answer or "")
                incoming = str(answer or "")
                option_map = interaction.question.choice_map
                if not is_readable_choice_answer(stored, option_map) and is_readable_choice_answer(
                    incoming, option_map
                ):
                    interaction.user_answer = incoming
                    interaction.session_id = session_id or interaction.session_id
                    interaction.turn_id = turn_id or interaction.turn_id
                    tx.put_interaction(interaction)
                    tx.emit(
                        "interaction.answered",
                        {"interaction_id": interaction.interaction_id},
                        session_id=interaction.session_id,
                        turn_id=interaction.turn_id,
                    )
            return interaction

        _, interaction = self._store.mutate(book_id, record)
        return interaction

    def grade_interaction(
        self,
        book_id: str,
        *,
        answer: str,
        question_id: str = "",
        answers: dict[str, str] | None = None,
        answer_for_grading: str | None = None,
        expected_answer: str | None = None,
        resolved_choice_options: dict[str, str] | None = None,
        scheduler: SpacedRepetitionScheduler | None = None,
        session_id: str = "",
        turn_id: str = "",
        _assessment: dict | None = None,
    ) -> tuple[LearningProgress, MasteryInteraction, bool]:
        """Grade and resolve an interaction in one idempotent transaction.

        Returns ``(progress, interaction, replayed)``.  A retry carrying the
        same ``question_id`` returns the stored result and never appends a
        second attempt.
        """

        def grade(tx):
            interaction = tx.get_interaction(question_id) if question_id else None
            if interaction is None and not question_id:
                interaction = tx.active_interaction()
            if interaction is None:
                legacy = self._interaction_from_legacy_pending(
                    tx.progress, session_id=session_id, turn_id=turn_id
                )
                if legacy is not None and (not question_id or legacy.interaction_id == question_id):
                    interaction = legacy
                    tx.put_interaction(interaction)
            if interaction is None:
                active = tx.active_interaction()
                if active is not None and question_id:
                    raise StaleInteractionError(question_id, active.interaction_id)
                raise NoPendingInteractionError("No question is awaiting an answer")
            if question_id and interaction.interaction_id != question_id:
                raise StaleInteractionError(question_id, interaction.interaction_id)
            if interaction.status == InteractionStatus.GRADED:
                if interaction.question.questions and answers is not None:
                    self._merge_group_answers(interaction, answers)
                return interaction, True
            if interaction.status == InteractionStatus.ABANDONED:
                raise NoPendingInteractionError("The question was abandoned")
            if _assessment:
                from deeptutor.learning.lesson_evidence import objective_fingerprint
                from deeptutor.learning.semantic_assessment import fingerprint

                if fingerprint(interaction.model_dump()) != _assessment["state"] or any(
                    objective_fingerprint(tx.progress, key) != value
                    for key, value in _assessment["objectives"].items()
                ):
                    raise MasteryInteractionError(
                        "The question, answer or objective changed during assessment; retry."
                    )
                for question in interaction.question.questions or [interaction.question]:
                    if question.question_id in _assessment.get("sources", {}):
                        question.source_evidence = _assessment["sources"][question.question_id]

            if interaction.question.questions:
                return self._grade_group(
                    tx,
                    interaction,
                    answers=answers,
                    scheduler=scheduler,
                    session_id=session_id,
                    turn_id=turn_id,
                    verdicts=_assessment["verdicts"] if _assessment else None,
                )

            from deeptutor.learning.lesson_evidence import LessonUnavailable

            try:
                from deeptutor.learning.semantic_assessment import validate_question

                validate_question(self._store, tx.progress, interaction.question)
            except LessonUnavailable as exc:
                raise MasteryInteractionError(str(exc)) from exc

            raw_answer, is_correct, visual_result, visual_diagnosis = self._evaluate_question(
                tx,
                interaction,
                answer=answer,
                answer_for_grading=answer_for_grading,
                expected_answer=expected_answer,
                resolved_choice_options=resolved_choice_options,
                scheduler=scheduler,
                session_id=session_id,
                turn_id=turn_id,
                verdict=(_assessment or {})
                .get("verdicts", {})
                .get(interaction.question.question_id),
            )
            pending = interaction.question
            receipt = (_assessment or {}).get("verdicts", {}).get(pending.question_id, {})
            if visual_result == "ungraded" and not receipt:
                receipt = {
                    "result": "ungraded",
                    "final": False,
                    "needs_clarification": True,
                    "feedback": visual_diagnosis,
                    "confidence": None,
                    "is_correct": None,
                }
            if (
                tx.progress.pending_question is not None
                and tx.progress.pending_question.question_id == pending.question_id
                and receipt.get("final", True)
            ):
                tx.progress.pending_question = None
            interaction.status = (
                InteractionStatus.GRADED
                if receipt.get("final", True)
                else InteractionStatus.ANSWERED
            )
            interaction.user_answer = raw_answer
            interaction.session_id = session_id or interaction.session_id
            interaction.turn_id = turn_id or interaction.turn_id
            interaction.result = {
                "is_correct": is_correct,
                "knowledge_point_id": pending.knowledge_point_id,
                **receipt,
                "independent": _question_independent(pending),
            }
            if pending.visual_context:
                interaction.result.update(
                    {
                        "result": visual_result,
                        "diagnosis": visual_diagnosis,
                        "visual_context": pending.visual_context,
                        "independent": _question_independent(pending),
                    }
                )
            tx.put_interaction(interaction)
            tx.emit(
                "practice.ungraded" if visual_result == "ungraded" else "attempt.recorded",
                {
                    "interaction_id": interaction.interaction_id,
                    "knowledge_point_id": pending.knowledge_point_id,
                    "is_correct": is_correct,
                },
                session_id=interaction.session_id,
                turn_id=interaction.turn_id,
            )
            if visual_result != "ungraded" and tx.progress.learning_evidence:
                latest = tx.progress.learning_evidence[-1]
                if latest.knowledge_point_id == pending.knowledge_point_id:
                    tx.emit(
                        "evidence.recorded",
                        {
                            "knowledge_point_id": latest.knowledge_point_id,
                            "assessment_type": latest.assessment_type,
                            "result": latest.result,
                            "quality": latest.quality,
                        },
                        session_id=interaction.session_id,
                        turn_id=interaction.turn_id,
                    )
            tx.emit(
                "interaction.graded",
                dict(interaction.result),
                session_id=interaction.session_id,
                turn_id=interaction.turn_id,
            )
            return interaction, False

        progress, result = self._store.mutate(book_id, grade)
        interaction, replayed = result
        return progress, interaction, replayed

    @staticmethod
    def _group_contract(pending: PendingQuestion) -> list[tuple]:
        # Choice shuffling changes labels, not the answer contract. Ignore new
        # generated ids when a duplicate tool call re-presents the same group.
        return [
            (
                q.knowledge_point_id,
                q.prompt,
                q.question_type,
                tuple(sorted(q.choice_map.values())),
                q.choice_map.get(q.expected_answer, q.expected_answer),
                q.explanation,
                q.difficulty,
                q.visual_context,
            )
            for q in pending.questions
        ]

    @staticmethod
    def _validate_group_answers(pending: PendingQuestion, answers: Any) -> dict[str, str]:
        ids = {question.question_id for question in pending.questions}
        if (
            not isinstance(answers, dict)
            or not answers
            or not set(answers).issubset(ids)
            or any(
                not isinstance(value, str) or not value.strip() or len(value) > 10000
                for value in answers.values()
            )
        ):
            raise MasteryInteractionError(
                "Supply at least one actual answer using its exact group question_id"
            )
        from deeptutor.learning.pending import resolve_choice_submission

        for question in pending.questions:
            if (
                question.question_id in answers
                and question.question_type == "choice"
                and not resolve_choice_submission(
                    answers[question.question_id], question.choice_map
                )
            ):
                raise MasteryInteractionError(
                    "Choose one unambiguous option for each choice question"
                )
        return {key: value.strip() for key, value in answers.items()}

    def _merge_group_answers(self, interaction: MasteryInteraction, answers: Any) -> dict[str, str]:
        submitted = self._validate_group_answers(
            interaction.question, interaction.answers if answers is None else answers
        )
        revisable = {
            row["question_id"]
            for row in interaction.result.get("results", [])
            if row.get("final") is False
        }
        if any(
            key in interaction.answers
            and interaction.answers[key] != value
            and key not in revisable
            for key, value in submitted.items()
        ):
            raise MasteryInteractionError("This group already has a different committed answer")
        return {**interaction.answers, **submitted}

    @staticmethod
    def _group_result(pending: PendingQuestion, results: list[dict]) -> dict:
        values = [result["is_correct"] for result in results]
        graded_ids = {result["question_id"] for result in results if result.get("final", True)}
        remaining = [q.question_id for q in pending.questions if q.question_id not in graded_ids]
        complete = not remaining
        outcomes = {
            row.get("result") or ("correct" if row["is_correct"] else "incorrect")
            for row in results
        }
        return {
            "question_id": pending.question_id,
            "question_type": "group",
            "results": results,
            "complete": complete,
            "final": complete,
            "needs_clarification": any(row.get("needs_clarification", False) for row in results),
            "remaining_question_ids": remaining,
            "is_correct": None if not complete or None in values else all(values),
            "result": "ungraded"
            if not complete
            else next(iter(outcomes))
            if len(outcomes) == 1
            else "mixed",
        }

    def _grade_group(
        self,
        tx,
        interaction: MasteryInteraction,
        *,
        answers,
        scheduler=None,
        session_id="",
        turn_id="",
        verdicts=None,
    ) -> tuple[MasteryInteraction, bool]:
        """Commit new replies once; unanswered siblings remain awaiting input."""
        pending = interaction.question
        submitted = self._merge_group_answers(interaction, answers)
        known_ids = {kp.id for module in tx.progress.modules for kp in module.knowledge_points}
        if any(q.knowledge_point_id not in known_ids for q in pending.questions):
            raise MasteryInteractionError("An objective changed; refresh the question group")
        from deeptutor.learning.lesson_evidence import LessonUnavailable
        from deeptutor.learning.question_card import build_grade_result

        leaves = []
        for question in pending.questions:
            if question.question_id not in submitted:
                continue
            stored = tx.get_interaction(question.question_id)
            if stored is not None and (
                stored.result.get("group_question_id") != pending.question_id
                or stored.question.knowledge_point_id != question.knowledge_point_id
                or stored.user_answer != submitted[question.question_id]
                and stored.result.get("final", True)
            ):
                raise MasteryInteractionError("This child belongs to another interaction or reply")
            if (
                stored is None
                or stored.status != InteractionStatus.GRADED
                or not stored.result.get("final", True)
            ):
                try:
                    from deeptutor.learning.semantic_assessment import validate_question

                    validate_question(self._store, tx.progress, question)
                except LessonUnavailable as exc:
                    raise MasteryInteractionError(str(exc)) from exc
            leaves.append((question, stored))

        results = []
        new_results = False
        for question, stored in leaves:
            if (
                stored is not None
                and stored.status == InteractionStatus.GRADED
                and stored.result.get("final", True)
            ):
                results.append(self._group_leaf_result(stored))
                continue
            new_results = True
            if stored:
                tx.emit(
                    "assessment.revised",
                    {
                        "question_id": question.question_id,
                        "previous_answer": stored.user_answer,
                        "previous_result": stored.result,
                    },
                    session_id=session_id,
                    turn_id=turn_id,
                )
            leaf = MasteryInteraction(
                interaction_id=question.question_id,
                path_id=interaction.path_id,
                question=question,
                status=InteractionStatus.ANSWERED,
                user_answer=submitted[question.question_id],
            )
            raw, correct, visual_result, diagnosis = self._evaluate_question(
                tx,
                leaf,
                answer=submitted[question.question_id],
                scheduler=scheduler,
                session_id=session_id,
                turn_id=turn_id,
                verdict=(verdicts or {}).get(question.question_id),
            )
            result = build_grade_result(
                question_id=question.question_id,
                is_correct=bool(correct),
                learner_answer=raw,
                correct_label=question.expected_answer if correct is not None else "",
                choice_options=question.choice_map,
                explanation=question.explanation if correct is not None else diagnosis,
                result=visual_result,
                final=correct is not None,
                needs_clarification=correct is None,
                feedback=diagnosis,
                independent=_question_independent(question),
            )
            result["is_correct"] = correct
            result.update((verdicts or {}).get(question.question_id, {}))
            result["knowledge_point_id"] = question.knowledge_point_id
            if diagnosis:
                result["diagnosis"] = diagnosis
            results.append(result)
            leaf.session_id = session_id or interaction.session_id
            leaf.turn_id = turn_id or interaction.turn_id
            leaf.status = InteractionStatus.GRADED
            leaf.result = {**result, "group_question_id": pending.question_id}
            tx.put_interaction(leaf)
            tx.emit(
                "practice.ungraded" if correct is None else "attempt.recorded",
                {
                    "interaction_id": interaction.interaction_id,
                    "question_id": question.question_id,
                    "knowledge_point_id": question.knowledge_point_id,
                    "is_correct": correct,
                },
                session_id=session_id,
                turn_id=turn_id,
            )
            if correct is not None or result.get("result") == "partial":
                evidence = tx.progress.learning_evidence[-1]
                tx.emit(
                    "evidence.recorded",
                    {
                        "knowledge_point_id": evidence.knowledge_point_id,
                        "assessment_type": evidence.assessment_type,
                        "result": evidence.result,
                        "quality": evidence.quality,
                    },
                    session_id=session_id,
                    turn_id=turn_id,
                )
        if not new_results:
            return interaction, True
        interaction.result = self._group_result(pending, results)
        complete = interaction.result["complete"]
        interaction.status = (
            InteractionStatus.GRADED
            if complete
            else InteractionStatus.ANSWERED
            if interaction.status == InteractionStatus.ANSWERED
            else InteractionStatus.AWAITING_INPUT
        )
        interaction.answers = submitted
        interaction.session_id = session_id or interaction.session_id
        interaction.turn_id = turn_id or interaction.turn_id
        if complete:
            tx.progress.pending_question = None
        tx.put_interaction(interaction)
        tx.emit(
            "interaction.graded" if complete else "interaction.partially_graded",
            dict(interaction.result),
            session_id=interaction.session_id,
            turn_id=interaction.turn_id,
        )
        return interaction, False

    def _evaluate_question(
        self,
        tx,
        interaction: MasteryInteraction,
        *,
        answer: str,
        answer_for_grading: str | None = None,
        expected_answer: str | None = None,
        resolved_choice_options: dict[str, str] | None = None,
        scheduler: SpacedRepetitionScheduler | None = None,
        session_id: str = "",
        turn_id: str = "",
        verdict: dict | None = None,
    ) -> tuple[str, bool | None, str, str]:
        """Shared leaf grader: never creates a parent attempt or commits separately."""
        pending = interaction.question
        _apply_source_assistance(tx.progress, pending)
        raw_answer = str(answer or "")
        if interaction.status == InteractionStatus.ANSWERED:
            stored = str(interaction.user_answer or "")
            if pending.question_type == "choice":
                from deeptutor.learning.pending import (
                    has_option_bodies,
                    is_readable_choice_answer,
                    resolve_choice_submission,
                )

                option_map = pending.choice_map
                if is_readable_choice_answer(stored, option_map):
                    raw_answer = stored
                elif is_readable_choice_answer(raw_answer, option_map):
                    # Prior commit was unreadable clarifying text (#1004) —
                    # accept the fresh readable answer and rewrite storage.
                    interaction.user_answer = raw_answer
                else:
                    raw_answer = stored
                if has_option_bodies(option_map):
                    graded_answer = resolve_choice_submission(raw_answer, option_map) or raw_answer
                else:
                    # Legacy questions may need option bodies recovered by
                    # the trusted tool adapter from the original turn.
                    graded_answer = raw_answer if answer_for_grading is None else answer_for_grading
            else:
                raw_answer = stored
                graded_answer = raw_answer
        else:
            graded_answer = raw_answer if answer_for_grading is None else answer_for_grading
        authoritative_answer = (
            pending.expected_answer if expected_answer is None else expected_answer
        )
        if pending.question_type == "choice" and resolved_choice_options:
            # Bodies recovered for a legacy question (see the tool
            # adapter): store them in the structured form so nothing has
            # to recover them again.
            pending.options = [
                PendingOption(label=label, body=body)
                for label, body in resolved_choice_options.items()
            ]
            pending.expected_answer = authoritative_answer
            interaction.question = pending
        visual_result = ""
        visual_diagnosis = ""
        if pending.visual_context:
            from deeptutor.learning.visual_practice import (
                account_for_recent_assistance,
                evaluate_visual,
            )

            pending.visual_context = account_for_recent_assistance(
                pending.visual_context, tx.progress.quiz_attempts, pending.knowledge_point_id
            )
            visual_result, visual_diagnosis = evaluate_visual(pending, raw_answer)
            if (
                tx.progress.explained_objectives.get(pending.knowledge_point_id, {}).get(
                    "timestamp", 0
                )
                > pending.created_at
            ):
                pending.visual_context["hints_used"] = max(
                    1, pending.visual_context.get("hints_used", 0)
                )
                pending.visual_context["teaching_after_question"] = True
            if visual_result == "correct":
                graded_answer = authoritative_answer
            if verdict and verdict["final"]:
                from deeptutor.learning.visual_practice import verified_visual_images

                try:
                    verified_visual_images(pending)
                except ValueError as exc:
                    raise MasteryInteractionError(str(exc)) from exc
                visual_result = verdict["result"]
        is_correct = (
            None
            if visual_result == "ungraded" or verdict and not verdict["final"]
            else self._apply_grade(
                tx.progress,
                question_id=pending.question_id,
                knowledge_point_id=pending.knowledge_point_id,
                module_id=pending.module_id,
                user_answer=graded_answer,
                expected_answer=authoritative_answer,
                question_type=pending.question_type,
                scheduler=scheduler,
                session_id=session_id,
                turn_id=turn_id,
                visual_context=pending.visual_context,
                assistance_used=pending.assistance_used,
                verdict=verdict,
            )
        )
        if verdict:
            is_correct = verdict["is_correct"]
            visual_result = verdict["result"]
            visual_diagnosis = verdict["feedback"]
        return raw_answer, is_correct, visual_result, visual_diagnosis

    def replace_modules_for_path(
        self,
        book_id: str,
        modules: list[LearningModule],
        *,
        append: bool = False,
        name: str = "",
        event_type: str = "path.modules_replaced",
        session_id: str = "",
        turn_id: str = "",
        identity_mode: str = "explicit",
        relation_refs: dict[str, RelationRefs] | None = None,
        source_aliases: dict[str, str] | None = None,
        topic_sources: list[TopicSource] | None = None,
        fresh_identity: bool = False,
    ) -> LearningProgress:
        """Install a module set, optionally naming a path that has no name yet.

        ``name`` is applied only when the path is still unnamed, in the same
        transaction as the modules so a built path is never briefly nameless.
        Replacing the map deliberately does NOT rename: the map is what the
        path teaches, the name is which path it is — deriving one from the
        other is what made a rebuild look like a different course.

        ``identity_mode`` is ``semantic`` for a full outline replace (unique
        ``(name, type)`` mapping) and ``explicit`` for targeted revise / topic
        edits that already carry durable IDs. Position never establishes identity.
        """

        progress, _ = self._store.mutate(
            book_id,
            lambda tx: self._replace_module_set(
                tx,
                modules,
                append=append,
                name=name,
                event_type=event_type,
                session_id=session_id,
                turn_id=turn_id,
                identity_mode=identity_mode,
                relation_refs=relation_refs,
                source_aliases=source_aliases,
                topic_sources=topic_sources,
                fresh_identity=fresh_identity,
            ),
            create=True,
        )
        return progress

    def _replace_module_set(
        self,
        tx,
        modules: list[LearningModule],
        *,
        append: bool = False,
        name: str = "",
        event_type: str = "path.modules_replaced",
        session_id: str = "",
        turn_id: str = "",
        identity_mode: str = "explicit",
        relation_refs: dict[str, RelationRefs] | None = None,
        source_aliases: dict[str, str] | None = None,
        topic_sources: list[TopicSource] | None = None,
        fresh_identity: bool = False,
        dry_run: bool = False,
    ) -> dict[str, Any]:
        """Shared identity, relation and question effects for preview and save."""
        active_interaction_removed = False
        book_id = tx.progress.book_id
        if name.strip() and not tx.progress.name.strip():
            tx.progress.name = name.strip()[:_MAX_PATH_NAME_LEN]
        applied_modules = [module.model_copy(deep=True) for module in modules]
        identity_map: dict[str, list[str] | str] = {
            "mode": "append" if append else ("fresh" if fresh_identity else identity_mode),
            "preserved": [],
            "minted": [],
            "dropped": [],
        }
        if append:
            reserved = _reserved_objective_ids(tx.progress)
            offset = len(tx.progress.modules)
            minted: list[str] = []
            for index, module in enumerate(applied_modules, start=offset):
                module.id = f"{book_id}_m{index}"
                module.order = index
                for kp_index, kp in enumerate(module.knowledge_points):
                    kp.module_id = module.id
                    candidate = f"{module.id}_kp{kp_index}"
                    if candidate in reserved:
                        kp.id = _new_objective_id(module.id, reserved)
                    else:
                        kp.id = candidate
                        reserved.add(candidate)
                    tx.progress.knowledge_types[kp.id] = kp.type
                    minted.append(kp.id)
            identity_map["minted"] = minted
            existing_modules = tx.progress.modules
            self._resolve_final_relations(
                applied_modules,
                modules,
                relation_refs or {},
                source_aliases or {},
                tx.topic_sources() if topic_sources is None else topic_sources,
                existing_modules=existing_modules,
            )
            validate_objective_relations(
                [*existing_modules, *applied_modules],
                tx.topic_sources() if topic_sources is None else topic_sources,
            )
            tx.progress.modules.extend(applied_modules)
            if not tx.progress.current_module_id and applied_modules:
                tx.progress.current_module_id = applied_modules[0].id
                tx.progress.current_kp_index = 0
        else:
            current_kp_id = ""
            for current_module in tx.progress.modules:
                if current_module.id != tx.progress.current_module_id:
                    continue
                if 0 <= tx.progress.current_kp_index < len(current_module.knowledge_points):
                    current_kp_id = current_module.knowledge_points[tx.progress.current_kp_index].id
                break
            pending_kp_id = (
                tx.progress.pending_question.knowledge_point_id
                if tx.progress.pending_question is not None
                else ""
            )
            active_interaction = tx.active_interaction()
            active_kp_id = (
                active_interaction.question.knowledge_point_id
                if active_interaction is not None
                else ""
            )

            if fresh_identity:
                reserved = _reserved_objective_ids(tx.progress)
                for module in applied_modules:
                    for kp in module.knowledge_points:
                        kp.id = _new_objective_id(module.id, reserved)
                        kp.module_id = module.id
                identity_map["minted"] = [
                    kp.id for module in applied_modules for kp in module.knowledge_points
                ]
                identity_map["dropped"] = sorted(
                    {kp.id for module in tx.progress.modules for kp in module.knowledge_points}
                )
            else:
                identity_map = assign_objective_identities(
                    tx.progress,
                    applied_modules,
                    identity_mode=identity_mode,
                )
            sources = tx.topic_sources() if topic_sources is None else topic_sources
            self._resolve_final_relations(
                applied_modules,
                modules,
                relation_refs or {},
                source_aliases or {},
                sources,
            )
            validate_objective_relations(applied_modules, sources)
            self.replace_modules(tx.progress, applied_modules)
            objective_locations = {
                kp.id: (module.id, kp_index)
                for module in applied_modules
                for kp_index, kp in enumerate(module.knowledge_points)
            }

            if current_kp_id in objective_locations:
                (
                    tx.progress.current_module_id,
                    tx.progress.current_kp_index,
                ) = objective_locations[current_kp_id]
            elif applied_modules:
                tx.progress.current_module_id = applied_modules[0].id
                tx.progress.current_kp_index = 0
            else:
                tx.progress.current_module_id = ""
                tx.progress.current_kp_index = 0

            if tx.progress.pending_question is not None:
                pending_leaves = tx.progress.pending_question.questions or [
                    tx.progress.pending_question
                ]
                if pending_kp_id not in objective_locations or any(
                    q.knowledge_point_id not in objective_locations for q in pending_leaves
                ):
                    tx.progress.pending_question = None
                else:
                    tx.progress.pending_question.module_id = objective_locations[pending_kp_id][0]
                    for question in pending_leaves:
                        question.module_id = objective_locations[question.knowledge_point_id][0]

            if active_interaction is not None:
                active_leaves = active_interaction.question.questions or [
                    active_interaction.question
                ]
                active_interaction_removed = active_kp_id not in objective_locations or any(
                    q.knowledge_point_id not in objective_locations for q in active_leaves
                )
                if active_interaction_removed:
                    if not dry_run:
                        tx.abandon_active_interactions()
                else:
                    active_module_id = objective_locations[active_kp_id][0]
                    active_changed = (
                        active_interaction.question.module_id != active_module_id
                        or any(
                            question.module_id
                            != objective_locations[question.knowledge_point_id][0]
                            for question in active_leaves
                        )
                    )
                    active_interaction.question.module_id = active_module_id
                    for question in active_leaves:
                        question.module_id = objective_locations[question.knowledge_point_id][0]
                    if active_changed and not dry_run:
                        tx.put_interaction(active_interaction)
        if not dry_run:
            tx.touch()
            tx.emit(
                event_type,
                {
                    "mode": "append" if append else "replace",
                    "identity_map": identity_map,
                    "module_count": len(applied_modules),
                    "knowledge_point_count": sum(
                        len(module.knowledge_points) for module in applied_modules
                    ),
                },
                session_id=session_id,
                turn_id=turn_id,
            )
        return {
            "identity_map": identity_map,
            "active_interaction_removed": active_interaction_removed,
        }

    def preview_module_revision(
        self,
        book_id: str,
        modules: list[LearningModule],
        *,
        expected_revision: int,
        session_id: str,
        request_id: str = "",
    ) -> tuple[dict[str, Any], LearningProgress]:
        """Run the real replacement engine on a copy, then record the reviewed draft."""
        from deeptutor.learning.outline_revision import exact_diff, state_digest
        from deeptutor.learning.storage import LearningConflictError

        with self._store.transaction(book_id) as tx:
            if tx.base_revision != expected_revision:
                raise LearningConflictError(book_id, expected_revision, tx.base_revision)
            original = tx.progress
            tx.progress = original.model_copy(deep=True)
            try:
                effects = self._replace_module_set(tx, modules, dry_run=True)
                proposed = tx.progress.model_copy(deep=True)
            finally:
                tx.progress = original
            # Save-time bookkeeping is not a curriculum change or progress reset.
            exclude = {"version", "updated_at"}
            changes = exact_diff(
                original.model_dump(mode="json", exclude=exclude),
                proposed.model_dump(mode="json", exclude=exclude),
            )
            if not changes:
                raise ValueError("This plan changes nothing. Leave the current outline in place.")
            payload = {
                "base_revision": expected_revision,
                "request_id": request_id,
                "before_digest": state_digest(original),
                "after_digest": state_digest(proposed),
                "modules": [module.model_dump(mode="json") for module in proposed.modules],
                "changes": changes,
                "effects": effects,
                "before_module_order": [module.id for module in original.modules],
                "proposed_module_order": [module.id for module in proposed.modules],
            }
            preview_id = tx.record_module_preview(payload, session_id=session_id)
        return {
            "preview_id": preview_id,
            "base_revision": expected_revision,
            "changes": changes,
            "effects": effects,
            "before_module_order": payload["before_module_order"],
            "proposed_module_order": payload["proposed_module_order"],
            "module_order_changed": (
                payload["before_module_order"] != payload["proposed_module_order"]
            ),
        }, proposed

    def commit_module_revision(
        self,
        book_id: str,
        preview_id: int,
        *,
        session_id: str,
        turn_id: str = "",
        request_id: str = "",
    ) -> tuple[LearningProgress, dict[str, Any]]:
        """Apply only the persisted draft; stale state rolls back instead of overwriting."""
        from deeptutor.learning.outline_revision import state_digest
        from deeptutor.learning.storage import LearningConflictError

        with self._store.transaction(book_id) as tx:
            draft = tx.module_preview(preview_id, session_id=session_id)
            replayed = draft["committed_revision"] is not None
            if not replayed:
                if draft.get("request_id") and (
                    not request_id or request_id == draft["request_id"]
                ):
                    raise ValueError(
                        "Inspect this preview in a later model round before committing it."
                    )
                expected = int(draft["base_revision"])
                if expected != tx.base_revision:
                    raise LearningConflictError(book_id, expected, tx.base_revision)
                if state_digest(tx.progress) != draft["before_digest"]:
                    raise ValueError(
                        "The outline state changed. Create and review a fresh preview."
                    )
                self._replace_module_set(
                    tx,
                    [LearningModule.model_validate(m) for m in draft["modules"]],
                    session_id=session_id,
                    turn_id=turn_id,
                )
                if state_digest(tx.progress) != draft["after_digest"]:
                    raise ValueError(
                        "The preview no longer matches the engine result. Nothing was saved."
                    )
                tx.emit(
                    "path.modules_revision_committed",
                    {"preview_id": preview_id},
                    session_id=session_id,
                    turn_id=turn_id,
                )
            receipt = {
                "preview_id": preview_id,
                "replayed": replayed,
                "applied_revision": draft["committed_revision"]
                if replayed
                else tx.base_revision + 1,
                "applied_module_order": [module["id"] for module in draft["modules"]],
            }
        return tx.progress, receipt

    def create_topic(
        self,
        book_id: str,
        *,
        name: str,
        modules: list[LearningModule],
        metadata: TopicMetadata,
        sources: list[TopicSource],
        relation_refs: dict[str, RelationRefs] | None = None,
        source_aliases: dict[str, str] | None = None,
    ) -> LearningProgress:
        """Create a confirmed topic, sources, and route in one transaction."""

        if self._store.exists(book_id):
            raise ValueError(f"Mastery topic {book_id!r} already exists")

        def create(tx):
            tx.progress.name = str(name or "").strip()[:_MAX_PATH_NAME_LEN]
            tx.put_topic(metadata, sources)
            applied_modules = [module.model_copy(deep=True) for module in modules]
            self._resolve_final_relations(
                applied_modules,
                modules,
                relation_refs or {},
                source_aliases or {},
                sources,
            )
            validate_objective_relations(applied_modules, sources)
            self.replace_modules(tx.progress, applied_modules)
            tx.progress.current_module_id = applied_modules[0].id if applied_modules else ""
            tx.progress.current_kp_index = 0
            tx.touch()
            tx.emit(
                "topic.created",
                {
                    "module_count": len(modules),
                    "knowledge_point_count": sum(
                        len(module.knowledge_points) for module in modules
                    ),
                    "source_count": len(sources),
                },
            )

        progress, _ = self._store.mutate(book_id, create, create=True)
        return progress

    def rename_path(self, book_id: str, name: str) -> LearningProgress:
        """Set (or clear) the learner-facing name of a path.

        Clearing it is meaningful, not a no-op: an empty name hands the path
        back to the derived display name, which is the only way to undo a
        rename without inventing a second "auto" flag.
        """
        cleaned = str(name or "").strip()[:_MAX_PATH_NAME_LEN]

        def rename(tx):
            if tx.progress.name == cleaned:
                return cleaned
            tx.progress.name = cleaned
            tx.touch()
            tx.emit("path.renamed", {"name": cleaned})
            return cleaned

        progress, _ = self._store.mutate(book_id, rename)
        return progress

    def record_learner_profile(
        self,
        book_id: str,
        *,
        fields: dict[str, str],
        session_id: str = "",
        turn_id: str = "",
        teaching_updates: list[dict] | None = None,
        expected_revision: int | None = None,
        learner_message: str = "",
        clear_fields: list[str] | None = None,
        clear_request: str = "",
    ) -> tuple[LearningProgress, list[str]]:
        """Merge intake answers into this goal's learner profile.

        Merge, never replace: intake is not a single moment. The first session
        asks four questions, and months later "我时间变少了" has to be able to
        change one of them without wiping the other three. Only fields the
        caller actually names are touched, so an omitted field keeps whatever
        the learner said about it before.

        Returns the progress and the names of the fields that really changed,
        so the caller can tell the learner what it recorded rather than
        claiming to have recorded everything it was handed.
        """
        cleaned = {
            key: str(value or "").strip()[:_MAX_PROFILE_FIELD_LEN]
            for key, value in fields.items()
            if key in _LEARNER_PROFILE_FIELDS and value is not None and str(value).strip()
        }
        # Optional schema placeholders are not learner-authored deletions.
        # Deletion has its own explicit, quoted, revision-fenced operation.
        if clear_fields is not None and (
            not isinstance(clear_fields, list)
            or any(
                not isinstance(key, str)
                or key not in _LEARNER_PROFILE_FIELDS
                or key == "teaching_strategy"
                for key in clear_fields
            )
        ):
            raise ValueError("clear_fields must name intake text fields")
        if clear_fields:
            if (
                not isinstance(clear_request, str)
                or not clear_request.strip()
                or clear_request not in learner_message
            ):
                raise ValueError(
                    "clear_request must be a literal quote from the current learner message"
                )
            if any(key in cleaned for key in clear_fields):
                raise ValueError("Cannot update and clear the same profile field")
            if type(expected_revision) is not int or expected_revision < 0:
                raise ValueError("clear_fields requires the current path revision")
            cleaned.update({key: "" for key in clear_fields})
        from deeptutor.learning.teaching import apply_teaching_updates, parse_teaching_updates

        updates = (
            parse_teaching_updates(teaching_updates, learner_message)
            if teaching_updates is not None
            else []
        )
        if updates and (type(expected_revision) is not int or expected_revision < 0):
            raise ValueError("teaching_updates requires the current path revision")
        if "teaching_strategy" in cleaned and cleaned["teaching_strategy"] not in {
            "probe_first",
            "teach_first",
        }:
            raise ValueError("teaching_strategy must be probe_first or teach_first")

        def record(tx):
            profile = tx.progress.learner_profile or LearnerProfile()
            teaching_fields = (
                apply_teaching_updates(
                    profile,
                    updates,
                    {kp.id for module in tx.progress.modules for kp in module.knowledge_points},
                    session_id=session_id,
                    turn_id=turn_id,
                )
                if updates
                else {}
            )
            changed = [key for key, value in cleaned.items() if getattr(profile, key) != value]
            changed.extend(teaching_fields)
            if not changed:
                return []
            if (updates or clear_fields) and tx.progress.version != expected_revision:
                from deeptutor.learning.storage import LearningConflictError

                raise LearningConflictError(book_id, expected_revision, tx.progress.version)
            updated = profile.model_copy(
                update={**cleaned, **teaching_fields, "updated_at": time.time()}
            )
            tx.progress.learner_profile = updated
            tx.touch()
            tx.emit(
                "path.learner_profile_recorded",
                {"fields": changed},
                session_id=session_id,
                turn_id=turn_id,
            )
            return changed

        return self._store.mutate(book_id, record, create=not bool(updates or clear_fields))

    def abandon_active_question(self, book_id: str) -> tuple[LearningProgress, bool]:
        """Drop the outstanding question so the path can move on.

        A posed question outranks everything in ``policy.next_objective`` and
        blocks ``register_question`` from posing another, which is what keeps
        the gate honest — but it also means a question the learner can no
        longer answer (its conversation is gone, the card was never shown)
        would stall the path with no way out short of resetting all progress.
        Abandoning is deliberately explicit rather than automatic: an
        unanswered question is normally resumable across turns, so only the
        learner can say this one is not.

        Returns the progress and whether anything was outstanding.
        """

        def abandon(tx):
            interaction = tx.active_interaction()
            abandoned = tx.abandon_active_interactions() > 0
            if tx.progress.pending_question is not None:
                tx.progress.pending_question = None
                abandoned = True
            if not abandoned:
                return False
            tx.touch()
            tx.emit(
                "interaction.abandoned",
                {"interaction_id": interaction.interaction_id if interaction else ""},
            )
            return True

        return self._store.mutate(book_id, abandon)

    def reset_path(self, book_id: str) -> LearningProgress:
        def reset(tx):
            progress = tx.progress
            progress.current_stage = LearningStage.DIAGNOSTIC
            progress.mastery_levels = {}
            progress.qualitative_mastery = {}
            progress.quiz_attempts = []
            progress.error_records = []
            progress.learning_evidence = []
            progress.repetition_states = {}
            progress.review_queue = []
            progress.learner_mastery_overrides = {}
            progress.deferred_objectives = {}
            progress.explained_objectives = {}
            progress.pending_question = None
            progress.feynman_retries = {}
            progress.feynman_explanations = {}
            progress.stage_failure_counts = {}
            progress.stage_failure_notes = {}
            progress.diagnostic = None
            progress.current_kp_index = 0
            progress.current_module_id = progress.modules[0].id if progress.modules else ""
            tx.abandon_active_interactions()
            tx.touch()
            tx.emit("path.reset", {})

        progress, _ = self._store.mutate(book_id, reset)
        return progress

    def set_learner_mastery_override(
        self,
        book_id: str,
        kp_id: str,
        *,
        mastered: bool,
        note: str = "",
    ) -> LearningProgress:
        """Set or clear an explicit learner claim without changing evidence."""

        def update(tx):
            from deeptutor.learning.policy import find_knowledge_point

            kp, _, _ = find_knowledge_point(tx.progress, kp_id)
            if kp is None:
                raise MasteryInteractionError(f"Unknown objective {kp_id!r}")
            if mastered:
                tx.progress.learner_mastery_overrides[kp_id] = LearnerMasteryOverride(
                    knowledge_point_id=kp_id,
                    note=str(note or "").strip()[:500],
                )
                tx.progress.deferred_objectives.pop(kp_id, None)
                event_type = "mastery.overridden"
            else:
                if kp_id not in tx.progress.learner_mastery_overrides:
                    return
                tx.progress.learner_mastery_overrides.pop(kp_id, None)
                event_type = "mastery.override_cleared"
            tx.touch()
            tx.emit(
                event_type,
                {"knowledge_point_id": kp_id, "mastered": bool(mastered)},
            )

        progress, _ = self._store.mutate(book_id, update)
        return progress

    def _recompute_objective_state(
        self,
        progress: LearningProgress,
        kp_id: str,
        scheduler: SpacedRepetitionScheduler | None,
    ) -> None:
        if not kp_id:
            return
        self.update_mastery(progress, kp_id, self.calculate_mastery(progress, kp_id))
        if scheduler is None:
            return
        kp_type = progress.knowledge_types.get(kp_id)
        attempts = [
            attempt
            for attempt in progress.quiz_attempts
            if attempt.knowledge_point_id == kp_id and not attempt.voided
        ]
        events = [
            event for event in progress.learning_evidence if event.knowledge_point_id == kp_id
        ]
        if kp_type is None or (not attempts and not events):
            progress.repetition_states.pop(kp_id, None)
        elif events:
            progress.repetition_states[kp_id] = scheduler.replay(
                kp_type,
                # Live transitions follow durable append order. A linked
                # assessment can arrive after a newer one with an older source
                # timestamp; sorting it here would make repair diverge (#1541).
                events,
                desired_retention=progress.desired_retention,
            )
        else:
            synthesized = [
                LearningEvidence(
                    question_id=attempt.question_id,
                    knowledge_point_id=kp_id,
                    timestamp=attempt.timestamp,
                    assessment_type="quiz",
                    result="correct" if attempt.is_correct else "incorrect",
                    quality=1.0 if attempt.is_correct else 0.0,
                    attempt_count=index,
                )
                for index, attempt in enumerate(
                    sorted(attempts, key=lambda item: item.timestamp),
                    start=1,
                )
            ]
            progress.repetition_states[kp_id] = scheduler.replay(
                kp_type, synthesized, desired_retention=progress.desired_retention
            )
        progress.review_queue = scheduler.build_review_queue(progress)

    def repair_question(
        self,
        book_id: str,
        question_id: str = "",
        *,
        action: str,
        expected_answer: str = "",
        reason: str = "",
        scheduler: SpacedRepetitionScheduler | None = None,
        session_id: str = "",
        turn_id: str = "",
        _assessment: dict | None = None,
    ) -> tuple[LearningProgress, dict]:
        """Void or re-key one question and rebuild that objective's evidence."""

        action_name = str(action or "").strip().lower()
        if action_name not in {"void", "correct"}:
            raise MasteryInteractionError("action must be 'void' or 'correct'")
        note = str(reason or "").strip()[:500]
        if not note:
            raise MasteryInteractionError("A reason is required so the repair can be audited")
        if action_name == "correct" and not str(expected_answer or "").strip():
            raise MasteryInteractionError("correcting a question requires the new expected_answer")

        def repair(tx):
            requested_id = str(question_id or "").strip()
            interaction = tx.get_interaction(requested_id) if requested_id else None
            if interaction is None and not requested_id:
                interaction = tx.active_interaction()
            pending = tx.progress.pending_question
            if interaction is not None:
                resolved_id = interaction.interaction_id
            elif requested_id:
                resolved_id = requested_id
            elif pending is not None:
                resolved_id = pending.question_id
            else:
                latest = next(
                    (
                        attempt.question_id
                        for attempt in reversed(tx.progress.quiz_attempts)
                        if not attempt.voided
                    ),
                    "",
                )
                resolved_id = latest
            if not resolved_id:
                raise NoPendingInteractionError("No question is available to repair")
            if interaction is None:
                interaction = tx.get_interaction(resolved_id)
            if pending is not None and pending.question_id != resolved_id:
                pending = None
            elif (
                pending is None
                and tx.progress.pending_question is not None
                and tx.progress.pending_question.question_id == resolved_id
            ):
                pending = tx.progress.pending_question

            attempts = [
                attempt
                for attempt in tx.progress.quiz_attempts
                if attempt.question_id == resolved_id
            ]
            question = interaction.question if interaction is not None else pending
            original_expected = question.expected_answer if question is not None else ""
            previous_result = dict(interaction.result) if interaction else {}
            if (
                action_name == "correct"
                and previous_result.get("confidence") is not None
                and not _assessment
            ):
                raise MasteryInteractionError(
                    "A semantic verdict requires semantic re-evaluation; use repair_question_semantic."
                )
            if _assessment:
                from deeptutor.learning.lesson_evidence import (
                    LessonUnavailable,
                    objective_fingerprint,
                )
                from deeptutor.learning.semantic_assessment import fingerprint, validate_question

                if (
                    interaction is None
                    or fingerprint(interaction.model_dump()) != _assessment["state"]
                    or objective_fingerprint(tx.progress, question.knowledge_point_id)
                    != _assessment["objective"]
                ):
                    raise MasteryInteractionError(
                        "Question or answer changed during correction; retry."
                    )
                question = _assessment["question"].model_copy(deep=True)
                try:
                    validate_question(self._store, tx.progress, question)
                except LessonUnavailable as exc:
                    raise MasteryInteractionError(str(exc)) from exc
                interaction.question = question
            if question is not None and question.questions:
                raise MasteryInteractionError(
                    "A group has no aggregate answer key; review or challenge an individual child question_id"
                )
            kp_id = (question.knowledge_point_id if question is not None else "") or (
                attempts[0].knowledge_point_id if attempts else ""
            )
            module_id = (question.module_id if question is not None else "") or (
                attempts[0].module_id if attempts else ""
            )
            question_type = question.question_type if question is not None else "short"
            previous_expected = original_expected
            previous_is_correct = attempts[0].is_correct if attempts else None
            if action_name == "correct" and question is not None and question.visual_context:
                from deeptutor.learning.visual_practice import prepare_visual

                candidate_answer = str(expected_answer or question.expected_answer)
                if not question.visual_context.get("pixels_inspected"):
                    raise MasteryInteractionError(
                        "This visual practice had no verified pixel inspection. Void it and pose a supported replacement; a challenge cannot create mastery evidence."
                    )
                try:
                    corrected_visual, corrected_aliases = prepare_visual(
                        {
                            **question.visual_context,
                            "accepted_answers": [],
                            "key_status": "verified",
                        },
                        expected_answer=candidate_answer,
                        options=question.choice_map,
                    )
                except (OSError, ValueError, TypeError) as exc:
                    raise MasteryInteractionError(
                        "Visual correction lacks current source support; void the assessment and pose a supported replacement."
                    ) from exc
                if corrected_visual["key_status"] != "verified":
                    raise MasteryInteractionError(
                        "Visual correction lacks a source-supported key; void the assessment instead of granting unsupported mastery."
                    )
                question.accepted_answers = corrected_aliases
                question.visual_context = corrected_visual
            user_answer = (interaction.user_answer if interaction is not None else "") or (
                str(attempts[0].user_answer or "") if attempts else ""
            )

            repaired_correct: bool | None = previous_is_correct
            new_expected = previous_expected
            if action_name == "void":
                for attempt in attempts:
                    attempt.voided = True
                    attempt.void_reason = note
                tx.progress.error_records = [
                    record
                    for record in tx.progress.error_records
                    if record.question_id != resolved_id
                ]
                if pending is not None:
                    tx.progress.pending_question = None
                active = tx.active_interaction()
                if active is not None and active.interaction_id == resolved_id:
                    tx.abandon_active_interactions()
                elif interaction is not None and interaction.status != InteractionStatus.ABANDONED:
                    interaction.result = {
                        **dict(interaction.result or {}),
                        "voided": True,
                        "reason": note,
                    }
                    tx.put_interaction(interaction)
                _drop_quiz_evidence_for_attempts(tx.progress, attempts)
                repaired_correct = None
            else:
                new_expected = str(expected_answer or "").strip()
                from deeptutor.learning.lesson_evidence import LessonUnavailable, validate_evidence

                try:
                    if _assessment:
                        validate_question(self._store, tx.progress, question)
                    else:
                        validate_evidence(
                            self._store,
                            tx.progress,
                            kp_id,
                            question.source_evidence if question else {},
                        )
                except LessonUnavailable as exc:
                    raise MasteryInteractionError(str(exc)) from exc
                if question is not None:
                    question.expected_answer = new_expected
                if interaction is not None:
                    interaction.question.expected_answer = new_expected
                if (
                    tx.progress.pending_question is not None
                    and tx.progress.pending_question.question_id == resolved_id
                ):
                    tx.progress.pending_question.expected_answer = new_expected
                if attempts:
                    for attempt in attempts:
                        if attempt.voided:
                            continue
                        receipt = _assessment.get("receipt") if _assessment else None
                        is_correct = (
                            receipt["result"] == "correct"
                            if receipt
                            else bool(new_expected)
                            and grade_answer(
                                str(attempt.user_answer or ""),
                                new_expected,
                                question_type,
                            )
                        )
                        attempt.is_correct = is_correct
                        attempt.result = (
                            receipt["result"]
                            if receipt
                            else ("correct" if is_correct else "incorrect")
                        )
                        attempt.error_type = (
                            None
                            if is_correct or attempt.result == "partial"
                            else classify_error(str(attempt.user_answer or ""))
                        )
                        repaired_correct = is_correct
                        if is_correct:
                            for record in tx.progress.error_records:
                                if record.question_id == resolved_id:
                                    record.status = "graduated"
                        elif attempt.result == "partial":
                            tx.progress.error_records = [
                                record
                                for record in tx.progress.error_records
                                if record.question_id != resolved_id
                            ]
                        elif not any(
                            record.question_id == resolved_id
                            for record in tx.progress.error_records
                        ):
                            tx.progress.error_records.append(
                                ErrorRecord(
                                    id=uuid.uuid4().hex,
                                    question_id=resolved_id,
                                    knowledge_point_id=kp_id,
                                    module_id=module_id,
                                    error_type=attempt.error_type
                                    or classify_error(str(attempt.user_answer or "")),
                                    status="active",
                                )
                            )
                if interaction is not None:
                    repair_receipt = (_assessment or {}).get("receipt") or {
                        "result": "correct" if repaired_correct else "incorrect",
                        "final": True,
                        "needs_clarification": False,
                        "feedback": note,
                        "confidence": None,
                    }
                    if _assessment and _assessment.get("receipt"):
                        repaired_correct = repair_receipt["is_correct"]
                    interaction.result = {
                        **dict(interaction.result or {}),
                        "is_correct": repaired_correct,
                        "corrected": True,
                        "reason": note,
                        **repair_receipt,
                    }
                    tx.put_interaction(interaction)
                _update_quiz_evidence_for_attempts(
                    tx.progress,
                    [attempt for attempt in attempts if not attempt.voided],
                )

            self._recompute_objective_state(tx.progress, kp_id, scheduler)
            if interaction is not None and interaction.result.get("group_question_id"):
                self._refresh_group_result(tx, interaction)
            tx.touch()
            tx.emit(
                "assessment.voided" if action_name == "void" else "assessment.corrected",
                {
                    "question_id": resolved_id,
                    "knowledge_point_id": kp_id,
                    "reason": note,
                    "previous_expected": previous_expected,
                    "expected_answer": new_expected,
                    "previous_is_correct": previous_is_correct,
                    "previous_result": previous_result,
                    "learner_answer": user_answer,
                    "is_correct": repaired_correct,
                },
                session_id=session_id or (interaction.session_id if interaction else ""),
                turn_id=turn_id or (interaction.turn_id if interaction else ""),
            )
            return {
                "action": action_name,
                "question_id": resolved_id,
                "knowledge_point_id": kp_id,
                "module_id": module_id,
                "reason": note,
                "previous_expected": previous_expected,
                "expected_answer": new_expected,
                "previous_is_correct": previous_is_correct,
                "is_correct": repaired_correct,
                "result": interaction.result.get("result", "") if interaction else "",
                "feedback": interaction.result.get("feedback", "") if interaction else "",
                "user_answer": user_answer,
                "question_type": question_type,
                "prompt": question.prompt if question is not None else "",
                "options": question.choice_map if question is not None else {},
                "explanation": question.explanation if question is not None else "",
                "difficulty": question.difficulty if question is not None else "",
                "session_id": session_id or (interaction.session_id if interaction else ""),
                "turn_id": turn_id or (interaction.turn_id if interaction else ""),
            }

        progress, details = self._store.mutate(book_id, repair)
        return progress, details

    @staticmethod
    def _group_leaf_result(stored: MasteryInteraction) -> dict:
        """Project a committed leaf, including later repairs, without regrading."""
        from deeptutor.learning.question_card import build_grade_result

        correct = None if stored.result.get("voided") else stored.result.get("is_correct")
        result = build_grade_result(
            question_id=stored.interaction_id,
            is_correct=bool(correct),
            learner_answer=stored.user_answer,
            correct_label=stored.question.expected_answer if correct is not None else "",
            choice_options=stored.question.choice_map,
            explanation=stored.question.explanation
            if correct is not None
            else str(stored.result.get("reason") or stored.result.get("diagnosis") or ""),
            result="ungraded" if correct is None else "",
            independent=stored.result.get("independent", _question_independent(stored.question)),
        )
        result.update(
            {"is_correct": correct, "knowledge_point_id": stored.question.knowledge_point_id}
        )
        result.update(
            {
                key: stored.result[key]
                for key in ("result", "final", "needs_clarification", "feedback", "confidence")
                if key in stored.result
            }
        )
        if stored.result.get("diagnosis"):
            result["diagnosis"] = stored.result["diagnosis"]
        return result

    def _refresh_group_result(self, tx, leaf: MasteryInteraction) -> None:
        """Keep a complete or partial parent consistent after a native leaf repair."""
        parent = tx.get_interaction(leaf.result["group_question_id"])
        if parent is None:
            return
        results = []
        questions = []
        for question in parent.question.questions:
            stored = tx.get_interaction(question.question_id)
            if stored is None or stored.result.get("group_question_id") != parent.interaction_id:
                questions.append(question)
                continue
            questions.append(stored.question)
            results.append(self._group_leaf_result(stored))
        parent.question.questions = questions
        parent.result = self._group_result(parent.question, results)
        if (
            tx.progress.pending_question is not None
            and tx.progress.pending_question.question_id == parent.interaction_id
        ):
            tx.progress.pending_question = parent.question
        tx.put_interaction(parent)

    def defer_objective(
        self,
        book_id: str,
        kp_id: str = "",
        *,
        note: str = "",
        session_id: str = "",
        turn_id: str = "",
    ) -> tuple[LearningProgress, dict]:
        """Skip this objective for now without recording mastery."""

        def defer(tx):
            from deeptutor.learning.policy import find_knowledge_point, is_mastered, next_objective

            target_id = str(kp_id or "").strip()
            if not target_id:
                pending = tx.progress.pending_question
                if pending is not None:
                    target_id = pending.knowledge_point_id
                else:
                    target_id = next_objective(tx.progress).knowledge_point_id
            kp, _, _ = find_knowledge_point(tx.progress, target_id)
            if kp is None:
                raise MasteryInteractionError(f"Unknown objective {target_id!r}")
            if is_mastered(tx.progress, kp):
                raise MasteryInteractionError(
                    f"{kp.name!r} is already mastered, so there is nothing to defer"
                )
            abandoned = False
            pending = tx.progress.pending_question
            if pending is not None and any(
                q.knowledge_point_id == target_id for q in pending.questions or [pending]
            ):
                tx.progress.pending_question = None
                abandoned = True
            active = tx.active_interaction()
            if active is not None and any(
                q.knowledge_point_id == target_id
                for q in active.question.questions or [active.question]
            ):
                tx.abandon_active_interactions()
                abandoned = True
            tx.progress.deferred_objectives[target_id] = DeferredObjective(
                knowledge_point_id=target_id,
                note=str(note or "").strip()[:500],
            )
            tx.touch()
            tx.emit(
                "objective.deferred",
                {
                    "knowledge_point_id": target_id,
                    "note": str(note or "").strip()[:500],
                    "abandoned_question": abandoned,
                },
                session_id=session_id,
                turn_id=turn_id,
            )
            return {"knowledge_point_id": target_id, "abandoned_question": abandoned}

        return self._store.mutate(book_id, defer)

    def record_qualitative(
        self,
        progress: LearningProgress,
        kp_id: str,
        *,
        passed: bool,
        evidence: str = "",
        scheduler: SpacedRepetitionScheduler | None = None,
    ) -> None:
        """Record the qualitative (CONCEPT / DESIGN) gate outcome.

        The boolean is the gate of record; ``mastery_levels`` is nudged only so
        the map's colour matches the gate (full on pass, capped on fail).

        Every assessment applies the same retention transition that evidence
        replay uses. This keeps the persisted state reproducible and lets an
        initial failure schedule the prompt repair it demonstrably needs.
        """
        self.record_qualitative_in_memory(
            progress,
            kp_id,
            passed=passed,
            evidence=evidence,
            scheduler=scheduler,
        )
        self.save(progress)

    def record_qualitative_for_path(
        self,
        book_id: str,
        kp_id: str,
        *,
        passed: bool,
        evidence: str = "",
        scheduler: SpacedRepetitionScheduler | None = None,
        session_id: str = "",
        turn_id: str = "",
        _assessment: dict | None = None,
    ) -> LearningProgress:
        def record(tx):
            from deeptutor.learning.policy import QUALITATIVE_TYPES, find_knowledge_point

            kp, _, _ = find_knowledge_point(tx.progress, kp_id)
            if kp is None:
                raise MasteryInteractionError(
                    f"Unknown objective {kp_id!r}; refresh mastery_status"
                )
            if kp.type not in QUALITATIVE_TYPES:
                raise MasteryInteractionError(
                    f"Objective {kp.name!r} must be graded with mastery_quiz + mastery_grade"
                )
            from deeptutor.learning.lesson_evidence import LessonUnavailable, validate_evidence

            try:
                validate_evidence(
                    self._store, tx.progress, kp_id, tx.progress.lesson_evidence.get(kp_id, {})
                )
                if _assessment:
                    from deeptutor.learning.lesson_evidence import objective_fingerprint
                    from deeptutor.learning.semantic_assessment import fingerprint

                    if (
                        objective_fingerprint(tx.progress, kp_id) != _assessment["objective"]
                        or fingerprint(tx.progress.lesson_evidence.get(kp_id, {}))
                        != _assessment["source"]
                    ):
                        raise MasteryInteractionError(
                            "Objective or source changed during assessment; retry."
                        )
            except LessonUnavailable as exc:
                raise MasteryInteractionError(str(exc)) from exc
            applied = self.record_qualitative_in_memory(
                tx.progress,
                kp_id,
                passed=passed,
                evidence=evidence,
                scheduler=scheduler,
                session_id=session_id,
                turn_id=turn_id,
                verdict=_assessment["receipt"] if _assessment else None,
            )
            if not applied:
                return
            tx.touch()
            tx.emit(
                "mastery.assessed",
                {
                    "knowledge_point_id": kp_id,
                    "passed": bool(passed),
                },
                session_id=session_id,
                turn_id=turn_id,
            )
            if tx.progress.learning_evidence:
                latest = tx.progress.learning_evidence[-1]
                if latest.knowledge_point_id == kp_id:
                    tx.emit(
                        "evidence.recorded",
                        {
                            "knowledge_point_id": latest.knowledge_point_id,
                            "assessment_type": latest.assessment_type,
                            "result": latest.result,
                            "quality": latest.quality,
                        },
                        session_id=session_id,
                        turn_id=turn_id,
                    )

        progress, _ = self._store.mutate(book_id, record)
        return progress

    @staticmethod
    def record_qualitative_in_memory(
        progress: LearningProgress,
        kp_id: str,
        *,
        passed: bool,
        evidence: str = "",
        scheduler: SpacedRepetitionScheduler | None = None,
        session_id: str = "",
        turn_id: str = "",
        verdict: dict | None = None,
    ) -> bool:
        evidence_id = ""
        if session_id or turn_id:
            evidence_id = uuid.uuid5(
                uuid.NAMESPACE_URL,
                f"deeptutor:qualitative:{session_id}:{turn_id}:{kp_id}",
            ).hex
            if any(item.evidence_id == evidence_id for item in progress.learning_evidence):
                return False
        progress.qualitative_mastery[kp_id] = bool(passed)
        progress.deferred_objectives.pop(kp_id, None)
        current = progress.mastery_levels.get(kp_id, 0.0)
        progress.mastery_levels[kp_id] = max(current, 1.0) if passed else min(current, 0.4)
        if evidence:
            progress.feynman_explanations[kp_id] = evidence
        moment = time.time()
        review_evidence = LearningEvidence(
            evidence_id=evidence_id,
            knowledge_point_id=kp_id,
            timestamp=moment,
            assessment_type="qualitative",
            result=verdict["result"] if verdict else ("correct" if passed else "partial"),
            quality={"correct": 1.0, "partial": 0.5, "incorrect": 0.0}[verdict["result"]]
            if verdict
            else ((1.0 if evidence else 0.9) if passed else 0.2),
            confidence=verdict.get("confidence") if verdict else None,
            learner_answer=evidence,
            feedback=verdict.get("feedback", "") if verdict else "",
            attempt_count=1,
            session_id=session_id,
            turn_id=turn_id,
        )
        progress.learning_evidence.append(review_evidence)
        kp_type = progress.knowledge_types.get(kp_id)
        if kp_type is not None and scheduler is not None:
            state = progress.repetition_states.get(kp_id) or scheduler.get_initial_state(
                kp_type,
                now=review_evidence.timestamp,
                desired_retention=progress.desired_retention,
            )
            progress.repetition_states[kp_id] = state
            scheduler.schedule_review(
                state,
                kp_type,
                review_evidence,
                now=review_evidence.timestamp,
            )
            progress.review_queue = scheduler.build_review_queue(progress)
        progress.updated_at = moment
        return True

    def list_path_overviews(self) -> list[dict]:
        """Gate-accurate one-line state for every path the learner owns.

        ``list_progress`` reports an *average* mastery percentage, which is the
        right number for a progress bar and the wrong one for deciding what is
        finished: mastery is a per-objective gate, so "3 of 4 cleared" is the
        fact, and an average can sit at 75% with nothing actually mastered.
        This reports the counts the gate itself produces.
        """
        from deeptutor.learning import policy

        overviews: list[dict] = []
        for path_id in self._store.list_all():
            try:
                progress = self._store.load(path_id)
            except Exception:
                logging.getLogger(__name__).warning(
                    "Failed to load mastery path %s for overview", path_id, exc_info=True
                )
                continue
            if progress is None:
                continue
            summary = policy.map_summary(progress)
            counts = summary["counts"]
            overviews.append(
                {
                    "path_id": progress.book_id,
                    "name": policy.path_display_name(progress),
                    "objectives": counts["total"],
                    "mastered": counts["mastered"],
                    "learning": counts["learning"],
                    "not_started": counts["new"],
                    "due_reviews": summary["due_reviews"],
                    "complete": summary["complete"],
                    "open_question": progress.pending_question is not None,
                    "updated_at": progress.updated_at,
                }
            )
        overviews.sort(key=lambda overview: overview["updated_at"], reverse=True)
        return overviews

    def list_progress(self) -> dict:
        """Return summary of all book progress with per-book error info."""
        from deeptutor.learning import policy

        logger = logging.getLogger(__name__)

        book_ids = self._store.list_all()
        summaries = []
        errors = []
        for bid in book_ids:
            try:
                progress = self._store.load(bid)
                if progress is None:
                    continue
                # Only count KPs from current modules (exclude stale IDs)
                current_kp_ids = {kp.id for m in progress.modules for kp in m.knowledge_points}
                total_kps = len(current_kp_ids)
                total_mastery = sum(
                    progress.mastery_levels.get(kp_id, 0) for kp_id in current_kp_ids
                )
                summaries.append(
                    {
                        "book_id": progress.book_id,
                        "name": policy.path_display_name(progress),
                        "modules_count": len(progress.modules),
                        "kp_count": total_kps,
                        "current_stage": progress.current_stage.value
                        if progress.current_stage
                        else "",
                        # Average mastery across current KPs (not the % of KPs mastered).
                        "avg_mastery_pct": round(total_mastery / total_kps * 100)
                        if total_kps
                        else 0,
                        "updated_at": progress.updated_at,
                    }
                )
            except Exception:
                logger.warning("Failed to load progress for book %s, skipping", bid, exc_info=True)
                errors.append({"book_id": bid, "error": "Failed to load"})
                continue
        return {"summaries": summaries, "errors": errors}

    def save(self, progress: LearningProgress) -> None:
        self._store.save(progress)

    async def assess_qualitative_semantic(
        self, book_id, kp_id, *, learner_answer, config=None, **kwargs
    ):
        from deeptutor.learning import semantic_assessment as semantic
        from deeptutor.learning.lesson_evidence import (
            LessonUnavailable,
            objective_fingerprint,
            validate_evidence,
        )
        from deeptutor.learning.policy import find_knowledge_point

        answer = str(learner_answer or "").strip()
        if not answer or len(answer) > 10000:
            raise MasteryInteractionError(
                "Assessment needs the actual learner explanation, at most 10000 characters."
            )
        progress = self._store.load(book_id)
        kp, module_id, _ = find_knowledge_point(progress, kp_id)
        if kp is None:
            raise MasteryInteractionError("Unknown objective")
        session_id, turn_id = kwargs.get("session_id", ""), kwargs.get("turn_id", "")
        if session_id or turn_id:
            evidence_id = uuid.uuid5(
                uuid.NAMESPACE_URL, f"deeptutor:qualitative:{session_id}:{turn_id}:{kp_id}"
            ).hex
            existing = next(
                (item for item in progress.learning_evidence if item.evidence_id == evidence_id),
                None,
            )
            if existing:
                return progress, semantic.Verdict(
                    result=existing.result,
                    confidence=existing.confidence if existing.confidence is not None else 1.0,
                    feedback=existing.feedback or "Previously saved assessment.",
                ).receipt()
        evidence = progress.lesson_evidence.get(kp_id, {})
        try:
            validate_evidence(self._store, progress, kp_id, evidence)
            objective = objective_fingerprint(progress, kp_id)
            decisions = await semantic.judge_answers(
                config,
                [
                    {
                        "question_id": kp_id,
                        "prompt": "Explain this objective in your own words: " + kp.name,
                        "expected_answer": "A complete, accurate explanation of the objective and its relationships; do not infer mastery from acknowledgements or requests.",
                        "objective": kp.model_dump(),
                        "module_id": module_id,
                        "answer": answer,
                        "source_evidence": evidence,
                    }
                ],
            )
        except (semantic.AssessmentUnavailable, LessonUnavailable) as exc:
            raise MasteryInteractionError(str(exc)) from exc
        receipt = decisions[kp_id].receipt()
        if not receipt["final"]:
            return progress, receipt
        progress = self.record_qualitative_for_path(
            book_id,
            kp_id,
            passed=receipt["result"] == "correct",
            evidence=answer,
            _assessment={
                "objective": objective,
                "source": semantic.fingerprint(evidence),
                "receipt": receipt,
            },
            **kwargs,
        )
        return progress, receipt

    async def grade_interaction_semantic(self, book_id: str, *, config=None, **kwargs):
        """Evaluate outside the transaction, then fence every input at commit."""
        from deeptutor.learning import semantic_assessment as semantic
        from deeptutor.learning.lesson_evidence import LessonUnavailable, objective_fingerprint

        question_id = kwargs.get("question_id", "")
        interaction = (
            self._store.get_interaction(book_id, question_id)
            if question_id
            else self._store.get_active_interaction(book_id)
        )
        if interaction is None:
            legacy_progress = self._store.load(book_id)
            legacy = legacy_progress.pending_question if legacy_progress else None
            if legacy is not None and (not question_id or legacy.question_id == question_id):
                interaction = self.record_question_answer(
                    book_id,
                    kwargs.get("answer", ""),
                    answers=kwargs.get("answers"),
                    interaction_id=question_id,
                    session_id=kwargs.get("session_id", ""),
                    turn_id=kwargs.get("turn_id", ""),
                )
        if interaction is None or interaction.status in {
            InteractionStatus.GRADED,
            InteractionStatus.ABANDONED,
        }:
            return self.grade_interaction(book_id, **kwargs)
        progress = self._store.load(book_id)
        state = semantic.fingerprint(interaction.model_dump())
        pending = interaction.question
        answers = (
            self._merge_group_answers(interaction, kwargs.get("answers"))
            if pending.questions
            else {
                pending.question_id: interaction.user_answer
                if interaction.status == InteractionStatus.ANSWERED
                else kwargs.get("answer", "")
            }
        )
        if not pending.questions and pending.question_type == "choice":
            from deeptutor.learning.pending import is_readable_choice_answer

            if not is_readable_choice_answer(answers[pending.question_id], pending.choice_map):
                answers[pending.question_id] = kwargs.get("answer", "")
        verdicts, items, objectives, source_updates = {}, [], {}, {}
        try:
            for question in pending.questions or [pending]:
                if question.question_id not in answers:
                    continue
                if len(answers[question.question_id]) > 10000:
                    raise MasteryInteractionError(
                        "An assessment answer must be at most 10000 characters."
                    )
                stored = (
                    self._store.get_interaction(book_id, question.question_id)
                    if pending.questions
                    else None
                )
                if (
                    stored
                    and stored.status == InteractionStatus.GRADED
                    and stored.result.get("final", True)
                ):
                    continue
                if question.source_evidence and not question.source_evidence.get(
                    "assessment_contract"
                ):
                    await semantic.bind_question(self._store, progress, question, config)
                    source_updates[question.question_id] = question.source_evidence
                semantic.validate_question(self._store, progress, question)
                objectives[question.knowledge_point_id] = objective_fingerprint(
                    progress, question.knowledge_point_id
                )
                if question.visual_context:
                    from deeptutor.learning.visual_practice import (
                        evaluate_visual,
                        verified_visual_images,
                    )

                    visual_result, diagnosis = evaluate_visual(
                        question, answers[question.question_id]
                    )
                    if visual_result in {"correct", "incorrect"}:
                        continue
                    try:
                        images = verified_visual_images(question)
                    except ValueError:
                        # A failed source/key/pixel check remains ungraded; a
                        # semantic model cannot promote missing authority.
                        verdicts[question.question_id] = semantic.Verdict(
                            result="ungraded", confidence=0, feedback=diagnosis
                        ).receipt()
                        continue
                    if question.question_type == "choice":
                        verdicts[question.question_id] = semantic.Verdict(
                            result="ungraded", confidence=0, feedback=diagnosis
                        ).receipt()
                        continue
                    items.append(
                        {
                            **semantic.question_contract(question),
                            "answer": answers[question.question_id],
                            "source_evidence": {},
                            "_visual_images": images,
                        }
                    )
                    continue
                exact = semantic.exact_verdict(question, answers[question.question_id])
                if exact:
                    verdicts[question.question_id] = exact.receipt()
                else:
                    items.append(
                        {
                            **semantic.question_contract(question),
                            "answer": answers[question.question_id],
                            "source_evidence": question.source_evidence,
                        }
                    )
            if items:
                decisions = await semantic.judge_answers(config, items)
                verdicts.update({key: value.receipt() for key, value in decisions.items()})
        except (semantic.AssessmentUnavailable, LessonUnavailable) as exc:
            raise MasteryInteractionError(str(exc)) from exc
        return self.grade_interaction(
            book_id,
            _assessment={
                "state": state,
                "objectives": objectives,
                "verdicts": verdicts,
                "sources": source_updates,
            },
            **kwargs,
        )

    async def repair_question_semantic(self, book_id, question_id="", *, config=None, **kwargs):
        """A challenged grade is corrected durably, with the same source/answer fences."""
        if kwargs.get("action") != "correct":
            return self.repair_question(book_id, question_id, **kwargs)
        from deeptutor.learning import semantic_assessment as semantic
        from deeptutor.learning.lesson_evidence import LessonUnavailable, objective_fingerprint

        progress = self._store.load(book_id)
        interaction = (
            self._store.get_interaction(book_id, question_id)
            if question_id
            else self._store.get_active_interaction(book_id)
        )
        if interaction is None and not question_id and progress.quiz_attempts:
            interaction = self._store.get_interaction(
                book_id, progress.quiz_attempts[-1].question_id
            )
        if interaction is None or interaction.question.questions:
            raise MasteryInteractionError(
                "Correct an exact stored leaf question_id; otherwise void the unsupported record."
            )
        question = interaction.question.model_copy(deep=True)
        question.expected_answer = str(kwargs.get("expected_answer") or "").strip()
        if question.expected_answer != interaction.question.expected_answer:
            question.accepted_answers = []
        if not question.expected_answer:
            raise MasteryInteractionError("Correcting a question requires its answer key.")
        if question.question_type == "choice" and question.choice_map:
            from deeptutor.learning.pending import resolve_choice_submission

            corrected_label = resolve_choice_submission(
                question.expected_answer, question.choice_map
            )
            if not corrected_label:
                raise MasteryInteractionError("The corrected key must identify one stored option.")
            question.expected_answer = corrected_label
            kwargs["expected_answer"] = corrected_label
        answers = {
            str(a.user_answer or "")
            for a in progress.quiz_attempts
            if a.question_id == interaction.interaction_id and not a.voided
        }
        if len(answers) > 1:
            raise MasteryInteractionError(
                "This legacy question has multiple distinct attempts; void it rather than overwriting their independent decisions."
            )
        answer = next(iter(answers), interaction.user_answer)
        receipt = None
        try:
            if question.visual_context:
                from deeptutor.learning.visual_practice import (
                    prepare_visual,
                    verified_visual_images,
                )

                question.visual_context, question.accepted_answers = prepare_visual(
                    {**question.visual_context, "accepted_answers": [], "key_status": "verified"},
                    expected_answer=question.expected_answer,
                    options=question.choice_map,
                )
                images = verified_visual_images(question)
            else:
                images = []
            await semantic.bind_question(self._store, progress, question, config)
            if answer:
                exact = semantic.exact_verdict(question, answer)
                if exact:
                    receipt = exact.receipt()
                else:
                    decisions = await semantic.judge_answers(
                        config,
                        [
                            {
                                **semantic.question_contract(question),
                                "answer": answer,
                                "source_evidence": question.source_evidence,
                                "_visual_images": images,
                            }
                        ],
                    )
                    receipt = decisions[question.question_id].receipt()
                if not receipt["final"]:
                    raise MasteryInteractionError(
                        "The challenged grade remains uncertain; clarify or void it. No correction was saved."
                    )
        except (semantic.AssessmentUnavailable, LessonUnavailable, ValueError) as exc:
            raise MasteryInteractionError(str(exc)) from exc
        return self.repair_question(
            book_id,
            interaction.interaction_id,
            _assessment={
                "state": semantic.fingerprint(interaction.model_dump()),
                "objective": objective_fingerprint(progress, question.knowledge_point_id),
                "question": question,
                "receipt": receipt,
            },
            **kwargs,
        )


__all__ = [
    "LearningService",
    "MasteryInteractionError",
    "NoPendingInteractionError",
    "StaleInteractionError",
]