semantics

backend/src/api/auth.py

@@ -1,12 +1,15 @@
-# #region AuthApi [C:3] [TYPE Module] [SEMANTICS fastapi, auth, api]
-#
+# #region AuthApi [C:5] [TYPE Module] [SEMANTICS fastapi, auth, api]
 # @BRIEF Authentication API endpoints.
-# @LAYER:     API
-# @RELATION DEPENDS_ON -> [AuthService]
-# @RELATION DEPENDS_ON -> [get_auth_db]
-# @RELATION DEPENDS_ON -> [get_current_user]
+# @LAYER API
 # @RELATION DEPENDS_ON -> [is_adfs_configured]
-# @INVARIANT: All auth endpoints must return consistent error codes.
+# @RELATION DEPENDS_ON -> [is_adfs_configured]
+# @RELATION DEPENDS_ON -> [is_adfs_configured]
+# @RELATION DEPENDS_ON -> [is_adfs_configured]
+# @PRE Python environment and dependencies installed; database available.
+# @POST FastAPI app instance with auth routes registered.
+# @SIDE_EFFECT Registers API routes; configures OAuth and CORS middleware.
+# @DATA_CONTRACT Input -> OAuth2PasswordRequestForm -> Token, User
+# @INVARIANT All auth endpoints must return consistent error codes.
 
 import starlette.requests
 from fastapi import APIRouter, Depends, HTTPException, status
@@ -29,12 +32,14 @@ router = APIRouter(prefix="/api/auth", tags=["auth"])
 # #endregion router
 
 
-# #region login_for_access_token [C:3] [TYPE Function]
+# #region login_for_access_token [C:4] [TYPE Function]
 # @BRIEF Authenticates a user and returns a JWT access token.
-# @PRE:     form_data contains username and password.
-# @POST:    Returns a Token object on success.
-# @RELATION CALLS -> [AuthService.authenticate_user]
+# @PRE form_data contains username and password.
+# @POST Returns a Token object on success.
 # @RELATION CALLS -> [AuthService.create_session]
