refactor(semantics): migrate legacy @TIER to @COMPLEXITY annotations

- Replaced @TIER: TRIVIAL with @COMPLEXITY: 1
- Replaced @TIER: STANDARD with @COMPLEXITY: 3
- Replaced @TIER: CRITICAL with @COMPLEXITY: 5
- Manually elevated specific critical/complex components to levels 2 and 4
- Ignored legacy, specs, and node_modules directories
- Updated generated semantic map

backend/src/core/utils/async_network.py

@@ -1,9 +1,13 @@
 # [DEF:backend.src.core.utils.async_network:Module]
 #
-# @TIER: CRITICAL
+# @COMPLEXITY: 5
 # @SEMANTICS: network, httpx, async, superset, authentication, cache
 # @PURPOSE: Provides async Superset API client with shared auth-token cache to avoid per-request re-login.
 # @LAYER: Infra
+# @PRE: Config payloads contain a Superset base URL and authentication fields needed for login.
+# @POST: Async network clients reuse cached auth tokens and expose stable async request/error translation flow.
+# @SIDE_EFFECT: Performs upstream HTTP I/O and mutates process-local auth cache entries.
+# @DATA_CONTRACT: Input[config: Dict[str, Any]] -> Output[authenticated async Superset HTTP interactions]
 # @RELATION: DEPENDS_ON -> backend.src.core.utils.network.SupersetAuthCache
 # @INVARIANT: Async client reuses cached auth tokens per environment credentials and invalidates on 401.
 
