semantic clean up

2026-03-10 19:38:10 +03:00
parent 0078c1ae05
commit 4f1c33e02b
31 changed files with 5392 additions and 6647 deletions
--- a/.ai/PROJECT_MAP.md
+++ b/.ai/PROJECT_MAP.md
@@ -1197,9 +1197,7 @@
  - ƒ **saveSettings** (`Function`) `[TRIVIAL]`
    - 📝 Auto-detected function (orphan)
 - 🧩 **MigrationDashboard** (`Component`) `[CRITICAL]`
-  - 📝 Main dashboard for configuring and starting migrations.
-  - 🏗️ Layer: Page
-  - 🔒 Invariant: Migration cannot start without source and target environments.
+  - 📝 Orchestrate migration UI workflow and route user actions to backend APIs and task store.
  - ⬅️ READS_FROM `lib`
  - ⬅️ READS_FROM `selectedTask`
  - ➡️ WRITES_TO `selectedTask`
@@ -1221,20 +1219,26 @@
    - 📝 Starts the migration process.
  - ƒ **startDryRun** (`Function`) `[CRITICAL]`
    - 📝 Builds pre-flight diff and risk summary without applying migration.
+- ▦ **MigrationDashboardView** (`Block`) `[CRITICAL]`
+  - 📝 Render migration configuration controls, action CTAs, dry-run results, and modal entry points.
  - 🧩 **DashboardSelectionSection** (`Component`) `[CRITICAL]`
- 🧩 **MappingManagement** (`Component`) `[CRITICAL]`
-  - 📝 Page for managing database mappings between environments.
-  - 🏗️ Layer: Page
-  - 🔒 Invariant: Mappings are saved to the backend for persistence.
-  - ⬅️ READS_FROM `lib`
-  - ➡️ WRITES_TO `t`
-  - ⬅️ READS_FROM `t`
+- ▦ **MappingsPageScript** (`Block`) `[CRITICAL]`
+  - 📝 Define imports, state, and handlers that drive migration mappings page FSM.
+  - 🔗 CALLS -> `fetchEnvironments`
+  - 🔗 CALLS -> `fetchDatabases`
+  - 🔗 CALLS -> `handleUpdate`
+  - ▦ **Imports** (`Block`) `[CRITICAL]`
+  - 🗄️ **UiState** (`Store`) `[CRITICAL]`
+    - 📝 Maintain local page state for environments, fetched databases, mappings, suggestions, and UX messages.
+  - ƒ **belief_scope** (`Function`) `[CRITICAL]`
+    - 📝 Frontend semantic scope wrapper for CRITICAL trace boundaries without changing business behavior.
  - ƒ **fetchEnvironments** (`Function`) `[CRITICAL]`
-    - 📝 Fetches the list of environments.
+    - 📝 Load environment options for source/target selectors on initial mount.
  - ƒ **fetchDatabases** (`Function`) `[CRITICAL]`
-    - 📝 Fetches databases from both environments and gets suggestions.
+    - 📝 Fetch both environment database catalogs, existing mappings, and suggested matches.
  - ƒ **handleUpdate** (`Function`) `[CRITICAL]`
-    - 📝 Saves a mapping to the backend.
+    - 📝 Persist a selected mapping pair and reconcile local mapping list by source database UUID.
+- ▦ **MappingsPageTemplate** (`Block`) `[CRITICAL]`
 - 📦 **+page** (`Module`) `[TRIVIAL]`
  - 📝 Auto-generated module for frontend/src/routes/profile/+page.svelte
  - 🏗️ Layer: Unknown
@@ -1761,16 +1765,14 @@
  - ➡️ WRITES_TO `t`
  - ƒ **handleSelect** (`Function`)
    - 📝 Dispatches the selection change event.
