chore(semantic): checkpoint remediation progress

backend/src/services/auth_service.py

@@ -11,6 +11,10 @@
 # @RELATION:  [DEPENDS_ON] ->[backend.src.models.auth.Role]
 #
 # @INVARIANT: Authentication succeeds only for active users with valid credentials; issued sessions encode subject and scopes from assigned roles.
+# @PRE:       Core auth models and security utilities available.
+# @POST:      User identity verified and session tokens issued according to role scopes.
+# @SIDE_EFFECT: Writes last login timestamps and JIT-provisions external users.
+# @DATA_CONTRACT: [Credentials | ADFSClaims] -> [UserEntity | SessionToken]
 
 # [SECTION: IMPORTS]
 from typing import Dict, Any
@@ -23,9 +27,11 @@ from ..core.logger import belief_scope
 # [/SECTION]
 
 # [DEF:AuthService:Class]
+# @TIER: STANDARD
 # @PURPOSE: Provides high-level authentication services.
 class AuthService:
     # [DEF:__init__:Function]
+    # @TIER: TRIVIAL
     # @PURPOSE: Initializes the authentication service with repository access over an active DB session.
     # @PRE: db is a valid SQLAlchemy Session instance bound to the auth persistence context.
     # @POST: self.repo is initialized and ready for auth user/role CRUD operations.
@@ -37,6 +43,7 @@ class AuthService:
     # [/DEF:__init__:Function]
 
     # [DEF:authenticate_user:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Validates credentials and account state for local username/password authentication.
     # @PRE: username and password are non-empty credential inputs.
     # @POST: Returns User only when user exists, is active, and password hash verification succeeds; otherwise returns None.
@@ -62,6 +69,7 @@ class AuthService:
     # [/DEF:authenticate_user:Function]
 
     # [DEF:create_session:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Issues an access token payload for an already authenticated user.
     # @PRE: user is a valid User entity containing username and iterable roles with role.name values.
     # @POST: Returns session dict with non-empty access_token and token_type='bearer'.
@@ -87,6 +95,7 @@ class AuthService:
     # [/DEF:create_session:Function]
 
     # [DEF:provision_adfs_user:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Performs ADFS Just-In-Time provisioning and role synchronization from AD group mappings.
     # @PRE: user_info contains identity claims where at least one of 'upn' or 'email' is present; 'groups' may be absent.
     # @POST: Returns persisted user entity with roles synchronized to mapped AD groups and refreshed state.
@@ -121,7 +130,6 @@ class AuthService:
             self.repo.db.refresh(user)
             return user
     # [/DEF:provision_adfs_user:Function]
-
 # [/DEF:AuthService:Class]
 
 # [/DEF:backend.src.services.auth_service:Module]