@@ -25,8 +29,8 @@ from .network import (
 # [/SECTION]
 
 
-# [DEF:AsyncAPIClient:Class]
-# @TIER: STANDARD
+# [DEF:backend.src.core.utils.async_network.AsyncAPIClient:Class]
+# @COMPLEXITY: 3
 # @PURPOSE: Async Superset API client backed by httpx.AsyncClient with shared auth cache.
 # @RELATION: [DEPENDS_ON] ->[backend.src.core.utils.network.SupersetAuthCache]
 # @RELATION: [CALLS] ->[backend.src.core.utils.network.SupersetAuthCache.get]
@@ -35,8 +39,8 @@ class AsyncAPIClient:
     DEFAULT_TIMEOUT = 30
     _auth_locks: Dict[tuple[str, str, bool], asyncio.Lock] = {}
 
-    # [DEF:__init__:Function]
-    # @TIER: STANDARD
+    # [DEF:backend.src.core.utils.async_network.AsyncAPIClient.__init__:Function]
+    # @COMPLEXITY: 3
     # @PURPOSE: Initialize async API client for one environment.
     # @PRE: config contains base_url and auth payload.
     # @POST: Client is ready for async request/authentication flow.
@@ -61,8 +65,8 @@ class AsyncAPIClient:
 
     # [/DEF:__init__:Function]
 
-    # [DEF:_normalize_base_url:Function]
-    # @TIER: TRIVIAL
+    # [DEF:backend.src.core.utils.async_network.AsyncAPIClient._normalize_base_url:Function]
+    # @COMPLEXITY: 1
     # @PURPOSE: Normalize base URL for Superset API root construction.
     # @POST: Returns canonical base URL without trailing slash and duplicate /api/v1 suffix.
     def _normalize_base_url(self, raw_url: str) -> str:
@@ -73,7 +77,7 @@ class AsyncAPIClient:
     # [/DEF:_normalize_base_url:Function]
 
     # [DEF:_build_api_url:Function]
-    # @TIER: TRIVIAL
+    # @COMPLEXITY: 1
     # @PURPOSE: Build full API URL from relative Superset endpoint.
     # @POST: Returns absolute URL for upstream request.
     def _build_api_url(self, endpoint: str) -> str:
@@ -88,7 +92,7 @@ class AsyncAPIClient:
     # [/DEF:_build_api_url:Function]
 
     # [DEF:_get_auth_lock:Function]
-    # @TIER: TRIVIAL
+    # @COMPLEXITY: 1
     # @PURPOSE: Return per-cache-key async lock to serialize fresh login attempts.
     # @POST: Returns stable asyncio.Lock instance.
     @classmethod
@@ -102,7 +106,7 @@ class AsyncAPIClient:
     # [/DEF:_get_auth_lock:Function]
 
     # [DEF:authenticate:Function]
-    # @TIER: STANDARD
+    # @COMPLEXITY: 3
     # @PURPOSE: Authenticate against Superset and cache access/csrf tokens.
     # @POST: Client tokens are populated and reusable across requests.
     # @SIDE_EFFECT: Performs network requests to Superset authentication endpoints.
@@ -162,7 +166,7 @@ class AsyncAPIClient:
     # [/DEF:authenticate:Function]
 
     # [DEF:get_headers:Function]
-    # @TIER: STANDARD
+    # @COMPLEXITY: 3
     # @PURPOSE: Return authenticated Superset headers for async requests.
     # @POST: Headers include Authorization and CSRF tokens.
     # @RELATION: CALLS -> self.authenticate
@@ -178,7 +182,7 @@ class AsyncAPIClient:
     # [/DEF:get_headers:Function]
 
     # [DEF:request:Function]
-    # @TIER: STANDARD
+    # @COMPLEXITY: 3
     # @PURPOSE: Perform one authenticated async Superset API request.
     # @POST: Returns JSON payload or raw httpx.Response when raw_response=true.
     # @SIDE_EFFECT: Performs network I/O.
@@ -215,7 +219,7 @@ class AsyncAPIClient:
     # [/DEF:request:Function]
 
     # [DEF:_handle_http_error:Function]
-    # @TIER: STANDARD
+    # @COMPLEXITY: 3
     # @PURPOSE: Translate upstream HTTP errors into stable domain exceptions.
     # @POST: Raises domain-specific exception for caller flow control.
     # @DATA_CONTRACT: Input[httpx.HTTPStatusError] -> Exception
@@ -234,7 +238,7 @@ class AsyncAPIClient:
     # [/DEF:_handle_http_error:Function]
 
     # [DEF:_handle_network_error:Function]
-    # @TIER: STANDARD
+    # @COMPLEXITY: 3
     # @PURPOSE: Translate generic httpx errors into NetworkError.
     # @POST: Raises NetworkError with URL context.
     # @DATA_CONTRACT: Input[httpx.HTTPError] -> NetworkError
@@ -250,7 +254,7 @@ class AsyncAPIClient:
     # [/DEF:_handle_network_error:Function]
 
     # [DEF:aclose:Function]
-    # @TIER: STANDARD
+    # @COMPLEXITY: 3
     # @PURPOSE: Close underlying httpx client.
     # @POST: Client resources are released.
     # @SIDE_EFFECT: Closes network connections.

backend/src/core/utils/network.py

@@ -1,5 +1,6 @@
-# [DEF:backend.core.utils.network:Module]
+# [DEF:network:Module]
 #
+# @COMPLEXITY: 3
 # @SEMANTICS: network, http, client, api, requests, session, authentication
 # @PURPOSE: Инкапсулирует низкоуровневую HTTP-логику для взаимодействия с Superset API, включая аутентификацию, управление сессией, retry-логику и обработку ошибок.
 # @LAYER: Infra
@@ -22,9 +23,11 @@ from ..logger import logger as app_logger, belief_scope
 # [/SECTION]
 
 # [DEF:SupersetAPIError:Class]
+# @COMPLEXITY: 1
 # @PURPOSE: Base exception for all Superset API related errors.
 class SupersetAPIError(Exception):
     # [DEF:__init__:Function]
+    # @COMPLEXITY: 1
     # @PURPOSE: Initializes the exception with a message and context.
     # @PRE: message is a string, context is a dict.
     # @POST: Exception is initialized with context.
@@ -36,9 +39,11 @@ class SupersetAPIError(Exception):
 # [/DEF:SupersetAPIError:Class]
 
 # [DEF:AuthenticationError:Class]
+# @COMPLEXITY: 1
 # @PURPOSE: Exception raised when authentication fails.
 class AuthenticationError(SupersetAPIError):
     # [DEF:__init__:Function]
+    # @COMPLEXITY: 1
     # @PURPOSE: Initializes the authentication error.
     # @PRE: message is a string, context is a dict.
     # @POST: AuthenticationError is initialized.
@@ -77,7 +82,7 @@ class DashboardNotFoundError(SupersetAPIError):
 # [DEF:NetworkError:Class]
 # @PURPOSE: Exception raised when a network level error occurs.
 class NetworkError(Exception):
-    # [DEF:__init__:Function]
+    # [DEF:network.APIClient.__init__:Function]
     # @PURPOSE: Initializes the network error.
     # @PRE: message is a string.
     # @POST: NetworkError is initialized.
@@ -89,7 +94,7 @@ class NetworkError(Exception):
 # [/DEF:NetworkError:Class]
 
 
-# [DEF:SupersetAuthCache:Class]
+# [DEF:network.SupersetAuthCache:Class]
 # @PURPOSE: Process-local cache for Superset access/csrf tokens keyed by environment credentials.
 # @PRE: base_url and username are stable strings.
 # @POST: Cached entries expire automatically by TTL and can be reused across requests.
@@ -145,10 +150,10 @@ class SupersetAuthCache:
 # [/DEF:SupersetAuthCache:Class]
 
 # [DEF:APIClient:Class]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Synchronous Superset API client with process-local auth token caching.
-# @RELATION: DEPENDS_ON -> backend.src.core.utils.network.SupersetAuthCache
-# @RELATION: DEPENDS_ON -> backend.src.core.logger.logger
+# @RELATION: DEPENDS_ON -> network.SupersetAuthCache
+# @RELATION: DEPENDS_ON -> logger
 class APIClient:
     DEFAULT_TIMEOUT = 30