chore(semantic): checkpoint remediation progress

backend/src/core/auth/repository.py

@@ -4,6 +4,10 @@
 # @SEMANTICS: auth, repository, database, user, role, permission
 # @PURPOSE:   Data access layer for authentication and user preference entities.
 # @LAYER:     Domain
+# @PRE:       SQLAlchemy session manager and auth models are available.
+# @POST:      Provides transactional access to Auth-related database entities.
+# @SIDE_EFFECT: Performs database I/O via SQLAlchemy sessions.
+# @DATA_CONTRACT: Input[Session] -> Model[User, Role, Permission, UserDashboardPreference]
 # @RELATION:  [DEPENDS_ON] ->[sqlalchemy.orm.Session]
 # @RELATION:  [DEPENDS_ON] ->[backend.src.models.auth]
 # @RELATION:  [DEPENDS_ON] ->[backend.src.models.profile]
@@ -21,10 +25,12 @@ from ..logger import belief_scope, logger
 # [/SECTION]
 
 # [DEF:AuthRepository:Class]
+# @TIER: CRITICAL
 # @PURPOSE: Encapsulates database operations for authentication-related entities.
 # @RELATION: [DEPENDS_ON] ->[sqlalchemy.orm.Session]
 class AuthRepository:
     # [DEF:__init__:Function]
+    # @TIER: CRITICAL
     # @PURPOSE: Bind repository instance to an existing SQLAlchemy session.
     # @PRE:     db is an initialized sqlalchemy.orm.Session instance.
     # @POST:    self.db points to the provided session and is used by all repository methods.
@@ -42,6 +48,7 @@ class AuthRepository:
     # [/DEF:__init__:Function]
 
     # [DEF:get_user_by_username:Function]
+    # @TIER: CRITICAL
     # @PURPOSE: Retrieve a user entity by unique username.
     # @PRE:     username is a non-empty str and self.db is a valid open Session.
     # @POST:    Returns matching User entity when present, otherwise None.
@@ -68,6 +75,7 @@ class AuthRepository:
     # [/DEF:get_user_by_username:Function]
 
     # [DEF:get_user_by_id:Function]
+    # @TIER: CRITICAL
     # @PURPOSE: Retrieve a user entity by identifier.
     # @PRE:     user_id is a non-empty str and self.db is a valid open Session.
     # @POST:    Returns matching User entity when present, otherwise None.
@@ -89,6 +97,7 @@ class AuthRepository:
     # [/DEF:get_user_by_id:Function]
 
     # [DEF:get_role_by_name:Function]
+    # @TIER: CRITICAL
     # @PURPOSE: Retrieve a role entity by role name.
     # @PRE:     name is a non-empty str and self.db is a valid open Session.
     # @POST:    Returns matching Role entity when present, otherwise None.
@@ -100,6 +109,7 @@ class AuthRepository:
     # [/DEF:get_role_by_name:Function]
 
     # [DEF:update_last_login:Function]
+    # @TIER: CRITICAL
     # @PURPOSE: Update last_login timestamp for the provided user entity.
     # @PRE:     user is a managed User instance and self.db is a valid open Session.
     # @POST:    user.last_login is set to current UTC timestamp and transaction is committed.
@@ -119,6 +129,7 @@ class AuthRepository:
     # [/DEF:update_last_login:Function]
 
     # [DEF:get_role_by_id:Function]
+    # @TIER: CRITICAL
     # @PURPOSE: Retrieve a role entity by identifier.
     # @PRE:     role_id is a non-empty str and self.db is a valid open Session.
     # @POST:    Returns matching Role entity when present, otherwise None.
@@ -130,6 +141,7 @@ class AuthRepository:
     # [/DEF:get_role_by_id:Function]
 
     # [DEF:get_permission_by_id:Function]
+    # @TIER: CRITICAL
     # @PURPOSE: Retrieve a permission entity by identifier.
     # @PRE:     perm_id is a non-empty str and self.db is a valid open Session.
     # @POST:    Returns matching Permission entity when present, otherwise None.
@@ -141,6 +153,7 @@ class AuthRepository:
     # [/DEF:get_permission_by_id:Function]
 
     # [DEF:get_permission_by_resource_action:Function]
+    # @TIER: CRITICAL
     # @PURPOSE: Retrieve a permission entity by resource and action pair.
     # @PRE:     resource and action are non-empty str values; self.db is a valid open Session.
     # @POST:    Returns matching Permission entity when present, otherwise None.
@@ -155,6 +168,7 @@ class AuthRepository:
     # [/DEF:get_permission_by_resource_action:Function]
 
     # [DEF:get_user_dashboard_preference:Function]
+    # @TIER: CRITICAL
     # @PURPOSE: Retrieve dashboard preference entity owned by specified user.
     # @PRE:     user_id is a non-empty str and self.db is a valid open Session.
     # @POST:    Returns matching UserDashboardPreference entity when present, otherwise None.
@@ -170,6 +184,7 @@ class AuthRepository:
     # [/DEF:get_user_dashboard_preference:Function]
 
     # [DEF:save_user_dashboard_preference:Function]
+    # @TIER: CRITICAL
     # @PURPOSE: Persist dashboard preference entity and return refreshed persistent row.
     # @PRE:     preference is a valid UserDashboardPreference entity and self.db is a valid open Session.
     # @POST:    preference is committed to DB, refreshed from DB state, and returned.
@@ -192,6 +207,7 @@ class AuthRepository:
     # [/DEF:save_user_dashboard_preference:Function]
 
     # [DEF:list_permissions:Function]
+    # @TIER: CRITICAL
     # @PURPOSE: List all permission entities available in storage.
     # @PRE:     self.db is a valid open Session.
     # @POST:    Returns list containing all Permission entities visible to the session.