Add clinical progression ranks and records

api/QuestionsApi/Controllers/DashboardController.cs

@@ -8,7 +8,7 @@ namespace QuestionsApi.Controllers;
 [ApiController]
 [Route("api/dashboard")]
 [Authorize(Roles = "USER,SUPER")]
-public sealed class DashboardController(DashboardStore dashboard) : ControllerBase
+public sealed class DashboardController(DashboardStore dashboard, ProgressionStore progression) : ControllerBase
 {
     [HttpGet]
     public async Task<IActionResult> Get()
@@ -18,6 +18,8 @@ public sealed class DashboardController(DashboardStore dashboard) : ControllerBa
             ?? User.Identity?.Name
             ?? "";
         if (string.IsNullOrWhiteSpace(userId)) return Unauthorized();
-        return Ok(await dashboard.GetAsync(userId, DateTime.UtcNow));
+        var response = await dashboard.GetAsync(userId, DateTime.UtcNow);
+        response.Progression = await progression.GetAsync(userId);
+        return Ok(response);
     }
 }

api/QuestionsApi/Controllers/ExamSimulationsController.cs

@@ -13,7 +13,8 @@ public class ExamSimulationsController(
     ExamSimulationStore simulations,
     CreditStore credits,
     MasteryAwardService masteryAwards,
-    StudySessionStore studySessions) : ControllerBase
+    StudySessionStore studySessions,
+    ProgressionStore progression) : ControllerBase
 {
     [HttpGet("readiness")]
     public async Task<IActionResult> Readiness() => Ok(await simulations.GetReadinessAsync(UserId()));
@@ -145,6 +146,7 @@ public class ExamSimulationsController(
         {
             var userId = UserId();
             await masteryAwards.PrepareAsync(userId);
+            await progression.PrepareAsync(userId);
             simulation = await simulations.SubmitBlockAsync(simulation);
             var response = await simulations.ToResponseAsync(simulation);
             var session = await studySessions.CompleteSimulationBlockAsync(userId, simulation.Id ?? id, simulation.CurrentBlock);
@@ -164,6 +166,10 @@ public class ExamSimulationsController(
             }
             else if (session.Summary is not null)
                 response.Credits = await credits.GetStatusAsync(userId);
+            var progressionResult = await progression.RefreshAsync(userId);
+            response.Progression = progressionResult.State;
+            response.CreditAwards.AddRange(progressionResult.Awards);
+            if (progressionResult.Awards.Count > 0) response.Credits = await credits.GetStatusAsync(userId);
             return Ok(response);
         }
         catch (InvalidOperationException exception) { return Conflict(exception.Message); }

api/QuestionsApi/Controllers/ProgressionController.cs

@@ -0,0 +1,18 @@
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+using QuestionsApi.Services;
+using System.Security.Claims;
+
+namespace QuestionsApi.Controllers;
+
+[ApiController, Route("api/progression"), Authorize(Roles = "USER,SUPER")]
+public sealed class ProgressionController(ProgressionStore progression) : ControllerBase
+{
+    [HttpGet]
+    public async Task<IActionResult> Get()
+    {
+        var userId = User.FindFirstValue(ClaimTypes.NameIdentifier) ?? User.FindFirstValue(ClaimTypes.Name)
+            ?? User.Identity?.Name ?? "";
+        return string.IsNullOrWhiteSpace(userId) ? Unauthorized() : Ok(await progression.GetAsync(userId));
+    }
+}

api/QuestionsApi/Controllers/QuestionsController.cs

@@ -23,6 +23,7 @@ public class QuestionsController : ControllerBase
     private readonly MasteryAwardService _masteryAwards;
     private readonly StudySessionStore _studySessions;
     private readonly DailyMissionStore _dailyMissions;
+    private readonly ProgressionStore _progression;
 
     public QuestionsController(
         QuestionStore questions,
@@ -36,7 +37,8 @@ public class QuestionsController : ControllerBase
         CreditStore credits,
         MasteryAwardService masteryAwards,
         StudySessionStore studySessions,
-        DailyMissionStore dailyMissions)
+        DailyMissionStore dailyMissions,
+        ProgressionStore progression)
     {
         _questions = questions;
         _attempts = attempts;
@@ -50,6 +52,7 @@ public class QuestionsController : ControllerBase
         _masteryAwards = masteryAwards;
         _studySessions = studySessions;
         _dailyMissions = dailyMissions;
+        _progression = progression;
     }
 
     [HttpGet("systems")]
@@ -162,6 +165,7 @@ public class QuestionsController : ControllerBase
             return Unauthorized();
 
         await _masteryAwards.PrepareAsync(userId);
+        await _progression.PrepareAsync(userId);
 
         var record = await _attempts.RecordFirstAttemptAsync(
             question.ExternalId,
@@ -237,6 +241,8 @@ public class QuestionsController : ControllerBase
                 && creditAwards.All(existing => existing.ReasonCode != value.ReasonCode)));
         var dailyMissions = await _dailyMissions.RecordQuestionAsync(userId, record.Attempt, question);
         if (dailyMissions is not null) creditAwards.AddRange(dailyMissions.CreditAwards);
