semantics

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