chore(semantic): checkpoint remediation progress

backend/src/core/config_manager.py

@@ -4,12 +4,15 @@
 # @SEMANTICS: config, manager, persistence, migration, postgresql
 # @PURPOSE: Manages application configuration persistence in DB with one-time migration from legacy JSON.
 # @LAYER: Domain
-# @RELATION: [DEPENDS_ON] ->[ConfigModels]
-# @RELATION: [DEPENDS_ON] ->[SessionLocal]
-# @RELATION: [DEPENDS_ON] ->[AppConfigRecord]
-# @RELATION: [CALLS] ->[logger]
-# @RELATION: [CALLS] ->[configure_logger]
-# @RELATION: [BINDS_TO] ->[ConfigManager]
+# @PRE: Database schema for AppConfigRecord must be initialized.
+# @POST: Configuration is loaded into memory and logger is configured.
+# @SIDE_EFFECT: Performs DB I/O and may update global logging level.
+# @DATA_CONTRACT: Input[json, record] -> Model[AppConfig]
+# @RELATION: [DEPENDS_ON] ->[backend.src.core.config_models.AppConfig]
+# @RELATION: [DEPENDS_ON] ->[backend.src.core.database.SessionLocal]
+# @RELATION: [DEPENDS_ON] ->[backend.src.models.config.AppConfigRecord]
+# @RELATION: [CALLS] ->[backend.src.core.logger.logger]
+# @RELATION: [CALLS] ->[backend.src.core.logger.configure_logger]
 # @INVARIANT: Configuration must always be representable by AppConfig and persisted under global record id.
 #
 import json
@@ -57,6 +60,7 @@ class ConfigManager:
     # [/DEF:__init__:Function]
 
     # [DEF:_default_config:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Build default application configuration fallback.
     # @PRE: None.
     # @POST: Returns valid AppConfig with empty environments and default storage settings.
@@ -71,6 +75,7 @@ class ConfigManager:
     # [/DEF:_default_config:Function]
 
     # [DEF:_sync_raw_payload_from_config:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Merge typed AppConfig state into raw payload while preserving unsupported legacy sections.
     # @PRE: self.config is initialized as AppConfig.
     # @POST: self.raw_payload contains AppConfig fields refreshed from self.config.
@@ -85,6 +90,7 @@ class ConfigManager:
     # [/DEF:_sync_raw_payload_from_config:Function]
 
     # [DEF:_load_from_legacy_file:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Load legacy JSON configuration for migration fallback path.
     # @PRE: self.config_path is initialized.
     # @POST: Returns AppConfig from file payload or safe default.
@@ -110,6 +116,7 @@ class ConfigManager:
     # [/DEF:_load_from_legacy_file:Function]
 
     # [DEF:_get_record:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Resolve global configuration record from DB.
     # @PRE: session is an active SQLAlchemy Session.
     # @POST: Returns record when present, otherwise None.
@@ -121,6 +128,7 @@ class ConfigManager:
     # [/DEF:_get_record:Function]
 
     # [DEF:_load_config:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Load configuration from DB or perform one-time migration from legacy JSON.
     # @PRE: SessionLocal factory is available and AppConfigRecord schema is accessible.
     # @POST: Returns valid AppConfig and closes opened DB session.
@@ -152,6 +160,7 @@ class ConfigManager:
     # [/DEF:_load_config:Function]
 
     # [DEF:_save_config_to_db:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Persist provided AppConfig into the global DB configuration record.
     # @PRE: config is AppConfig; session is either None or an active Session.
     # @POST: Global DB record payload equals config.model_dump() when commit succeeds.
@@ -186,6 +195,7 @@ class ConfigManager:
     # [/DEF:_save_config_to_db:Function]
 
     # [DEF:save:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Persist current in-memory configuration state.
     # @PRE: self.config is initialized.
     # @POST: Current self.config is written to DB global record.
@@ -197,6 +207,7 @@ class ConfigManager:
     # [/DEF:save:Function]
 
     # [DEF:get_config:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Return current in-memory configuration snapshot.
     # @PRE: self.config is initialized.
     # @POST: Returns AppConfig reference stored in manager.
@@ -208,6 +219,7 @@ class ConfigManager:
     # [/DEF:get_config:Function]
 
     # [DEF:get_payload:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Return full persisted payload including sections outside typed AppConfig schema.
     # @PRE: Manager state is initialized.
     # @POST: Returns dict payload with current AppConfig fields synchronized.
@@ -219,6 +231,7 @@ class ConfigManager:
     # [/DEF:get_payload:Function]
 
     # [DEF:save_config:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Persist configuration provided either as typed AppConfig or raw payload dict.
     # @PRE: config is AppConfig or dict compatible with AppConfig core schema.
     # @POST: self.config and self.raw_payload are synchronized and persisted to DB.
@@ -240,6 +253,7 @@ class ConfigManager:
     # [/DEF:save_config:Function]
 
     # [DEF:update_global_settings:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Replace global settings and persist the resulting configuration.
     # @PRE: settings is GlobalSettings.
     # @POST: self.config.settings equals provided settings and DB state is updated.
@@ -258,6 +272,7 @@ class ConfigManager:
     # [/DEF:update_global_settings:Function]
 
     # [DEF:validate_path:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Validate that path exists and is writable, creating it when absent.
     # @PRE: path is a string path candidate.
     # @POST: Returns (True, msg) for writable path, else (False, reason).
@@ -279,6 +294,7 @@ class ConfigManager:
     # [/DEF:validate_path:Function]
 
     # [DEF:get_environments:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Return all configured environments.
     # @PRE: self.config is initialized.
     # @POST: Returns list of Environment models from current configuration.
@@ -290,6 +306,7 @@ class ConfigManager:
     # [/DEF:get_environments:Function]
 
     # [DEF:has_environments:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Check whether at least one environment exists in configuration.
     # @PRE: self.config is initialized.
     # @POST: Returns True iff environment list length is greater than zero.
@@ -301,6 +318,7 @@ class ConfigManager:
     # [/DEF:has_environments:Function]
 
     # [DEF:get_environment:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Resolve a configured environment by identifier.
     # @PRE: env_id is string identifier.
     # @POST: Returns matching Environment when found; otherwise None.
@@ -315,6 +333,7 @@ class ConfigManager:
     # [/DEF:get_environment:Function]
 
     # [DEF:add_environment:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Upsert environment by id into configuration and persist.
     # @PRE: env is Environment.
     # @POST: Configuration contains provided env id with new payload persisted.
@@ -333,6 +352,7 @@ class ConfigManager:
     # [/DEF:add_environment:Function]
 
     # [DEF:update_environment:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Update existing environment by id and preserve masked password placeholder behavior.
     # @PRE: env_id is non-empty string and updated_env is Environment.
     # @POST: Returns True and persists update when target exists; else returns False.
@@ -362,6 +382,7 @@ class ConfigManager:
     # [/DEF:update_environment:Function]
 
     # [DEF:delete_environment:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Delete environment by id and persist when deletion occurs.
     # @PRE: env_id is non-empty string.
     # @POST: Environment is removed when present; otherwise configuration is unchanged.