+        var progression = await _progression.RefreshAsync(userId);
+        creditAwards.AddRange(progression.Awards);
         return Ok(new FirstQuestionAttemptResponse
         {
             QuestionExternalId = question.ExternalId,
@@ -249,7 +255,8 @@ public class QuestionsController : ControllerBase
             CreditAwards = creditAwards,
             StudySessionProgress = studySession?.Progress,
             SessionSummary = studySession?.Summary,
-            DailyMissions = dailyMissions?.State
+            DailyMissions = dailyMissions?.State,
+            Progression = progression.State
         });
     }
 
@@ -310,6 +317,8 @@ public class QuestionsController : ControllerBase
         if (string.IsNullOrWhiteSpace(userId))
             return Unauthorized();
 
+        await _progression.PrepareAsync(userId);
+
         var record = await _attempts.RecordFirstAttemptAsync(
             question.ExternalId,
             userId,
@@ -342,6 +351,7 @@ public class QuestionsController : ControllerBase
             throw;
         }
 
+        var progression = await _progression.RefreshAsync(userId);
         return Ok(new SkipQuestionResponse
         {
             QuestionExternalId = question.ExternalId,
@@ -350,7 +360,8 @@ public class QuestionsController : ControllerBase
                 question,
                 await _statistics.GetPercentagesForQuestionAsync(question.ExternalId)),
             QuestionElo = rating.QuestionElo,
-            Rating = rating
+            Rating = rating,
+            Progression = progression.State
         });
     }
 

api/QuestionsApi/Controllers/ReviewQueueController.cs

@@ -18,7 +18,8 @@ public sealed class ReviewQueueController(
     CreditStore credits,
     MasteryAwardService masteryAwards,
     StudySessionStore studySessions,
-    DailyMissionStore dailyMissions) : ControllerBase
+    DailyMissionStore dailyMissions,
+    ProgressionStore progression) : ControllerBase
 {
     [HttpPost("next")]
     public async Task<IActionResult> Next([FromBody] ReviewQueueNextRequest req)
@@ -76,6 +77,7 @@ public sealed class ReviewQueueController(
         }
 
         await masteryAwards.PrepareAsync(userId);
+        await progression.PrepareAsync(userId);
         var result = await queue.RecordReviewAsync(
             userId,
             req.ClientAttemptId,
@@ -110,6 +112,8 @@ public sealed class ReviewQueueController(
                 && awards.All(existing => existing.ReasonCode != value.ReasonCode)));
         var missionResult = await dailyMissions.RecordReviewAsync(userId, result.Attempt);
         if (missionResult is not null) awards.AddRange(missionResult.CreditAwards);
+        var progressionResult = await progression.RefreshAsync(userId);
+        awards.AddRange(progressionResult.Awards);
         return Ok(new ReviewQueueAttemptResponse
         {
             QuestionExternalId = question.ExternalId,
@@ -120,7 +124,8 @@ public sealed class ReviewQueueController(
             CreditAwards = awards,
             StudySessionProgress = studySession?.Progress,
             SessionSummary = studySession?.Summary,
-            DailyMissions = missionResult?.State
+            DailyMissions = missionResult?.State,
+            Progression = progressionResult.State
         });
     }
 

api/QuestionsApi/Models/CreditModels.cs

@@ -112,6 +112,7 @@ public static class CreditReasonCodes
     public const string SessionGoalComplete = "session_goal_complete";
     public const string DailyMissionComplete = "daily_mission_complete";
     public const string WeeklyGoalComplete = "weekly_goal_complete";
+    public const string RankPromotion = "rank_promotion";
     public const string Purchase = "purchase";
 }
 

api/QuestionsApi/Models/DashboardModels.cs

@@ -31,6 +31,7 @@ public sealed class DashboardResponse
     public List<DashboardSystemPerformance> Systems { get; set; } = [];
     public List<DashboardActivityDay> WeeklyActivity { get; set; } = [];
     public List<DashboardRecentActivity> RecentActivity { get; set; } = [];
+    public ProgressionResponse? Progression { get; set; }
 }
 
 public sealed class DashboardTrendPoint

api/QuestionsApi/Models/ExamSimulation.cs

@@ -121,6 +121,7 @@ public class ExamSimulationStateResponse
     public List<CreditAward> CreditAwards { get; set; } = [];
     public StudySessionProgress? StudySessionProgress { get; set; }
     public StudySessionSummary? SessionSummary { get; set; }
+    public ProgressionResponse? Progression { get; set; }
 }
 
 public class ExamSimulationReadinessResponse