- 🧩 **ProtectedRoute** (`Component`) `[CRITICAL]`
-  - 📝 Wraps content to ensure only authenticated and authorized users can access it.
-  - 🏗️ Layer: Component
-  - 🔒 Invariant: Redirects to /login if user is not authenticated and to fallback route when permission is denied.
-  - 📥 Props: requiredPermission: string | null , fallbackPath: string 
-  - ⬅️ READS_FROM `app`
-  - ⬅️ READS_FROM `lib`
-  - ⬅️ READS_FROM `auth`
-  - ƒ **verifySessionAndAccess** (`Function`) `[CRITICAL]`
-    - 📝 Validates active session and optional route permission before rendering protected slot.
+- 📦 **ProtectedRoute.svelte** (`Module`)
+  - 📝 Enforces authenticated and authorized access before protected route content is rendered.
+  - 🏗️ Layer: UI
+  - 🔒 Invariant: Unauthenticated users are redirected to /login, unauthorized users are redirected to fallbackPath, and protected slot renders only when access is verified.
+  - 🧩 **ProtectedRoute** (`Component`) `[CRITICAL]`
+    - 📝 Wraps protected slot content with session and permission verification guards.
+    - ƒ **verifySessionAndAccess** (`Function`) `[CRITICAL]`
+      - 📝 Validates session and optional permission gate before allowing protected content render.
 - 🧩 **TaskLogPanel** (`Component`)
  - 📝 Combines log filtering and display into a single cohesive dark-themed panel.
  - 🏗️ Layer: UI
@@ -2499,46 +2501,49 @@
  - ƒ **as_bool** (`Function`) `[TRIVIAL]`
    - 📝 Auto-detected function (orphan)
 - 📦 **ConfigManagerModule** (`Module`) `[CRITICAL]`
-  - 📝 Manages application configuration persisted in database with one-time migration from JSON.
-  - 🏗️ Layer: Core
-  - 🔒 Invariant: Configuration must always be valid according to AppConfig model.
+  - 📝 Manages application configuration persistence in DB with one-time migration from legacy JSON.
+  - 🏗️ Layer: Domain
+  - 🔒 Invariant: Configuration must always be representable by AppConfig and persisted under global record id.
  - 🔗 DEPENDS_ON -> `ConfigModels`
+  - 🔗 DEPENDS_ON -> `SessionLocal`
  - 🔗 DEPENDS_ON -> `AppConfigRecord`
  - 🔗 CALLS -> `logger`
+  - 🔗 CALLS -> `configure_logger`
+  - 🔗 BINDS_TO -> `ConfigManager`
  - ℂ **ConfigManager** (`Class`) `[CRITICAL]`
-    - 📝 A class to handle application configuration persistence and management.
+    - 📝 Handles application configuration load, validation, mutation, and persistence lifecycle.
    - ƒ **__init__** (`Function`) `[CRITICAL]`
-      - 📝 Initializes the ConfigManager.
+      - 📝 Initialize manager state from persisted or migrated configuration.
    - ƒ **_default_config** (`Function`) `[CRITICAL]`
-      - 📝 Returns default application configuration.
+      - 📝 Build default application configuration fallback.
    - ƒ **_load_from_legacy_file** (`Function`) `[CRITICAL]`
-      - 📝 Loads legacy configuration from config.json for migration fallback.
+      - 📝 Load legacy JSON configuration for migration fallback path.
    - ƒ **_get_record** (`Function`) `[CRITICAL]`
-      - 📝 Loads config record from DB.
+      - 📝 Resolve global configuration record from DB.
    - ƒ **_load_config** (`Function`) `[CRITICAL]`
-      - 📝 Loads the configuration from DB or performs one-time migration from JSON file.
+      - 📝 Load configuration from DB or perform one-time migration from legacy JSON.
    - ƒ **_save_config_to_db** (`Function`) `[CRITICAL]`
-      - 📝 Saves the provided configuration object to DB.
+      - 📝 Persist provided AppConfig into the global DB configuration record.
    - ƒ **save** (`Function`) `[CRITICAL]`
-      - 📝 Saves the current configuration state to DB.
+      - 📝 Persist current in-memory configuration state.
    - ƒ **get_config** (`Function`) `[CRITICAL]`
-      - 📝 Returns the current configuration.
+      - 📝 Return current in-memory configuration snapshot.
    - ƒ **update_global_settings** (`Function`) `[CRITICAL]`
-      - 📝 Updates the global settings and persists the change.
+      - 📝 Replace global settings and persist the resulting configuration.
    - ƒ **validate_path** (`Function`) `[CRITICAL]`
-      - 📝 Validates if a path exists and is writable.
+      - 📝 Validate that path exists and is writable, creating it when absent.
    - ƒ **get_environments** (`Function`) `[CRITICAL]`
-      - 📝 Returns the list of configured environments.
+      - 📝 Return all configured environments.
    - ƒ **has_environments** (`Function`) `[CRITICAL]`
