semantics

backend/src/core/database.py

@@ -1,11 +1,11 @@
 # #region DatabaseModule [C:3] [TYPE Module] [SEMANTICS sqlalchemy, connection, session]
 #
 # @BRIEF Configures database connection and session management (PostgreSQL-first).
-# @LAYER: Infrastructure
+# @LAYER Infrastructure
 # @RELATION DEPENDS_ON -> [MappingModels]
 # @RELATION DEPENDS_ON -> [auth_config]
 #
-# @INVARIANT: A single engine instance is used for the entire application.
+# @INVARIANT  A single engine instance is used for the entire application.
 
 import os
 from pathlib import Path
@@ -67,7 +67,7 @@ AUTH_DATABASE_URL = os.getenv("AUTH_DATABASE_URL", auth_config.AUTH_DATABASE_URL
 
 # #region engine [C:1] [TYPE Variable]
 # @BRIEF SQLAlchemy engine for mappings database.
-# @SIDE_EFFECT: Creates database engine and manages connection pool.
+# @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"):
@@ -90,27 +90,27 @@ auth_engine = _build_engine(AUTH_DATABASE_URL)
 
 # #region SessionLocal [C:1] [TYPE Class]
 # @BRIEF A session factory for the main mappings database.
-# @PRE: engine is initialized.
+# @PRE  engine is initialized.
 SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
 # #endregion SessionLocal
 
 # #region TasksSessionLocal [C:1] [TYPE Class]
 # @BRIEF A session factory for the tasks execution database.
-# @PRE: tasks_engine is initialized.
+# @PRE  tasks_engine is initialized.
 TasksSessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=tasks_engine)
 # #endregion TasksSessionLocal
 
 # #region AuthSessionLocal [C:1] [TYPE Class]
 # @BRIEF A session factory for the authentication database.
-# @PRE: auth_engine is initialized.
+# @PRE  auth_engine is initialized.
 AuthSessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=auth_engine)
 # #endregion AuthSessionLocal
 
 
 # #region _ensure_user_dashboard_preferences_columns [C:3] [TYPE Function]
 # @BRIEF 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.
+# @PRE  bind_engine points to application database where profile table is stored.
+# @POST  Missing columns are added without data loss.
 # @RELATION DEPENDS_ON -> [engine]
 def _ensure_user_dashboard_preferences_columns(bind_engine):
     with belief_scope("_ensure_user_dashboard_preferences_columns"):
@@ -266,8 +266,8 @@ def _ensure_llm_validation_results_columns(bind_engine):
 
 # #region _ensure_git_server_configs_columns [C:3] [TYPE Function]
 # @BRIEF Applies additive schema upgrades for git_server_configs table.
-# @PRE: bind_engine points to application database.
-# @POST: Missing columns are added without data loss.
+# @PRE  bind_engine points to application database.
+# @POST  Missing columns are added without data loss.
 # @RELATION DEPENDS_ON -> [engine]
 def _ensure_git_server_configs_columns(bind_engine):
     with belief_scope("_ensure_git_server_configs_columns"):
@@ -306,8 +306,8 @@ def _ensure_git_server_configs_columns(bind_engine):
 
 # #region _ensure_auth_users_columns [C:3] [TYPE Function]
 # @BRIEF Applies additive schema upgrades for auth users table.
-# @PRE: bind_engine points to authentication database.
-# @POST: Missing columns are added without data loss.
+# @PRE  bind_engine points to authentication database.
+# @POST  Missing columns are added without data loss.
 # @RELATION DEPENDS_ON -> [auth_engine]
 def _ensure_auth_users_columns(bind_engine):
     with belief_scope("_ensure_auth_users_columns"):
@@ -368,8 +368,8 @@ def _ensure_auth_users_columns(bind_engine):
 
 # #region _ensure_filter_source_enum_values [C:3] [TYPE Function]
 # @BRIEF Adds missing FilterSource enum values to the PostgreSQL native filtersource type.
-# @PRE: bind_engine points to application database with imported_filters table.
-# @POST: New enum values are available without data loss.
+# @PRE  bind_engine points to application database with imported_filters table.
+# @POST  New enum values are available without data loss.
 # @RELATION DEPENDS_ON -> [engine]
 def _ensure_filter_source_enum_values(bind_engine):
     with belief_scope("_ensure_filter_source_enum_values"):
