Implement PauseManagementService state machine
epic-peer-mentor-pause-management-core-workflows-task-006 — Build the core business logic service enforcing the pause state machine with transitions: active→paused (via mentor self-service), paused→active (reactivation), any→expired_cert (triggered externally by certification checker). Implement activatePause(mentorId, reason, expectedReturnDate), reactivateMentor(mentorId), and expireCertification(mentorId). Each transition must persist via PeerMentorStatusRepository and trigger PauseNotificationService. Enforce invariants: cannot pause already-paused mentor, cannot reactivate non-paused mentor.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 3 - 413 tasks
Can start after Tier 2 completes
Implementation Notes
Implement a private _assertTransition(currentStatus, allowedStatuses, errorCode) helper to centralise the invariant check pattern — this keeps each public method concise and the invariants explicit. To prevent race conditions on the read-then-write, consider wrapping the status check + update in a Supabase RPC (PostgreSQL function) that accepts mentorId, expectedCurrentStatus, and newStatus, and returns an error if the current status does not match — this is atomic. Define PauseInvariantException as a typed exception class with a String code and String message, so the UI layer can show appropriate localised error messages without pattern-matching on exception message strings. Keep notification dispatch outside the repository transaction: call notifyCoordinator AFTER the database persist returns successfully, wrapped in a try/catch that logs but does not rethrow.
Expose the service as a Riverpod Provider
Testing Requirements
Write comprehensive unit tests using flutter_test with mocked PeerMentorStatusRepository and mocked PauseNotificationService. Test every valid transition: (1) active → paused via activatePause succeeds. (2) paused → active via reactivateMentor succeeds. (3) active → expired_cert via expireCertification succeeds.
(4) paused → expired_cert via expireCertification succeeds. Test every invalid transition: (5) activatePause on paused mentor throws PauseInvariantException('already_paused'). (6) activatePause on expired_cert mentor throws PauseInvariantException('expired_cert'). (7) reactivateMentor on active mentor throws PauseInvariantException('not_paused').
(8) reactivateMentor on expired_cert mentor throws PauseInvariantException('expired_cert'). Test notification behaviour: (9) activatePause calls notifyCoordinatorOfPause exactly once. (10) Notification failure does not cause activatePause to throw. (11) reactivateMentor calls notifyCoordinatorOfReactivation exactly once.
Achieve 95%+ branch coverage. Write one integration test against a local Supabase instance covering the full activate → expire → reactivate flow.
Concurrent status transitions (e.g., coordinator and automated scheduler both attempting to update the same mentor's status simultaneously) may produce race conditions or inconsistent state in the database, leading to audit log gaps or incorrect notifications.
Mitigation & Contingency
Mitigation: Implement all status transitions as atomic Postgres RPC functions with optimistic locking (version column or updated_at check). Use database-level constraints rather than application-level guards as the final enforcement point.
Contingency: Add a compensation job that reconciles status and log table consistency on each nightly scheduler run, surfacing any discrepancies to coordinator dashboards.
The coordinator-to-mentor assignment relationship may not always be 1:1 or may be stale (coordinator reassigned after a pause was set), causing notifications to be sent to the wrong coordinator or not sent at all.
Mitigation & Contingency
Mitigation: Query the assignment relationship at notification dispatch time rather than caching it at pause creation time. Add a fallback to notify the chapter administrator if no active coordinator assignment exists.
Contingency: Log all undeliverable notification attempts with the originating mentor ID so administrators can manually follow up, and surface undelivered notification counts on the coordinator dashboard.
The CoordinatorPauseRosterScreen may load slowly for coordinators managing large rosters with many concurrent certification expiry queries, degrading usability on low-bandwidth mobile connections.
Mitigation & Contingency
Mitigation: Use a single Supabase RPC that joins mentor status, certification expiry, and assignment data in one query rather than N+1 individual calls. Implement pagination with a configurable page size and skeleton loading states.
Contingency: Add an offline cache of the last-fetched roster state using Riverpod with SharedPreferences, ensuring coordinators can at minimum view stale data when connectivity is poor.