-      - 📝 Checks if at least one environment is configured.
+      - 📝 Check whether at least one environment exists in configuration.
    - ƒ **get_environment** (`Function`) `[CRITICAL]`
-      - 📝 Returns a single environment by ID.
+      - 📝 Resolve a configured environment by identifier.
    - ƒ **add_environment** (`Function`) `[CRITICAL]`
-      - 📝 Adds a new environment to the configuration.
+      - 📝 Upsert environment by id into configuration and persist.
    - ƒ **update_environment** (`Function`) `[CRITICAL]`
-      - 📝 Updates an existing environment.
+      - 📝 Update existing environment by id and preserve masked password placeholder behavior.
    - ƒ **delete_environment** (`Function`) `[CRITICAL]`
-      - 📝 Deletes an environment by ID.
+      - 📝 Delete environment by id and persist when deletion occurs.
 - 📦 **SchedulerModule** (`Module`)
  - 📝 Manages scheduled tasks using APScheduler.
  - 🏗️ Layer: Core
@@ -2676,22 +2681,25 @@
  - ƒ **has_plugin** (`Function`)
    - 📝 Checks if a plugin with the given ID is registered.
 - 📦 **backend.src.core.migration_engine** (`Module`) `[CRITICAL]`
-  - 📝 Handles the interception and transformation of Superset asset ZIP archives.
-  - 🏗️ Layer: Core
-  - 🔒 Invariant: ZIP structure must be preserved after transformation.
-  - 🔗 DEPENDS_ON -> `PyYAML`
+  - 📝 Transforms Superset export ZIP archives while preserving archive integrity and patching mapped identifiers.
+  - 🏗️ Layer: Domain
+  - 🔒 Invariant: ZIP structure and non-targeted metadata must remain valid after transformation.
+  - 🔗 DEPENDS_ON -> `src.core.logger`
+  - 🔗 DEPENDS_ON -> `src.core.mapping_service.IdMappingService`
+  - 🔗 DEPENDS_ON -> `src.models.mapping.ResourceType`
+  - 🔗 DEPENDS_ON -> `yaml`
  - ℂ **MigrationEngine** (`Class`) `[CRITICAL]`
    - 📝 Engine for transforming Superset export ZIPs.
    - ƒ **__init__** (`Function`) `[CRITICAL]`
-      - 📝 Initializes the migration engine with optional ID mapping service.
+      - 📝 Initializes migration orchestration dependencies for ZIP/YAML metadata transformations.
    - ƒ **transform_zip** (`Function`) `[CRITICAL]`
      - 📝 Extracts ZIP, replaces database UUIDs in YAMLs, patches cross-filters, and re-packages.
    - ƒ **_transform_yaml** (`Function`) `[CRITICAL]`
      - 📝 Replaces database_uuid in a single YAML file.
    - ƒ **_extract_chart_uuids_from_archive** (`Function`) `[CRITICAL]`
-      - 📝 Scans the unpacked ZIP to map local exported integer IDs back to their UUIDs.
+      - 📝 Scans extracted chart YAML files and builds a source chart ID to UUID lookup map.
    - ƒ **_patch_dashboard_metadata** (`Function`) `[CRITICAL]`
-      - 📝 Replaces integer IDs in json_metadata.
+      - 📝 Rewrites dashboard json_metadata chart/dataset integer identifiers using target environment mappings.
 - 📦 **backend.src.core.async_superset_client** (`Module`) `[CRITICAL]`
  - 📝 Async Superset client for dashboard hot-path requests without blocking FastAPI event loop.
  - 🏗️ Layer: Core
@@ -2802,34 +2810,38 @@
  - ƒ **get_password_hash** (`Function`) `[CRITICAL]`
    - 📝 Generates a bcrypt hash for a plain password.
 - 📦 **backend.src.core.auth.repository** (`Module`) `[CRITICAL]`
-  - 📝 Data access layer for authentication-related entities.
-  - 🏗️ Layer: Core
-  - 🔒 Invariant: All database operations must be performed within a session.
-  - 🔗 DEPENDS_ON -> `sqlalchemy`
+  - 📝 Data access layer for authentication and user preference entities.
+  - 🏗️ Layer: Domain
+  - 🔒 Invariant: All database read/write operations must execute via the injected SQLAlchemy session boundary.
+  - 🔗 DEPENDS_ON -> `sqlalchemy.orm.Session`
+  - 🔗 DEPENDS_ON -> `backend.src.models.auth`
+  - 🔗 DEPENDS_ON -> `backend.src.models.profile`
+  - 🔗 DEPENDS_ON -> `backend.src.core.logger.belief_scope`
  - ℂ **AuthRepository** (`Class`) `[CRITICAL]`