@@ -439,9 +439,9 @@ def _ensure_filter_source_enum_values(bind_engine):
 
 # #region _ensure_dataset_review_session_columns [C:4] [TYPE Function]
 # @BRIEF Apply additive schema upgrades for dataset review persistence required by optimistic-lock and recovery metadata semantics.
-# @PRE: bind_engine points to the application database where dataset review tables are stored.
-# @POST: Missing additive columns across legacy dataset review tables are created without removing existing data.
-# @SIDE_EFFECT: Executes ALTER TABLE statements against dataset review tables in the application database.
+# @PRE  bind_engine points to the application database where dataset review tables are stored.
+# @POST  Missing additive columns across legacy dataset review tables are created without removing existing data.
+# @SIDE_EFFECT  Executes ALTER TABLE statements against dataset review tables in the application database.
 # @RELATION DEPENDS_ON -> [DatasetReviewSession]
 # @RELATION DEPENDS_ON -> [ImportedFilter]
 def _ensure_translation_jobs_columns(bind_engine):
@@ -572,8 +572,8 @@ def _ensure_dataset_review_session_columns(bind_engine):
 
 # #region _ensure_translation_schedules_columns [C:3] [TYPE Function]
 # @BRIEF Applies additive schema upgrades for translation_schedules table.
-# @PRE: bind_engine points to application database.
-# @POST: Missing columns are added without data loss.
+# @PRE  bind_engine points to application database.
+# @POST  Missing columns are added without data loss.
 # @RELATION DEPENDS_ON -> [engine]
 def _ensure_translation_schedules_columns(bind_engine):
     with belief_scope("_ensure_translation_schedules_columns"):
@@ -662,9 +662,9 @@ def _ensure_dictionary_entries_columns(bind_engine):
 
 # #region init_db [C:3] [TYPE Function]
 # @BRIEF Initializes the database by creating all tables.
-# @PRE: engine, tasks_engine and auth_engine are initialized.
-# @POST: Database tables created in all databases.
-# @SIDE_EFFECT: Creates physical database files if they don't exist.
+# @PRE  engine, tasks_engine and auth_engine are initialized.
+# @POST  Database tables created in all databases.
+# @SIDE_EFFECT  Creates physical database files if they don't exist.
 # @RELATION CALLS -> [_ensure_filter_source_enum_values]
 # @RELATION CALLS -> [_ensure_dataset_review_session_columns]
 # @RELATION CALLS -> [_ensure_dictionary_entries_columns]
@@ -690,8 +690,8 @@ def init_db():
 
 # #region get_db [C:3] [TYPE Function]
 # @BRIEF Dependency for getting a database session.
-# @PRE: SessionLocal is initialized.
-# @POST:    Session is closed after use.
+# @PRE  SessionLocal is initialized.
+# @POST     Session is closed after use.
 # @RELATION DEPENDS_ON -> [SessionLocal]
 def get_db():
     with belief_scope("get_db"):
@@ -707,8 +707,8 @@ def get_db():
 
 # #region get_tasks_db [C:3] [TYPE Function]
 # @BRIEF Dependency for getting a tasks database session.
-# @PRE: TasksSessionLocal is initialized.
-# @POST:    Session is closed after use.
+# @PRE  TasksSessionLocal is initialized.
+# @POST     Session is closed after use.
 # @RELATION DEPENDS_ON -> [TasksSessionLocal]
 def get_tasks_db():
     with belief_scope("get_tasks_db"):
@@ -724,9 +724,9 @@ def get_tasks_db():
 
 # #region get_auth_db [C:3] [TYPE Function]
 # @BRIEF Dependency for getting an authentication database session.
-# @PRE: AuthSessionLocal is initialized.
-# @POST: Session is closed after use.
-# @DATA_CONTRACT: None -> Output[sqlalchemy.orm.Session]
+# @PRE  AuthSessionLocal is initialized.
+# @POST  Session is closed after use.
+# @DATA_CONTRACT  None -> Output[EXT:Library:sqlalchemy.orm.Session]
 # @RELATION DEPENDS_ON -> [AuthSessionLocal]
 def get_auth_db():
     with belief_scope("get_auth_db"):