chore(semantic): checkpoint remediation progress

backend/src/core/task_manager/persistence.py

@@ -3,7 +3,12 @@
 # @SEMANTICS: persistence, sqlite, sqlalchemy, task, storage
 # @PURPOSE: Handles the persistence of tasks using SQLAlchemy and the tasks.db database.
 # @LAYER: Core
-# @RELATION: Used by TaskManager to save and load tasks.
+# @PRE: Tasks database must be initialized with TaskRecord and TaskLogRecord schemas.
+# @POST: Provides reliable storage and retrieval for task metadata and logs.
+# @SIDE_EFFECT: Performs database I/O on tasks.db.
+# @DATA_CONTRACT: Input[Task, LogEntry] -> Model[TaskRecord, TaskLogRecord]
+# @RELATION: [USED_BY] ->[backend.src.core.task_manager.manager.TaskManager]
+# @RELATION: [DEPENDS_ON] ->[backend.src.core.database.TasksSessionLocal]
 # @INVARIANT: Database schema must match the TaskRecord model structure.
 
 # [SECTION: IMPORTS]
@@ -118,6 +123,7 @@ class TaskPersistenceService:
     # [/DEF:_resolve_environment_id:Function]
 
     # [DEF:__init__:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Initializes the persistence service.
     # @PRE:     None.
     # @POST:    Service is ready.
@@ -128,6 +134,7 @@ class TaskPersistenceService:
     # [/DEF:__init__:Function]
 
     # [DEF:persist_task:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Persists or updates a single task in the database.
     # @PRE:     isinstance(task, Task)
     # @POST:    Task record created or updated in database.
@@ -190,6 +197,7 @@ class TaskPersistenceService:
     # [/DEF:persist_task:Function]
 
     # [DEF:persist_tasks:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Persists multiple tasks.
     # @PRE:     isinstance(tasks, list)
     # @POST:    All tasks in list are persisted.
@@ -201,6 +209,7 @@ class TaskPersistenceService:
     # [/DEF:persist_tasks:Function]
 
     # [DEF:load_tasks:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Loads tasks from the database.
     # @PRE:     limit is an integer.
     # @POST:    Returns list of Task objects.
@@ -255,6 +264,7 @@ class TaskPersistenceService:
     # [/DEF:load_tasks:Function]
 
     # [DEF:delete_tasks:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Deletes specific tasks from the database.
     # @PRE:     task_ids is a list of strings.
     # @POST:    Specified task records deleted from database.
@@ -277,9 +287,9 @@ class TaskPersistenceService:
 # [/DEF:TaskPersistenceService:Class]
 
 # [DEF:TaskLogPersistenceService:Class]
+# @TIER: CRITICAL
 # @SEMANTICS: persistence, service, database, log, sqlalchemy
 # @PURPOSE: Provides methods to save and query task logs from the task_logs table.
-# @TIER: CRITICAL
 # @RELATION: DEPENDS_ON -> TaskLogRecord
 # @INVARIANT: Log entries are batch-inserted for performance.
 #
@@ -311,6 +321,7 @@ class TaskLogPersistenceService:
     # [/DEF:__init__:Function]
     
     # [DEF:add_logs:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Batch insert log entries for a task.
     # @PRE: logs is a list of LogEntry objects.
     # @POST: All logs inserted into task_logs table.
@@ -342,6 +353,7 @@ class TaskLogPersistenceService:
     # [/DEF:add_logs:Function]
     
     # [DEF:get_logs:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Query logs for a task with filtering and pagination.
     # @PRE: task_id is a valid task ID.
     # @POST: Returns list of TaskLog objects matching filters.
@@ -394,6 +406,7 @@ class TaskLogPersistenceService:
     # [/DEF:get_logs:Function]
     
     # [DEF:get_log_stats:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Get statistics about logs for a task.
     # @PRE: task_id is a valid task ID.
     # @POST: Returns LogStats with counts by level and source.
@@ -439,6 +452,7 @@ class TaskLogPersistenceService:
     # [/DEF:get_log_stats:Function]
     
     # [DEF:get_sources:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Get unique sources for a task's logs.
     # @PRE: task_id is a valid task ID.
     # @POST: Returns list of unique source strings.
@@ -458,6 +472,7 @@ class TaskLogPersistenceService:
     # [/DEF:get_sources:Function]
     
     # [DEF:delete_logs_for_task:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Delete all logs for a specific task.
     # @PRE: task_id is a valid task ID.
     # @POST: All logs for the task are deleted.
@@ -479,6 +494,7 @@ class TaskLogPersistenceService:
     # [/DEF:delete_logs_for_task:Function]
     
     # [DEF:delete_logs_for_tasks:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Delete all logs for multiple tasks.
     # @PRE: task_ids is a list of task IDs.
     # @POST: All logs for the tasks are deleted.