-    - 📝 Encapsulates database operations for authentication.
+    - 📝 Encapsulates database operations for authentication-related entities.
+    - 🔗 DEPENDS_ON -> `sqlalchemy.orm.Session`
    - ƒ **__init__** (`Function`) `[CRITICAL]`
-      - 📝 Initializes the repository with a database session.
+      - 📝 Bind repository instance to an existing SQLAlchemy session.
    - ƒ **get_user_by_username** (`Function`) `[CRITICAL]`
-      - 📝 Retrieves a user by their username.
+      - 📝 Retrieve a user entity by unique username.
    - ƒ **get_user_by_id** (`Function`) `[CRITICAL]`
-      - 📝 Retrieves a user by their unique ID.
+      - 📝 Retrieve a user entity by identifier.
    - ƒ **get_role_by_name** (`Function`) `[CRITICAL]`
-      - 📝 Retrieves a role by its name.
+      - 📝 Retrieve a role entity by role name.
    - ƒ **update_last_login** (`Function`) `[CRITICAL]`
-      - 📝 Updates the last_login timestamp for a user.
+      - 📝 Update last_login timestamp for the provided user entity.
    - ƒ **get_role_by_id** (`Function`) `[CRITICAL]`
-      - 📝 Retrieves a role by its unique ID.
+      - 📝 Retrieve a role entity by identifier.
    - ƒ **get_permission_by_id** (`Function`) `[CRITICAL]`
-      - 📝 Retrieves a permission by its unique ID.
+      - 📝 Retrieve a permission entity by identifier.
    - ƒ **get_permission_by_resource_action** (`Function`) `[CRITICAL]`
-      - 📝 Retrieves a permission by resource and action.
+      - 📝 Retrieve a permission entity by resource and action pair.
    - ƒ **get_user_dashboard_preference** (`Function`) `[CRITICAL]`
-      - 📝 Retrieves dashboard preference by owner user ID.
+      - 📝 Retrieve dashboard preference entity owned by specified user.
    - ƒ **save_user_dashboard_preference** (`Function`) `[CRITICAL]`
-      - 📝 Persists dashboard preference entity and returns refreshed row.
+      - 📝 Persist dashboard preference entity and return refreshed persistent row.
    - ƒ **list_permissions** (`Function`) `[CRITICAL]`
-      - 📝 Lists all available permissions.
+      - 📝 List all permission entities available in storage.
 - 📦 **test_auth** (`Module`)
  - 📝 Unit tests for authentication module
  - 🏗️ Layer: Domain
@@ -3068,10 +3080,10 @@
    - 📝 Test that configure_logger updates task_log_level.
  - ƒ **test_enable_belief_state_flag** (`Function`)
    - 📝 Test that enable_belief_state flag controls belief_scope logging.
-    - ƒ **test_belief_scope_missing_anchor** (`Function`)
-      - 📝 Test @PRE condition: anchor_id must be provided
-    - ƒ **test_configure_logger_post_conditions** (`Function`)
-      - 📝 Test @POST condition: Logger level, handlers, belief state flag, and task log level are updated.
+  - ƒ **test_belief_scope_missing_anchor** (`Function`)
+    - 📝 Test @PRE condition: anchor_id must be provided
+  - ƒ **test_configure_logger_post_conditions** (`Function`)
+    - 📝 Test @POST condition: Logger level, handlers, belief state flag, and task log level are updated.
  - ƒ **reset_logger_state** (`Function`) `[TRIVIAL]`
    - 📝 Auto-detected function (orphan)
 - 📦 **backend.src.core.migration.dry_run_orchestrator** (`Module`) `[CRITICAL]`
@@ -3114,8 +3126,11 @@
    - ƒ **_normalize_object_payload** (`Function`) `[CRITICAL]`
      - 📝 Convert raw YAML payload to stable diff signature shape.
 - 📦 **backend.src.core.migration.risk_assessor** (`Module`) `[CRITICAL]`
