semantic update

backend/src/scripts/migrate_sqlite_to_postgres.py

@@ -1,5 +1,6 @@
 # [DEF:backend.src.scripts.migrate_sqlite_to_postgres:Module]
 #
+# @TIER:      STANDARD
 # @SEMANTICS: migration, sqlite, postgresql, config, task_logs, task_records
 # @PURPOSE:   Migrates legacy config and task history from SQLite/file storage to PostgreSQL.
 # @LAYER:     Scripts
@@ -35,7 +36,10 @@ DEFAULT_TARGET_URL = os.getenv(
 
 
 # [DEF:_json_load_if_needed:Function]
+# @TIER: STANDARD
 # @PURPOSE: Parses JSON-like values from SQLite TEXT/JSON columns to Python objects.
+# @PRE: value is scalar JSON/text/list/dict or None.
+# @POST: Returns normalized Python object or original scalar value.
 def _json_load_if_needed(value: Any) -> Any:
     with belief_scope("_json_load_if_needed"):
         if value is None:
@@ -52,6 +56,7 @@ def _json_load_if_needed(value: Any) -> Any:
                 except json.JSONDecodeError:
                     return value
         return value
+# [/DEF:_json_load_if_needed:Function]
 
 
 # [DEF:_find_legacy_config_path:Function]
@@ -70,6 +75,7 @@ def _find_legacy_config_path(explicit_path: Optional[str]) -> Optional[Path]:
             if candidate.exists():
                 return candidate
         return None
+# [/DEF:_find_legacy_config_path:Function]
 
 
 # [DEF:_connect_sqlite:Function]
@@ -79,6 +85,7 @@ def _connect_sqlite(path: Path) -> sqlite3.Connection:
         conn = sqlite3.connect(str(path))
         conn.row_factory = sqlite3.Row
         return conn
+# [/DEF:_connect_sqlite:Function]
 
 
 # [DEF:_ensure_target_schema:Function]
@@ -143,6 +150,7 @@ def _ensure_target_schema(engine) -> None:
         with engine.begin() as conn:
             for stmt in stmts:
                 conn.execute(text(stmt))
+# [/DEF:_ensure_target_schema:Function]
 
 
 # [DEF:_migrate_config:Function]
@@ -168,6 +176,7 @@ def _migrate_config(engine, legacy_config_path: Optional[Path]) -> int:
             )
         logger.info("[_migrate_config][Coherence:OK] Config migrated from %s", legacy_config_path)
         return 1
+# [/DEF:_migrate_config:Function]
 
 
 # [DEF:_migrate_tasks_and_logs:Function]
@@ -283,6 +292,7 @@ def _migrate_tasks_and_logs(engine, sqlite_conn: sqlite3.Connection) -> Dict[str
             stats["task_logs_total"],
         )
         return stats
+# [/DEF:_migrate_tasks_and_logs:Function]
 
 
 # [DEF:run_migration:Function]
@@ -303,6 +313,7 @@ def run_migration(sqlite_path: Path, target_url: str, legacy_config_path: Option
             return stats
         finally:
             sqlite_conn.close()
+# [/DEF:run_migration:Function]
 
 
 # [DEF:main:Function]