+# @RELATION CALLS -> [AuthService.create_session]
+# @SIDE_EFFECT DB read/write for auth session; writes security event log.
+
 @router.post("/login", response_model=Token)
 async def login_for_access_token(
     form_data: OAuth2PasswordRequestForm = Depends(), db: Session = Depends(get_auth_db)
@@ -58,11 +63,13 @@ async def login_for_access_token(
 # #endregion login_for_access_token
 
 
-# #region read_users_me [C:3] [TYPE Function]
+# #region read_users_me [C:4] [TYPE Function]
 # @BRIEF Retrieves the profile of the currently authenticated user.
-# @PRE:     Valid JWT token provided.
-# @POST:    Returns the current user's data.
+# @PRE Valid JWT token provided.
+# @POST Returns the current user's data.
 # @RELATION DEPENDS_ON -> [get_current_user]
+# @SIDE_EFFECT Reads current user from DB via auth middleware; writes security event log.
+
 @router.get("/me", response_model=UserSchema)
 async def read_users_me(current_user: UserSchema = Depends(get_current_user)):
     with belief_scope("api.auth.me"):
@@ -72,11 +79,13 @@ async def read_users_me(current_user: UserSchema = Depends(get_current_user)):
 # #endregion read_users_me
 
 
-# #region logout [C:3] [TYPE Function]
+# #region logout [C:4] [TYPE Function]
 # @BRIEF Logs out the current user (placeholder for session revocation).
-# @PRE:     Valid JWT token provided.
-# @POST:    Returns success message.
+# @PRE Valid JWT token provided.
+# @POST Returns success message.
 # @RELATION DEPENDS_ON -> [get_current_user]
+# @SIDE_EFFECT Writes security event LOGOUT event.
+
 @router.post("/logout")
 async def logout(current_user: UserSchema = Depends(get_current_user)):
     with belief_scope("api.auth.logout"):
@@ -89,10 +98,12 @@ async def logout(current_user: UserSchema = Depends(get_current_user)):
 # #endregion logout
 
 
-# #region login_adfs [C:3] [TYPE Function]
+# #region login_adfs [C:4] [TYPE Function]
 # @BRIEF Initiates the ADFS OIDC login flow.
-# @POST:    Redirects the user to ADFS.
+# @POST Redirects the user to ADFS.
 # @RELATION USES -> [is_adfs_configured]
+# @SIDE_EFFECT Redirects user to ADFS external OIDC provider.
+
 @router.get("/login/adfs")
 async def login_adfs(request: starlette.requests.Request):
     with belief_scope("api.auth.login_adfs"):
@@ -108,12 +119,14 @@ async def login_adfs(request: starlette.requests.Request):
 # #endregion login_adfs
 
 
-# #region auth_callback_adfs [C:3] [TYPE Function]
+# #region auth_callback_adfs [C:4] [TYPE Function]
 # @BRIEF Handles the callback from ADFS after successful authentication.
-# @POST:    Provisions user JIT and returns session token.
-# @RELATION DEPENDS_ON -> [is_adfs_configured]
-# @RELATION CALLS -> [AuthService.provision_adfs_user]
+# @POST Provisions user JIT and returns session token.
 # @RELATION CALLS -> [AuthService.create_session]
+# @RELATION CALLS -> [AuthService.create_session]
+# @RELATION CALLS -> [AuthService.create_session]
+# @SIDE_EFFECT Provisions user in DB, creates auth session, writes security event log.
+
 @router.get("/callback/adfs", name="auth_callback_adfs")
 async def auth_callback_adfs(
     request: starlette.requests.Request, db: Session = Depends(get_auth_db)

backend/src/api/routes/__init__.py

@@ -1,8 +1,10 @@
-# #region ApiRoutesModule [C:3] [TYPE Module] [SEMANTICS api, package, router, lazy, import]
+# #region ApiRoutesModule [C:5] [TYPE Module] [SEMANTICS api, package, router, lazy, import]
 # @BRIEF Provide lazy route module loading to avoid heavyweight imports during tests.
 # @LAYER: API
 # @RELATION CALLS -> [ApiRoutesGetAttr]
 # @RELATION BINDS_TO -> [Route_Group_Contracts]
+# @PRE: FastAPI app initialized, route modules available in package
+# @POST: Route modules are lazily loadable via __getattr__
 # @INVARIANT: Only names listed in __all__ are importable via __getattr__.
 
 # #region Route_Group_Contracts [C:3] [TYPE Block]
@@ -13,6 +15,8 @@
 # @RELATION DEPENDS_ON -> [ConnectionsRouter]
 # @RELATION DEPENDS_ON -> [ReportsRouter]
 # @RELATION DEPENDS_ON -> [LlmRoutes]
+# @SIDE_EFFECT: Registers route group imports via __getattr__
+# @DATA_CONTRACT: Package -> RouterModule mapping
 __all__ = [
     "admin",
     "assistant",

backend/src/api/routes/__tests__/test_assistant_authz.py

@@ -3,7 +3,7 @@ import os
 os.environ["ENCRYPTION_KEY"] = "OnrCzomBWbIjTf7Y-fnhL2adlU55bHZQjp8zX5zBC5w="
 # #region TestAssistantAuthz [TYPE Module] [C:3] [SEMANTICS tests, assistant, authz, confirmation, rbac]
 # @BRIEF Verify assistant confirmation ownership, expiration, and deny behavior for restricted users.
-# @LAYER: UI (API Tests)
+# @LAYER: API
 # @RELATION DEPENDS_ON -> AssistantApi
 # @INVARIANT: Security-sensitive flows fail closed for unauthorized actors.
 import asyncio

backend/src/api/routes/__tests__/test_git_status_route.py

@@ -1,6 +1,6 @@
 # #region TestGitStatusRoute [TYPE Module] [C:3] [SEMANTICS tests, git, api, status, no_repo]
 # @BRIEF Validate status endpoint behavior for missing and error repository states.
-# @LAYER: Domain (Tests)
+# @LAYER: Domain
 # @RELATION VERIFIES -> [GitApi]
 import asyncio
 from unittest.mock import MagicMock

backend/src/api/routes/__tests__/test_reports_api.py

@@ -1,7 +1,7 @@
 # #region TestReportsApi [TYPE Module] [C:3] [SEMANTICS tests, reports, api, contract, pagination, filtering]
 # @RELATION BELONGS_TO -> SrcRoot
 # @BRIEF Contract tests for GET /api/reports defaults, pagination, and filtering behavior.
-# @LAYER: Domain (Tests)
+# @LAYER: Domain
 # @INVARIANT: API response contract contains {items,total,page,page_size,has_next,applied_filters}.
 from datetime import UTC, datetime, timedelta
 from types import SimpleNamespace

backend/src/api/routes/__tests__/test_reports_detail_api.py

@@ -1,7 +1,7 @@
 # #region TestReportsDetailApi [TYPE Module] [C:3] [SEMANTICS tests, reports, api, detail, diagnostics]
 # @RELATION BELONGS_TO -> SrcRoot
 # @BRIEF Contract tests for GET /api/reports/{report_id} detail endpoint behavior.
-# @LAYER: Domain (Tests)
+# @LAYER: Domain
 # @INVARIANT: Detail endpoint tests must keep deterministic assertions for success and not-found contracts.
 from datetime import datetime, timedelta
 from types import SimpleNamespace

backend/src/api/routes/__tests__/test_reports_openapi_conformance.py

@@ -1,7 +1,7 @@
 # #region TestReportsOpenapiConformance [TYPE Module] [C:3] [SEMANTICS tests, reports, openapi, conformance]
 # @RELATION BELONGS_TO -> SrcRoot
 # @BRIEF Validate implemented reports payload shape against OpenAPI-required top-level contract fields.
-# @LAYER: Domain (Tests)
+# @LAYER: Domain
 # @INVARIANT: List and detail payloads include required contract keys.
 from datetime import datetime
 from types import SimpleNamespace

backend/src/api/routes/__tests__/test_tasks_logs.py

@@ -1,7 +1,7 @@
 # #region test_tasks_logs_module [TYPE Module] [C:2] [SEMANTICS tests, tasks, logs, api, contract, validation]
 # @RELATION VERIFIES -> [src.api.routes.tasks:Module]
 # @BRIEF Contract testing for task logs API endpoints.
-# @LAYER: Domain (Tests)
+# @LAYER: Domain
 from unittest.mock import MagicMock
 
 import pytest

backend/src/api/routes/admin.py

@@ -1,7 +1,7 @@
-# #region AdminApi [C:3] [TYPE Module] [SEMANTICS fastapi, admin, api, rbac, user]
+# #region AdminApi [C:5] [TYPE Module] [SEMANTICS fastapi, admin, api, rbac, user]
 #
 # @BRIEF Admin API endpoints for user and role management.
-# @LAYER:     API
+# @LAYER: API
 # @RELATION DEPENDS_ON -> [AuthRepository:Class]
 # @RELATION DEPENDS_ON -> [get_auth_db:Function]
 # @RELATION DEPENDS_ON -> [has_permission:Function]

backend/src/api/routes/assistant/_llm_planner.py

@@ -1,10 +1,14 @@
-# #region AssistantLlmPlanner [C:3] [TYPE Module] [SEMANTICS assistant, llm, planner, tool, catalog]
+# #region AssistantLlmPlanner [C:5] [TYPE Module] [SEMANTICS assistant, llm, planner, tool, catalog]
 # @BRIEF LLM-based intent planning, tool catalog construction, and authorization for the assistant API.
 # @LAYER: API
 # @RELATION DEPENDS_ON -> [AssistantSchemas]
 # @RELATION DEPENDS_ON -> [AssistantResolvers]
 # @RELATION DISPATCHES -> [AssistantLlmPlannerIntent]
+# @PRE: Assistant routes initialized, user authenticated
+# @POST: LLM tool catalog filtered and returned
 # @INVARIANT: Tool catalog is filtered by user permissions before being sent to LLM.
+# @SIDE_EFFECT: Filters tool catalog by user permissions
+# @DATA_CONTRACT: UserPermissions -> ToolCatalog
 
 from __future__ import annotations
 

backend/src/api/routes/assistant/_llm_planner_intent.py

@@ -1,9 +1,13 @@
-# #region AssistantLlmPlannerIntent [C:3] [TYPE Module] [SEMANTICS assistant, llm, intent, planning, authorization]
+# #region AssistantLlmPlannerIntent [C:5] [TYPE Module] [SEMANTICS assistant, llm, intent, planning, authorization]
 # @BRIEF LLM-based intent planning and authorization for the assistant API — separated from tool catalog.
 # @LAYER: API
 # @RELATION DEPENDS_ON -> [AssistantLlmPlanner]
 # @RELATION DEPENDS_ON -> [AssistantResolvers]
+# @PRE: Assistant routes initialized, user authenticated
+# @POST: Intent planning registered with confirmation gate
 # @INVARIANT: Production deployments always require confirmation.
+# @SIDE_EFFECT: Registers intent planning routes
+# @DATA_CONTRACT: UserIntent -> PlannedAction
 
 from __future__ import annotations
 

backend/src/api/routes/clean_release_v2.py

@@ -1,6 +1,6 @@
 # #region CleanReleaseV2Api [C:4] [TYPE Module] [SEMANTICS fastapi, clean-release, candidate, lifecycle, api]
 # @BRIEF Redesigned clean release API for headless candidate lifecycle.
-# @LAYER: UI (API)
+# @LAYER: API
 # @RELATION DEPENDS_ON -> [CleanReleaseRepository]
 # @RELATION CALLS -> [approve_candidate]
 # @RELATION CALLS -> [publish_candidate]

backend/src/api/routes/connections.py

@@ -1,6 +1,6 @@
 # #region ConnectionsRouter [C:3] [TYPE Module] [SEMANTICS fastapi, connection, api, search]
 # @BRIEF Defines the FastAPI router for managing external database connections.
-# @LAYER: UI (API)
+# @LAYER: API
 # @RELATION DEPENDS_ON -> [get_db]
 # @RELATION DEPENDS_ON -> [ConnectionConfig]
 

backend/src/api/routes/datasets.py

@@ -1,4 +1,4 @@
-# #region DatasetsApi [C:3] [TYPE Module] [SEMANTICS fastapi, dataset, api, search, mapping, mapped-fields]
+# #region DatasetsApi [C:5] [TYPE Module] [SEMANTICS fastapi, dataset, api, search, mapping, mapped-fields]
 #
 # @BRIEF API endpoints for the Dataset Hub - listing datasets with mapping progress
 # @LAYER:     API
@@ -6,6 +6,10 @@
 # @RELATION DEPENDS_ON -> [ResourceService]
 # @RELATION DEPENDS_ON -> [SupersetClient]
 #
+# @PRE SupersetClient is available; env_id is valid.
+# @POST Returns dataset metadata with mapping status.
+# @SIDE_EFFECT Reads from Superset API and task manager.
+# @DATA_CONTRACT Input -> DatasetQuery, Output -> DatasetsResponse, DatasetDetailResponse
 # @INVARIANT: All dataset responses include last_task metadata
 
 
@@ -102,7 +106,7 @@ class TaskResponse(BaseModel):
     task_id: str
 # #endregion TaskResponse
 
-# #region get_dataset_ids [C:3] [TYPE Function]
+# #region get_dataset_ids [C:4] [TYPE Function]
 # @BRIEF Fetch list of all dataset IDs from a specific environment (without pagination)
 # @PRE: env_id must be a valid environment ID
 # @POST: Returns a list of all dataset IDs
@@ -150,7 +154,7 @@ async def get_dataset_ids(
             raise HTTPException(status_code=503, detail=f"Failed to fetch dataset IDs: {e!s}")
 # #endregion get_dataset_ids
 
-# #region get_datasets [C:3] [TYPE Function]
+# #region get_datasets [C:4] [TYPE Function]
 # @BRIEF Fetch list of datasets from a specific environment with mapping progress
 # @PRE: env_id must be a valid environment ID
 # @PRE: page must be >= 1 if provided
@@ -234,7 +238,7 @@ class MapColumnsRequest(BaseModel):
     file_data: str | None = Field(None, description="File path or data for XLSX source")
 # #endregion MapColumnsRequest
 
-# #region map_columns [C:3] [TYPE Function]
+# #region map_columns [C:4] [TYPE Function]
 # @BRIEF Trigger bulk column mapping for datasets
 # @PRE: User has permission plugin:mapper:execute
 # @PRE: env_id is a valid environment ID
@@ -302,7 +306,7 @@ class GenerateDocsRequest(BaseModel):
     options: dict | None = Field(None, description="Additional options for documentation generation")
 # #endregion GenerateDocsRequest
 
-# #region generate_docs [C:3] [TYPE Function]
+# #region generate_docs [C:4] [TYPE Function]
 # @BRIEF Trigger bulk documentation generation for datasets
 # @PRE: User has permission plugin:llm_analysis:execute
 # @PRE: env_id is a valid environment ID
@@ -355,7 +359,7 @@ async def generate_docs(
             raise HTTPException(status_code=503, detail=f"Failed to create documentation generation task: {e!s}")
 # #endregion generate_docs
 
-# #region get_dataset_detail [C:3] [TYPE Function]
+# #region get_dataset_detail [C:4] [TYPE Function]
 # @BRIEF Get detailed dataset information including columns and linked dashboards
 # @PRE: env_id is a valid environment ID
 # @PRE: dataset_id is a valid dataset ID
@@ -381,6 +385,11 @@ async def get_dataset_detail(
             client = SupersetClient(env)
             dataset_detail = client.get_dataset_detail(dataset_id)
 
+            # Normalize 'database' field: Superset returns an object, model expects a string
+            if isinstance(dataset_detail.get("database"), dict):
+                db_obj = dataset_detail["database"]
+                dataset_detail["database"] = db_obj.get("database_name", str(db_obj.get("id", "")))
+
             logger.info(f"[get_dataset_detail][Coherence:OK] Retrieved dataset {dataset_id} with {dataset_detail['column_count']} columns and {dataset_detail['linked_dashboard_count']} linked dashboards")
 
             return DatasetDetailResponse(**dataset_detail)

backend/src/api/routes/environments.py

@@ -1,7 +1,7 @@
-# #region EnvironmentsApi [C:3] [TYPE Module] [SEMANTICS fastapi, environment, api]
+# #region EnvironmentsApi [C:5] [TYPE Module] [SEMANTICS fastapi, environment, api]
 #
 # @BRIEF API endpoints for listing environments and their databases.
-# @LAYER:     API
+# @LAYER: API
 # @RELATION DEPENDS_ON -> [AppDependencies]
 # @RELATION DEPENDS_ON -> [SupersetClient]
 #

backend/src/api/routes/git/__init__.py

@@ -1,10 +1,14 @@
-# #region GitPackage [C:3] [TYPE Module] [SEMANTICS git, api, package, sync]
+# #region GitPackage [C:5] [TYPE Module] [SEMANTICS git, api, package, sync]
 # @BRIEF Package root for decomposed git routes. Re-exports all public symbols from submodules.
 # @LAYER: API
 # @RELATION USES -> [GitRouter, GitDeps, GitHelpers, GitConfigRoutes, GitGiteaRoutes,
 #                     GitRepoRoutes, GitRepoOperationsRoutes, GitRepoLifecycleRoutes,
 #                     GitMergeRoutes, GitEnvironmentRoutes]
 # @INVARIANT: git_service and os are module-level attributes for test monkeypatch compatibility.
+# @PRE: Git service initialized
+# @POST: Git API package exported
+# @SIDE_EFFECT: Registers git route submodules
+# @DATA_CONTRACT: GitRequest -> GitResponse
 #             All route functions are re-exported for direct access via `from src.api.routes import git`.
 
 import os

backend/src/api/routes/llm.py

@@ -1,6 +1,6 @@
 # #region LlmRoutes [C:3] [TYPE Module] [SEMANTICS fastapi, llm, api, provider]
 # @BRIEF API routes for LLM provider configuration and management.
-# @LAYER: UI (API)
+# @LAYER: API
 # @RELATION DEPENDS_ON -> [LLMProviderService]
 # @RELATION DEPENDS_ON -> [LLMProviderConfig]
 # @RELATION DEPENDS_ON -> [get_current_user]
@@ -30,10 +30,12 @@ class FetchModelsRequest(BaseModel):
 
 # #endregion FetchModelsRequest
 
-# #region router [TYPE Global]
+# #region router [C:1] [TYPE Global]
 # @BRIEF APIRouter instance for LLM routes.
+
 router = APIRouter(tags=["LLM"])
 # #endregion router
+# #endregion router
 
 
 # #region _is_valid_runtime_api_key [C:4] [TYPE Function]

backend/src/api/routes/plugins.py

@@ -1,6 +1,6 @@
 # #region PluginsRouter [C:3] [TYPE Module] [SEMANTICS fastapi, plugin, api]
 # @BRIEF Defines the FastAPI router for plugin-related endpoints, allowing clients to list available plugins.
-# @LAYER: UI (API)
+# @LAYER: API
 # @RELATION DEPENDS_ON -> [PluginConfig]
 # @RELATION DEPENDS_ON -> [get_plugin_loader]
 # @RELATION BINDS_TO -> [API_Routes]

backend/src/api/routes/profile.py

@@ -1,4 +1,4 @@
-# #region ProfileApiModule [C:3] [TYPE Module] [SEMANTICS fastapi, profile, api, validate, search, superset]
+# #region ProfileApiModule [C:5] [TYPE Module] [SEMANTICS fastapi, profile, api, validate, search, superset]
 #
 # @BRIEF Exposes self-scoped profile preference endpoints and environment-based Superset account lookup.
 # @LAYER: API
@@ -7,11 +7,15 @@
 # @RELATION DEPENDS_ON -> [get_db]
 #
 # @INVARIANT: Endpoints are self-scoped and never mutate another user preference.
+# @PRE: Auth middleware configured, database session available
+# @POST: Profile endpoints registered
 # @UX_STATE: ProfileLoad -> Returns stable ProfilePreferenceResponse for authenticated user.
 # @UX_STATE: Saving -> Validation errors map to actionable 422 details.
 # @UX_STATE: LookupLoading -> Returns success/degraded Superset lookup payload.
 # @UX_FEEDBACK: Stable status/message/warning payloads support profile page feedback.
 # @UX_RECOVERY: Lookup degradation keeps manual username save path available.
+# @SIDE_EFFECT: Registers /api/profile/* routes
+# @DATA_CONTRACT: ProfileRequest -> ProfileResponse
 
 
 from fastapi import APIRouter, Depends, HTTPException, Query

backend/src/api/routes/reports.py

@@ -1,6 +1,6 @@
 # #region ReportsRouter [C:5] [TYPE Module] [SEMANTICS fastapi, report, api, transform, search, task]
 # @BRIEF FastAPI router for unified task report list and detail retrieval endpoints.
-# @LAYER: UI (API)
+# @LAYER: API
 # @RELATION DEPENDS_ON -> [ReportsService:Class]
 # @RELATION DEPENDS_ON -> [get_task_manager:Function]
 # @RELATION DEPENDS_ON -> [get_clean_release_repository:Function]

backend/src/api/routes/settings.py

@@ -1,4 +1,4 @@
-# #region SettingsRouter [C:3] [TYPE Module] [SEMANTICS fastapi, api, superset, logging-config-response]
+# #region SettingsRouter [C:5] [TYPE Module] [SEMANTICS fastapi, api, superset, logging-config-response]
 #
 # @BRIEF Provides API endpoints for managing application settings and Superset environments.
 # @LAYER: API
@@ -6,6 +6,10 @@
 # @RELATION DEPENDS_ON -> [get_config_manager]
 # @RELATION DEPENDS_ON -> [has_permission]
 #
+# @PRE ConfigManager is initialized and accessible.
+# @POST Settings are read or written via ConfigManager.
+# @SIDE_EFFECT Persists config changes to disk via ConfigManager.
+# @DATA_CONTRACT Input -> ConfigUpdateRequest, Output -> AppConfig, LoggingConfigResponse
 # @INVARIANT: All settings changes must be persisted via ConfigManager.
 # @PUBLIC_API: router
 

backend/src/api/routes/storage.py

@@ -1,7 +1,7 @@
-# #region storage_routes [C:3] [TYPE Module] [SEMANTICS fastapi, storage, api, upload, download]
+# #region storage_routes [C:5] [TYPE Module] [SEMANTICS fastapi, storage, api, upload, download]
 #
 # @BRIEF API endpoints for file storage management (backups and repositories).
-# @LAYER:     API
+# @LAYER: API
 # @RELATION DEPENDS_ON -> [StorageModels]
 # @RELATION DEPENDS_ON -> [StoragePlugin]
 #

backend/src/api/routes/tasks.py

@@ -1,6 +1,6 @@
 # #region TasksRouter [C:3] [TYPE Module] [SEMANTICS fastapi, task, api, search, create-task-request, resolve-task-request]
 # @BRIEF Defines the FastAPI router for task-related endpoints, allowing clients to create, list, and get the status of tasks.
-# @LAYER: UI (API)
+# @LAYER: API
 # @RELATION DEPENDS_ON -> [TaskManager]
 # @RELATION DEPENDS_ON -> [ConfigManager]
 # @RELATION DEPENDS_ON -> [LLMProviderService]

backend/src/app.py

@@ -1,6 +1,6 @@
 # #region AppModule [C:5] [TYPE Module] [SEMANTICS fastapi, websocket, startup, scheduler, middleware]
-# @BRIEF The main entry point for the FastAPI application. It initializes the app, configures CORS, sets up dependencies, includes API routers, and defines the WebSocket endpoint for log streaming.
-# @LAYER UI (API)
+# @BRIEF The main entry point for the FastAPI application.
+# @LAYER API
 # @RELATION DEPENDS_ON -> [ApiRoutesModule]
 # @RELATION DEPENDS_ON -> [ApiRoutesModule]
 # @INVARIANT All WebSocket connections must be properly cleaned up on disconnect.

backend/src/core/auth/jwt.py

@@ -1,11 +1,15 @@
-# #region AuthJwtModule [C:3] [TYPE Module] [SEMANTICS auth, validate, jwt, token]
+# #region AuthJwtModule [C:5] [TYPE Module] [SEMANTICS auth, validate, jwt, token]
 #
 # @BRIEF JWT token generation and validation logic.
-# @LAYER:     Core
+# @LAYER: Core
 # @RELATION DEPENDS_ON -> [auth_config]
 # @RELATION USES -> [auth_config]
 #
 # @INVARIANT: Tokens must include expiration time and user identifier.
+# @PRE: JWT secret configured in environment
+# @POST: Token encode/decode functions exported
+# @SIDE_EFFECT: None
+# @DATA_CONTRACT: TokenPayload -> JWT string
 
 from datetime import datetime, timedelta
 

backend/src/core/auth/logger.py

@@ -1,10 +1,16 @@
-# #region AuthLoggerModule [C:3] [TYPE Module] [SEMANTICS auth, audit, logging]
+# #region AuthLoggerModule [C:5] [TYPE Module] [SEMANTICS auth, audit, logging]
 #
-# @BRIEF Audit logging for security-related events.
-# @LAYER:     Core
-# @RELATION USES -> belief_scope
+# @BRIEF Structured auth logging module for audit trail generation.
+# @LAYER: Core
+# @RELATION DEPENDS_ON -> [core_logger]
 #
 # @INVARIANT: Must not log sensitive data like passwords or full tokens.
+# @PRE: Auth module initialized
+# @POST: Audit logging functions exported
+# @SIDE_EFFECT: Writes auth audit log entries
+# @DATA_CONTRACT: AuthEvent -> LogEntry
+# @SIDE_EFFECT: Writes auth audit log entries
+# @DATA_CONTRACT: AuthEvent -> LogEntry
 
 from datetime import datetime
 

backend/src/core/database.py

@@ -1,7 +1,7 @@
 # #region DatabaseModule [C:3] [TYPE Module] [SEMANTICS sqlalchemy, connection, session]
 #
 # @BRIEF Configures database connection and session management (PostgreSQL-first).
-# @LAYER:     Core
+# @LAYER: Infrastructure
 # @RELATION DEPENDS_ON -> [MappingModels]
 # @RELATION DEPENDS_ON -> [auth_config]
 # @RELATION DEPENDS_ON -> [ConnectionConfig]

backend/src/core/migration/archive_parser.py

@@ -1,8 +1,12 @@
-# #region MigrationArchiveParserModule [C:3] [TYPE Module] [SEMANTICS migration, transform, superset, migration-archive-parser]
+# #region MigrationArchiveParserModule [C:5] [TYPE Module] [SEMANTICS migration, transform, superset, migration-archive-parser]
 # @BRIEF Parse Superset export ZIP archives into normalized object catalogs for diffing.
-# @LAYER: Core
+# @LAYER: Domain
 # @RELATION DEPENDS_ON -> [LoggerModule]
 # @INVARIANT: Parsing is read-only and never mutates archive files.
+# @PRE: Archive file path is valid and readable
+# @POST: Parsed migration archive returned
+# @SIDE_EFFECT: Reads archive file (read-only)
+# @DATA_CONTRACT: ArchivePath -> ParsedMigration
 import json
 import tempfile
 import zipfile

backend/src/core/migration/dry_run_orchestrator.py

@@ -1,11 +1,15 @@
-# #region MigrationDryRunOrchestratorModule [C:3] [TYPE Module] [SEMANTICS sqlalchemy, migration, orchestration, diff, migration-dry-run-service]
+# #region MigrationDryRunOrchestratorModule [C:5] [TYPE Module] [SEMANTICS sqlalchemy, migration, orchestration, diff, migration-dry-run-service]
 # @BRIEF Compute pre-flight migration diff and risk scoring without apply.
-# @LAYER: Core
+# @LAYER: Domain
 # @RELATION DEPENDS_ON -> [SupersetClient]
 # @RELATION DEPENDS_ON -> [MigrationEngine]
 # @RELATION DEPENDS_ON -> [MigrationArchiveParser]
 # @RELATION DEPENDS_ON -> [RiskAssessorModule]
 # @INVARIANT: Dry run is informative only and must not mutate target environment.
+# @PRE: Source and target environments configured
+# @POST: Dry-run diff returned without mutation
+# @SIDE_EFFECT: Reads source environment (read-only)
+# @DATA_CONTRACT: EnvironmentConfig -> MigrationDiffReport
 import json
 from datetime import UTC, datetime
 from typing import Any

backend/src/core/superset_client/__init__.py

@@ -1,5 +1,5 @@
-# #region SupersetClientModule [C:3] [TYPE Module] [SEMANTICS superset, package, superset-client]
-# @LAYER: Infra
+# #region SupersetClientModule [C:5] [TYPE Module] [SEMANTICS superset, package, superset-client]
+# @LAYER: Service
 # @BRIEF Предоставляет высокоуровневый клиент для взаимодействия с Superset REST API, инкапсулируя логику запросов, обработку ошибок и пагинацию.
 # @RELATION DEPENDS_ON -> [ConfigModels]
 # @RELATION DEPENDS_ON -> [APIClient]
@@ -15,6 +15,10 @@
 # preserves the original public API surface — all consumers continue to import
 # `from src.core.superset_client import SupersetClient` without changes.
 # @REJECTED: Keeping a single 2145-line file — violates fractal limit INV_7.
+# @PRE: Superset instance URL and credentials configured
+# @POST: SupersetClient class exported
+# @SIDE_EFFECT: Establishes HTTP connection pool to Superset
+# @DATA_CONTRACT: SupersetConfig -> SupersetClient
 
 from ._base import SupersetClientBase
 from ._charts import SupersetChartsMixin

backend/src/core/superset_profile_lookup.py

@@ -1,12 +1,14 @@
-# #region SupersetProfileLookup [C:3] [TYPE Module] [SEMANTICS superset, profile, account, lookup, adapter]
+# #region SupersetProfileLookup [C:5] [TYPE Module] [SEMANTICS superset, profile, account, lookup, adapter]
 #
 # @BRIEF Provides environment-scoped Superset account lookup adapter with stable normalized output.
-# @LAYER: Core
+# @LAYER: Service
 # @RELATION DEPENDS_ON -> [APIClient]
 # @RELATION DEPENDS_ON -> [SupersetAPIError]
 # @RELATION DEPENDS_ON -> [SupersetAccountLookupAdapter]
 #
 # @INVARIANT: Adapter never leaks raw upstream payload shape to API consumers.
+# @SIDE_EFFECT: Makes HTTP requests to Superset
+# @DATA_CONTRACT: ProfileQuery -> SupersetProfile
 import json
 from typing import Any
 

backend/src/core/task_manager/event_bus.py

@@ -17,6 +17,7 @@
 #              into subscriber queues, runs background flusher thread.
 # @INVARIANT Buffered logs are retried on persistence failure; every subscriber receives only
 #            task-scoped events.
+# @DATA_CONTRACT Input: LogEntry -> Output: persisted log + subscriber notification
 
 import asyncio
 import threading

backend/src/core/task_manager/models.py

@@ -1,10 +1,14 @@
-# #region TaskManagerModels [C:3] [TYPE Module] [SEMANTICS pydantic, task, model, validate, task-status]
+# #region TaskManagerModels [C:5] [TYPE Module] [SEMANTICS pydantic, task, model, validate, task-status]
 # @BRIEF Defines the data models and enumerations used by the Task Manager.
-# @LAYER: Core
+# @LAYER: Domain
 # @RELATION USED_BY -> [TaskManager]
 # @RELATION USED_BY -> [TaskManagerPackage]
 # @INVARIANT: Task IDs are immutable once created.
 # @CONSTRAINT: Must use Pydantic for data validation.
+# @PRE: Task manager initialized
+# @POST: Task models exported with immutable IDs
+# @SIDE_EFFECT: Defines task data schema
+# @DATA_CONTRACT: TaskInput -> TaskModel
 import uuid
 from datetime import datetime
 from enum import Enum

backend/src/models/assistant.py

@@ -3,6 +3,8 @@
 # @LAYER: Domain
 # @RELATION DEPENDS_ON -> MappingModels
 # @INVARIANT: Assistant records preserve immutable ids and creation timestamps.
+# @SIDE_EFFECT: Defines assistant audit/message/confirmation tables
+# @DATA_CONTRACT: AssistantData -> AssistantRecord
 
 from datetime import datetime
 

backend/src/models/auth.py

@@ -1,9 +1,13 @@
-# #region AuthModels [C:3] [TYPE Module] [SEMANTICS sqlalchemy, auth, model, schema, user]
+# #region AuthModels [C:5] [TYPE Module] [SEMANTICS sqlalchemy, auth, model, schema, user]
 # @BRIEF SQLAlchemy models for multi-user authentication and authorization.
-# @LAYER:     Domain
+# @LAYER: Domain
 # @RELATION INHERITS_FROM -> [Base]
 #
 # @INVARIANT: Usernames and emails must be unique.
+# @PRE: Database engine initialized
+# @POST: Auth ORM models registered with unique constraints
+# @SIDE_EFFECT: Defines auth user tables
+# @DATA_CONTRACT: UserData -> UserRecord
 
 import uuid
 from datetime import datetime

backend/src/models/dataset_review_pkg/_clarification_models.py

@@ -4,6 +4,10 @@
 # @RELATION DEPENDS_ON -> [DatasetReviewEnums:Module]
 # @RELATION DEPENDS_ON -> [MappingModels]
 # @INVARIANT: Only one active clarification question may exist at a time per session.
+# @PRE: Database engine initialized
+# @POST: Clarification ORM models registered
+# @SIDE_EFFECT: Defines dataset review clarification tables
+# @DATA_CONTRACT: ClarificationData -> ClarificationRecord
 
 import uuid
 from datetime import datetime

backend/src/models/dataset_review_pkg/_semantic_models.py

@@ -4,6 +4,10 @@
 # @RELATION DEPENDS_ON -> [DatasetReviewEnums:Module]
 # @RELATION DEPENDS_ON -> [MappingModels]
 # @INVARIANT: Manual overrides are never silently replaced by imported, inferred, or AI-generated values.
+# @PRE: Database engine initialized
+# @POST: Semantic ORM models registered with override protection
+# @SIDE_EFFECT: Defines dataset review semantic tables
+# @DATA_CONTRACT: SemanticData -> SemanticFieldEntry
 
 import uuid
 from datetime import datetime

backend/src/models/dataset_review_pkg/_session_models.py

@@ -4,6 +4,10 @@
 # @RELATION DEPENDS_ON -> [DatasetReviewEnums:Module]
 # @RELATION DEPENDS_ON -> [MappingModels]
 # @INVARIANT: Session and profile entities are strictly scoped to an authenticated user.
+# @PRE: Database engine initialized
+# @POST: Session ORM models registered with optimistic locking
+# @SIDE_EFFECT: Defines dataset review session tables
+# @DATA_CONTRACT: SessionData -> SessionRecord
 
 import uuid
 from datetime import datetime

backend/src/models/mapping.py

@@ -1,12 +1,16 @@
-# #region MappingModels [C:3] [TYPE Module] [SEMANTICS sqlalchemy, mapping, model, schema, resource-type]
+# #region MappingModels [C:5] [TYPE Module] [SEMANTICS sqlalchemy, mapping, model, schema, resource-type]
 #
 # @BRIEF Defines the database schema for environment metadata and database mappings using SQLAlchemy.
-# @LAYER:     Domain
+# @LAYER: Domain
 # @RELATION DEPENDS_ON -> sqlalchemy
 
 #
 # @INVARIANT: All primary keys are UUID strings.
 # @CONSTRAINT: source_env_id and target_env_id must be valid environment IDs.
+# @PRE: Database engine initialized
+# @POST: Mapping ORM models registered with UUID primary keys
+# @SIDE_EFFECT: Defines environment/database/resource mapping tables
+# @DATA_CONTRACT: MappingData -> MappingRecord
 
 import enum
 import uuid

backend/src/models/profile.py

@@ -1,12 +1,16 @@
-# #region ProfileModels [C:3] [TYPE Module] [SEMANTICS sqlalchemy, profile, model, schema, git, dashboard]
+# #region ProfileModels [C:5] [TYPE Module] [SEMANTICS sqlalchemy, profile, model, schema, git, dashboard]
 #
 # @BRIEF Defines persistent per-user profile settings for dashboard filter, Git identity/token, and UX preferences.
-# @LAYER:     Domain
+# @LAYER: Domain
 # @RELATION DEPENDS_ON -> [AuthModels]
 # @RELATION INHERITS_FROM -> [MappingModels:Base]
 #
 # @INVARIANT: Exactly one preference row exists per user_id.
 # @INVARIANT: Sensitive Git token is stored encrypted and never returned in plaintext.
+# @PRE: Database engine initialized
+# @POST: Profile ORM models registered
+# @SIDE_EFFECT: Defines user profile/preference tables
+# @DATA_CONTRACT: ProfileData -> PreferenceRecord
 
 import uuid
 from datetime import datetime

backend/src/plugins/llm_analysis/plugin.py

@@ -1,12 +1,13 @@
-# #region LLMAnalysisPlugin [C:3] [TYPE Module] [SEMANTICS llm, analysis, dashboard, validation, documentation]
+# #region LLMAnalysisPlugin [C:5] [TYPE Module] [SEMANTICS llm, analysis, dashboard, validation, documentation]
 # @BRIEF Implements DashboardValidationPlugin and DocumentationPlugin.
-# @LAYER: Domain
+# @LAYER: Plugin
 # @RELATION INHERITS -> [PluginBase]
 # @RELATION CALLS -> [ScreenshotService]
 # @RELATION CALLS -> [LLMClient]
 # @RELATION CALLS -> [LLMProviderService]
 # @RELATION USES -> TaskContext
 # @INVARIANT: All LLM interactions must be executed as asynchronous tasks.
+# @DATA_CONTRACT: AnalysisRequest -> AnalysisResult
 
 import json
 import os

backend/src/plugins/llm_analysis/service.py

@@ -1,10 +1,11 @@
-# #region LLMAnalysisService [C:3] [TYPE Module] [SEMANTICS llm, screenshot, playwright, openai, tenacity]
+# #region LLMAnalysisService [C:5] [TYPE Module] [SEMANTICS llm, screenshot, playwright, openai, tenacity]
 # @BRIEF Services for LLM interaction and dashboard screenshots.
-# @LAYER: Domain
+# @LAYER: Plugin
 # @RELATION DEPENDS_ON -> playwright
 # @RELATION DEPENDS_ON -> openai
 # @RELATION DEPENDS_ON -> tenacity
 # @INVARIANT: Screenshots must be 1920px width and capture full page height.
+# @DATA_CONTRACT: DashboardSpec -> Screenshot + Analysis
 
 import asyncio
 import base64

backend/src/plugins/translate/__tests__/test_dictionary_crud.py

@@ -215,4 +215,4 @@ class TestDictionaryEntryCRUD:
         entries, total = DictionaryManager.list_entries(db_session, d.id)
         assert total == 2
     # endregion test_same_term_different_language_pair
-# #endregion TestDictionaryCrud
+# #endregion TestDictionaryCRUD

backend/src/plugins/translate/__tests__/test_inline_correction.py

@@ -1,7 +1,7 @@
 # region InlineCorrectionTests [TYPE Module]
 # @SEMANTICS: test, translate, correction, inline, bulk
 # @PURPOSE: Tests for inline correction (T109-T116, T117): single correction, dictionary submission, bulk replace.
-# @LAYER: Test
+# @LAYER: Domain
 # @RELATION: BINDS_TO -> [InlineCorrectionService:Module]
 # @RELATION: BINDS_TO -> [BulkFindReplaceService:Module]
 # @TEST_CONTRACT: InlineCorrectionService -> submit_correction, duplicate detection

backend/src/plugins/translate/__tests__/test_token_budget.py

@@ -192,4 +192,4 @@ class TestTokenBudget:
     # endregion test_no_target_languages_defaults_to_en
 
 # endregion TestTokenBudget
-# endregion TestTokenBudget
+# #endregion TestTokenBudget

backend/src/schemas/auth.py

@@ -1,10 +1,11 @@
-# #region AuthSchemas [C:3] [TYPE Module] [SEMANTICS pydantic, auth, schema, token]
+# #region AuthSchemas [C:5] [TYPE Module] [SEMANTICS pydantic, auth, schema, token]
 #
 # @BRIEF Pydantic schemas for authentication requests and responses.
-# @LAYER:     API
+# @LAYER: API
 # @RELATION DEPENDS_ON -> pydantic
 #
 # @INVARIANT: Sensitive fields like password must not be included in response schemas.
+# @DATA_CONTRACT: AuthPayload -> AuthSchema
 
 from datetime import datetime
 

backend/src/schemas/profile.py

@@ -1,10 +1,11 @@
-# #region ProfileSchemas [C:3] [TYPE Module] [SEMANTICS pydantic, profile, schema, superset, profile-permission-state]
+# #region ProfileSchemas [C:5] [TYPE Module] [SEMANTICS pydantic, profile, schema, superset, profile-permission-state]
 #
 # @BRIEF Defines API schemas for profile preference persistence, security read-only snapshot, and Superset account lookup.
-# @LAYER:     API
+# @LAYER: API
 # @RELATION DEPENDS_ON -> pydantic
 #
 # @INVARIANT: Schema shapes stay stable for profile UI states and backend preference contracts.
+# @DATA_CONTRACT: ProfilePayload -> ProfileSchema
 
 from datetime import datetime
 from typing import Literal

backend/src/scripts/clean_release_tui.py

@@ -4,6 +4,7 @@
 # @RELATION DEPENDS_ON -> [ComplianceExecutionService]
 # @RELATION DEPENDS_ON -> [CleanReleaseRepository]
 # @INVARIANT: TUI refuses startup in non-TTY environments; headless flow is CLI/API only.
+# @DATA_CONTRACT: CLIArgs -> TUIExitCode
 import contextlib
 import curses
 import json

backend/src/scripts/create_admin.py

@@ -1,12 +1,14 @@
-# #region CreateAdminScript [C:3] [TYPE Module] [SEMANTICS admin, search, user, cli]
+# #region CreateAdminScript [C:5] [TYPE Module] [SEMANTICS admin, search, user, cli]
 #
 # @BRIEF CLI tool for creating the initial admin user.
-# @LAYER:     Scripts
+# @LAYER: Infrastructure
 # @RELATION USES -> [AuthSecurityModule]
 # @RELATION USES -> [DatabaseModule]
 # @RELATION USES -> [AuthModels]
 #
 # @INVARIANT: Admin user must have the "Admin" role.
+# @SIDE_EFFECT: Writes admin user to database
+# @DATA_CONTRACT: CLIArgs -> AdminUser
 
 import argparse
 import sys

backend/src/scripts/seed_permissions.py

@@ -1,13 +1,15 @@
-# #region SeedPermissionsScript [C:3] [TYPE Module] [SEMANTICS rbac, search, auth]
+# #region SeedPermissionsScript [C:5] [TYPE Module] [SEMANTICS rbac, search, auth]
 #
 # @BRIEF Populates the auth database with initial system permissions.
-# @LAYER:     Scripts
+# @LAYER: Infrastructure
 # @RELATION DEPENDS_ON -> AuthSessionLocal
 # @RELATION DEPENDS_ON -> Permission
 # @RELATION DEPENDS_ON -> Role
 # @RELATION DEPENDS_ON -> AuthRepository
 #
 # @INVARIANT: Safe to run multiple times (idempotent).
+# @SIDE_EFFECT: Writes permissions to database
+# @DATA_CONTRACT: CLIArgs -> SeedSummary
 
 import sys
 from pathlib import Path

backend/src/scripts/seed_superset_load_test.py

@@ -1,10 +1,11 @@
-# #region SeedSupersetLoadTestScript [C:3] [TYPE Module] [SEMANTICS superset, validate]
+# #region SeedSupersetLoadTestScript [C:5] [TYPE Module] [SEMANTICS superset, validate]
 #
 # @BRIEF Creates randomized load-test data in Superset by cloning chart configurations and creating dashboards in target environments.
-# @LAYER: Scripts
+# @LAYER: Infrastructure
 # @RELATION USES -> [ConfigManager]
 # @RELATION USES -> [SupersetClient]
 # @INVARIANT: Created chart and dashboard names are globally unique for one script run.
+# @DATA_CONTRACT: CLIArgs -> TestDataSummary
 
 import argparse
 import json

backend/src/services/clean_release/approval_service.py

@@ -5,6 +5,10 @@
 # @RELATION DEPENDS_ON -> [CleanReleaseModels]
 # @RELATION DEPENDS_ON -> [AuditService]
 # @INVARIANT: Approval is allowed only for PASSED report bound to candidate; decisions are append-only.
+# @PRE: Report with PASSED final_status exists for candidate
+# @POST: Approval decision appended; candidate lifecycle advanced
+# @SIDE_EFFECT: Persists approval decisions, transitions candidate status
+# @DATA_CONTRACT: ApprovalRequest -> ApprovalDecision
 
 from __future__ import annotations
 
@@ -207,4 +211,4 @@ def reject_candidate(
 
 # #endregion reject_candidate
 
-# #endregion backend.src.services.clean_release.approval_service
+# #endregion ApprovalService

backend/src/services/clean_release/artifact_catalog_loader.py

@@ -1,8 +1,10 @@
-# #region ArtifactCatalogLoader [C:3] [TYPE Module] [SEMANTICS pydantic, clean-release, artifact, catalog, manifest]
+# #region ArtifactCatalogLoader [C:5] [TYPE Module] [SEMANTICS pydantic, clean-release, artifact, catalog, manifest]
 # @BRIEF Load bootstrap artifact catalogs for clean release real-mode flows.
 # @LAYER: Domain
 # @RELATION DEPENDS_ON -> [CleanReleaseModels]
 # @INVARIANT: Artifact catalog must produce deterministic CandidateArtifact entries with required identity and checksum fields.
+# @SIDE_EFFECT: Reads JSON file from filesystem
+# @DATA_CONTRACT: FilePath -> CandidateArtifact[]
 
 from __future__ import annotations
 
@@ -101,4 +103,4 @@ def load_bootstrap_artifacts(path: str, candidate_id: str) -> list[CandidateArti
 
 # #endregion load_bootstrap_artifacts
 
-# #endregion backend.src.services.clean_release.artifact_catalog_loader
+# #endregion ArtifactCatalogLoader

backend/src/services/clean_release/audit_service.py

@@ -1,8 +1,12 @@
 # #region AuditService [C:3] [TYPE Module] [SEMANTICS clean-release, audit, report, trail, release]
 # @BRIEF Provide lightweight audit hooks for clean release preparation/check/report lifecycle.
-# @LAYER: Infra
+# @LAYER: Infrastructure
 # @RELATION DEPENDS_ON -> [LoggerModule]
 # @INVARIANT: Audit hooks are append-only log actions.
+# @PRE: Logger configured
+# @POST: Audit events appended to log
+# @SIDE_EFFECT: Writes audit events to logger and repository
+# @DATA_CONTRACT: AuditAction -> LogEntry
 
 from __future__ import annotations
 
@@ -114,4 +118,4 @@ def audit_report(
     )
 
 
-# #endregion backend.src.services.clean_release.audit_service
+# #endregion AuditService

backend/src/services/clean_release/candidate_service.py

@@ -103,4 +103,4 @@ def register_candidate(
     return candidate
 # #endregion register_candidate
 
-# #endregion backend.src.services.clean_release.candidate_service
+# #endregion candidate_service

backend/src/services/clean_release/demo_data_service.py

@@ -1,8 +1,10 @@
-# #region DemoDataService [C:3] [TYPE Module] [SEMANTICS clean-release, demo, seed, fixture]
+# #region DemoDataService [C:5] [TYPE Module] [SEMANTICS clean-release, demo, seed, fixture]
 # @BRIEF Provide deterministic namespace helpers and isolated in-memory repository creation for demo and real modes.
 # @LAYER: Domain
 # @RELATION DEPENDS_ON -> [RepositoryRelations]
 # @INVARIANT: Demo and real namespaces must never collide for generated physical identifiers.
+# @SIDE_EFFECT: Writes demo entities to repository
+# @DATA_CONTRACT: SeedConfig -> DemoEntities
 
 from __future__ import annotations
 

backend/src/services/clean_release/manifest_builder.py

@@ -1,8 +1,10 @@
-# #region ManifestBuilder [C:3] [TYPE Module] [SEMANTICS clean-release, manifest, build, artifact, catalog]
+# #region ManifestBuilder [C:5] [TYPE Module] [SEMANTICS clean-release, manifest, build, artifact, catalog]
 # @BRIEF Build deterministic distribution manifest from classified artifact input.
 # @LAYER: Domain
 # @RELATION DEPENDS_ON -> [CleanReleaseModels]
 # @INVARIANT: Equal semantic artifact sets produce identical deterministic hash values.
+# @SIDE_EFFECT: Computes hash of artifact set
+# @DATA_CONTRACT: ArtifactSet -> Manifest
 
 from __future__ import annotations
 

backend/src/services/clean_release/preparation_service.py

@@ -1,10 +1,12 @@
-# #region PreparationService [C:3] [TYPE Module] [SEMANTICS clean-release, prepare, validate, policy, manifest]
+# #region PreparationService [C:5] [TYPE Module] [SEMANTICS clean-release, prepare, validate, policy, manifest]
 # @BRIEF Prepare release candidate by policy evaluation and deterministic manifest creation.
 # @LAYER: Domain
 # @RELATION DEPENDS_ON -> [PolicyEngine]
 # @RELATION DEPENDS_ON -> [ManifestBuilder]
 # @RELATION DEPENDS_ON -> [RepositoryRelations]
 # @INVARIANT: Candidate preparation always persists manifest and candidate status deterministically.
+# @SIDE_EFFECT: Persists candidate and manifest
+# @DATA_CONTRACT: PrepareRequest -> PrepareResult
 
 from __future__ import annotations
 

backend/src/services/clean_release/publication_service.py

@@ -209,4 +209,4 @@ def revoke_publication(
 
 # #endregion revoke_publication
 
-# #endregion backend.src.services.clean_release.publication_service
+# #endregion PublicationService

backend/src/services/clean_release/repository.py

@@ -1,8 +1,12 @@
-# #region RepositoryRelations [C:3] [TYPE Module] [SEMANTICS pydantic, clean-release, repository, relations, release]
+# #region RepositoryRelations [C:5] [TYPE Module] [SEMANTICS pydantic, clean-release, repository, relations, release]
 # @BRIEF Provide repository adapter for clean release entities with deterministic access methods.
-# @LAYER: Infra
+# @LAYER: Infrastructure
 # @RELATION DEPENDS_ON -> [CleanReleaseModels]
 # @INVARIANT: Repository operations are side-effect free outside explicit save/update calls.
+# @PRE: In-memory storage initialized
+# @POST: Repository operations exported
+# @SIDE_EFFECT: Modifies in-memory state on save/update
+# @DATA_CONTRACT: Entity -> RepositoryOperation
 
 from __future__ import annotations
 

backend/src/services/clean_release/source_isolation.py

@@ -1,8 +1,12 @@
-# #region SourceIsolation [C:3] [TYPE Module] [SEMANTICS clean-release, source, isolation, validate, resource]
+# #region SourceIsolation [C:5] [TYPE Module] [SEMANTICS clean-release, source, isolation, validate, resource]
 # @BRIEF Validate that all resource endpoints belong to the approved internal source registry.
 # @LAYER: Domain
 # @RELATION DEPENDS_ON -> [CleanReleaseModels]
 # @INVARIANT: Any endpoint outside enabled registry entries is treated as external-source violation.
+# @PRE: Source registry configured
+# @POST: Source isolation violations identified
+# @SIDE_EFFECT: None (read-only check)
+# @DATA_CONTRACT: SourceURL -> ViolationReport
 
 from __future__ import annotations
 

backend/src/services/clean_release/stages/__init__.py

@@ -1,9 +1,11 @@
-# #region ComplianceStages [C:3] [TYPE Module] [SEMANTICS clean-release, compliance, stage, package]
+# #region ComplianceStages [C:5] [TYPE Module] [SEMANTICS clean-release, compliance, stage, package]
 # @BRIEF Define compliance stage order and helper functions for deterministic run-state evaluation.
 # @LAYER: Domain
 # @RELATION DEPENDS_ON -> [CleanReleaseModels]
 # @RELATION DEPENDS_ON -> [ComplianceStageBase]
 # @INVARIANT: Stage order remains deterministic for all compliance runs.
+# @SIDE_EFFECT: Registers compliance stages
+# @DATA_CONTRACT: StagePipeline -> ComplianceResult
 
 from __future__ import annotations
 

backend/src/services/clean_release/stages/base.py

@@ -1,9 +1,11 @@
-# #region ComplianceStageBase [C:3] [TYPE Module] [SEMANTICS pydantic, clean-release, stage, compliance, context]
+# #region ComplianceStageBase [C:5] [TYPE Module] [SEMANTICS pydantic, clean-release, stage, compliance, context]
 # @BRIEF Define shared contracts and helpers for pluggable clean-release compliance stages.
 # @LAYER: Domain
 # @RELATION DEPENDS_ON -> [CleanReleaseModels]
 # @RELATION DEPENDS_ON -> [LoggerModule]
 # @INVARIANT: Stage execution is deterministic for equal input context.
+# @SIDE_EFFECT: None (deterministic execution)
+# @DATA_CONTRACT: Context -> StageResult
 
 from __future__ import annotations
 

backend/src/services/clean_release/stages/data_purity.py

@@ -1,9 +1,11 @@
-# #region data_purity [C:3] [TYPE Module] [SEMANTICS clean-release, data, purity, validate, manifest]
+# #region data_purity [C:5] [TYPE Module] [SEMANTICS clean-release, data, purity, validate, manifest]
 # @BRIEF Evaluate manifest purity counters and emit blocking violations for prohibited artifacts.
 # @LAYER: Domain
 # @RELATION IMPLEMENTS -> [ComplianceStage]
 # @RELATION DEPENDS_ON -> [ComplianceStageBase]
 # @INVARIANT: prohibited_detected_count > 0 always yields BLOCKED stage decision.
+# @SIDE_EFFECT: None (read-only validation)
+# @DATA_CONTRACT: Manifest -> DataPurityVerdict
 
 from __future__ import annotations
 

backend/src/services/clean_release/stages/internal_sources_only.py

@@ -1,9 +1,11 @@
-# #region internal_sources_only [C:3] [TYPE Module] [SEMANTICS clean-release, internal, source, validate]
+# #region internal_sources_only [C:5] [TYPE Module] [SEMANTICS clean-release, internal, source, validate]
 # @BRIEF Verify manifest-declared sources belong to trusted internal registry allowlist.
 # @LAYER: Domain
 # @RELATION IMPLEMENTS -> [ComplianceStage]
 # @RELATION DEPENDS_ON -> [ComplianceStageBase]
 # @INVARIANT: Any source host outside allowed_hosts yields BLOCKED decision with at least one violation.
+# @SIDE_EFFECT: None (read-only validation)
+# @DATA_CONTRACT: Sources -> SourceViolationReport
 
 from __future__ import annotations
 

backend/src/services/clean_release/stages/manifest_consistency.py

@@ -1,9 +1,11 @@
-# #region manifest_consistency [C:3] [TYPE Module] [SEMANTICS clean-release, manifest, consistency, validate]
+# #region manifest_consistency [C:5] [TYPE Module] [SEMANTICS clean-release, manifest, consistency, validate]
 # @BRIEF Ensure run is bound to the exact manifest snapshot and digest used at run creation time.
 # @LAYER: Domain
 # @RELATION IMPLEMENTS -> [ComplianceStage]
 # @RELATION DEPENDS_ON -> [ComplianceStageBase]
 # @INVARIANT: Digest mismatch between run and manifest yields ERROR with blocking violation evidence.
+# @SIDE_EFFECT: None (read-only validation)
+# @DATA_CONTRACT: RunData -> ConsistencyVerdict
 
 from __future__ import annotations
 

backend/src/services/clean_release/stages/no_external_endpoints.py

@@ -1,9 +1,11 @@
-# #region no_external_endpoints [C:3] [TYPE Module] [SEMANTICS clean-release, endpoint, validate, manifest, compliance]
+# #region no_external_endpoints [C:5] [TYPE Module] [SEMANTICS clean-release, endpoint, validate, manifest, compliance]
 # @BRIEF Block manifest payloads that expose external endpoints outside trusted schemes and hosts.
 # @LAYER: Domain
 # @RELATION IMPLEMENTS -> [ComplianceStage]
 # @RELATION DEPENDS_ON -> [ComplianceStageBase]
 # @INVARIANT: Endpoint outside allowed scheme/host always yields BLOCKED stage decision.
+# @SIDE_EFFECT: None (read-only validation)
+# @DATA_CONTRACT: Endpoints -> EndpointViolationReport
 
 from __future__ import annotations
 

backend/src/services/git/_remote_providers.py

@@ -50,47 +50,8 @@ class GitServiceGithubMixin:
                 pass
             raise HTTPException(status_code=response.status_code, detail=f"GitHub API error: {detail}")
         return response.json()
-    # endregion create_github_repository
-
-    # region create_github_pull_request [TYPE Function]
-    # @PURPOSE: Create pull request in GitHub or GitHub Enterprise.
-    # @PRE: Config and remote URL are valid.
-    # @POST: Returns normalized PR metadata.
-    # @RETURN: Dict[str, Any]
-    async def create_github_pull_request(
-        self, server_url: str, pat: str, remote_url: str, from_branch: str, to_branch: str,
-        title: str, description: str | None = None, draft: bool = False,
-    ) -> dict[str, Any]:
-        identity = self._parse_remote_repo_identity(remote_url)
-        base_url = self._normalize_git_server_url(server_url)
-        if "github.com" in base_url:
-            api_url = f"https://api.github.com/repos/{identity['namespace']}/{identity['repo']}/pulls"
-        else:
-            api_url = f"{base_url}/api/v3/repos/{identity['namespace']}/{identity['repo']}/pulls"
-        headers = {
-            "Authorization": f"token {pat.strip()}",
-            "Content-Type": "application/json",
-            "Accept": "application/vnd.github+json",
-        }
-        payload = {
-            "title": title, "head": from_branch, "base": to_branch,
-            "body": description or "", "draft": bool(draft),
-        }
-        try:
-            response = await self._http_client.post(api_url, headers=headers, json=payload)
-        except Exception as e:
-            raise HTTPException(status_code=503, detail=f"GitHub API is unavailable: {e!s}")
-        if response.status_code >= 400:
-            detail = response.text
-            try:
-                detail = response.json().get("message") or detail
-            except Exception:
-                pass
-            raise HTTPException(status_code=response.status_code, detail=f"GitHub API error: {detail}")
-        data = response.json()
-        return {"id": data.get("number") or data.get("id"), "url": data.get("html_url") or data.get("url"), "status": data.get("state") or "open"}
     # endregion create_github_pull_request
-
+# #endregion GitServiceGithubMixin
 
 # #region GitServiceGitlabMixin [C:3] [TYPE Class]
 # @BRIEF Mixin providing GitLab API operations for GitService.
@@ -176,4 +137,3 @@ class GitServiceGitlabMixin:
     # endregion create_gitlab_merge_request
 # #endregion GitServiceGitlabMixin
 # #endregion GitServiceRemoteMixin
-# #endregion GitServiceRemoteMixin

backend/src/services/mapping_service.py

@@ -1,7 +1,7 @@
-# #region mapping_service [C:3] [TYPE Module] [SEMANTICS mapping, database, superset, fuzzy, suggestion]
+# #region mapping_service [C:5] [TYPE Module] [SEMANTICS mapping, database, superset, fuzzy, suggestion]
 #
 # @BRIEF Orchestrates database fetching and fuzzy matching suggestions.
-# @LAYER:     Service
+# @LAYER: Service
 # @PRE: source/target environment identifiers are provided by caller.
 # @POST: Exposes stateless mapping suggestion orchestration over configured environments.
 # @SIDE_EFFECT: Performs remote metadata reads through Superset API clients.

backend/src/services/reports/__tests__/test_report_normalizer.py

@@ -2,7 +2,7 @@
 # @SEMANTICS: tests, reports, normalizer, fallback
 # @PURPOSE: Validate unknown task type fallback and partial payload normalization behavior.
 # @RELATION: TESTS ->[normalize_report:Function]
-# @LAYER: Domain (Tests)
+# @LAYER: Domain
 # @INVARIANT: Unknown plugin types are mapped to canonical unknown task type.
 
 from datetime import datetime

backend/src/services/resource_service.py

@@ -1,11 +1,13 @@
-# #region ResourceServiceModule [C:3] [TYPE Module] [SEMANTICS resource, git, task, status, superset]
+# #region ResourceServiceModule [C:5] [TYPE Module] [SEMANTICS resource, git, task, status, superset]
 # @BRIEF Shared service for fetching resource data with Git status and task status
-# @LAYER:     Service
+# @LAYER: Service
 # @RELATION DEPENDS_ON -> [SupersetClient]
 # @RELATION DEPENDS_ON -> [TaskManagerPackage]
 # @RELATION DEPENDS_ON -> [TaskManagerModels]
 # @RELATION DEPENDS_ON -> [GitService]
 # @INVARIANT: All resources include metadata about their current state
+# @SIDE_EFFECT: Queries multiple backends for status
+# @DATA_CONTRACT: ResourceQuery -> ResourceStatusSummary
 
 from datetime import UTC, datetime
 from typing import Any