-  - 📝 Risk evaluation helpers for migration pre-flight reporting.
-  - 🏗️ Layer: Core
+  - 📝 Compute deterministic migration risk items and aggregate score for dry-run reporting.
+  - 🏗️ Layer: Domain
+  - 🔒 Invariant: Risk scoring must remain bounded to [0,100] and preserve severity-to-weight mapping.
+  - 🔗 DEPENDS_ON -> `backend.src.core.superset_client.SupersetClient`
+  - 🔗 DISPATCHES -> `backend.src.core.migration.dry_run_orchestrator.MigrationDryRunService.run`
  - ƒ **index_by_uuid** (`Function`) `[CRITICAL]`
    - 📝 Build UUID-index from normalized objects.
  - ƒ **extract_owner_identifiers** (`Function`) `[CRITICAL]`
@@ -3525,24 +3540,30 @@
    - 📝 Fetch the list of databases from a specific environment.
    - 🏗️ Layer: API
 - 📦 **backend.src.api.routes.migration** (`Module`) `[CRITICAL]`
-  - 📝 API endpoints for migration operations.
-  - 🏗️ Layer: API
+  - 📝 HTTP contract layer for migration orchestration, settings, dry-run, and mapping sync endpoints.
+  - 🏗️ Layer: Infra
+  - 🔒 Invariant: Migration endpoints never execute with invalid environment references and always return explicit HTTP errors on guard failures.
  - 🔗 DEPENDS_ON -> `backend.src.dependencies`
+  - 🔗 DEPENDS_ON -> `backend.src.core.database`
+  - 🔗 DEPENDS_ON -> `backend.src.core.superset_client`
+  - 🔗 DEPENDS_ON -> `backend.src.core.migration.dry_run_orchestrator`
+  - 🔗 DEPENDS_ON -> `backend.src.core.mapping_service`
  - 🔗 DEPENDS_ON -> `backend.src.models.dashboard`
+  - 🔗 DEPENDS_ON -> `backend.src.models.mapping`
  - ƒ **get_dashboards** (`Function`) `[CRITICAL]`
-    - 📝 Fetch all dashboards from the specified environment for the grid.
+    - 📝 Fetch dashboard metadata from a requested environment for migration selection UI.
  - ƒ **execute_migration** (`Function`) `[CRITICAL]`
-    - 📝 Execute the migration of selected dashboards.
+    - 📝 Validate migration selection and enqueue asynchronous migration task execution.
  - ƒ **dry_run_migration** (`Function`) `[CRITICAL]`
-    - 📝 Build pre-flight diff and risk summary without applying migration.
+    - 📝 Build pre-flight migration diff and risk summary without mutating target systems.
  - ƒ **get_migration_settings** (`Function`) `[CRITICAL]`
-    - 📝 Get current migration Cron string explicitly.
+    - 📝 Read and return configured migration synchronization cron expression.
  - ƒ **update_migration_settings** (`Function`) `[CRITICAL]`
-    - 📝 Update migration Cron string.
+    - 📝 Validate and persist migration synchronization cron expression update.
  - ƒ **get_resource_mappings** (`Function`) `[CRITICAL]`
-    - 📝 Fetch synchronized object mappings with search, filtering, and pagination.
+    - 📝 Fetch synchronized resource mappings with optional filters and pagination for migration mappings view.
  - ƒ **trigger_sync_now** (`Function`) `[CRITICAL]`
-    - 📝 Triggers an immediate ID synchronization for all environments.
+    - 📝 Trigger immediate ID synchronization for every configured environment.
 - 📦 **PluginsRouter** (`Module`)
  - 📝 Defines the FastAPI router for plugin-related endpoints, allowing clients to list available plugins.
  - 🏗️ Layer: UI (API)
@@ -3790,28 +3811,28 @@
    - 📝 Normalize intent entity value types from LLM output to route-compatible values.
  - ƒ **_confirmation_summary** (`Function`)
    - 📝 Build human-readable confirmation prompt for an intent before execution.