api/QuestionsApi/Models/ProgressionModels.cs

@@ -0,0 +1,98 @@
+using MongoDB.Bson;
+using MongoDB.Bson.Serialization.Attributes;
+
+namespace QuestionsApi.Models;
+
+public sealed class UserProgression
+{
+    [BsonId, BsonRepresentation(BsonType.ObjectId)] public string? Id { get; set; }
+    public string UserId { get; set; } = "";
+    public int HighestRankOrdinal { get; set; }
+    public DateTime TrackingStartedUtc { get; set; }
+    public bool BaselineApplied { get; set; }
+    public Dictionary<string, DateTime> EarnedRanksUtc { get; set; } = [];
+    public int CurrentHardStreak { get; set; }
+    public int BestHardStreak { get; set; }
+    public DateTime? BestHardStreakUtc { get; set; }
+    public PersonalRecordValue BestTimedBlock { get; set; } = new();
+    public PersonalRecordValue SystemsAdvancedWeek { get; set; } = new();
+    public PersonalRecordValue ReviewQueueReduction { get; set; } = new();
+    public PersonalRecordValue WeakSystemImprovement { get; set; } = new();
+    public DateTime UpdatedUtc { get; set; }
+}
+
+public sealed class PersonalRecordValue
+{
+    public int Value { get; set; }
+    public int SampleSize { get; set; }
+    public string Detail { get; set; } = "";
+    public DateTime? AchievedUtc { get; set; }
+}
+
+public sealed class ProgressionWeeklySnapshot
+{
+    [BsonId] public string Id { get; set; } = "";
+    public string UserId { get; set; } = "";
+    public DateTime WeekStartUtc { get; set; }
+    public List<ProgressionSystemSnapshot> OpeningSystems { get; set; } = [];
+    public List<ProgressionSystemSnapshot> LatestSystems { get; set; } = [];
+    public int OpeningPendingReviews { get; set; }
+    public int LatestPendingReviews { get; set; }
+    public DateTime UpdatedUtc { get; set; }
+}
+
+public sealed class ProgressionSystemSnapshot
+{
+    public string System { get; set; } = "";
+    public int StateOrdinal { get; set; }
+    public int MasteryScore { get; set; }
+    public int DistinctQuestions { get; set; }
+}
+
+public sealed class ProgressionRequirementResponse
+{
+    public string Key { get; set; } = "";
+    public string Label { get; set; } = "";
+    public int Current { get; set; }
+    public int Required { get; set; }
+    public bool Complete => Current >= Required;
+}
+
+public sealed class ProgressionRecordResponse
+{
+    public string Key { get; set; } = "";
+    public string Label { get; set; } = "";
+    public string Definition { get; set; } = "";
+    public int Value { get; set; }
+    public int SampleSize { get; set; }
+    public string Detail { get; set; } = "";
+    public DateTime? AchievedUtc { get; set; }
+    public bool TrackingFromLaunch { get; set; }
+}
+
+public sealed class ProgressionResponse
+{
+    public int RankOrdinal { get; set; }
+    public int QualifiedRankOrdinal { get; set; }
+    public string RankName { get; set; } = "Case Scout";
+    public string Division { get; set; } = "III";
+    public string DisplayName => $"{RankName} {Division}";
+    public DateTime TrackingStartedUtc { get; set; }
+    public List<string> EarnedBadges { get; set; } = [];
+    public Dictionary<string, DateTime> EarnedRanksUtc { get; set; } = [];
+    public List<ProgressionRankResponse> Ladder { get; set; } = [];
+    public string? NextRankName { get; set; }
+    public string? NextDivision { get; set; }
+    public List<ProgressionRequirementResponse> NextRequirements { get; set; } = [];
+    public List<ProgressionRecordResponse> Records { get; set; } = [];
+}
+
+public sealed class ProgressionRankResponse
+{
+    public int Ordinal { get; set; }
+    public string RankName { get; set; } = "";
+    public string Division { get; set; } = "";
+    public bool Earned { get; set; }
+    public DateTime? EarnedUtc { get; set; }
+    public string RequirementSummary { get; set; } = "";
+}

api/QuestionsApi/Models/QuestionResponse.cs

@@ -150,6 +150,7 @@ public class FirstQuestionAttemptResponse
     public StudySessionProgress? StudySessionProgress { get; set; }
     public StudySessionSummary? SessionSummary { get; set; }
     public DailyMissionSetResponse? DailyMissions { get; set; }
+    public ProgressionResponse? Progression { get; set; }
 }
 
 public class SkipQuestionResponse
@@ -159,6 +160,7 @@ public class SkipQuestionResponse
     public Dictionary<string, int> ChoiceSelectionPercentages { get; set; } = [];
     public int QuestionElo { get; set; } = 1000;
     public RatingChangeResponse? Rating { get; set; }
