chore(semantic): checkpoint remediation progress

backend/src/core/database.py

@@ -4,9 +4,9 @@
 # @SEMANTICS: database, postgresql, sqlalchemy, session, persistence
 # @PURPOSE:   Configures database connection and session management (PostgreSQL-first).
 # @LAYER:     Core
-# @RELATION:  DEPENDS_ON -> sqlalchemy
-# @RELATION:  DEPENDS_ON -> backend.src.models.mapping
-# @RELATION:  DEPENDS_ON -> backend.src.core.auth.config
+# @RELATION:  DEPENDS_ON ->[sqlalchemy]
+# @RELATION:  DEPENDS_ON ->[backend.src.models.mapping]
+# @RELATION:  DEPENDS_ON ->[backend.src.core.auth.config]
 #
 # @INVARIANT: A single engine instance is used for the entire application.
 
@@ -31,11 +31,13 @@ from pathlib import Path
 # [/SECTION]
 
 # [DEF:BASE_DIR:Variable]
+# @TIER: TRIVIAL
 # @PURPOSE: Base directory for the backend.
 BASE_DIR = Path(__file__).resolve().parent.parent.parent
 # [/DEF:BASE_DIR:Variable]
 
 # [DEF:DATABASE_URL:Constant]
+# @TIER: TRIVIAL
 # @PURPOSE: URL for the main application database.
 DEFAULT_POSTGRES_URL = os.getenv(
     "POSTGRES_URL",
@@ -45,34 +47,39 @@ DATABASE_URL = os.getenv("DATABASE_URL", DEFAULT_POSTGRES_URL)
 # [/DEF:DATABASE_URL:Constant]
 
 # [DEF:TASKS_DATABASE_URL:Constant]
+# @TIER: TRIVIAL
 # @PURPOSE: URL for the tasks execution database.
 # Defaults to DATABASE_URL to keep task logs in the same PostgreSQL instance.
 TASKS_DATABASE_URL = os.getenv("TASKS_DATABASE_URL", DATABASE_URL)
 # [/DEF:TASKS_DATABASE_URL:Constant]
 
 # [DEF:AUTH_DATABASE_URL:Constant]
+# @TIER: TRIVIAL
 # @PURPOSE: URL for the authentication database.
 AUTH_DATABASE_URL = os.getenv("AUTH_DATABASE_URL", auth_config.AUTH_DATABASE_URL)
 # [/DEF:AUTH_DATABASE_URL:Constant]
 
 # [DEF:engine:Variable]
+# @TIER: TRIVIAL
+# @PURPOSE: SQLAlchemy engine for mappings database.
+# @SIDE_EFFECT: Creates database engine and manages connection pool.
 def _build_engine(db_url: str):
     with belief_scope("_build_engine"):
         if db_url.startswith("sqlite"):
             return create_engine(db_url, connect_args={"check_same_thread": False})
         return create_engine(db_url, pool_pre_ping=True)
 
-
-# @PURPOSE: SQLAlchemy engine for mappings database.
 engine = _build_engine(DATABASE_URL)
 # [/DEF:engine:Variable]
 
 # [DEF:tasks_engine:Variable]
+# @TIER: TRIVIAL
 # @PURPOSE: SQLAlchemy engine for tasks database.
 tasks_engine = _build_engine(TASKS_DATABASE_URL)
 # [/DEF:tasks_engine:Variable]
 
 # [DEF:auth_engine:Variable]
+# @TIER: TRIVIAL
 # @PURPOSE: SQLAlchemy engine for authentication database.
 auth_engine = _build_engine(AUTH_DATABASE_URL)
 # [/DEF:auth_engine:Variable]
@@ -99,6 +106,7 @@ AuthSessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=auth_eng
 # [/DEF:AuthSessionLocal:Class]
 
 # [DEF:_ensure_user_dashboard_preferences_columns:Function]
+# @TIER: STANDARD
 # @PURPOSE: Applies additive schema upgrades for user_dashboard_preferences table.
 # @PRE: bind_engine points to application database where profile table is stored.
 # @POST: Missing columns are added without data loss.
@@ -165,6 +173,7 @@ def _ensure_user_dashboard_preferences_columns(bind_engine):
 
 
 # [DEF:_ensure_user_dashboard_preferences_health_columns:Function]
+# @TIER: STANDARD
 # @PURPOSE: Applies additive schema upgrades for user_dashboard_preferences table (health fields).
 def _ensure_user_dashboard_preferences_health_columns(bind_engine):
     with belief_scope("_ensure_user_dashboard_preferences_health_columns"):
@@ -208,6 +217,7 @@ def _ensure_user_dashboard_preferences_health_columns(bind_engine):
 
 
 # [DEF:_ensure_llm_validation_results_columns:Function]
+# @TIER: STANDARD
 # @PURPOSE: Applies additive schema upgrades for llm_validation_results table.
 def _ensure_llm_validation_results_columns(bind_engine):
     with belief_scope("_ensure_llm_validation_results_columns"):
@@ -247,6 +257,7 @@ def _ensure_llm_validation_results_columns(bind_engine):
 
 
 # [DEF:_ensure_git_server_configs_columns:Function]
+# @TIER: STANDARD
 # @PURPOSE: Applies additive schema upgrades for git_server_configs table.
 # @PRE: bind_engine points to application database.
 # @POST: Missing columns are added without data loss.
@@ -284,6 +295,7 @@ def _ensure_git_server_configs_columns(bind_engine):
 
 
 # [DEF:ensure_connection_configs_table:Function]
+# @TIER: STANDARD
 # @PURPOSE: Ensures the external connection registry table exists in the main database.
 # @PRE: bind_engine points to the application database.
 # @POST: connection_configs table exists without dropping existing data.
@@ -301,6 +313,7 @@ def ensure_connection_configs_table(bind_engine):
 
 
 # [DEF:init_db:Function]
+# @TIER: STANDARD
 # @PURPOSE: Initializes the database by creating all tables.
 # @PRE: engine, tasks_engine and auth_engine are initialized.
 # @POST: Database tables created in all databases.
@@ -318,6 +331,7 @@ def init_db():
 # [/DEF:init_db:Function]
 
 # [DEF:get_db:Function]
+# @TIER: STANDARD
 # @PURPOSE: Dependency for getting a database session.
 # @PRE: SessionLocal is initialized.
 # @POST:    Session is closed after use.
@@ -332,6 +346,7 @@ def get_db():
 # [/DEF:get_db:Function]
 
 # [DEF:get_tasks_db:Function]
+# @TIER: STANDARD
 # @PURPOSE: Dependency for getting a tasks database session.
 # @PRE: TasksSessionLocal is initialized.
 # @POST:    Session is closed after use.
@@ -346,6 +361,7 @@ def get_tasks_db():
 # [/DEF:get_tasks_db:Function]
 
 # [DEF:get_auth_db:Function]
+# @TIER: STANDARD
 # @PURPOSE: Dependency for getting an authentication database session.
 # @PRE: AuthSessionLocal is initialized.
 # @POST:    Session is closed after use.