-    - ƒ **_clarification_text_for_intent** (`Function`)
-      - 📝 Convert technical missing-parameter errors into user-facing clarification prompts.
-    - ƒ **_plan_intent_with_llm** (`Function`)
-      - 📝 Use active LLM provider to select best tool/operation from dynamic catalog.
-    - ƒ **_authorize_intent** (`Function`)
-      - 📝 Validate user permissions for parsed intent before confirmation/dispatch.
-    - ƒ **_dispatch_intent** (`Function`)
-      - 📝 Execute parsed assistant intent via existing task/plugin/git services.
-    - ƒ **send_message** (`Function`)
-      - 📝 Parse assistant command, enforce safety gates, and dispatch executable intent.
-    - ƒ **confirm_operation** (`Function`)
-      - 📝 Execute previously requested risky operation after explicit user confirmation.
-    - ƒ **cancel_operation** (`Function`)
-      - 📝 Cancel pending risky operation and mark confirmation token as cancelled.
-    - ƒ **list_conversations** (`Function`)
-      - 📝 Return paginated conversation list for current user with archived flag and last message preview.
-    - ƒ **delete_conversation** (`Function`)
-      - 📝 Soft-delete or hard-delete a conversation and clear its in-memory trace.
-    - ƒ **get_history** (`Function`)
-      - 📝 Retrieve paginated assistant conversation history for current user.
-    - ƒ **get_assistant_audit** (`Function`)
-      - 📝 Return assistant audit decisions for current user from persistent and in-memory stores.
+  - ƒ **_clarification_text_for_intent** (`Function`)
+    - 📝 Convert technical missing-parameter errors into user-facing clarification prompts.
+  - ƒ **_plan_intent_with_llm** (`Function`)
+    - 📝 Use active LLM provider to select best tool/operation from dynamic catalog.
+  - ƒ **_authorize_intent** (`Function`)
+    - 📝 Validate user permissions for parsed intent before confirmation/dispatch.
+  - ƒ **_dispatch_intent** (`Function`)
+    - 📝 Execute parsed assistant intent via existing task/plugin/git services.
+  - ƒ **send_message** (`Function`)
+    - 📝 Parse assistant command, enforce safety gates, and dispatch executable intent.
+  - ƒ **confirm_operation** (`Function`)
+    - 📝 Execute previously requested risky operation after explicit user confirmation.
+  - ƒ **cancel_operation** (`Function`)
+    - 📝 Cancel pending risky operation and mark confirmation token as cancelled.
+  - ƒ **list_conversations** (`Function`)
+    - 📝 Return paginated conversation list for current user with archived flag and last message preview.
+  - ƒ **delete_conversation** (`Function`)
+    - 📝 Soft-delete or hard-delete a conversation and clear its in-memory trace.
+  - ƒ **get_history** (`Function`)
+    - 📝 Retrieve paginated assistant conversation history for current user.
+  - ƒ **get_assistant_audit** (`Function`)
+    - 📝 Return assistant audit decisions for current user from persistent and in-memory stores.
  - ƒ **_async_confirmation_summary** (`Function`) `[TRIVIAL]`
    - 📝 Auto-detected function (orphan)
  - ƒ **_label** (`Function`) `[TRIVIAL]`
@@ -4462,18 +4483,20 @@
    - 📝 Status command without explicit task_id should resolve to latest task for current user.
  - ƒ **test_llm_validation_with_dashboard_ref_requires_confirmation** (`Function`)
    - 📝 LLM validation with dashboard_ref should now require confirmation before dispatch.
-    - ƒ **test_list_conversations_groups_by_conversation_and_marks_archived** (`Function`)
-      - 📝 Conversations endpoint must group messages and compute archived marker by inactivity threshold.
-    - ƒ **test_history_from_latest_returns_recent_page_first** (`Function`)
-      - 📝 History endpoint from_latest mode must return newest page while preserving chronological order in chunk.
-    - ƒ **test_list_conversations_archived_only_filters_active** (`Function`)
-      - 📝 archived_only mode must return only archived conversations.
-    - ƒ **test_guarded_operation_always_requires_confirmation** (`Function`)
-      - 📝 Non-dangerous (guarded) commands must still require confirmation before execution.
-    - ƒ **test_guarded_operation_confirm_roundtrip** (`Function`)
-      - 📝 Guarded operation must execute successfully after explicit confirmation.
-      - ƒ **test_confirm_nonexistent_id_returns_404** (`Function`)
-        - 📝 Confirming a non-existent ID should raise 404.
+  - ƒ **test_list_conversations_groups_by_conversation_and_marks_archived** (`Function`)
+    - 📝 Conversations endpoint must group messages and compute archived marker by inactivity threshold.
+  - ƒ **test_history_from_latest_returns_recent_page_first** (`Function`)
+    - 📝 History endpoint from_latest mode must return newest page while preserving chronological order in chunk.
+  - ƒ **test_list_conversations_archived_only_filters_active** (`Function`)
+    - 📝 archived_only mode must return only archived conversations.
+  - ƒ **test_guarded_operation_always_requires_confirmation** (`Function`)
+    - 📝 Non-dangerous (guarded) commands must still require confirmation before execution.
+  - ƒ **test_guarded_operation_confirm_roundtrip** (`Function`)
+    - 📝 Guarded operation must execute successfully after explicit confirmation.
+  - ƒ **test_confirm_nonexistent_id_returns_404** (`Function`)
+    - 📝 Confirming a non-existent ID should raise 404.
+  - ƒ **test_migration_with_dry_run_includes_summary** (`Function`)
+    - 📝 Migration command with dry run flag must return the dry run summary in confirmation text.
  - ƒ **__init__** (`Function`) `[TRIVIAL]`
    - 📝 Auto-detected function (orphan)
  - ƒ **__init__** (`Function`) `[TRIVIAL]`
