semantics

backend/src/services/dataset_review/clarification_engine.py

@@ -1,4 +1,4 @@
-# #region ClarificationEngine [C:4] [TYPE Module] [SEMANTICS dataset_review, clarification, question_payload, answer_persistence, readiness, findings]
+# #region ClarificationEngine [C:4] [TYPE Module] [SEMANTICS pydantic, dataset, clarification, finding, resolution]
 # @BRIEF Manage one-question-at-a-time clarification state, deterministic answer persistence, and readiness/finding updates.
 # @LAYER: Domain
 # @RELATION DEPENDS_ON -> [DatasetReviewSessionRepository]
@@ -104,15 +104,15 @@ class ClarificationAnswerCommand:
 # @POST: Returned clarification state is persistence-backed and aligned with session readiness/recommended action.
 # @SIDE_EFFECT: Mutates clarification answers, session flags, and related clarification findings.
 class ClarificationEngine:
-    # [DEF:ClarificationEngine_init:Function]
+    # region ClarificationEngine_init [TYPE Function]
     # @COMPLEXITY: 2
     # @PURPOSE: Bind repository dependency for clarification persistence operations.
     def __init__(self, repository: DatasetReviewSessionRepository) -> None:
         self.repository = repository
 
-    # [/DEF:ClarificationEngine_init:Function]
+    # endregion ClarificationEngine_init
 
-    # [DEF:build_question_payload:Function]
+    # region build_question_payload [TYPE Function]
     # @COMPLEXITY: 4
     # @PURPOSE: Return the one active highest-priority clarification question payload.
     # @PRE: Session contains unresolved clarification state or a resumable clarification session.
@@ -170,9 +170,9 @@ class ClarificationEngine:
             logger.reflect("Clarification payload built", extra={"session_id": session.session_id, "question_id": payload.question_id, "option_count": len(payload.options)})
             return payload
 
-    # [/DEF:build_question_payload:Function]
+    # endregion build_question_payload
 
-    # [DEF:record_answer:Function]
+    # region record_answer [TYPE Function]
     # @COMPLEXITY: 4
     # @PURPOSE: Persist one clarification answer before any pointer/readiness mutation.
     # @PRE: Target question belongs to the session's active clarification session and is still open.
@@ -257,9 +257,9 @@ class ClarificationEngine:
                 changed_findings=[changed_finding] if changed_finding else [],
             )
 
-    # [/DEF:record_answer:Function]
+    # endregion record_answer
 
-    # [DEF:summarize_progress:Function]
+    # region summarize_progress [TYPE Function]
     # @COMPLEXITY: 1
     # @PURPOSE: Produce a compact progress summary for pause/resume and completion UX.
     def summarize_progress(self, clarification_session: ClarificationSession) -> str:
@@ -267,9 +267,9 @@ class ClarificationEngine:
         remaining = count_remaining_questions(clarification_session)
         return f"{resolved} resolved, {remaining} unresolved"
 
-    # [/DEF:summarize_progress:Function]
+    # endregion summarize_progress
 
-    # [DEF:_get_latest_clarification_session:Function]
+    # region _get_latest_clarification_session [TYPE Function]
     # @COMPLEXITY: 2
     # @PURPOSE: Select the latest clarification session for the current dataset review aggregate.
     def _get_latest_clarification_session(self, session: DatasetReviewSession) -> Optional[ClarificationSession]:
@@ -278,9 +278,9 @@ class ClarificationEngine:
         ordered = sorted(session.clarification_sessions, key=lambda item: (item.started_at, item.clarification_session_id), reverse=True)
         return ordered[0]
 
-    # [/DEF:_get_latest_clarification_session:Function]
+    # endregion _get_latest_clarification_session
 
-    # [DEF:_find_question:Function]
+    # region _find_question [TYPE Function]
     # @COMPLEXITY: 1
     # @PURPOSE: Resolve a clarification question from the active clarification aggregate.
     def _find_question(self, clarification_session: ClarificationSession, question_id: str) -> Optional[ClarificationQuestion]:
@@ -289,7 +289,7 @@ class ClarificationEngine:
                 return q
         return None
 
-    # [/DEF:_find_question:Function]
+    # endregion _find_question
 
 
 # #endregion ClarificationEngine