@playcademy/sandbox 0.4.1-beta.1 → 0.4.1-beta.2

package/dist/cli.js

@@ -243,7 +243,7 @@ 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",
@@ -288,6 +288,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
@@ -1065,7 +1076,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@playcademy/sandbox",
-    version: "0.4.1-beta.1",
+    version: "0.4.1-beta.2",
     description: "Local development server for Playcademy game development",
     type: "module",
     exports: {
@@ -29891,7 +29902,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();
@@ -29966,22 +29977,22 @@ var init_schemas4 = __esm(() => {
     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),
@@ -30258,6 +30269,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;
@@ -30648,6 +30777,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;
   }
@@ -30657,13 +30788,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;
@@ -30824,6 +30984,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;
@@ -30983,7 +31193,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([
@@ -31018,7 +31228,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,
@@ -31028,7 +31239,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, {
@@ -31040,10 +31251,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);
@@ -31147,7 +31367,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;
@@ -31183,7 +31410,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);
@@ -31471,6 +31713,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");
@@ -94207,15 +94450,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;

package/dist/constants.js

@@ -78,7 +78,7 @@ 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_timeback = __esm(() => {
   TIMEBACK_ROUTES = {
     END_ACTIVITY: "/integrations/timeback/end-activity",
@@ -123,6 +123,17 @@ var init_timeback = __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

package/dist/server.js

@@ -242,7 +242,7 @@ 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",
@@ -287,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
@@ -1064,7 +1075,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@playcademy/sandbox",
-    version: "0.4.1-beta.1",
+    version: "0.4.1-beta.2",
     description: "Local development server for Playcademy game development",
     type: "module",
     exports: {
@@ -29890,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();
@@ -29965,22 +29976,22 @@ var init_schemas4 = __esm(() => {
     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),
@@ -30257,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;
@@ -30647,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;
   }
@@ -30656,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;
@@ -30823,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;
@@ -30982,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([
@@ -31017,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,
@@ -31027,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, {
@@ -31039,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);
@@ -31146,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;
@@ -31182,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);
@@ -31470,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");
@@ -94206,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;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@playcademy/sandbox",
-    "version": "0.4.1-beta.1",
+    "version": "0.4.1-beta.2",
     "description": "Local development server for Playcademy game development",
     "type": "module",
     "exports": {