@@ -4568,13 +4591,15 @@
  - ƒ **test_dry_run_migration_rejects_same_environment** (`Function`) `[TRIVIAL]`
    - 📝 Auto-detected function (orphan)
 - 📦 **backend.src.models.config** (`Module`) `[CRITICAL]`
-  - 📝 Defines database schema for persisted application configuration.
+  - 📝 Defines SQLAlchemy persistence models for application and notification configuration records.
  - 🏗️ Layer: Domain
+  - 🔒 Invariant: Configuration payload and notification credentials must remain persisted as non-null JSON documents.
  - 🔗 DEPENDS_ON -> `sqlalchemy`
+  - 🔗 DEPENDS_ON -> `backend.src.models.mapping:Base`
  - ℂ **AppConfigRecord** (`Class`) `[CRITICAL]`
-    - 📝 Stores the single source of truth for application configuration.
+    - 📝 Stores persisted application configuration as a single authoritative record model.
  - ℂ **NotificationConfig** (`Class`) `[CRITICAL]`
-    - 📝 Global settings for external notification providers.
+    - 📝 Stores persisted provider-level notification configuration and encrypted credentials metadata.
 - 📦 **backend.src.models.llm** (`Module`)
  - 📝 SQLAlchemy models for LLM provider configuration and validation results.
  - 🏗️ Layer: Domain
@@ -4628,8 +4653,8 @@
    - 📝 Represents a mapping between source and target databases.
  - ℂ **MigrationJob** (`Class`) `[TRIVIAL]`
    - 📝 Represents a single migration execution job.
-    - ℂ **ResourceMapping** (`Class`)
-      - 📝 Maps a universal UUID for a resource to its actual ID on a specific environment.
+  - ℂ **ResourceMapping** (`Class`)
+    - 📝 Maps a universal UUID for a resource to its actual ID on a specific environment.
 - 📦 **backend.src.models.report** (`Module`) `[CRITICAL]`
  - 📝 Canonical report schemas for unified task reporting across heterogeneous task types.
  - 🏗️ Layer: Domain
@@ -5066,19 +5091,24 @@
  - ƒ **__getattr__** (`Function`) `[TRIVIAL]`
    - 📝 Auto-detected function (orphan)
 - 📦 **backend.src.services.auth_service** (`Module`) `[CRITICAL]`
-  - 📝 Orchestrates authentication business logic.
-  - 🏗️ Layer: Service
-  - 🔒 Invariant: Authentication must verify both credentials and account status.
+  - 📝 Orchestrates credential authentication and ADFS JIT user provisioning.
+  - 🏗️ Layer: Domain
+  - 🔒 Invariant: Authentication succeeds only for active users with valid credentials; issued sessions encode subject and scopes from assigned roles.
+  - 🔗 DEPENDS_ON -> `backend.src.core.auth.repository.AuthRepository`
+  - 🔗 DEPENDS_ON -> `backend.src.core.auth.security.verify_password`
+  - 🔗 DEPENDS_ON -> `backend.src.core.auth.jwt.create_access_token`
+  - 🔗 DEPENDS_ON -> `backend.src.models.auth.User`
+  - 🔗 DEPENDS_ON -> `backend.src.models.auth.Role`
  - ℂ **AuthService** (`Class`) `[CRITICAL]`
    - 📝 Provides high-level authentication services.
    - ƒ **__init__** (`Function`) `[CRITICAL]`