+    public ProgressionResponse? Progression { get; set; }
 }
 
 public static class RatingCategory

api/QuestionsApi/Models/ReviewQueueModels.cs

@@ -87,6 +87,7 @@ public sealed class ReviewQueueAttemptResponse
     public StudySessionProgress? StudySessionProgress { get; set; }
     public StudySessionSummary? SessionSummary { get; set; }
     public DailyMissionSetResponse? DailyMissions { get; set; }
+    public ProgressionResponse? Progression { get; set; }
 }
 
 public sealed class ReviewQueueRecordResult

api/QuestionsApi/Program.cs

@@ -114,6 +114,7 @@ builder.Services.AddSingleton<DashboardStore>();
 builder.Services.AddSingleton<StudySessionStore>();
 builder.Services.AddSingleton<DailyMissionStore>();
 builder.Services.AddSingleton<WeeklyGoalStore>();
+builder.Services.AddSingleton<ProgressionStore>();
 builder.Services.AddSingleton<UserProfileStore>();
 builder.Services.AddSingleton<IFlashcardScheduler, FsrsFlashcardScheduler>();
 builder.Services.AddSingleton<FlashcardDeckStore>();

api/QuestionsApi/Services/ProgressionPolicy.cs

@@ -0,0 +1,42 @@
+using QuestionsApi.Models;
+
+namespace QuestionsApi.Services;
+
+public static class ProgressionPolicy
+{
+    public sealed record Threshold(int L, int P, int S, int M, int H, int R);
+    public static readonly Threshold[] Thresholds =
+    [
+        new(0,0,0,0,0,0), new(2,0,0,0,1,0), new(4,1,0,0,3,1),
+        new(6,2,0,0,6,1), new(8,4,0,0,10,2), new(10,6,0,0,15,3),
+        new(0,8,1,0,20,4), new(0,9,2,0,28,5), new(0,10,4,0,36,7),
+        new(0,11,5,1,45,9), new(0,12,7,2,55,11), new(0,13,9,4,65,13),
+        new(0,14,10,6,75,15), new(0,14,12,9,90,18), new(0,14,14,12,105,21)
+    ];
+    public static readonly string[] Names = ["Case Scout", "Pattern Hunter", "Diagnostic Tactician", "Management Strategist", "Clinical Vanguard"];
+    public static readonly string[] Divisions = ["III", "II", "I"];
+
+    public static int Qualified(IReadOnlyCollection<DashboardSystemPerformance> systems, int retention)
+    {
+        var l = systems.Count(x => State(x.MasteryState) >= 1);
+        var p = systems.Count(x => State(x.MasteryState) >= 2);
+        var s = systems.Count(x => State(x.MasteryState) >= 3);
+        var m = systems.Count(x => State(x.MasteryState) >= 4);
+        var h = systems.Sum(x => x.Difficulty4PlusSuccessful);
+        for (var i = Thresholds.Length - 1; i >= 0; i--)
+        {
+            var t = Thresholds[i];
+            if (l >= t.L && p >= t.P && s >= t.S && m >= t.M && h >= t.H && retention >= t.R) return i;
+        }
+        return 0;
+    }
+
+    public static int State(string state) => state switch
+    {
+        MasteryStates.Learning => 1, MasteryStates.Practicing => 2,
+        MasteryStates.Strong => 3, MasteryStates.Mastered => 4, _ => 0
+    };
+    public static string Name(int ordinal) => Names[Math.Clamp(ordinal / 3, 0, 4)];
+    public static string Division(int ordinal) => Divisions[Math.Clamp(ordinal % 3, 0, 2)];
+    public static int TierStart(int ordinal) => ordinal / 3 * 3;
+}

api/QuestionsApi/Services/ProgressionStore.cs

@@ -0,0 +1,253 @@
+using MongoDB.Driver;
+using QuestionsApi.Models;
+
+namespace QuestionsApi.Services;
+
+public sealed class ProgressionStore
+{
+    private readonly IMongoCollection<UserProgression> _progressions;
+    private readonly IMongoCollection<ProgressionWeeklySnapshot> _snapshots;
+    private readonly IMongoCollection<QuestionAttempt> _attempts;
+    private readonly IMongoCollection<QuestionReviewAttempt> _reviews;
+    private readonly IMongoCollection<ReviewQueueItem> _queue;
+    private readonly IMongoCollection<StudySession> _sessions;
+    private readonly QuestionStore _questions;
+    private readonly CreditStore _credits;
+    private readonly TimeProvider _clock;
+
+    public ProgressionStore(MongoDatabaseProvider mongo, QuestionStore questions, CreditStore credits, TimeProvider clock)
+    {
+        var db = mongo.Database;
+        _progressions = db.GetCollection<UserProgression>("UserProgressions");
+        _snapshots = db.GetCollection<ProgressionWeeklySnapshot>("ProgressionWeeklySnapshots");
+        _attempts = db.GetCollection<QuestionAttempt>("QuestionAttempts");
+        _reviews = db.GetCollection<QuestionReviewAttempt>("QuestionReviewAttempts");
+        _queue = db.GetCollection<ReviewQueueItem>("ReviewQueueItems");
+        _sessions = db.GetCollection<StudySession>("StudySessions");
+        _questions = questions;
+        _credits = credits;
+        _clock = clock;
+        _progressions.Indexes.CreateOne(new CreateIndexModel<UserProgression>(
+            Builders<UserProgression>.IndexKeys.Ascending(x => x.UserId), new CreateIndexOptions { Unique = true }));
+        _snapshots.Indexes.CreateOne(new CreateIndexModel<ProgressionWeeklySnapshot>(
+            Builders<ProgressionWeeklySnapshot>.IndexKeys.Ascending(x => x.UserId).Descending(x => x.WeekStartUtc)));
+    }
+
+    public async Task PrepareAsync(string userId)
+    {
+        if (await _progressions.Find(x => x.UserId == userId).AnyAsync())
+        {
+            await EnsureWeeklyOpeningAsync(userId);
+            return;
+        }
+        var evidence = await EvidenceAsync(userId);
+        var qualified = ProgressionPolicy.Qualified(evidence.Systems, evidence.Retention);
+        var now = _clock.GetUtcNow().UtcDateTime;
+        var progression = new UserProgression
+        {
+            UserId = userId, HighestRankOrdinal = qualified, BaselineApplied = true,
+            TrackingStartedUtc = now, UpdatedUtc = now,
+            EarnedRanksUtc = Enumerable.Range(0, qualified + 1).ToDictionary(x => x.ToString(), _ => now)
+        };
+        ApplyHistoricalRecords(progression, evidence);
+        try { await _progressions.InsertOneAsync(progression); }
+        catch (MongoWriteException exception) when (exception.WriteError?.Category == ServerErrorCategory.DuplicateKey) { }
+        await EnsureWeeklyOpeningAsync(userId, evidence);
+    }
+
+    public async Task<(ProgressionResponse State, List<CreditAward> Awards)> RefreshAsync(string userId)
+    {
+        await PrepareAsync(userId);
+        var evidence = await EvidenceAsync(userId);
+        var progression = await _progressions.Find(x => x.UserId == userId).FirstAsync();
+        var oldHighest = progression.HighestRankOrdinal;
+        var qualified = ProgressionPolicy.Qualified(evidence.Systems, evidence.Retention);
+        var now = _clock.GetUtcNow().UtcDateTime;
+        ApplyHistoricalRecords(progression, evidence);
+        if (qualified > progression.HighestRankOrdinal)
+        {
+            progression.HighestRankOrdinal = qualified;
+            for (var i = oldHighest + 1; i <= qualified; i++) progression.EarnedRanksUtc.TryAdd(i.ToString(), now);
+        }
+        await UpdateWeeklyAsync(progression, evidence, now);
+        progression.UpdatedUtc = now;
+        var update = Builders<UserProgression>.Update.Max(x => x.HighestRankOrdinal, qualified)
+            .Set(x => x.CurrentHardStreak, progression.CurrentHardStreak)
+            .Set(x => x.BestHardStreak, progression.BestHardStreak)
+            .Set(x => x.BestHardStreakUtc, progression.BestHardStreakUtc)
+            .Set(x => x.BestTimedBlock, progression.BestTimedBlock)
+            .Set(x => x.SystemsAdvancedWeek, progression.SystemsAdvancedWeek)
+            .Set(x => x.ReviewQueueReduction, progression.ReviewQueueReduction)
+            .Set(x => x.WeakSystemImprovement, progression.WeakSystemImprovement)
+            .Set(x => x.UpdatedUtc, now);
+        for (var i = oldHighest + 1; i <= qualified; i++) update = update.Set($"EarnedRanksUtc.{i}", now);
+        await _progressions.UpdateOneAsync(x => x.UserId == userId, update);
+        progression = await _progressions.Find(x => x.UserId == userId).FirstAsync();
+
+        var awards = new List<CreditAward>();
+        foreach (var tier in new[] { 3, 6, 9, 12 }.Where(x => oldHighest < x && qualified >= x))
+        {
+            var amount = tier switch { 3 => 5, 6 => 10, 9 => 15, _ => 25 };
+            var result = await _credits.AwardAsync(userId, new CreditAwardRequest(
+                $"progression:rank:{tier}", amount, CreditReasonCodes.RankPromotion,
+                $"Advanced to {ProgressionPolicy.Name(tier)}", "progression_rank", tier.ToString(), false));
+            if (result.Award is not null) awards.Add(result.Award);
+        }
+        return (Response(progression, qualified, evidence), awards);
+    }
+
+    public async Task<ProgressionResponse> GetAsync(string userId) => (await RefreshAsync(userId)).State;
+
+    private async Task EnsureWeeklyOpeningAsync(string userId, Evidence? supplied = null)
+    {
+        var now = _clock.GetUtcNow().UtcDateTime;
+        var week = WeekStart(now);
+        var id = $"{userId}:{week:yyyyMMdd}";
+        if (await _snapshots.Find(x => x.Id == id).AnyAsync()) return;
+        var evidence = supplied ?? await EvidenceAsync(userId);
+        var values = Snapshots(evidence.Systems);
+        var snapshot = new ProgressionWeeklySnapshot
+        {
+            Id = id, UserId = userId, WeekStartUtc = week,
+            OpeningSystems = values, LatestSystems = values,
+            OpeningPendingReviews = evidence.Pending, LatestPendingReviews = evidence.Pending, UpdatedUtc = now
+        };
+        try { await _snapshots.InsertOneAsync(snapshot); }
+        catch (MongoWriteException exception) when (exception.WriteError?.Category == ServerErrorCategory.DuplicateKey) { }
+    }
+
+    private async Task UpdateWeeklyAsync(UserProgression progression, Evidence evidence, DateTime now)
+    {
+        await EnsureWeeklyOpeningAsync(progression.UserId, evidence);
+        var week = WeekStart(now);
+        var id = $"{progression.UserId}:{week:yyyyMMdd}";
+        await _snapshots.UpdateOneAsync(x => x.Id == id, Builders<ProgressionWeeklySnapshot>.Update
+            .Set(x => x.LatestSystems, Snapshots(evidence.Systems)).Set(x => x.LatestPendingReviews, evidence.Pending)
+            .Set(x => x.UpdatedUtc, now));
+        var all = await _snapshots.Find(x => x.UserId == progression.UserId).ToListAsync();
+        foreach (var snapshot in all)
+        {
+            var opening = snapshot.OpeningSystems.ToDictionary(x => x.System);
+            var advanced = snapshot.LatestSystems.Count(x => opening.TryGetValue(x.System, out var before) && x.StateOrdinal > before.StateOrdinal);
+            SetRecordIfBetter(progression.SystemsAdvancedWeek, advanced, 0, $"Week of {snapshot.WeekStartUtc:yyyy-MM-dd}", snapshot.UpdatedUtc);
+            var reduced = Math.Max(0, snapshot.OpeningPendingReviews - snapshot.LatestPendingReviews);
+            SetRecordIfBetter(progression.ReviewQueueReduction, reduced, snapshot.OpeningPendingReviews,
+                $"Week of {snapshot.WeekStartUtc:yyyy-MM-dd}", snapshot.UpdatedUtc);
+            foreach (var after in snapshot.LatestSystems)
+            {
+                if (!opening.TryGetValue(after.System, out var before) || before.MasteryScore >= 75 || before.DistinctQuestions < 5) continue;
+                SetRecordIfBetter(progression.WeakSystemImprovement, Math.Max(0, after.MasteryScore - before.MasteryScore),
+                    after.DistinctQuestions, after.System, snapshot.UpdatedUtc);
+            }
+        }
+    }
+
+    private async Task<Evidence> EvidenceAsync(string userId)
+    {
+        var attempts = await _attempts.Find(x => x.UserId == userId).SortBy(x => x.CreatedUtc).ToListAsync();
+        var reviews = await _reviews.Find(x => x.UserId == userId).SortBy(x => x.CreatedUtc).ToListAsync();
+        var queue = await _queue.Find(x => x.UserId == userId).ToListAsync();
+        var ids = attempts.Select(x => x.QuestionExternalId).Concat(reviews.Select(x => x.QuestionExternalId)).Concat(queue.Select(x => x.QuestionExternalId));
+        var questions = await _questions.GetByExternalIdsAsync(ids);
+        var systems = MasteryCalculator.Calculate(attempts, reviews, queue, questions, _clock.GetUtcNow().UtcDateTime);
+        var delayed = reviews.Where(x => x.IsCorrect).Select(x => new
+        {
+            Review = x, Item = queue.FirstOrDefault(q => q.QuestionExternalId == x.QuestionExternalId)
+        }).Where(x => x.Item is not null && x.Review.CreatedUtc - x.Item.CreatedUtc >= TimeSpan.FromHours(24))
+          .Select(x => x.Review.QuestionExternalId).Distinct().Count();
+        var directHard = attempts.Where(x => x.IsCorrect && !x.IsSkip && questions.TryGetValue(x.QuestionExternalId, out var q) && q.Difficulty >= 4)
+            .Select(x => x.QuestionExternalId).Distinct().Count();
+        var sessions = await _sessions.Find(x => x.UserId == userId && x.State == StudySessionStates.Completed
+            && x.Mode == "Timed" && x.GoalType != StudyGoalTypes.SimulationBlock).ToListAsync();
+        return new Evidence(attempts, reviews, queue, sessions, questions, systems, delayed + directHard / 5,
+            queue.Count(x => x.State == ReviewQueueStates.Pending));
+    }
+
+    private void ApplyHistoricalRecords(UserProgression progression, Evidence evidence)
+    {
+        var streak = 0;
+        foreach (var attempt in evidence.Attempts.Where(x => evidence.Questions.TryGetValue(x.QuestionExternalId, out var q) && q.Difficulty >= 4))
+        {
+            streak = attempt.IsCorrect && !attempt.IsSkip ? streak + 1 : 0;
+            if (streak > progression.BestHardStreak)
+            {
+                progression.BestHardStreak = streak;
+                progression.BestHardStreakUtc = attempt.CreatedUtc;
+            }
+        }
+        progression.CurrentHardStreak = streak;
+
+        var attemptsById = evidence.Attempts.Where(x => x.Id is not null).ToDictionary(x => x.Id!);
+        foreach (var session in evidence.Sessions)
+        {
+            var sessionAttempts = session.AppliedEventIds.Where(attemptsById.ContainsKey).Select(x => attemptsById[x]).ToList();
+            if (sessionAttempts.Count < 20 || sessionAttempts.Count != session.AppliedEventIds.Count) continue;
+            var hard = sessionAttempts.Count(x => evidence.Questions.TryGetValue(x.QuestionExternalId, out var q) && q.Difficulty >= 4);
+            if (hard * 2 < sessionAttempts.Count) continue;
+            var accuracy = (int)Math.Round(sessionAttempts.Count(x => x.IsCorrect && !x.IsSkip) * 100d / sessionAttempts.Count);
+            if (accuracy > progression.BestTimedBlock.Value
+                || accuracy == progression.BestTimedBlock.Value && sessionAttempts.Count > progression.BestTimedBlock.SampleSize)
+                progression.BestTimedBlock = new PersonalRecordValue { Value = accuracy, SampleSize = sessionAttempts.Count,
+                    Detail = $"{hard} difficulty 4–5 questions", AchievedUtc = session.CompletedUtc ?? session.UpdatedUtc };
+        }
+    }
+
+    private static void SetRecordIfBetter(PersonalRecordValue record, int value, int sample, string detail, DateTime date)
+    {
+        if (value <= record.Value) return;
+        record.Value = value; record.SampleSize = sample; record.Detail = detail; record.AchievedUtc = date;
+    }
+
+    private static ProgressionResponse Response(UserProgression p, int qualified, Evidence evidence)
+    {
+        var earnedTierNames = Enumerable.Range(0, p.HighestRankOrdinal / 3 + 1).Select(x => ProgressionPolicy.Names[x]).ToList();
+        var response = new ProgressionResponse
+        {
+            RankOrdinal = p.HighestRankOrdinal, QualifiedRankOrdinal = qualified,
+            RankName = ProgressionPolicy.Name(p.HighestRankOrdinal), Division = ProgressionPolicy.Division(p.HighestRankOrdinal),
+            TrackingStartedUtc = p.TrackingStartedUtc, EarnedBadges = earnedTierNames, EarnedRanksUtc = p.EarnedRanksUtc,
+            Records = Records(p), Ladder = Enumerable.Range(0, ProgressionPolicy.Thresholds.Length).Select(i =>
+            {
+                var t = ProgressionPolicy.Thresholds[i];
+                var parts = new List<string>();
+                if (t.L > 0) parts.Add($"Learning+ {t.L}"); if (t.P > 0) parts.Add($"Practicing+ {t.P}");
+                if (t.S > 0) parts.Add($"Strong+ {t.S}"); if (t.M > 0) parts.Add($"Mastered {t.M}");
+                if (t.H > 0) parts.Add($"Hard successes {t.H}"); if (t.R > 0) parts.Add($"Retention {t.R}");
+                return new ProgressionRankResponse { Ordinal=i, RankName=ProgressionPolicy.Name(i), Division=ProgressionPolicy.Division(i),
+                    Earned=i <= p.HighestRankOrdinal, EarnedUtc=p.EarnedRanksUtc.GetValueOrDefault(i.ToString()),
+                    RequirementSummary=parts.Count == 0 ? "Starting rank" : string.Join(" · ", parts) };
+            }).ToList()
+        };
+        if (p.HighestRankOrdinal >= ProgressionPolicy.Thresholds.Length - 1) return response;
+        var next = p.HighestRankOrdinal + 1;
+        response.NextRankName = ProgressionPolicy.Name(next); response.NextDivision = ProgressionPolicy.Division(next);
+        var threshold = ProgressionPolicy.Thresholds[next];
+        var values = new Dictionary<string, (string Label, int Current, int Required)>
+        {
+            ["learning"] = ("Systems at Learning+", evidence.Systems.Count(x => ProgressionPolicy.State(x.MasteryState) >= 1), threshold.L),
+            ["practicing"] = ("Systems at Practicing+", evidence.Systems.Count(x => ProgressionPolicy.State(x.MasteryState) >= 2), threshold.P),
+            ["strong"] = ("Systems at Strong+", evidence.Systems.Count(x => ProgressionPolicy.State(x.MasteryState) >= 3), threshold.S),
+            ["mastered"] = ("Systems Mastered", evidence.Systems.Count(x => ProgressionPolicy.State(x.MasteryState) >= 4), threshold.M),
+            ["hard"] = ("Difficulty 4+ successes", evidence.Systems.Sum(x => x.Difficulty4PlusSuccessful), threshold.H),
+            ["retention"] = ("Retention evidence", evidence.Retention, threshold.R)
+        };
+        response.NextRequirements = values.Where(x => x.Value.Required > 0).Select(x => new ProgressionRequirementResponse
+            { Key = x.Key, Label = x.Value.Label, Current = x.Value.Current, Required = x.Value.Required }).ToList();
+        return response;
+    }
+
+    private static List<ProgressionRecordResponse> Records(UserProgression p) =>
+    [
+        new() { Key="timed_block", Label="Advanced Timed Block", Definition="Best accuracy in a completed 20+ question Timed block with at least 50% difficulty 4–5.", Value=p.BestTimedBlock.Value, SampleSize=p.BestTimedBlock.SampleSize, Detail=p.BestTimedBlock.Detail, AchievedUtc=p.BestTimedBlock.AchievedUtc },
+        new() { Key="hard_streak", Label="Hard-Question Streak", Definition="Consecutive correct first attempts at difficulty 4–5; easier questions are ignored.", Value=p.BestHardStreak, AchievedUtc=p.BestHardStreakUtc },
+        new() { Key="systems_week", Label="Systems Advanced in a Week", Definition="Unique systems whose mastery state increased in one UTC Monday–Sunday week.", Value=p.SystemsAdvancedWeek.Value, Detail=p.SystemsAdvancedWeek.Detail, AchievedUtc=p.SystemsAdvancedWeek.AchievedUtc, TrackingFromLaunch=true },
+        new() { Key="reviews_week", Label="Review Queue Reduction", Definition="Largest weekly decrease in pending reviews.", Value=p.ReviewQueueReduction.Value, SampleSize=p.ReviewQueueReduction.SampleSize, Detail=p.ReviewQueueReduction.Detail, AchievedUtc=p.ReviewQueueReduction.AchievedUtc, TrackingFromLaunch=true },
+        new() { Key="weak_gain", Label="Weak-System Improvement", Definition="Largest weekly mastery-score gain in a system that began below 75 with at least five questions of evidence.", Value=p.WeakSystemImprovement.Value, SampleSize=p.WeakSystemImprovement.SampleSize, Detail=p.WeakSystemImprovement.Detail, AchievedUtc=p.WeakSystemImprovement.AchievedUtc, TrackingFromLaunch=true }
+    ];
+
+    private static List<ProgressionSystemSnapshot> Snapshots(IEnumerable<DashboardSystemPerformance> systems) => systems.Select(x => new ProgressionSystemSnapshot
+        { System=x.System, StateOrdinal=ProgressionPolicy.State(x.MasteryState), MasteryScore=x.MasteryScore, DistinctQuestions=x.DistinctQuestions }).ToList();
+    private static DateTime WeekStart(DateTime value) => value.Date.AddDays(-((7 + (int)value.DayOfWeek - (int)DayOfWeek.Monday) % 7));
+    private sealed record Evidence(List<QuestionAttempt> Attempts, List<QuestionReviewAttempt> Reviews, List<ReviewQueueItem> Queue, List<StudySession> Sessions,
+        IReadOnlyDictionary<string, Question> Questions, List<DashboardSystemPerformance> Systems, int Retention, int Pending);
+}

api/QuestionsApi/Services/UserProfileStore.cs

@@ -20,7 +20,8 @@ public sealed class UserProfileStore
         "ExternalIdentities", "ExternalAuthTransactions",
         "FlashcardDecks", "FlashcardNotes", "FlashcardSchedules", "FlashcardReviewLogs",
         "FlashcardMediaAssets", "FlashcardSettings", "FlashcardImportPreviews",
-        "UserCreditAccounts", "CreditLedgerEntries", "StudySessions", "DailyMissionSets", "WeeklyGoals"
+        "UserCreditAccounts", "CreditLedgerEntries", "StudySessions", "DailyMissionSets", "WeeklyGoals",
+        "UserProgressions", "ProgressionWeeklySnapshots"
     ];
 
     public UserProfileStore(MongoDatabaseProvider mongo)