semantics

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