-      - 📝 Initializes the service with a database session.
+      - 📝 Initializes the authentication service with repository access over an active DB session.
    - ƒ **authenticate_user** (`Function`) `[CRITICAL]`
-      - 📝 Authenticates a user with username and password.
+      - 📝 Validates credentials and account state for local username/password authentication.
    - ƒ **create_session** (`Function`) `[CRITICAL]`
-      - 📝 Creates a JWT session for an authenticated user.
+      - 📝 Issues an access token payload for an already authenticated user.
    - ƒ **provision_adfs_user** (`Function`) `[CRITICAL]`
-      - 📝 Just-In-Time (JIT) provisioning for ADFS users based on group mappings.
+      - 📝 Performs ADFS Just-In-Time provisioning and role synchronization from AD group mappings.
 - 📦 **backend.src.services.git_service** (`Module`)
  - 📝 Core Git logic using GitPython to manage dashboard repositories.
  - 🏗️ Layer: Service
@@ -5435,14 +5465,18 @@
  - 🔗 DEPENDS_ON -> `backend.src.services.clean_release.repository`
  - ℂ **CleanComplianceOrchestrator** (`Class`)
    - 📝 Coordinate clean-release compliance verification stages.
+    - ƒ **CleanComplianceOrchestrator.__init__** (`Function`)
+      - 📝 Bind repository dependency used for orchestrator persistence and lookups.
    - ƒ **start_check_run** (`Function`)
      - 📝 Initiate a new compliance run session.
-      - ƒ **finalize_run** (`Function`)
-        - 📝 Finalize run status based on cumulative stage results.
+    - ƒ **execute_stages** (`Function`)
+      - 📝 Execute or accept compliance stage outcomes and set intermediate/final check-run status fields.
+    - ƒ **finalize_run** (`Function`)
+      - 📝 Finalize run status based on cumulative stage results.
+  - ƒ **run_check_legacy** (`Function`)
+    - 📝 Legacy wrapper for compatibility with previous orchestrator call style.
  - ƒ **__init__** (`Function`) `[TRIVIAL]`
    - 📝 Auto-detected function (orphan)
-  - ƒ **execute_stages** (`Function`) `[TRIVIAL]`
-    - 📝 Auto-detected function (orphan)
 - 📦 **backend.src.services.clean_release.compliance_execution_service** (`Module`) `[CRITICAL]`
  - 📝 Create and execute compliance runs with trusted snapshots, deterministic stages, violations and immutable report persistence.
  - 🏗️ Layer: Domain
@@ -5786,6 +5820,21 @@
  - 📝 Validate release candidate preparation flow, including policy evaluation and manifest persisting.
  - 🏗️ Layer: Domain
  - 🔒 Invariant: Candidate preparation always persists manifest and candidate status deterministically.
+  - 🔗 DEPENDS_ON -> `backend.src.services.clean_release.preparation_service:Module`
+  - ƒ **backend.tests.services.clean_release.test_preparation_service._mock_policy** (`Function`)
+    - 📝 Build a valid clean profile policy fixture for preparation tests.
+  - ƒ **backend.tests.services.clean_release.test_preparation_service._mock_registry** (`Function`)
+    - 📝 Build an internal-only source registry fixture for preparation tests.
+  - ƒ **backend.tests.services.clean_release.test_preparation_service._mock_candidate** (`Function`)
+    - 📝 Build a draft release candidate fixture with provided identifier.
+  - ƒ **backend.tests.services.clean_release.test_preparation_service.test_prepare_candidate_success** (`Function`)
+    - 📝 Verify candidate transitions to PREPARED when evaluation returns no violations.
+  - ƒ **backend.tests.services.clean_release.test_preparation_service.test_prepare_candidate_with_violations** (`Function`)
+    - 📝 Verify candidate transitions to BLOCKED when evaluation returns blocking violations.
+  - ƒ **backend.tests.services.clean_release.test_preparation_service.test_prepare_candidate_not_found** (`Function`)
+    - 📝 Verify preparation raises ValueError when candidate does not exist.
+  - ƒ **backend.tests.services.clean_release.test_preparation_service.test_prepare_candidate_no_active_policy** (`Function`)
+    - 📝 Verify preparation raises ValueError when no active policy is available.
  - ƒ **_mock_policy** (`Function`) `[TRIVIAL]`
    - 📝 Auto-detected function (orphan)
  - ƒ **_mock_registry** (`Function`) `[TRIVIAL]`