semantic markup update

backend/src/core/task_manager/manager.py

@@ -186,17 +186,23 @@ class TaskManager:
 
     # [DEF:get_task:Function]
     # @PURPOSE: Retrieves a task by its ID.
+    # @PRE:     task_id is a string.
+    # @POST:    Returns Task object or None.
     # @PARAM:   task_id (str) - ID of the task.
     # @RETURN:  Optional[Task] - The task or None.
     def get_task(self, task_id: str) -> Optional[Task]:
-        return self.tasks.get(task_id)
+        with belief_scope("TaskManager.get_task", f"task_id={task_id}"):
+            return self.tasks.get(task_id)
     # [/DEF:get_task:Function]
 
     # [DEF:get_all_tasks:Function]
     # @PURPOSE: Retrieves all registered tasks.
+    # @PRE:     None.
+    # @POST:    Returns list of all Task objects.
     # @RETURN:  List[Task] - All tasks.
     def get_all_tasks(self) -> List[Task]:
-        return list(self.tasks.values())
+        with belief_scope("TaskManager.get_all_tasks"):
+            return list(self.tasks.values())
     # [/DEF:get_all_tasks:Function]
 
     # [DEF:get_tasks:Function]
@@ -208,7 +214,8 @@ class TaskManager:
     # @PARAM:   status (Optional[TaskStatus]) - Filter by task status.
     # @RETURN:  List[Task] - List of tasks matching criteria.
     def get_tasks(self, limit: int = 10, offset: int = 0, status: Optional[TaskStatus] = None) -> List[Task]:
-        tasks = list(self.tasks.values())
+        with belief_scope("TaskManager.get_tasks"):
+            tasks = list(self.tasks.values())
         if status:
             tasks = [t for t in tasks if t.status == status]
         # Sort by start_time descending (most recent first)
@@ -218,11 +225,14 @@ class TaskManager:
 
     # [DEF:get_task_logs:Function]
     # @PURPOSE: Retrieves logs for a specific task.
+    # @PRE:     task_id is a string.
+    # @POST:    Returns list of LogEntry objects.
     # @PARAM:   task_id (str) - ID of the task.
     # @RETURN:  List[LogEntry] - List of log entries.
     def get_task_logs(self, task_id: str) -> List[LogEntry]:
-        task = self.tasks.get(task_id)
-        return task.logs if task else []
+        with belief_scope("TaskManager.get_task_logs", f"task_id={task_id}"):
+            task = self.tasks.get(task_id)
+            return task.logs if task else []
     # [/DEF:get_task_logs:Function]
 
     # [DEF:_add_log:Function]
@@ -234,51 +244,61 @@ class TaskManager:
     # @PARAM:   message (str) - Log message.
     # @PARAM:   context (Optional[Dict]) - Log context.
     def _add_log(self, task_id: str, level: str, message: str, context: Optional[Dict[str, Any]] = None):
-        task = self.tasks.get(task_id)
-        if not task:
-            return
+        with belief_scope("TaskManager._add_log", f"task_id={task_id}"):
+            task = self.tasks.get(task_id)
+            if not task:
+                return
 
-        log_entry = LogEntry(level=level, message=message, context=context)
-        task.logs.append(log_entry)
-        self.persistence_service.persist_task(task)
+            log_entry = LogEntry(level=level, message=message, context=context)
+            task.logs.append(log_entry)
+            self.persistence_service.persist_task(task)
 
-        # Notify subscribers
-        if task_id in self.subscribers:
-            for queue in self.subscribers[task_id]:
-                self.loop.call_soon_threadsafe(queue.put_nowait, log_entry)
+            # Notify subscribers
+            if task_id in self.subscribers:
+                for queue in self.subscribers[task_id]:
+                    self.loop.call_soon_threadsafe(queue.put_nowait, log_entry)
     # [/DEF:_add_log:Function]
 
     # [DEF:subscribe_logs:Function]
     # @PURPOSE: Subscribes to real-time logs for a task.
+    # @PRE:     task_id is a string.
+    # @POST:    Returns an asyncio.Queue for log entries.
     # @PARAM:   task_id (str) - ID of the task.
     # @RETURN:  asyncio.Queue - Queue for log entries.
     async def subscribe_logs(self, task_id: str) -> asyncio.Queue:
-        queue = asyncio.Queue()
-        if task_id not in self.subscribers:
-            self.subscribers[task_id] = []
-        self.subscribers[task_id].append(queue)
-        return queue
+        with belief_scope("TaskManager.subscribe_logs", f"task_id={task_id}"):
+            queue = asyncio.Queue()
+            if task_id not in self.subscribers:
+                self.subscribers[task_id] = []
+            self.subscribers[task_id].append(queue)
+            return queue
     # [/DEF:subscribe_logs:Function]
 
     # [DEF:unsubscribe_logs:Function]
     # @PURPOSE: Unsubscribes from real-time logs for a task.
+    # @PRE:     task_id is a string, queue is asyncio.Queue.
+    # @POST:    Queue removed from subscribers.
     # @PARAM:   task_id (str) - ID of the task.
     # @PARAM:   queue (asyncio.Queue) - Queue to remove.
     def unsubscribe_logs(self, task_id: str, queue: asyncio.Queue):
-        if task_id in self.subscribers:
-            if queue in self.subscribers[task_id]:
-                self.subscribers[task_id].remove(queue)
-            if not self.subscribers[task_id]:
-                del self.subscribers[task_id]
+        with belief_scope("TaskManager.unsubscribe_logs", f"task_id={task_id}"):
+            if task_id in self.subscribers:
+                if queue in self.subscribers[task_id]:
+                    self.subscribers[task_id].remove(queue)
+                if not self.subscribers[task_id]:
+                    del self.subscribers[task_id]
     # [/DEF:unsubscribe_logs:Function]
 
     # [DEF:load_persisted_tasks:Function]
     # @PURPOSE: Load persisted tasks using persistence service.
+    # @PRE:     None.
+    # @POST:    Persisted tasks loaded into self.tasks.
     def load_persisted_tasks(self) -> None:
-        loaded_tasks = self.persistence_service.load_tasks(limit=100)
-        for task in loaded_tasks:
-            if task.id not in self.tasks:
-                self.tasks[task.id] = task
+        with belief_scope("TaskManager.load_persisted_tasks"):
+            loaded_tasks = self.persistence_service.load_tasks(limit=100)
+            for task in loaded_tasks:
+                if task.id not in self.tasks:
+                    self.tasks[task.id] = task
     # [/DEF:load_persisted_tasks:Function]
 
     # [DEF:await_input:Function]
@@ -334,6 +354,8 @@ class TaskManager:
 
     # [DEF:clear_tasks:Function]
     # @PURPOSE: Clears tasks based on status filter.
+    # @PRE:     status is Optional[TaskStatus].
+    # @POST:    Tasks matching filter (or all non-active) cleared from registry and database.
     # @PARAM:   status (Optional[TaskStatus]) - Filter by task status.
     # @RETURN:  int - Number of tasks cleared.
     def clear_tasks(self, status: Optional[TaskStatus] = None) -> int: