@playcademy/sandbox 0.4.0 → 0.4.1-beta.2

package/dist/server.js

@@ -242,11 +242,12 @@ var init_platform = __esm(() => {
 var PLATFORM_TIMEZONE = "America/New_York";
 
 // ../constants/src/timeback.ts
-var TIMEBACK_ROUTES, TIMEBACK_ORG_SOURCED_ID = "PLAYCADEMY", TIMEBACK_ORG_NAME = "Playcademy Studios", TIMEBACK_ORG_TYPE = "department", TIMEBACK_COURSE_DEFAULTS, TIMEBACK_RESOURCE_DEFAULTS, TIMEBACK_COMPONENT_DEFAULTS, TIMEBACK_COMPONENT_RESOURCE_DEFAULTS;
+var TIMEBACK_ROUTES, TIMEBACK_ORG_SOURCED_ID = "PLAYCADEMY", TIMEBACK_ORG_NAME = "Playcademy Studios", TIMEBACK_ORG_TYPE = "department", TIMEBACK_COURSE_DEFAULTS, TIMEBACK_RESOURCE_DEFAULTS, TIMEBACK_COMPONENT_DEFAULTS, TIMEBACK_COMPONENT_RESOURCE_DEFAULTS, TIMEBACK_GAME_METRIC_DECIMAL_PLACES, TIMEBACK_GAME_METRIC_COMPARISON_TOLERANCE;
 var init_timeback2 = __esm(() => {
   TIMEBACK_ROUTES = {
     END_ACTIVITY: "/integrations/timeback/end-activity",
     GET_XP: "/integrations/timeback/xp",
+    GET_MASTERY: "/integrations/timeback/mastery",
     HEARTBEAT: "/integrations/timeback/heartbeat",
     ADVANCE_COURSE: "/integrations/timeback/advance-course"
   };
@@ -286,6 +287,17 @@ var init_timeback2 = __esm(() => {
     sortOrder: 1,
     lessonType: "quiz"
   };
+  TIMEBACK_GAME_METRIC_DECIMAL_PLACES = {
+    xp: 1,
+    mastery: 0,
+    score: 2
+  };
+  TIMEBACK_GAME_METRIC_COMPARISON_TOLERANCE = {
+    xp: 0.5 / 10 ** TIMEBACK_GAME_METRIC_DECIMAL_PLACES.xp,
+    mastery: 0,
+    time: 60,
+    score: 0.5 / 10 ** TIMEBACK_GAME_METRIC_DECIMAL_PLACES.score
+  };
 });
 
 // ../constants/src/cloudflare.ts
@@ -1063,7 +1075,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@playcademy/sandbox",
-    version: "0.4.0",
+    version: "0.4.1-beta.2",
     description: "Local development server for Playcademy game development",
     type: "module",
     exports: {
@@ -28233,6 +28245,7 @@ var init_constants3 = __esm(() => {
     TIMEBACK: {
       END_ACTIVITY: `/api${TIMEBACK_ROUTES.END_ACTIVITY}`,
       GET_XP: `/api${TIMEBACK_ROUTES.GET_XP}`,
+      GET_MASTERY: `/api${TIMEBACK_ROUTES.GET_MASTERY}`,
       HEARTBEAT: `/api${TIMEBACK_ROUTES.HEARTBEAT}`,
       ADVANCE_COURSE: `/api${TIMEBACK_ROUTES.ADVANCE_COURSE}`
     }
@@ -29888,7 +29901,7 @@ function isValidAdminAttributionDate(value) {
   const date3 = new Date(Date.UTC(year, month - 1, day, 12, 0, 0));
   return date3.getUTCFullYear() === year && date3.getUTCMonth() + 1 === month && date3.getUTCDate() === day;
 }
-var TIMEBACK_GRADES, TIMEBACK_SUBJECTS4, TimebackGradeSchema, TimebackSubjectSchema, CourseGoalsSchema, UpdateGameTimebackIntegrationRequestSchema, TimebackActivityDataSchema, EndActivityRequestSchema, GameActivityMetricsSchema, GameCourseMetricsSchema, GameMetricsResponseSchema, AdvanceCourseRequestSchema, HeartbeatRequestSchema, PopulateStudentRequestSchema, DerivedPlatformCourseConfigSchema, TimebackBaseConfigSchema, PlatformTimebackSetupRequestSchema, AdminTimebackMutationBaseSchema, AdminAttributionDateSchema, ADMIN_GRANT_XP_MIN = -1e5, ADMIN_GRANT_XP_MAX = 1e5, ADMIN_GRANT_XP_AMOUNT_RANGE_MESSAGE, GrantTimebackXpRequestSchema, AdjustTimebackTimeRequestSchema, AdjustTimebackMasteryRequestSchema, ReconcileMasteryForConfigChangeSchema, EnrollStudentRequestSchema, UnenrollStudentRequestSchema, ReactivateEnrollmentRequestSchema, InsertAssessmentTestSchema, CreateAssessmentRequestSchema, ReorderAssessmentsRequestSchema, ReorderQuestionsRequestSchema;
+var TIMEBACK_GRADES, TIMEBACK_SUBJECTS4, TimebackGradeSchema, TimebackSubjectSchema, CourseGoalsSchema, UpdateGameTimebackIntegrationRequestSchema, TimebackActivityDataSchema, EndActivityRequestSchema, GameRunMetricsSchema, GameCourseMetricsSchema, GameMetricsResponseSchema, AdvanceCourseRequestSchema, HeartbeatRequestSchema, PopulateStudentRequestSchema, DerivedPlatformCourseConfigSchema, TimebackBaseConfigSchema, PlatformTimebackSetupRequestSchema, AdminTimebackMutationBaseSchema, AdminAttributionDateSchema, ADMIN_GRANT_XP_MIN = -1e5, ADMIN_GRANT_XP_MAX = 1e5, ADMIN_GRANT_XP_AMOUNT_RANGE_MESSAGE, GrantTimebackXpRequestSchema, AdjustTimebackTimeRequestSchema, AdjustTimebackMasteryRequestSchema, ReconcileMasteryForConfigChangeSchema, EnrollStudentRequestSchema, UnenrollStudentRequestSchema, ReactivateEnrollmentRequestSchema, InsertAssessmentTestSchema, CreateAssessmentRequestSchema, ReorderAssessmentsRequestSchema, ReorderQuestionsRequestSchema;
 var init_schemas4 = __esm(() => {
   init_drizzle_zod();
   init_esm();
@@ -29957,24 +29970,28 @@ var init_schemas4 = __esm(() => {
     }).optional(),
     xpEarned: exports_external.number().optional(),
     masteredUnits: exports_external.number().optional(),
+    masteredUnitsAbsolute: exports_external.number().int().nonnegative().optional(),
     extensions: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
+  }).refine((data) => !(data.masteredUnits !== undefined && data.masteredUnitsAbsolute !== undefined), {
+    message: "Cannot provide both masteredUnits and masteredUnitsAbsolute",
+    path: ["masteredUnitsAbsolute"]
   });
-  GameActivityMetricsSchema = exports_external.object({
+  GameRunMetricsSchema = exports_external.object({
+    runId: exports_external.string().uuid(),
     activityId: exports_external.string().min(1),
     activityName: exports_external.string().optional(),
-    totalXp: exports_external.number().nonnegative(),
-    masteredUnits: exports_external.number().int().nonnegative(),
-    activeTimeSeconds: exports_external.number().nonnegative(),
-    completionCount: exports_external.number().int().nonnegative(),
-    lastCompletedAt: exports_external.string().datetime().optional()
+    totalXp: exports_external.number().nonnegative().optional(),
+    masteredUnits: exports_external.number().int().nonnegative().optional(),
+    activeTimeSeconds: exports_external.number().nonnegative().optional(),
+    score: exports_external.number().min(0).max(100).optional()
   });
   GameCourseMetricsSchema = exports_external.object({
     grade: TimebackGradeSchema,
     subject: TimebackSubjectSchema,
-    totalXp: exports_external.number().nonnegative(),
-    masteredUnits: exports_external.number().int().nonnegative(),
-    activeTimeSeconds: exports_external.number().nonnegative(),
-    activities: exports_external.array(GameActivityMetricsSchema).optional()
+    totalXp: exports_external.number().nonnegative().optional(),
+    masteredUnits: exports_external.number().int().nonnegative().optional(),
+    activeTimeSeconds: exports_external.number().nonnegative().optional(),
+    activities: exports_external.array(GameRunMetricsSchema).optional()
   });
   GameMetricsResponseSchema = exports_external.object({
     studentId: exports_external.string().min(1),
@@ -30251,6 +30268,124 @@ var init_timeback_admin_util = __esm(() => {
   init_errors();
 });
 
+// ../api-core/src/utils/timeback-game-metrics-comparison.util.ts
+function createMetricRow(definition) {
+  const { gameValue, kind, metric, timebackValue, tolerance } = definition;
+  if (timebackValue === undefined && gameValue === undefined) {
+    return null;
+  }
+  if (gameValue === undefined) {
+    return {
+      metric,
+      kind,
+      status: "not_reported_by_game",
+      ...timebackValue !== undefined ? { timebackValue } : {}
+    };
+  }
+  if (timebackValue === undefined) {
+    return {
+      metric,
+      kind,
+      status: "not_recorded_by_timeback",
+      gameValue
+    };
+  }
+  const delta = gameValue - timebackValue;
+  const isDiscrepant = tolerance === 0 ? delta !== 0 : Math.abs(delta) >= tolerance;
+  return {
+    metric,
+    kind,
+    status: isDiscrepant ? "discrepant" : "matched",
+    timebackValue,
+    gameValue,
+    delta
+  };
+}
+function createRunComparison(activity, gameRun) {
+  const runId = activity.runId ?? "";
+  if (!gameRun) {
+    return {
+      runId,
+      status: "not_reported",
+      discrepancyCount: 0,
+      rows: []
+    };
+  }
+  const rows = [
+    createMetricRow({
+      metric: "xp",
+      kind: "number",
+      timebackValue: activity.xpDelta,
+      gameValue: gameRun.totalXp,
+      tolerance: TIMEBACK_GAME_METRIC_COMPARISON_TOLERANCE.xp
+    }),
+    createMetricRow({
+      metric: "mastery",
+      kind: "number",
+      timebackValue: activity.masteredUnitsDelta,
+      gameValue: gameRun.masteredUnits,
+      tolerance: TIMEBACK_GAME_METRIC_COMPARISON_TOLERANCE.mastery
+    }),
+    createMetricRow({
+      metric: "time",
+      kind: "time",
+      timebackValue: activity.timeDeltaSeconds,
+      gameValue: gameRun.activeTimeSeconds,
+      tolerance: TIMEBACK_GAME_METRIC_COMPARISON_TOLERANCE.time
+    }),
+    createMetricRow({
+      metric: "score",
+      kind: "percent",
+      timebackValue: activity.score,
+      gameValue: gameRun.score,
+      tolerance: TIMEBACK_GAME_METRIC_COMPARISON_TOLERANCE.score
+    })
+  ].filter((row) => row !== null);
+  const discrepancyCount = rows.filter((row) => row.status === "discrepant").length;
+  return {
+    runId,
+    status: discrepancyCount > 0 ? "discrepant" : "matched",
+    discrepancyCount,
+    rows
+  };
+}
+function summarizeGameRunMetricsComparison(comparison) {
+  return {
+    runId: comparison.runId,
+    status: comparison.status,
+    discrepancyCount: comparison.discrepancyCount,
+    ...comparison.reason ? { reason: comparison.reason } : {}
+  };
+}
+function buildGameRunMetricComparisons(activities, course, response) {
+  const activitiesWithRunIds = activities.filter((activity) => typeof activity.runId === "string" && activity.runId.length > 0);
+  const comparisons = new Map;
+  if (activitiesWithRunIds.length === 0) {
+    return comparisons;
+  }
+  if (!response.supported) {
+    for (const activity of activitiesWithRunIds) {
+      comparisons.set(activity.runId, {
+        runId: activity.runId,
+        status: "unavailable",
+        discrepancyCount: 0,
+        reason: response.reason,
+        rows: []
+      });
+    }
+    return comparisons;
+  }
+  const gameCourseMetrics = response.metrics.courses.find((gameCourse) => gameCourse.grade === course.grade && gameCourse.subject === course.subject);
+  const gameRunsById = new Map(gameCourseMetrics?.activities?.map((gameRun) => [gameRun.runId.toLowerCase(), gameRun]));
+  for (const activity of activitiesWithRunIds) {
+    comparisons.set(activity.runId, createRunComparison(activity, gameRunsById.get(activity.runId.toLowerCase())));
+  }
+  return comparisons;
+}
+var init_timeback_game_metrics_comparison_util = __esm(() => {
+  init_src();
+});
+
 // ../api-core/src/utils/timeback-mastery-completion.util.ts
 async function upsertMasteryCompletionEntry(params) {
   const { client, courseId, studentId, appName, action } = params;
@@ -30328,7 +30463,7 @@ function mapEnrollmentsToUserEnrollments(enrollments, integrations) {
       subject: integration.subject,
       courseId: integration.courseId,
       orgId: courseToSchool.get(integration.courseId),
-      ...enrollment ? { enrollmentIds: { active: enrollment.sourcedId } } : {}
+      ...enrollment ? { id: enrollment.sourcedId } : {}
     };
   });
 }
@@ -30641,6 +30776,8 @@ class TimebackAdminService {
   static ANALYTICS_CONCURRENCY = 8;
   static MASTERABLE_UNITS_CONCURRENCY = 4;
   static GAME_METRICS_FETCH_TIMEOUT_MS = 1e4;
+  static GAME_METRICS_LIST_FETCH_TIMEOUT_MS = 3000;
+  static GAME_METRICS_RUN_IDS_PER_REQUEST = 50;
   constructor(deps) {
     this.deps = deps;
   }
@@ -30650,13 +30787,42 @@ class TimebackAdminService {
     }
     return this.deps.config.localGameUrls[slug2] ?? deployedUrl;
   }
-  static resolveGameMetricsUrl(baseUrl) {
+  static resolveGameMetricsUrl(baseUrl, runIds) {
     try {
-      return new URL("/__playcademy/metrics", baseUrl);
+      const url2 = new URL("/__playcademy/metrics", baseUrl);
+      for (const runId of runIds ?? []) {
+        url2.searchParams.append("runId", runId);
+      }
+      return url2;
     } catch {
       return null;
     }
   }
+  static normalizeRunIds(runIds, limit = Number.POSITIVE_INFINITY) {
+    const normalized = [];
+    const seen = new Set;
+    for (const runId of runIds ?? []) {
+      const value = runId.trim().toLowerCase();
+      if (isValidUUID(value) && !seen.has(value)) {
+        seen.add(value);
+        normalized.push(value);
+        if (normalized.length >= limit) {
+          break;
+        }
+      }
+    }
+    return normalized;
+  }
+  static chunkRunIds(runIds) {
+    const chunks = [];
+    for (let index2 = 0;index2 < runIds.length; index2 += this.GAME_METRICS_RUN_IDS_PER_REQUEST) {
+      chunks.push(runIds.slice(index2, index2 + this.GAME_METRICS_RUN_IDS_PER_REQUEST));
+    }
+    return chunks;
+  }
+  static isAbortError(error) {
+    return error instanceof Error && error.name === "AbortError";
+  }
   static roundXpToTenths(value) {
     const rounded = Math.round(value * TimebackAdminService.XP_PRECISION_FACTOR) / TimebackAdminService.XP_PRECISION_FACTOR;
     return Object.is(rounded, -0) ? 0 : rounded;
@@ -30817,6 +30983,56 @@ class TimebackAdminService {
     const remediationItems = events.map((event) => mapCaliperEventToRemediationActivity(event, relevantCourseIds)).filter((item) => Boolean(item));
     return [...groupedGameplayItems, ...remediationItems].toSorted((a, b) => b.occurredAt.localeCompare(a.occurredAt));
   }
+  async getGameMetricComparisonsForActivities(user, options) {
+    const runIds = TimebackAdminService.normalizeRunIds(options.activities.map((activity) => activity.runId).filter((runId) => Boolean(runId)));
+    if (runIds.length === 0) {
+      return new Map;
+    }
+    const activitiesByRunId = new Map(options.activities.filter((activity) => typeof activity.runId === "string" && activity.runId.length > 0).map((activity) => [activity.runId.toLowerCase(), activity]));
+    const comparisons = new Map;
+    await Promise.all(TimebackAdminService.chunkRunIds(runIds).map(async (chunk) => {
+      const activities = [];
+      for (const runId of chunk) {
+        const activity = activitiesByRunId.get(runId);
+        if (activity) {
+          activities.push(activity);
+        }
+      }
+      if (activities.length === 0) {
+        return;
+      }
+      let response;
+      try {
+        response = await this.getGameMetrics(options.gameId, options.studentId, user, {
+          runIds: chunk,
+          timeoutMs: options.timeoutMs
+        });
+      } catch (error) {
+        response = {
+          supported: false,
+          reason: "fetch_failed",
+          details: error instanceof Error ? error.message : String(error)
+        };
+      }
+      for (const [runId, comparison] of buildGameRunMetricComparisons(activities, options.course, response)) {
+        comparisons.set(runId, comparison);
+      }
+    }));
+    return comparisons;
+  }
+  async attachGameMetricSummariesToActivities(user, options) {
+    const comparisons = await this.getGameMetricComparisonsForActivities(user, options);
+    if (comparisons.size === 0) {
+      return [...options.activities];
+    }
+    return options.activities.map((activity) => {
+      const comparison = activity.runId ? comparisons.get(activity.runId) : undefined;
+      return comparison ? {
+        ...activity,
+        gameMetricsComparison: summarizeGameRunMetricsComparison(comparison)
+      } : activity;
+    });
+  }
   async getStudentEnrollmentsByCourseId(client, studentId, courseIds, options) {
     const enrollments = new Map;
     const allEnrollments = new Map;
@@ -30976,7 +31192,7 @@ class TimebackAdminService {
     });
     return { gameId, courseId, students: deduped };
   }
-  async getGameMetrics(gameId, timebackId, user) {
+  async getGameMetrics(gameId, timebackId, user, options) {
     const client = this.requireClient();
     await this.deps.validateGameManagementAccess(user, gameId);
     const [targetUser, integrations, game2, deployment] = await Promise.all([
@@ -31011,7 +31227,8 @@ class TimebackAdminService {
     if (!metricsBaseUrl) {
       return { supported: false, reason: "no_active_deployment" };
     }
-    const metricsUrl = TimebackAdminService.resolveGameMetricsUrl(metricsBaseUrl);
+    const runIds = TimebackAdminService.normalizeRunIds(options?.runIds, TimebackAdminService.GAME_METRICS_RUN_IDS_PER_REQUEST);
+    const metricsUrl = TimebackAdminService.resolveGameMetricsUrl(metricsBaseUrl, runIds);
     if (!metricsUrl) {
       return {
         supported: false,
@@ -31021,7 +31238,7 @@ class TimebackAdminService {
     }
     const token = await this.deps.mintPlatformServiceToken(gameId, targetUser.id);
     const controller = new AbortController;
-    const timeout = setTimeout(() => controller.abort(), TimebackAdminService.GAME_METRICS_FETCH_TIMEOUT_MS);
+    const timeout = setTimeout(() => controller.abort(), options?.timeoutMs ?? TimebackAdminService.GAME_METRICS_FETCH_TIMEOUT_MS);
     let response;
     try {
       response = await fetch(metricsUrl, {
@@ -31033,10 +31250,19 @@ class TimebackAdminService {
         signal: controller.signal
       });
     } catch (error) {
+      const timedOut = TimebackAdminService.isAbortError(error);
+      let details;
+      if (timedOut) {
+        details = "Game metrics request timed out";
+      } else if (error instanceof Error) {
+        details = error.message;
+      } else {
+        details = String(error);
+      }
       return {
         supported: false,
-        reason: "fetch_failed",
-        details: error instanceof Error ? error.message : String(error)
+        reason: timedOut ? "timeout" : "fetch_failed",
+        details
       };
     } finally {
       clearTimeout(timeout);
@@ -31140,7 +31366,14 @@ class TimebackAdminService {
     const allActivities = await this.listRecentActivityForStudent(client, studentId, gameSource, relevantCourseIds, fetchLimit);
     const activities = allActivities.slice(safeOffset, safeOffset + safeLimit);
     const hasMore = allActivities.length > safeOffset + safeLimit;
-    return { activities, hasMore };
+    const activitiesWithGameMetrics = await this.attachGameMetricSummariesToActivities(user, {
+      gameId,
+      studentId,
+      course: { grade: integration.grade, subject: integration.subject },
+      activities,
+      timeoutMs: TimebackAdminService.GAME_METRICS_LIST_FETCH_TIMEOUT_MS
+    });
+    return { activities: activitiesWithGameMetrics, hasMore };
   }
   async getActivityDetail(user, options) {
     const { gameId, studentId, courseId, activityId, runId } = options;
@@ -31176,7 +31409,22 @@ class TimebackAdminService {
     if (!activity) {
       throw new NotFoundError("Activity", activityId);
     }
-    return { activity, rawEvents: matchedEvents };
+    const comparisons = await this.getGameMetricComparisonsForActivities(user, {
+      gameId,
+      studentId,
+      course: { grade: integration.grade, subject: integration.subject },
+      activities: [activity]
+    });
+    const gameMetricsComparison = activity.runId ? comparisons.get(activity.runId) : undefined;
+    const activityWithGameMetrics = gameMetricsComparison ? {
+      ...activity,
+      gameMetricsComparison: summarizeGameRunMetricsComparison(gameMetricsComparison)
+    } : activity;
+    return {
+      activity: activityWithGameMetrics,
+      rawEvents: matchedEvents,
+      ...gameMetricsComparison ? { gameMetricsComparison } : {}
+    };
   }
   async grantManualXp(data, user) {
     const { client, sensorUrl, appName, actor } = await this.resolveAdminMutationContext(data.gameId, data.courseId, user, data.studentId);
@@ -31464,6 +31712,7 @@ var init_timeback_admin_service = __esm(() => {
   init_errors();
   init_timeback_admin_metrics_util();
   init_timeback_admin_util();
+  init_timeback_game_metrics_comparison_util();
   init_timeback_mastery_completion_util();
   init_timeback_util();
   logger17 = log.scope("TimebackAdminService");
@@ -32885,6 +33134,7 @@ var init_timeback_service = __esm(() => {
       sessionTimingData,
       xpEarned,
       masteredUnits,
+      masteredUnitsAbsolute,
       extensions,
       user
     }) {
@@ -32908,6 +33158,7 @@ var init_timeback_service = __esm(() => {
         durationSeconds: timingData.durationSeconds,
         xpEarned,
         masteredUnits,
+        masteredUnitsAbsolute,
         extensions: extensionsWithResumeId,
         activityId: activityData.activityId,
         activityName: activityData.activityName,
@@ -33156,6 +33407,46 @@ var init_timeback_service = __esm(() => {
       });
       return result;
     }
+    async getStudentMastery(timebackId, user, options) {
+      const client = this.requireClient();
+      const db2 = this.deps.db;
+      await this.deps.validateDeveloperAccess(user, options.gameId);
+      const conditions2 = [eq(gameTimebackIntegrations.gameId, options.gameId)];
+      if (options.grade !== undefined && options.subject) {
+        conditions2.push(eq(gameTimebackIntegrations.grade, options.grade));
+        conditions2.push(eq(gameTimebackIntegrations.subject, options.subject));
+      }
+      const integrations = await db2.query.gameTimebackIntegrations.findMany({
+        where: and(...conditions2)
+      });
+      const courseIds = integrations.map((i2) => i2.courseId);
+      if (courseIds.length === 0) {
+        logger20.debug("No integrations found for game, returning empty mastery", {
+          timebackId,
+          gameId: options.gameId,
+          grade: options.grade,
+          subject: options.subject
+        });
+        return {
+          totalMasteredUnits: 0,
+          totalMasterableUnits: 0,
+          ...options.include?.perCourse && { courses: [] }
+        };
+      }
+      const result = await client.getStudentMastery(timebackId, {
+        courseIds,
+        include: options.include
+      });
+      logger20.debug("Retrieved student mastery", {
+        timebackId,
+        gameId: options.gameId,
+        grade: options.grade,
+        subject: options.subject,
+        totalMasteredUnits: result.totalMasteredUnits,
+        courseCount: result.courses?.length
+      });
+      return result;
+    }
   };
 });
 
@@ -35481,15 +35772,18 @@ class MasteryTracker {
     this.edubridgeNamespace = edubridgeNamespace;
   }
   async checkProgress(input) {
-    const { studentId, courseId, resourceId, masteredUnits } = input;
-    if (typeof masteredUnits !== "number" || masteredUnits === 0) {
+    const { studentId, courseId, resourceId, masteredUnits, masteredUnitsAbsolute } = input;
+    const hasIncremental = typeof masteredUnits === "number" && masteredUnits !== 0;
+    const hasAbsolute = typeof masteredUnitsAbsolute === "number";
+    if (!hasIncremental && !hasAbsolute) {
       return;
     }
     const status = await this.calculateStatus({
       studentId,
       courseId,
       resourceId,
-      additionalMasteredUnits: masteredUnits
+      additionalMasteredUnits: hasAbsolute ? 0 : masteredUnits,
+      absoluteMasteredUnits: hasAbsolute ? masteredUnitsAbsolute : undefined
     });
     if (!status) {
       return;
@@ -35498,7 +35792,8 @@ class MasteryTracker {
     return {
       pctCompleteApp: status.pctCompleteApp,
       masteryAchieved: !wasComplete && status.isComplete,
-      masteryRevoked: wasComplete && !status.isComplete
+      masteryRevoked: wasComplete && !status.isComplete,
+      effectiveDelta: status.effectiveDelta
     };
   }
   async getStatus(input) {
@@ -35520,7 +35815,8 @@ class MasteryTracker {
     studentId,
     courseId,
     resourceId,
-    additionalMasteredUnits
+    additionalMasteredUnits,
+    absoluteMasteredUnits
   }) {
     const masterableUnits = await this.resolveMasterableUnits(resourceId);
     if (!masterableUnits || masterableUnits <= 0) {
@@ -35539,7 +35835,15 @@ class MasteryTracker {
       return;
     }
     const historicalMasteredUnits = this.sumAnalyticsMetric(facts, "masteredUnits");
-    const totalMastered = Math.max(0, historicalMasteredUnits + additionalMasteredUnits);
+    let totalMastered;
+    let effectiveDelta;
+    if (absoluteMasteredUnits !== undefined) {
+      totalMastered = Math.max(0, absoluteMasteredUnits);
+      effectiveDelta = totalMastered - historicalMasteredUnits;
+    } else {
+      effectiveDelta = additionalMasteredUnits;
+      totalMastered = Math.max(0, historicalMasteredUnits + effectiveDelta);
+    }
     const rawPct = totalMastered / masterableUnits * 100;
     const pctCompleteApp = Math.min(100, Math.max(0, Math.round(rawPct)));
     return {
@@ -35547,7 +35851,8 @@ class MasteryTracker {
       masterableUnits,
       pctCompleteApp,
       isComplete: totalMastered >= masterableUnits,
-      historicalMasteredUnits
+      historicalMasteredUnits,
+      effectiveDelta
     };
   }
   async createCompletionEntry(studentId, courseId, classId, appName) {
@@ -35776,7 +36081,7 @@ class ProgressRecorder {
     validateProgressData(progressData);
     const { ids, activityId, activityName, courseName, student } = await this.resolveContext(courseId, studentIdentifier, progressData);
     const { id: studentId, email: studentEmail } = student;
-    const { score, totalQuestions, correctQuestions, xpEarned, masteredUnits, attemptNumber } = progressData;
+    const { score, totalQuestions, correctQuestions, xpEarned, attemptNumber } = progressData;
     const actualLineItemId = await this.resolveAssessmentLineItem(activityId, activityName, progressData.classId, ids);
     const currentAttemptNumber = await this.resolveAttemptNumber(attemptNumber, score, studentId, actualLineItemId);
     const calculatedXp = this.calculateXpForProgress(progressData, totalQuestions, correctQuestions, xpEarned, currentAttemptNumber);
@@ -35785,8 +36090,10 @@ class ProgressRecorder {
       studentId,
       courseId,
       resourceId: ids.resource,
-      masteredUnits: progressData.masteredUnits ?? 0
+      masteredUnits: progressData.masteredUnits ?? 0,
+      masteredUnitsAbsolute: progressData.masteredUnitsAbsolute
     });
+    const effectiveMasteredUnits = masteryProgress ? masteryProgress.effectiveDelta : progressData.masteredUnits ?? 0;
     let pctCompleteApp;
     let masteryAchieved = false;
     let scoreStatus = SCORE_STATUS5.fullyGraded;
@@ -35814,7 +36121,7 @@ class ProgressRecorder {
         appName: progressData.appName,
         totalQuestions,
         correctQuestions,
-        masteredUnits,
+        masteredUnits: effectiveMasteredUnits || undefined,
         pctCompleteApp
       });
     } else {
@@ -35852,7 +36159,7 @@ class ProgressRecorder {
       totalQuestions,
       correctQuestions,
       xpEarned: calculatedXp,
-      masteredUnits,
+      masteredUnits: effectiveMasteredUnits || undefined,
       attemptNumber: currentAttemptNumber,
       progressData,
       extensions,
@@ -35861,7 +36168,7 @@ class ProgressRecorder {
     return {
       xpAwarded: calculatedXp,
       attemptNumber: currentAttemptNumber,
-      masteredUnitsApplied: progressData.masteredUnits ?? 0,
+      masteredUnitsApplied: effectiveMasteredUnits,
       pctCompleteApp,
       scoreStatus,
       inProgress
@@ -36396,6 +36703,65 @@ class TimebackClient {
       resourceId: ids.resource
     });
   }
+  async getStudentMastery(studentId, options) {
+    await this._ensureAuthenticated();
+    const enrollments = await this.edubridge.enrollments.listByUser(studentId);
+    const filteredEnrollments = options?.courseIds?.length ? enrollments.filter((e) => options.courseIds.includes(e.course.id)) : enrollments;
+    if (filteredEnrollments.length === 0) {
+      return {
+        totalMasteredUnits: 0,
+        totalMasterableUnits: 0,
+        ...options?.include?.perCourse && { courses: [] }
+      };
+    }
+    const masteryResults = await Promise.all(filteredEnrollments.map(async (enrollment) => {
+      try {
+        const ids = deriveSourcedIds2(enrollment.course.id);
+        const status = await this.masteryTracker.getStatus({
+          studentId,
+          courseId: enrollment.course.id,
+          resourceId: ids.resource
+        });
+        return { enrollment, status };
+      } catch (error) {
+        log.warn("[TimebackClient] Failed to fetch mastery for enrollment", {
+          enrollmentId: enrollment.id,
+          error
+        });
+        return { enrollment, status: undefined };
+      }
+    }));
+    let totalMasteredUnits = 0;
+    let totalMasterableUnits = 0;
+    const courses = [];
+    for (const { enrollment, status } of masteryResults) {
+      const masteredUnits = status?.masteredUnits ?? 0;
+      const masterableUnits = status?.masterableUnits ?? 0;
+      totalMasteredUnits += masteredUnits;
+      totalMasterableUnits += masterableUnits;
+      if (options?.include?.perCourse) {
+        const gradeStr = enrollment.course.grades?.[0];
+        const parsedGrade = gradeStr ? parseInt(gradeStr, 10) : 0;
+        const grade = isTimebackGrade3(parsedGrade) ? parsedGrade : 0;
+        const subjectStr = enrollment.course.subjects?.[0];
+        const subject = subjectStr && isTimebackSubject3(subjectStr) ? subjectStr : "None";
+        courses.push({
+          grade,
+          subject,
+          title: enrollment.course.title,
+          masteredUnits,
+          masterableUnits,
+          pctComplete: status?.pctCompleteApp ?? 0,
+          isComplete: status?.isComplete ?? false
+        });
+      }
+    }
+    return {
+      totalMasteredUnits,
+      totalMasterableUnits,
+      ...options?.include?.perCourse && { courses }
+    };
+  }
   async getStudentXp(studentId, options) {
     await this._ensureAuthenticated();
     const enrollments = await this.edubridge.enrollments.listByUser(studentId);
@@ -93718,7 +94084,7 @@ var init_session_controller = __esm(() => {
 });
 
 // ../api-core/src/controllers/timeback.controller.ts
-var logger45, populateStudent, getUser, getUserEnrollments, getUserById, setupIntegration, getIntegrations, updateIntegration, getIntegrationConfig, verifyIntegration, getConfig, deleteIntegrations, endActivity, heartbeat, advanceCourse, getStudentXp, getRoster, getStudentOverview, getGameMetrics, getStudentActivity, getActivityDetail, grantXp, adjustTime, adjustMastery, reconcileMasteryForConfigChange, searchStudents, enrollStudent, unenrollStudent, reactivateEnrollment, listAssessments, createAssessment, deleteAssessment, reorderAssessments, reorderQuestions, activateAssessment, deactivateAssessment, listQuestions, createQuestion, updateQuestion, deleteQuestion, getAssessmentBankStatus, destroyAssessmentBank, timeback2;
+var logger45, populateStudent, getUser, getUserEnrollments, getUserById, setupIntegration, getIntegrations, updateIntegration, getIntegrationConfig, verifyIntegration, getConfig, deleteIntegrations, endActivity, heartbeat, advanceCourse, getStudentXp, getStudentMastery, getRoster, getStudentOverview, getGameMetrics, getStudentActivity, getActivityDetail, grantXp, adjustTime, adjustMastery, reconcileMasteryForConfigChange, searchStudents, enrollStudent, unenrollStudent, reactivateEnrollment, listAssessments, createAssessment, deleteAssessment, reorderAssessments, reorderQuestions, activateAssessment, deactivateAssessment, listQuestions, createQuestion, updateQuestion, deleteQuestion, getAssessmentBankStatus, destroyAssessmentBank, timeback2;
 var init_timeback_controller = __esm(() => {
   init_esm();
   init_schemas_index();
@@ -93876,6 +94242,7 @@ var init_timeback_controller = __esm(() => {
       sessionTimingData,
       xpEarned,
       masteredUnits,
+      masteredUnitsAbsolute,
       extensions
     } = body2;
     logger45.debug("Ending activity", { userId: ctx.user.id, gameId });
@@ -93890,6 +94257,7 @@ var init_timeback_controller = __esm(() => {
       sessionTimingData,
       xpEarned,
       masteredUnits,
+      masteredUnitsAbsolute,
       extensions,
       user: ctx.user
     });
@@ -93999,6 +94367,53 @@ var init_timeback_controller = __esm(() => {
       include
     });
   });
+  getStudentMastery = requireDeveloper(async (ctx) => {
+    const timebackId = ctx.params.timebackId;
+    if (!timebackId) {
+      throw ApiError.badRequest("Missing timebackId parameter");
+    }
+    const gameId = ctx.url.searchParams.get("gameId");
+    if (!gameId) {
+      throw ApiError.badRequest("Missing required gameId query parameter");
+    }
+    const gradeParam = ctx.url.searchParams.get("grade");
+    const subjectParam = ctx.url.searchParams.get("subject");
+    if (gradeParam !== null !== (subjectParam !== null)) {
+      throw ApiError.badRequest("Both grade and subject must be provided together");
+    }
+    let grade;
+    let subject;
+    if (gradeParam !== null && subjectParam !== null) {
+      const parsedGrade = parseInt(gradeParam, 10);
+      if (!isTimebackGrade2(parsedGrade)) {
+        throw ApiError.badRequest(`Invalid grade: ${gradeParam}. Valid grades: ${TIMEBACK_GRADES.join(", ")}`);
+      }
+      if (!isTimebackSubject2(subjectParam)) {
+        throw ApiError.badRequest(`Invalid subject: ${subjectParam}. Valid subjects: ${TIMEBACK_SUBJECTS4.join(", ")}`);
+      }
+      grade = parsedGrade;
+      subject = subjectParam;
+    }
+    const includeParam = ctx.url.searchParams.get("include");
+    const includeOptions = includeParam ? includeParam.split(",").map((opt) => opt.trim().toLowerCase()) : [];
+    const include = {
+      perCourse: includeOptions.includes("percourse")
+    };
+    logger45.debug("Getting student mastery", {
+      requesterId: ctx.user.id,
+      timebackId,
+      gameId,
+      grade,
+      subject,
+      include
+    });
+    return ctx.services.timeback.getStudentMastery(timebackId, ctx.user, {
+      gameId,
+      grade,
+      subject,
+      include
+    });
+  });
   getRoster = requireGameManagementAccess(async (ctx) => {
     const gameId = ctx.params.gameId;
     const courseId = ctx.params.courseId;
@@ -94034,15 +94449,19 @@ var init_timeback_controller = __esm(() => {
   getGameMetrics = requireGameManagementAccess(async (ctx) => {
     const gameId = ctx.params.gameId;
     const timebackId = ctx.params.timebackId;
+    const runIds = [
+      ...new Set(ctx.url.searchParams.getAll("runId").map((runId) => runId.trim().toLowerCase()).filter(isValidUUID))
+    ];
     if (!gameId || !timebackId) {
       throw ApiError.badRequest("Missing gameId or timebackId path parameter");
     }
     logger45.debug("Getting game metrics", {
       requesterId: ctx.user.id,
       gameId,
-      timebackId
+      timebackId,
+      runIds
     });
-    return ctx.services.timebackAdmin.getGameMetrics(gameId, timebackId, ctx.user);
+    return ctx.services.timebackAdmin.getGameMetrics(gameId, timebackId, ctx.user, { runIds });
   });
   getStudentActivity = requireGameManagementAccess(async (ctx) => {
     const timebackId = ctx.params.timebackId;
@@ -94331,6 +94750,7 @@ var init_timeback_controller = __esm(() => {
     heartbeat,
     advanceCourse,
     getStudentXp,
+    getStudentMastery,
     getRoster,
     getStudentOverview,
     getGameMetrics,
@@ -95217,6 +95637,7 @@ var init_timeback6 = __esm(() => {
   init_controllers();
   init_errors();
   init_utils11();
+  init_schemas_index();
   init_api();
   init_error_handler();
   init_timeback5();
@@ -95296,6 +95717,14 @@ var init_timeback6 = __esm(() => {
       }
       if (gradeParam !== null && subjectParam !== null) {
         const grade = parseInt(gradeParam, 10);
+        if (!Number.isFinite(grade) || !isTimebackGrade2(grade)) {
+          const error2 = ApiError.badRequest(`Invalid grade: ${gradeParam}. Valid grades: ${TIMEBACK_GRADES.join(", ")}`);
+          return c2.json(createErrorResponse(error2), error2.status);
+        }
+        if (!isTimebackSubject2(subjectParam)) {
+          const error2 = ApiError.badRequest(`Invalid subject: ${subjectParam}. Valid subjects: ${TIMEBACK_SUBJECTS4.join(", ")}`);
+          return c2.json(createErrorResponse(error2), error2.status);
+        }
         enrollments = enrollments.filter((e) => e.grade === grade && e.subject === subjectParam);
       }
       const mockCourses = enrollments.map((e) => {
@@ -95320,6 +95749,62 @@ var init_timeback6 = __esm(() => {
     }
     return handle2(timeback2.getStudentXp)(c2);
   });
+  timebackRouter.get("/student-mastery/:timebackId", async (c2) => {
+    const user = c2.get("user");
+    if (!user) {
+      const error2 = ApiError.unauthorized("Must be logged in to get student mastery");
+      return c2.json(createErrorResponse(error2), error2.status);
+    }
+    if (shouldMockTimeback()) {
+      const url2 = new URL(c2.req.url);
+      const gradeParam = url2.searchParams.get("grade");
+      const subjectParam = url2.searchParams.get("subject");
+      const includeParam = url2.searchParams.get("include") || "";
+      const includeOptions = includeParam.split(",").map((opt) => opt.trim().toLowerCase());
+      const includePerCourse = includeOptions.includes("percourse");
+      const db2 = c2.get("db");
+      let enrollments = await getMockEnrollments(db2);
+      if (gradeParam !== null !== (subjectParam !== null)) {
+        const error2 = ApiError.badRequest("Both grade and subject must be provided together");
+        return c2.json(createErrorResponse(error2), error2.status);
+      }
+      if (gradeParam !== null && subjectParam !== null) {
+        const grade = parseInt(gradeParam, 10);
+        if (!Number.isFinite(grade) || !isTimebackGrade2(grade)) {
+          const error2 = ApiError.badRequest(`Invalid grade: ${gradeParam}. Valid grades: ${TIMEBACK_GRADES.join(", ")}`);
+          return c2.json(createErrorResponse(error2), error2.status);
+        }
+        if (!isTimebackSubject2(subjectParam)) {
+          const error2 = ApiError.badRequest(`Invalid subject: ${subjectParam}. Valid subjects: ${TIMEBACK_SUBJECTS4.join(", ")}`);
+          return c2.json(createErrorResponse(error2), error2.status);
+        }
+        enrollments = enrollments.filter((e) => e.grade === grade && e.subject === subjectParam);
+      }
+      const mockCourses = enrollments.map((e) => {
+        const seed3 = hashCode(`${e.grade}-${e.subject}`);
+        const masterableUnits = 5 + seed3 % 16;
+        const masteredUnits = seed3 % (masterableUnits + 1);
+        const pctComplete = masterableUnits > 0 ? Math.round(masteredUnits / masterableUnits * 1e4) / 100 : 0;
+        return {
+          grade: e.grade,
+          subject: e.subject,
+          title: `${e.subject} ${formatGradeLabel(e.grade)}`,
+          masteredUnits,
+          masterableUnits,
+          pctComplete,
+          isComplete: masteredUnits >= masterableUnits
+        };
+      });
+      const totalMasteredUnits = mockCourses.reduce((sum2, course) => sum2 + course.masteredUnits, 0);
+      const totalMasterableUnits = mockCourses.reduce((sum2, course) => sum2 + course.masterableUnits, 0);
+      return c2.json({
+        totalMasteredUnits,
+        totalMasterableUnits,
+        ...includePerCourse && { courses: mockCourses }
+      });
+    }
+    return handle2(timeback2.getStudentMastery)(c2);
+  });
 });
 
 // src/routes/integrations/lti.ts