@playcademy/sandbox 0.3.17-beta.7 → 0.3.17-beta.8

package/dist/server.js

@@ -398,7 +398,8 @@ var TIMEBACK_ROUTES, TIMEBACK_ORG_SOURCED_ID = "PLAYCADEMY", TIMEBACK_ORG_NAME =
 var init_timeback2 = __esm(() => {
   TIMEBACK_ROUTES = {
     END_ACTIVITY: "/integrations/timeback/end-activity",
-    GET_XP: "/integrations/timeback/xp"
+    GET_XP: "/integrations/timeback/xp",
+    HEARTBEAT: "/integrations/timeback/heartbeat"
   };
   TIMEBACK_COURSE_DEFAULTS = {
     gradingScheme: "STANDARD",
@@ -1309,7 +1310,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@playcademy/sandbox",
-    version: "0.3.17-beta.7",
+    version: "0.3.17-beta.8",
     description: "Local development server for Playcademy game development",
     type: "module",
     exports: {
@@ -28876,7 +28877,8 @@ var init_constants3 = __esm(() => {
     HEALTH: "/api/health",
     TIMEBACK: {
       END_ACTIVITY: `/api${TIMEBACK_ROUTES.END_ACTIVITY}`,
-      GET_XP: `/api${TIMEBACK_ROUTES.GET_XP}`
+      GET_XP: `/api${TIMEBACK_ROUTES.GET_XP}`,
+      HEARTBEAT: `/api${TIMEBACK_ROUTES.HEARTBEAT}`
     }
   };
 });
@@ -31279,589 +31281,703 @@ var init_timeback_admin_service = __esm(() => {
 });
 
 // ../api-core/src/services/timeback.service.ts
-class TimebackService {
-  deps;
-  constructor(deps) {
-    this.deps = deps;
-  }
-  requireClient() {
-    if (!this.deps.timeback) {
-      logger17.error("Timeback client not available in context");
-      throw new ValidationError("Timeback integration not available in this environment");
+var logger17, TimebackService;
+var init_timeback_service = __esm(() => {
+  init_drizzle_orm();
+  init_src();
+  init_tables_index();
+  init_src2();
+  init_types4();
+  init_src4();
+  init_errors();
+  init_timeback_util();
+  logger17 = log.scope("TimebackService");
+  TimebackService = class TimebackService {
+    static HEARTBEAT_DEDUPE_TTL_MS = 5 * 60 * 1000;
+    static processedHeartbeatWindows = new Map;
+    static inFlightHeartbeatWindows = new Map;
+    deps;
+    static cleanHeartbeatDedupeCache(now2 = Date.now()) {
+      for (const [key, timestamp3] of this.processedHeartbeatWindows) {
+        if (now2 - timestamp3 > this.HEARTBEAT_DEDUPE_TTL_MS) {
+          this.processedHeartbeatWindows.delete(key);
+        }
+      }
     }
-    return this.deps.timeback;
-  }
-  async getTodayXp(userId, date3, timezone2) {
-    const db2 = this.deps.db;
-    const tz = timezone2 || PLATFORM_TIMEZONE;
-    const base = date3 ? new Date(date3) : new Date;
-    if (isNaN(base.getTime())) {
-      throw new ValidationError("Invalid date format. Use ISO 8601 format.");
+    static isDuplicateHeartbeatWindow(key) {
+      this.cleanHeartbeatDedupeCache();
+      return this.processedHeartbeatWindows.has(key);
     }
-    try {
-      new Intl.DateTimeFormat(undefined, { timeZone: tz });
-    } catch {
-      throw new ValidationError(`Invalid timezone: ${tz}`);
+    static getInFlightHeartbeatWindow(key) {
+      return this.inFlightHeartbeatWindows.get(key);
     }
-    if (tz === PLATFORM_TIMEZONE) {
-      const todayMidnight = getUtcInstantForMidnight(base, tz);
-      const result2 = await db2.select({ xp: timebackDailyXp.xp, date: timebackDailyXp.date }).from(timebackDailyXp).where(and(eq(timebackDailyXp.userId, userId), eq(timebackDailyXp.date, todayMidnight))).limit(1);
-      if (result2.length === 0) {
-        return { xp: 0, date: todayMidnight.toISOString() };
-      }
-      return { xp: result2[0].xp, date: result2[0].date.toISOString() };
+    static markHeartbeatWindowProcessed(key) {
+      this.processedHeartbeatWindows.set(key, Date.now());
     }
-    const { startOfDay, endOfDay } = getDayBoundariesInTimezone(base, tz);
-    const result = await db2.select({ totalXp: sum(timebackXpEvents.xpDelta) }).from(timebackXpEvents).where(and(eq(timebackXpEvents.userId, userId), gte(timebackXpEvents.occurredAt, startOfDay), lte(timebackXpEvents.occurredAt, new Date(endOfDay.getTime() - 1))));
-    return { xp: Number(result[0]?.totalXp) || 0, date: startOfDay.toISOString() };
-  }
-  async getTotalXp(userId) {
-    const db2 = this.deps.db;
-    const result = await db2.select({ totalXp: sum(timebackDailyXp.xp) }).from(timebackDailyXp).where(eq(timebackDailyXp.userId, userId));
-    return { totalXp: Number(result[0]?.totalXp) || 0 };
-  }
-  async updateTodayXp(userId, data) {
-    const db2 = this.deps.db;
-    const { xp, userTimestamp } = data;
-    let targetDate;
-    if (userTimestamp) {
-      targetDate = new Date(userTimestamp);
-      if (isNaN(targetDate.getTime())) {
-        throw new ValidationError("Invalid userTimestamp format. Use ISO 8601 format.");
-      }
-      targetDate.setHours(0, 0, 0, 0);
-    } else {
-      targetDate = new Date;
-      targetDate.setUTCHours(0, 0, 0, 0);
+    static markHeartbeatWindowInFlight(key, promise) {
+      this.inFlightHeartbeatWindows.set(key, promise);
     }
-    const [result] = await db2.insert(timebackDailyXp).values({ userId, date: targetDate, xp }).onConflictDoUpdate({
-      target: [timebackDailyXp.userId, timebackDailyXp.date],
-      set: { xp: sql`excluded.xp`, updatedAt: new Date }
-    }).returning({ xp: timebackDailyXp.xp, date: timebackDailyXp.date });
-    if (!result) {
-      logger17.error("Daily XP upsert returned no rows", { userId, date: targetDate });
-      throw new InternalError("Failed to update daily XP record");
+    static clearInFlightHeartbeatWindow(key) {
+      this.inFlightHeartbeatWindows.delete(key);
     }
-    return { xp: result.xp, date: result.date.toISOString() };
-  }
-  async getXpHistory(userId, startDate, endDate) {
-    const db2 = this.deps.db;
-    const whereConditions = [eq(timebackDailyXp.userId, userId)];
-    if (startDate) {
-      const start2 = new Date(startDate);
-      start2.setUTCHours(0, 0, 0, 0);
-      whereConditions.push(gte(timebackDailyXp.date, start2));
+    constructor(deps) {
+      this.deps = deps;
     }
-    if (endDate) {
-      const end = new Date(endDate);
-      end.setUTCHours(23, 59, 59, 999);
-      whereConditions.push(lte(timebackDailyXp.date, end));
+    requireClient() {
+      if (!this.deps.timeback) {
+        logger17.error("Timeback client not available in context");
+        throw new ValidationError("Timeback integration not available in this environment");
+      }
+      return this.deps.timeback;
     }
-    const result = await db2.select({ date: timebackDailyXp.date, xp: timebackDailyXp.xp }).from(timebackDailyXp).where(and(...whereConditions)).orderBy(timebackDailyXp.date);
-    return {
-      history: result.map((row) => ({ date: row.date.toISOString(), xp: row.xp }))
-    };
-  }
-  async populateStudent(user, providedNames) {
-    const client = this.requireClient();
-    const db2 = this.deps.db;
-    const dbUser = await db2.query.users.findFirst({
-      where: eq(users.id, user.id),
-      columns: { id: true, timebackId: true }
-    });
-    if (dbUser?.timebackId) {
-      logger17.info("Student already onboarded", { userId: user.id });
-      return { status: "already_populated" };
+    async getTodayXp(userId, date3, timezone2) {
+      const db2 = this.deps.db;
+      const tz = timezone2 || PLATFORM_TIMEZONE;
+      const base = date3 ? new Date(date3) : new Date;
+      if (isNaN(base.getTime())) {
+        throw new ValidationError("Invalid date format. Use ISO 8601 format.");
+      }
+      try {
+        new Intl.DateTimeFormat(undefined, { timeZone: tz });
+      } catch {
+        throw new ValidationError(`Invalid timezone: ${tz}`);
+      }
+      if (tz === PLATFORM_TIMEZONE) {
+        const todayMidnight = getUtcInstantForMidnight(base, tz);
+        const result2 = await db2.select({ xp: timebackDailyXp.xp, date: timebackDailyXp.date }).from(timebackDailyXp).where(and(eq(timebackDailyXp.userId, userId), eq(timebackDailyXp.date, todayMidnight))).limit(1);
+        if (result2.length === 0) {
+          return { xp: 0, date: todayMidnight.toISOString() };
+        }
+        return { xp: result2[0].xp, date: result2[0].date.toISOString() };
+      }
+      const { startOfDay, endOfDay } = getDayBoundariesInTimezone(base, tz);
+      const result = await db2.select({ totalXp: sum(timebackXpEvents.xpDelta) }).from(timebackXpEvents).where(and(eq(timebackXpEvents.userId, userId), gte(timebackXpEvents.occurredAt, startOfDay), lte(timebackXpEvents.occurredAt, new Date(endOfDay.getTime() - 1))));
+      return { xp: Number(result[0]?.totalXp) || 0, date: startOfDay.toISOString() };
     }
-    let timebackId;
-    let name3;
-    try {
-      const existingUser = await client.oneroster.users.findByEmail(user.email);
-      timebackId = existingUser.sourcedId;
-      name3 = `${existingUser.givenName} ${existingUser.familyName}`;
-      logger17.info("Found existing student in OneRoster", {
-        userId: user.id,
-        timebackId
-      });
-    } catch {
-      if (!providedNames?.firstName || !providedNames?.lastName) {
-        return { status: "no_record" };
+    async getTotalXp(userId) {
+      const db2 = this.deps.db;
+      const result = await db2.select({ totalXp: sum(timebackDailyXp.xp) }).from(timebackDailyXp).where(eq(timebackDailyXp.userId, userId));
+      return { totalXp: Number(result[0]?.totalXp) || 0 };
+    }
+    async updateTodayXp(userId, data) {
+      const db2 = this.deps.db;
+      const { xp, userTimestamp } = data;
+      let targetDate;
+      if (userTimestamp) {
+        targetDate = new Date(userTimestamp);
+        if (isNaN(targetDate.getTime())) {
+          throw new ValidationError("Invalid userTimestamp format. Use ISO 8601 format.");
+        }
+        targetDate.setHours(0, 0, 0, 0);
+      } else {
+        targetDate = new Date;
+        targetDate.setUTCHours(0, 0, 0, 0);
       }
-      const sourcedId = crypto.randomUUID();
-      const response = await client.oneroster.users.create({
-        sourcedId,
-        status: "active",
-        enabledUser: true,
-        givenName: providedNames.firstName,
-        familyName: providedNames.lastName,
-        email: user.email,
-        roles: [
-          {
-            roleType: "primary",
-            role: "student",
-            org: { sourcedId: TIMEBACK_ORG_SOURCED_ID }
-          }
-        ]
-      });
-      if (!response.sourcedIdPairs?.allocatedSourcedId) {
-        return { status: "error", message: "Timeback did not return allocatedSourcedId" };
+      const [result] = await db2.insert(timebackDailyXp).values({ userId, date: targetDate, xp }).onConflictDoUpdate({
+        target: [timebackDailyXp.userId, timebackDailyXp.date],
+        set: { xp: sql`excluded.xp`, updatedAt: new Date }
+      }).returning({ xp: timebackDailyXp.xp, date: timebackDailyXp.date });
+      if (!result) {
+        logger17.error("Daily XP upsert returned no rows", { userId, date: targetDate });
+        throw new InternalError("Failed to update daily XP record");
       }
-      timebackId = response.sourcedIdPairs.allocatedSourcedId;
-      name3 = `${providedNames.firstName} ${providedNames.lastName}`;
-      logger17.info("Created student in OneRoster", { userId: user.id, timebackId });
+      return { xp: result.xp, date: result.date.toISOString() };
     }
-    const assessments = await this.fetchAssessments(timebackId);
-    await db2.transaction(async (tx) => {
-      if (assessments.length > 0) {
-        const events = mapAssessmentsToXpEvents(user.id, assessments);
-        for (const event of events) {
-          try {
-            await tx.insert(timebackXpEvents).values(event);
-          } catch {}
+    async getXpHistory(userId, startDate, endDate) {
+      const db2 = this.deps.db;
+      const whereConditions = [eq(timebackDailyXp.userId, userId)];
+      if (startDate) {
+        const start2 = new Date(startDate);
+        start2.setUTCHours(0, 0, 0, 0);
+        whereConditions.push(gte(timebackDailyXp.date, start2));
+      }
+      if (endDate) {
+        const end = new Date(endDate);
+        end.setUTCHours(23, 59, 59, 999);
+        whereConditions.push(lte(timebackDailyXp.date, end));
+      }
+      const result = await db2.select({ date: timebackDailyXp.date, xp: timebackDailyXp.xp }).from(timebackDailyXp).where(and(...whereConditions)).orderBy(timebackDailyXp.date);
+      return {
+        history: result.map((row) => ({ date: row.date.toISOString(), xp: row.xp }))
+      };
+    }
+    async populateStudent(user, providedNames) {
+      const client = this.requireClient();
+      const db2 = this.deps.db;
+      const dbUser = await db2.query.users.findFirst({
+        where: eq(users.id, user.id),
+        columns: { id: true, timebackId: true }
+      });
+      if (dbUser?.timebackId) {
+        logger17.info("Student already onboarded", { userId: user.id });
+        return { status: "already_populated" };
+      }
+      let timebackId;
+      let name3;
+      try {
+        const existingUser = await client.oneroster.users.findByEmail(user.email);
+        timebackId = existingUser.sourcedId;
+        name3 = `${existingUser.givenName} ${existingUser.familyName}`;
+        logger17.info("Found existing student in OneRoster", {
+          userId: user.id,
+          timebackId
+        });
+      } catch {
+        if (!providedNames?.firstName || !providedNames?.lastName) {
+          return { status: "no_record" };
         }
-        const dailyMap = new Map;
-        for (const a of assessments) {
-          const xp = a.metadata?.xp;
-          if (typeof xp === "number" && a.scoreDate) {
-            const day = getUtcInstantForMidnight(new Date(a.scoreDate), PLATFORM_TIMEZONE);
-            const key = day.toISOString();
-            dailyMap.set(key, (dailyMap.get(key) || 0) + xp);
+        const sourcedId = crypto.randomUUID();
+        const response = await client.oneroster.users.create({
+          sourcedId,
+          status: "active",
+          enabledUser: true,
+          givenName: providedNames.firstName,
+          familyName: providedNames.lastName,
+          email: user.email,
+          roles: [
+            {
+              roleType: "primary",
+              role: "student",
+              org: { sourcedId: TIMEBACK_ORG_SOURCED_ID }
+            }
+          ]
+        });
+        if (!response.sourcedIdPairs?.allocatedSourcedId) {
+          return { status: "error", message: "Timeback did not return allocatedSourcedId" };
+        }
+        timebackId = response.sourcedIdPairs.allocatedSourcedId;
+        name3 = `${providedNames.firstName} ${providedNames.lastName}`;
+        logger17.info("Created student in OneRoster", { userId: user.id, timebackId });
+      }
+      const assessments = await this.fetchAssessments(timebackId);
+      await db2.transaction(async (tx) => {
+        if (assessments.length > 0) {
+          const events = mapAssessmentsToXpEvents(user.id, assessments);
+          for (const event of events) {
+            try {
+              await tx.insert(timebackXpEvents).values(event);
+            } catch {}
+          }
+          const dailyMap = new Map;
+          for (const a of assessments) {
+            const xp = a.metadata?.xp;
+            if (typeof xp === "number" && a.scoreDate) {
+              const day = getUtcInstantForMidnight(new Date(a.scoreDate), PLATFORM_TIMEZONE);
+              const key = day.toISOString();
+              dailyMap.set(key, (dailyMap.get(key) || 0) + xp);
+            }
+          }
+          if (dailyMap.size > 0) {
+            const dailyRecords = [...dailyMap.entries()].map(([iso, xp]) => ({
+              userId: user.id,
+              date: new Date(iso),
+              xp
+            }));
+            await tx.insert(timebackDailyXp).values(dailyRecords).onConflictDoUpdate({
+              target: [timebackDailyXp.userId, timebackDailyXp.date],
+              set: { xp: sql`excluded.xp`, updatedAt: new Date }
+            });
           }
         }
-        if (dailyMap.size > 0) {
-          const dailyRecords = [...dailyMap.entries()].map(([iso, xp]) => ({
+        const [updated] = await tx.update(users).set({ timebackId, name: name3 }).where(eq(users.id, user.id)).returning({ id: users.id });
+        if (!updated) {
+          logger17.error("User Timeback ID update returned no rows", {
             userId: user.id,
-            date: new Date(iso),
-            xp
-          }));
-          await tx.insert(timebackDailyXp).values(dailyRecords).onConflictDoUpdate({
-            target: [timebackDailyXp.userId, timebackDailyXp.date],
-            set: { xp: sql`excluded.xp`, updatedAt: new Date }
+            timebackId
           });
+          throw new InternalError("Failed to update user with Timeback ID");
         }
-      }
-      const [updated] = await tx.update(users).set({ timebackId, name: name3 }).where(eq(users.id, user.id)).returning({ id: users.id });
-      if (!updated) {
-        logger17.error("User Timeback ID update returned no rows", {
-          userId: user.id,
-          timebackId
-        });
-        throw new InternalError("Failed to update user with Timeback ID");
-      }
-    });
-    return { status: "ok" };
-  }
-  async fetchAssessments(studentSourcedId) {
-    const client = this.requireClient();
-    const allAssessments = [];
-    const limit = 3000;
-    const fields = "sourcedId,assessmentLineItem,student,score,textScore,scoreDate,scoreStatus,scorePercentile,comment,metadata,inProgress,incomplete,late,missing";
-    let offset = 0;
-    try {
-      while (true) {
-        const results = await client.oneroster.assessmentResults.listByStudent(studentSourcedId, { limit, offset, fields });
-        allAssessments.push(...results);
-        if (results.length < limit) {
-          break;
-        }
-        offset += limit;
-      }
-      logger17.debug("Fetched assessments", {
-        studentSourcedId,
-        totalCount: allAssessments.length
       });
-      return allAssessments;
-    } catch (error) {
-      logger17.warn("Failed to fetch assessments", { studentSourcedId, error });
-      return [];
-    }
-  }
-  async getUserData(userId, gameId) {
-    const db2 = this.deps.db;
-    const userData = await db2.query.users.findFirst({ where: eq(users.id, userId) });
-    if (!userData) {
-      throw new NotFoundError("User", userId);
+      return { status: "ok" };
     }
-    if (!userData.timebackId) {
-      throw new NotFoundError("Timeback account not found for user");
-    }
-    const [profile, allEnrollments] = await Promise.all([
-      this.fetchStudentProfile(userData.timebackId),
-      this.fetchEnrollments(userData.timebackId)
-    ]);
-    const enrollments = gameId ? allEnrollments.filter((e) => e.gameId === gameId) : allEnrollments;
-    const enrollmentOrgIds = new Set(enrollments.map((e) => e.orgId).filter(Boolean));
-    const organizations = gameId && enrollmentOrgIds.size > 0 ? profile.organizations.filter((o) => enrollmentOrgIds.has(o.id)) : profile.organizations;
-    return { id: userData.timebackId, role: profile.role, enrollments, organizations };
-  }
-  async getUserDataByTimebackId(timebackId) {
-    const [profile, enrollments] = await Promise.all([
-      this.fetchStudentProfile(timebackId),
-      this.fetchEnrollments(timebackId)
-    ]);
-    return {
-      id: timebackId,
-      role: profile.role,
-      enrollments,
-      organizations: profile.organizations
-    };
-  }
-  async fetchStudentProfile(timebackId) {
-    const client = this.requireClient();
-    try {
-      const user = await client.oneroster.users.get(timebackId);
-      const primaryRole = user.roles.find((r) => r.roleType === "primary");
-      const role = primaryRole?.role ?? user.roles[0]?.role ?? "student";
-      const orgMap = new Map;
-      if (user.primaryOrg) {
-        orgMap.set(user.primaryOrg.sourcedId, {
-          id: user.primaryOrg.sourcedId,
-          name: user.primaryOrg.name ?? null,
-          type: user.primaryOrg.type || "school",
-          isPrimary: true
+    async fetchAssessments(studentSourcedId) {
+      const client = this.requireClient();
+      const allAssessments = [];
+      const limit = 3000;
+      const fields = "sourcedId,assessmentLineItem,student,score,textScore,scoreDate,scoreStatus,scorePercentile,comment,metadata,inProgress,incomplete,late,missing";
+      let offset = 0;
+      try {
+        while (true) {
+          const results = await client.oneroster.assessmentResults.listByStudent(studentSourcedId, { limit, offset, fields });
+          allAssessments.push(...results);
+          if (results.length < limit) {
+            break;
+          }
+          offset += limit;
+        }
+        logger17.debug("Fetched assessments", {
+          studentSourcedId,
+          totalCount: allAssessments.length
         });
+        return allAssessments;
+      } catch (error) {
+        logger17.warn("Failed to fetch assessments", { studentSourcedId, error });
+        return [];
       }
-      for (const r of user.roles) {
-        if (r.org && !orgMap.has(r.org.sourcedId)) {
-          orgMap.set(r.org.sourcedId, {
-            id: r.org.sourcedId,
-            name: null,
-            type: "school",
-            isPrimary: false
+    }
+    async getUserData(userId, gameId) {
+      const db2 = this.deps.db;
+      const userData = await db2.query.users.findFirst({ where: eq(users.id, userId) });
+      if (!userData) {
+        throw new NotFoundError("User", userId);
+      }
+      if (!userData.timebackId) {
+        throw new NotFoundError("Timeback account not found for user");
+      }
+      const [profile, allEnrollments] = await Promise.all([
+        this.fetchStudentProfile(userData.timebackId),
+        this.fetchEnrollments(userData.timebackId)
+      ]);
+      const enrollments = gameId ? allEnrollments.filter((e) => e.gameId === gameId) : allEnrollments;
+      const enrollmentOrgIds = new Set(enrollments.map((e) => e.orgId).filter(Boolean));
+      const organizations = gameId && enrollmentOrgIds.size > 0 ? profile.organizations.filter((o) => enrollmentOrgIds.has(o.id)) : profile.organizations;
+      return { id: userData.timebackId, role: profile.role, enrollments, organizations };
+    }
+    async getUserDataByTimebackId(timebackId) {
+      const [profile, enrollments] = await Promise.all([
+        this.fetchStudentProfile(timebackId),
+        this.fetchEnrollments(timebackId)
+      ]);
+      return {
+        id: timebackId,
+        role: profile.role,
+        enrollments,
+        organizations: profile.organizations
+      };
+    }
+    async fetchStudentProfile(timebackId) {
+      const client = this.requireClient();
+      try {
+        const user = await client.oneroster.users.get(timebackId);
+        const primaryRole = user.roles.find((r) => r.roleType === "primary");
+        const role = primaryRole?.role ?? user.roles[0]?.role ?? "student";
+        const orgMap = new Map;
+        if (user.primaryOrg) {
+          orgMap.set(user.primaryOrg.sourcedId, {
+            id: user.primaryOrg.sourcedId,
+            name: user.primaryOrg.name ?? null,
+            type: user.primaryOrg.type || "school",
+            isPrimary: true
           });
         }
+        for (const r of user.roles) {
+          if (r.org && !orgMap.has(r.org.sourcedId)) {
+            orgMap.set(r.org.sourcedId, {
+              id: r.org.sourcedId,
+              name: null,
+              type: "school",
+              isPrimary: false
+            });
+          }
+        }
+        return { role, organizations: [...orgMap.values()] };
+      } catch {
+        return { role: "student", organizations: [] };
       }
-      return { role, organizations: [...orgMap.values()] };
-    } catch {
-      return { role: "student", organizations: [] };
     }
-  }
-  async fetchEnrollments(timebackId) {
-    const client = this.requireClient();
-    const db2 = this.deps.db;
-    try {
-      const enrollments = await client.getEnrollments(timebackId);
-      const courseIds = enrollments.map((e) => e.courseId).filter((id) => Boolean(id));
-      if (courseIds.length === 0) {
+    async fetchEnrollments(timebackId) {
+      const client = this.requireClient();
+      const db2 = this.deps.db;
+      try {
+        const enrollments = await client.getEnrollments(timebackId);
+        const courseIds = enrollments.map((e) => e.courseId).filter((id) => Boolean(id));
+        if (courseIds.length === 0) {
+          return [];
+        }
+        const courseToSchool = new Map(enrollments.filter((e) => e.school?.id).map((e) => [e.courseId, e.school.id]));
+        const integrations = await db2.query.gameTimebackIntegrations.findMany({
+          where: inArray(gameTimebackIntegrations.courseId, courseIds)
+        });
+        return integrations.map((i2) => ({
+          gameId: i2.gameId,
+          grade: i2.grade,
+          subject: i2.subject,
+          courseId: i2.courseId,
+          orgId: courseToSchool.get(i2.courseId)
+        }));
+      } catch {
         return [];
       }
-      const courseToSchool = new Map(enrollments.filter((e) => e.school?.id).map((e) => [e.courseId, e.school.id]));
-      const integrations = await db2.query.gameTimebackIntegrations.findMany({
-        where: inArray(gameTimebackIntegrations.courseId, courseIds)
-      });
-      return integrations.map((i2) => ({
-        gameId: i2.gameId,
-        grade: i2.grade,
-        subject: i2.subject,
-        courseId: i2.courseId,
-        orgId: courseToSchool.get(i2.courseId)
-      }));
-    } catch {
-      return [];
     }
-  }
-  async setupIntegration(gameId, request, user) {
-    const client = this.requireClient();
-    const db2 = this.deps.db;
-    await this.deps.validateDeveloperAccess(user, gameId);
-    const { courses, baseConfig, verbose } = request;
-    const existing = await db2.query.gameTimebackIntegrations.findMany({
-      where: eq(gameTimebackIntegrations.gameId, gameId)
-    });
-    const integrations = [];
-    const verboseData = [];
-    for (const courseConfig of courses) {
-      let applySuffix = function(text3) {
-        return suffix ? `${text3} ${suffix}` : text3;
-      };
-      const {
-        subject: subjectInput,
-        grade,
-        title,
-        courseCode,
-        level,
-        metadata: metadata2,
-        totalXp: derivedTotalXp,
-        masterableUnits: derivedMasterableUnits
-      } = courseConfig;
-      if (!isTimebackSubject(subjectInput)) {
-        logger17.warn("Invalid Timeback subject in course config", {
+    async setupIntegration(gameId, request, user) {
+      const client = this.requireClient();
+      const db2 = this.deps.db;
+      await this.deps.validateDeveloperAccess(user, gameId);
+      const { courses, baseConfig, verbose } = request;
+      const existing = await db2.query.gameTimebackIntegrations.findMany({
+        where: eq(gameTimebackIntegrations.gameId, gameId)
+      });
+      const integrations = [];
+      const verboseData = [];
+      for (const courseConfig of courses) {
+        let applySuffix = function(text3) {
+          return suffix ? `${text3} ${suffix}` : text3;
+        };
+        const {
           subject: subjectInput,
-          courseCode,
-          title
-        });
-        throw new ValidationError(`Invalid subject "${subjectInput}"`);
-      }
-      if (!isTimebackGrade(grade)) {
-        logger17.warn("Invalid Timeback grade in course config", {
           grade,
-          courseCode,
-          title
-        });
-        throw new ValidationError(`Invalid grade "${grade}"`);
-      }
-      const subject = subjectInput;
-      const courseMetadata = isCourseMetadata(metadata2) ? metadata2 : undefined;
-      const totalXp = derivedTotalXp ?? courseMetadata?.metrics?.totalXp;
-      const masterableUnits = derivedMasterableUnits ?? (isPlaycademyResourceMetadata(courseMetadata?.playcademy) ? courseMetadata?.playcademy?.mastery?.masterableUnits : undefined);
-      if (typeof totalXp !== "number") {
-        logger17.warn("Course missing totalXp in Timeback config", {
-          courseCode,
-          title
-        });
-        throw new ValidationError(`Course "${title}" is missing totalXp`);
-      }
-      const suffix = baseConfig.component.titleSuffix || "";
-      const fullConfig = {
-        organization: baseConfig.organization,
-        course: {
           title,
-          subjects: [subject],
-          grades: [grade],
           courseCode,
           level,
-          gradingScheme: "STANDARD",
-          metadata: metadata2
-        },
-        component: {
-          ...baseConfig.component,
-          title: applySuffix(baseConfig.component.title || `${title} Activities`)
-        },
-        resource: {
-          ...baseConfig.resource,
-          title: applySuffix(baseConfig.resource.title || `${title} Game`),
-          metadata: buildResourceMetadata({
-            baseMetadata: baseConfig.resource.metadata,
-            subject,
-            grade,
-            totalXp,
-            masterableUnits
-          })
-        },
-        componentResource: {
-          ...baseConfig.componentResource,
-          title: applySuffix(baseConfig.componentResource.title || "")
-        }
-      };
-      const existingIntegration = existing.find((i2) => i2.grade === grade && i2.subject === subject);
-      if (existingIntegration) {
-        await client.update(existingIntegration.courseId, fullConfig);
-        const [updated] = await db2.update(gameTimebackIntegrations).set({ totalXp, updatedAt: new Date }).where(eq(gameTimebackIntegrations.id, existingIntegration.id)).returning();
-        if (updated) {
-          integrations.push(this.toGameTimebackIntegration(updated));
+          metadata: metadata2,
+          totalXp: derivedTotalXp,
+          masterableUnits: derivedMasterableUnits
+        } = courseConfig;
+        if (!isTimebackSubject(subjectInput)) {
+          logger17.warn("Invalid Timeback subject in course config", {
+            subject: subjectInput,
+            courseCode,
+            title
+          });
+          throw new ValidationError(`Invalid subject "${subjectInput}"`);
         }
-      } else {
-        const result = await client.setup(fullConfig, { verbose });
-        const [integration] = await db2.insert(gameTimebackIntegrations).values({ gameId, courseId: result.courseId, grade, subject, totalXp }).returning();
-        if (integration) {
-          const dto = this.toGameTimebackIntegration(integration);
-          integrations.push(dto);
-          if (verbose && result.verboseData) {
-            verboseData.push({ integration: dto, config: result.verboseData });
+        if (!isTimebackGrade(grade)) {
+          logger17.warn("Invalid Timeback grade in course config", {
+            grade,
+            courseCode,
+            title
+          });
+          throw new ValidationError(`Invalid grade "${grade}"`);
+        }
+        const subject = subjectInput;
+        const courseMetadata = isCourseMetadata(metadata2) ? metadata2 : undefined;
+        const totalXp = derivedTotalXp ?? courseMetadata?.metrics?.totalXp;
+        const masterableUnits = derivedMasterableUnits ?? (isPlaycademyResourceMetadata(courseMetadata?.playcademy) ? courseMetadata?.playcademy?.mastery?.masterableUnits : undefined);
+        if (typeof totalXp !== "number") {
+          logger17.warn("Course missing totalXp in Timeback config", {
+            courseCode,
+            title
+          });
+          throw new ValidationError(`Course "${title}" is missing totalXp`);
+        }
+        const suffix = baseConfig.component.titleSuffix || "";
+        const fullConfig = {
+          organization: baseConfig.organization,
+          course: {
+            title,
+            subjects: [subject],
+            grades: [grade],
+            courseCode,
+            level,
+            gradingScheme: "STANDARD",
+            metadata: metadata2
+          },
+          component: {
+            ...baseConfig.component,
+            title: applySuffix(baseConfig.component.title || `${title} Activities`)
+          },
+          resource: {
+            ...baseConfig.resource,
+            title: applySuffix(baseConfig.resource.title || `${title} Game`),
+            metadata: buildResourceMetadata({
+              baseMetadata: baseConfig.resource.metadata,
+              subject,
+              grade,
+              totalXp,
+              masterableUnits
+            })
+          },
+          componentResource: {
+            ...baseConfig.componentResource,
+            title: applySuffix(baseConfig.componentResource.title || "")
+          }
+        };
+        const existingIntegration = existing.find((i2) => i2.grade === grade && i2.subject === subject);
+        if (existingIntegration) {
+          await client.update(existingIntegration.courseId, fullConfig);
+          const [updated] = await db2.update(gameTimebackIntegrations).set({ totalXp, updatedAt: new Date }).where(eq(gameTimebackIntegrations.id, existingIntegration.id)).returning();
+          if (updated) {
+            integrations.push(this.toGameTimebackIntegration(updated));
+          }
+        } else {
+          const result = await client.setup(fullConfig, { verbose });
+          const [integration] = await db2.insert(gameTimebackIntegrations).values({ gameId, courseId: result.courseId, grade, subject, totalXp }).returning();
+          if (integration) {
+            const dto = this.toGameTimebackIntegration(integration);
+            integrations.push(dto);
+            if (verbose && result.verboseData) {
+              verboseData.push({ integration: dto, config: result.verboseData });
+            }
           }
         }
       }
+      return { integrations, ...verbose && verboseData.length > 0 && { verbose: verboseData } };
     }
-    return { integrations, ...verbose && verboseData.length > 0 && { verbose: verboseData } };
-  }
-  async getIntegrations(gameId, user) {
-    await this.deps.validateGameManagementAccess(user, gameId);
-    const rows = await this.deps.db.query.gameTimebackIntegrations.findMany({
-      where: eq(gameTimebackIntegrations.gameId, gameId)
-    });
-    return rows.map((row) => this.toGameTimebackIntegration(row));
-  }
-  async verifyIntegration(gameId, user) {
-    const client = this.requireClient();
-    const db2 = this.deps.db;
-    await this.deps.validateDeveloperAccess(user, gameId);
-    const integrations = await db2.query.gameTimebackIntegrations.findMany({
-      where: eq(gameTimebackIntegrations.gameId, gameId)
-    });
-    if (integrations.length === 0) {
-      throw new NotFoundError("Timeback integration", gameId);
+    async getIntegrations(gameId, user) {
+      await this.deps.validateGameManagementAccess(user, gameId);
+      const rows = await this.deps.db.query.gameTimebackIntegrations.findMany({
+        where: eq(gameTimebackIntegrations.gameId, gameId)
+      });
+      return rows.map((row) => this.toGameTimebackIntegration(row));
     }
-    const now2 = new Date;
-    const results = await Promise.all(integrations.map(async (integration) => {
-      const resources = await client.verify(integration.courseId);
-      const resourceValues = Object.values(resources);
-      const allFound = resourceValues.every((r) => r.found);
-      const errors3 = Object.entries(resources).filter(([_, r]) => !r.found).map(([name3]) => `${name3} not found`);
-      const status = allFound ? "success" : "error";
-      return {
-        integration: this.toGameTimebackIntegration({
-          ...integration,
-          lastVerifiedAt: now2
-        }),
-        resources,
-        status,
-        ...errors3.length > 0 && { errors: errors3 }
-      };
-    }));
-    await db2.update(gameTimebackIntegrations).set({ lastVerifiedAt: now2 }).where(eq(gameTimebackIntegrations.gameId, gameId));
-    const overallStatus = results.every((r) => r.status === "success") ? "success" : "error";
-    return { status: overallStatus, results };
-  }
-  async getConfig(gameId, user) {
-    const client = this.requireClient();
-    await this.deps.validateDeveloperAccess(user, gameId);
-    const integration = await this.deps.db.query.gameTimebackIntegrations.findFirst({
-      where: eq(gameTimebackIntegrations.gameId, gameId)
-    });
-    if (!integration) {
-      throw new NotFoundError("Timeback integration", gameId);
+    async verifyIntegration(gameId, user) {
+      const client = this.requireClient();
+      const db2 = this.deps.db;
+      await this.deps.validateDeveloperAccess(user, gameId);
+      const integrations = await db2.query.gameTimebackIntegrations.findMany({
+        where: eq(gameTimebackIntegrations.gameId, gameId)
+      });
+      if (integrations.length === 0) {
+        throw new NotFoundError("Timeback integration", gameId);
+      }
+      const now2 = new Date;
+      const results = await Promise.all(integrations.map(async (integration) => {
+        const resources = await client.verify(integration.courseId);
+        const resourceValues = Object.values(resources);
+        const allFound = resourceValues.every((r) => r.found);
+        const errors3 = Object.entries(resources).filter(([_, r]) => !r.found).map(([name3]) => `${name3} not found`);
+        const status = allFound ? "success" : "error";
+        return {
+          integration: this.toGameTimebackIntegration({
+            ...integration,
+            lastVerifiedAt: now2
+          }),
+          resources,
+          status,
+          ...errors3.length > 0 && { errors: errors3 }
+        };
+      }));
+      await db2.update(gameTimebackIntegrations).set({ lastVerifiedAt: now2 }).where(eq(gameTimebackIntegrations.gameId, gameId));
+      const overallStatus = results.every((r) => r.status === "success") ? "success" : "error";
+      return { status: overallStatus, results };
     }
-    return client.getConfig(integration.courseId);
-  }
-  async deleteIntegrations(gameId, user) {
-    const client = this.requireClient();
-    const db2 = this.deps.db;
-    await this.deps.validateDeveloperAccess(user, gameId);
-    const integrations = await db2.query.gameTimebackIntegrations.findMany({
-      where: eq(gameTimebackIntegrations.gameId, gameId)
-    });
-    if (integrations.length === 0) {
-      throw new NotFoundError("Timeback integration", gameId);
+    async getConfig(gameId, user) {
+      const client = this.requireClient();
+      await this.deps.validateDeveloperAccess(user, gameId);
+      const integration = await this.deps.db.query.gameTimebackIntegrations.findFirst({
+        where: eq(gameTimebackIntegrations.gameId, gameId)
+      });
+      if (!integration) {
+        throw new NotFoundError("Timeback integration", gameId);
+      }
+      return client.getConfig(integration.courseId);
     }
-    for (const integration of integrations) {
-      await client.cleanup(integration.courseId);
+    async deleteIntegrations(gameId, user) {
+      const client = this.requireClient();
+      const db2 = this.deps.db;
+      await this.deps.validateDeveloperAccess(user, gameId);
+      const integrations = await db2.query.gameTimebackIntegrations.findMany({
+        where: eq(gameTimebackIntegrations.gameId, gameId)
+      });
+      if (integrations.length === 0) {
+        throw new NotFoundError("Timeback integration", gameId);
+      }
+      for (const integration of integrations) {
+        await client.cleanup(integration.courseId);
+      }
+      await db2.delete(gameTimebackIntegrations).where(eq(gameTimebackIntegrations.gameId, gameId));
     }
-    await db2.delete(gameTimebackIntegrations).where(eq(gameTimebackIntegrations.gameId, gameId));
-  }
-  toGameTimebackIntegration(integration) {
-    return {
-      id: integration.id,
-      gameId: integration.gameId,
-      courseId: integration.courseId,
-      grade: integration.grade,
-      subject: integration.subject,
-      totalXp: integration.totalXp ?? null,
-      createdAt: integration.createdAt,
-      updatedAt: integration.updatedAt,
-      lastVerifiedAt: integration.lastVerifiedAt ?? null
-    };
-  }
-  async endActivity({
-    gameId,
-    studentId,
-    activityData,
-    scoreData,
-    timingData,
-    xpEarned,
-    masteredUnits,
-    extensions,
-    user
-  }) {
-    const client = this.requireClient();
-    const db2 = this.deps.db;
-    await this.deps.validateDeveloperAccess(user, gameId);
-    const integration = await db2.query.gameTimebackIntegrations.findFirst({
-      where: and(eq(gameTimebackIntegrations.gameId, gameId), eq(gameTimebackIntegrations.grade, activityData.grade), eq(gameTimebackIntegrations.subject, activityData.subject))
-    });
-    if (!integration) {
-      throw new NotFoundError(`Timeback integration for game (grade ${activityData.grade}, subject ${activityData.subject})`);
-    }
-    const scorePercentage = scoreData.totalQuestions > 0 ? scoreData.correctQuestions / scoreData.totalQuestions * 100 : 0;
-    const result = await client.recordProgress(integration.courseId, studentId, {
-      score: scorePercentage,
-      totalQuestions: scoreData.totalQuestions,
-      correctQuestions: scoreData.correctQuestions,
-      durationSeconds: timingData.durationSeconds,
+    toGameTimebackIntegration(integration) {
+      return {
+        id: integration.id,
+        gameId: integration.gameId,
+        courseId: integration.courseId,
+        grade: integration.grade,
+        subject: integration.subject,
+        totalXp: integration.totalXp ?? null,
+        createdAt: integration.createdAt,
+        updatedAt: integration.updatedAt,
+        lastVerifiedAt: integration.lastVerifiedAt ?? null
+      };
+    }
+    async endActivity({
+      gameId,
+      studentId,
+      runId,
+      activityData,
+      scoreData,
+      timingData,
+      sessionTimingData,
       xpEarned,
       masteredUnits,
       extensions,
-      activityId: activityData.activityId,
-      activityName: activityData.activityName,
-      subject: activityData.subject,
-      appName: activityData.appName,
-      sensorUrl: activityData.sensorUrl,
-      courseId: activityData.courseId,
-      courseName: activityData.courseName,
-      studentEmail: activityData.studentEmail,
-      courseTotalXp: integration.totalXp
-    });
-    await client.recordSessionEnd(integration.courseId, studentId, {
-      activeTimeSeconds: timingData.durationSeconds,
-      activityId: activityData.activityId,
-      activityName: activityData.activityName,
-      subject: activityData.subject,
-      appName: activityData.appName,
-      sensorUrl: activityData.sensorUrl,
-      courseId: activityData.courseId,
-      courseName: activityData.courseName,
-      studentEmail: activityData.studentEmail
-    });
-    logger17.info("Recorded activity completion", {
+      user
+    }) {
+      const client = this.requireClient();
+      const db2 = this.deps.db;
+      await this.deps.validateDeveloperAccess(user, gameId);
+      const integration = await db2.query.gameTimebackIntegrations.findFirst({
+        where: and(eq(gameTimebackIntegrations.gameId, gameId), eq(gameTimebackIntegrations.grade, activityData.grade), eq(gameTimebackIntegrations.subject, activityData.subject))
+      });
+      if (!integration) {
+        throw new NotFoundError(`Timeback integration for game (grade ${activityData.grade}, subject ${activityData.subject})`);
+      }
+      const scorePercentage = scoreData.totalQuestions > 0 ? scoreData.correctQuestions / scoreData.totalQuestions * 100 : 0;
+      const result = await client.recordProgress(integration.courseId, studentId, {
+        score: scorePercentage,
+        totalQuestions: scoreData.totalQuestions,
+        correctQuestions: scoreData.correctQuestions,
+        durationSeconds: timingData.durationSeconds,
+        xpEarned,
+        masteredUnits,
+        extensions,
+        activityId: activityData.activityId,
+        activityName: activityData.activityName,
+        subject: activityData.subject,
+        appName: activityData.appName,
+        sensorUrl: activityData.sensorUrl,
+        courseId: activityData.courseId,
+        courseName: activityData.courseName,
+        studentEmail: activityData.studentEmail,
+        courseTotalXp: integration.totalXp,
+        ...runId ? { runId } : {}
+      });
+      const sessionEndActiveSeconds = sessionTimingData?.activeSeconds ?? timingData.durationSeconds;
+      const sessionEndInactiveSeconds = sessionTimingData?.inactiveSeconds;
+      if (sessionEndActiveSeconds > 0 || (sessionEndInactiveSeconds ?? 0) > 0) {
+        await client.recordSessionEnd(integration.courseId, studentId, {
+          activeTimeSeconds: sessionEndActiveSeconds,
+          ...sessionEndInactiveSeconds !== undefined ? { inactiveTimeSeconds: sessionEndInactiveSeconds } : {},
+          activityId: activityData.activityId,
+          activityName: activityData.activityName,
+          subject: activityData.subject,
+          appName: activityData.appName,
+          sensorUrl: activityData.sensorUrl,
+          courseId: activityData.courseId,
+          courseName: activityData.courseName,
+          studentEmail: activityData.studentEmail,
+          ...runId ? { runId } : {}
+        });
+      }
+      logger17.info("Recorded activity completion", {
+        gameId,
+        courseId: integration.courseId,
+        studentId,
+        runId,
+        score: scorePercentage
+      });
+      return {
+        status: "ok",
+        courseId: integration.courseId,
+        xpAwarded: result.xpAwarded,
+        masteredUnits: result.masteredUnitsApplied,
+        pctCompleteApp: result.pctCompleteApp,
+        scoreStatus: result.scoreStatus,
+        inProgress: result.inProgress
+      };
+    }
+    async recordHeartbeat({
       gameId,
-      courseId: integration.courseId,
       studentId,
-      score: scorePercentage
-    });
-    return {
-      status: "ok",
-      courseId: integration.courseId,
-      xpAwarded: result.xpAwarded,
-      masteredUnits: result.masteredUnitsApplied,
-      pctCompleteApp: result.pctCompleteApp,
-      scoreStatus: result.scoreStatus,
-      inProgress: result.inProgress
-    };
-  }
-  async getStudentXp(timebackId, user, options) {
-    const client = this.requireClient();
-    const db2 = this.deps.db;
-    let courseIds = [];
-    if (options?.gameId) {
-      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));
+      runId,
+      activityData,
+      timingData,
+      windowSequence,
+      isFinal,
+      user
+    }) {
+      const client = this.requireClient();
+      const db2 = this.deps.db;
+      const heartbeatWindowKey = `${runId}:${windowSequence}`;
+      if (TimebackService.isDuplicateHeartbeatWindow(heartbeatWindowKey)) {
+        logger17.debug("Skipping duplicate heartbeat window", {
+          gameId,
+          studentId,
+          runId,
+          windowSequence,
+          isFinal
+        });
+        return { status: "ok" };
       }
-      const integrations = await db2.query.gameTimebackIntegrations.findMany({
-        where: and(...conditions2)
-      });
-      courseIds = integrations.map((i2) => i2.courseId);
-      if (courseIds.length === 0) {
-        logger17.debug("No integrations found for game, returning 0 XP", {
-          timebackId,
-          gameId: options.gameId,
-          grade: options.grade,
-          subject: options.subject
+      await this.deps.validateDeveloperAccess(user, gameId);
+      const inFlightHeartbeat = TimebackService.getInFlightHeartbeatWindow(heartbeatWindowKey);
+      if (inFlightHeartbeat) {
+        logger17.debug("Joining in-flight heartbeat window", {
+          gameId,
+          studentId,
+          runId,
+          windowSequence,
+          isFinal
         });
-        return {
-          totalXp: 0,
-          ...options?.include?.today && { todayXp: 0 },
-          ...options?.include?.perCourse && { courses: [] }
-        };
+        return inFlightHeartbeat;
+      }
+      const pendingHeartbeat = (async () => {
+        const integration = await db2.query.gameTimebackIntegrations.findFirst({
+          where: and(eq(gameTimebackIntegrations.gameId, gameId), eq(gameTimebackIntegrations.grade, activityData.grade), eq(gameTimebackIntegrations.subject, activityData.subject))
+        });
+        if (!integration) {
+          throw new NotFoundError(`Timeback integration for game (grade ${activityData.grade}, subject ${activityData.subject})`);
+        }
+        const activeTimeSeconds = timingData.activeMs / 1000;
+        const inactiveTimeSeconds = timingData.pausedMs / 1000;
+        if (activeTimeSeconds > 0 || inactiveTimeSeconds > 0) {
+          await client.recordSessionEnd(integration.courseId, studentId, {
+            activeTimeSeconds,
+            ...inactiveTimeSeconds > 0 ? { inactiveTimeSeconds } : {},
+            activityId: activityData.activityId,
+            activityName: activityData.activityName,
+            subject: activityData.subject,
+            appName: activityData.appName,
+            sensorUrl: activityData.sensorUrl,
+            courseId: activityData.courseId,
+            courseName: activityData.courseName,
+            studentEmail: activityData.studentEmail,
+            ...runId ? { runId } : {}
+          });
+        }
+        TimebackService.markHeartbeatWindowProcessed(heartbeatWindowKey);
+        logger17.debug("Recorded heartbeat", {
+          gameId,
+          courseId: integration.courseId,
+          studentId,
+          runId,
+          windowSequence,
+          activeTimeSeconds,
+          isFinal
+        });
+        return { status: "ok" };
+      })();
+      TimebackService.markHeartbeatWindowInFlight(heartbeatWindowKey, pendingHeartbeat);
+      try {
+        return await pendingHeartbeat;
+      } finally {
+        TimebackService.clearInFlightHeartbeatWindow(heartbeatWindowKey);
       }
     }
-    const result = await client.getStudentXp(timebackId, {
-      courseIds: courseIds.length > 0 ? courseIds : undefined,
-      include: options?.include
-    });
-    logger17.debug("Retrieved student XP", {
-      timebackId,
-      gameId: options?.gameId,
-      grade: options?.grade,
-      subject: options?.subject,
-      totalXp: result.totalXp,
-      courseCount: result.courses?.length
-    });
-    return result;
-  }
-}
-var logger17;
-var init_timeback_service = __esm(() => {
-  init_drizzle_orm();
-  init_src();
-  init_tables_index();
-  init_src2();
-  init_types4();
-  init_src4();
-  init_errors();
-  init_timeback_util();
-  logger17 = log.scope("TimebackService");
+    async getStudentXp(timebackId, user, options) {
+      const client = this.requireClient();
+      const db2 = this.deps.db;
+      let courseIds = [];
+      if (options?.gameId) {
+        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)
+        });
+        courseIds = integrations.map((i2) => i2.courseId);
+        if (courseIds.length === 0) {
+          logger17.debug("No integrations found for game, returning 0 XP", {
+            timebackId,
+            gameId: options.gameId,
+            grade: options.grade,
+            subject: options.subject
+          });
+          return {
+            totalXp: 0,
+            ...options?.include?.today && { todayXp: 0 },
+            ...options?.include?.perCourse && { courses: [] }
+          };
+        }
+      }
+      const result = await client.getStudentXp(timebackId, {
+        courseIds: courseIds.length > 0 ? courseIds : undefined,
+        include: options?.include
+      });
+      logger17.debug("Retrieved student XP", {
+        timebackId,
+        gameId: options?.gameId,
+        grade: options?.grade,
+        subject: options?.subject,
+        totalXp: result.totalXp,
+        courseCount: result.courses?.length
+      });
+      return result;
+    }
+  };
 });
 
 // ../api-core/src/services/upload.service.ts
@@ -34988,6 +35104,7 @@ function createCaliperNamespace(client) {
           email: data.studentEmail
         },
         action: TIMEBACK_ACTIONS4.completed,
+        ...data.runId ? { session: `urn:uuid:${data.runId}` } : {},
         object: {
           id: data.objectId || caliper.buildActivityUrl(data),
           type: TIMEBACK_TYPES4.activityContext,
@@ -35051,6 +35168,7 @@ function createCaliperNamespace(client) {
           email: data.studentEmail
         },
         action: TIMEBACK_ACTIONS4.spentTime,
+        ...data.runId ? { session: `urn:uuid:${data.runId}` } : {},
         object: {
           id: caliper.buildActivityUrl(data),
           type: TIMEBACK_TYPES4.activityContext,
@@ -35084,7 +35202,7 @@ function createCaliperNamespace(client) {
     },
     buildActivityUrl: (data) => {
       const base = data.sensorUrl.replace(/\/$/, "");
-      return `${base}/activities/${data.courseId}/${data.activityId}/${crypto.randomUUID()}`;
+      return `${base}/activities/${encodeURIComponent(data.courseId)}/${encodeURIComponent(data.activityId)}`;
     }
   };
   return caliper;
@@ -36134,7 +36252,8 @@ class ProgressRecorder {
       masteredUnits,
       attemptNumber: currentAttemptNumber,
       progressData,
-      extensions
+      extensions,
+      runId: progressData.runId
     });
     return {
       xpAwarded: calculatedXp,
@@ -36272,7 +36391,8 @@ class ProgressRecorder {
     masteredUnits,
     attemptNumber,
     progressData,
-    extensions
+    extensions,
+    runId
   }) {
     await this.caliperNamespace.emitActivityEvent({
       studentId,
@@ -36289,7 +36409,8 @@ class ProgressRecorder {
       subject: progressData.subject,
       appName: progressData.appName,
       sensorUrl: progressData.sensorUrl,
-      extensions: extensions || progressData.extensions
+      extensions: extensions || progressData.extensions,
+      ...runId ? { runId } : {}
     }).catch((error) => {
       log.error("[ProgressRecorder] Failed to emit activity event", { error });
     });
@@ -36343,7 +36464,7 @@ class SessionRecorder {
     const courseName = sessionData.courseName || "Game Course";
     const student = await this.studentResolver.resolve(studentIdentifier, sessionData.studentEmail);
     const { id: studentId, email: studentEmail } = student;
-    const { activeTimeSeconds, inactiveTimeSeconds, wasteTimeSeconds, extensions } = sessionData;
+    const { activeTimeSeconds, inactiveTimeSeconds, wasteTimeSeconds, extensions, runId } = sessionData;
     await this.caliperNamespace.emitTimeSpentEvent({
       studentId,
       studentEmail,
@@ -36357,6 +36478,7 @@ class SessionRecorder {
       subject: sessionData.subject,
       appName: sessionData.appName,
       sensorUrl: sessionData.sensorUrl,
+      ...runId ? { runId } : {},
       ...extensions ? { extensions } : {}
     });
   }
@@ -93633,7 +93755,7 @@ function isValidAdminAttributionDate(value) {
   const date4 = new Date(Date.UTC(year3, month - 1, day, 12, 0, 0));
   return date4.getUTCFullYear() === year3 && date4.getUTCMonth() + 1 === month && date4.getUTCDate() === day;
 }
-var TIMEBACK_GRADES, TIMEBACK_SUBJECTS5, TimebackGradeSchema, TimebackSubjectSchema, UpdateTimebackXpRequestSchema, EndActivityRequestSchema, PopulateStudentRequestSchema, DerivedPlatformCourseConfigSchema, TimebackBaseConfigSchema, PlatformTimebackSetupRequestSchema, AdminTimebackMutationBaseSchema, AdminAttributionDateSchema, GrantTimebackXpRequestSchema, AdjustTimebackTimeRequestSchema, AdjustTimebackMasteryRequestSchema, ToggleCourseCompletionRequestSchema, EnrollStudentRequestSchema, UnenrollStudentRequestSchema;
+var TIMEBACK_GRADES, TIMEBACK_SUBJECTS5, TimebackGradeSchema, TimebackSubjectSchema, UpdateTimebackXpRequestSchema, TimebackActivityDataSchema, EndActivityRequestSchema, HeartbeatRequestSchema, PopulateStudentRequestSchema, DerivedPlatformCourseConfigSchema, TimebackBaseConfigSchema, PlatformTimebackSetupRequestSchema, AdminTimebackMutationBaseSchema, AdminAttributionDateSchema, GrantTimebackXpRequestSchema, AdjustTimebackTimeRequestSchema, AdjustTimebackMasteryRequestSchema, ToggleCourseCompletionRequestSchema, EnrollStudentRequestSchema, UnenrollStudentRequestSchema;
 var init_schemas11 = __esm(() => {
   init_esm();
   TIMEBACK_GRADES = [-1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13];
@@ -93656,31 +93778,49 @@ var init_schemas11 = __esm(() => {
     xp: exports_external.number().min(0, "XP must be a non-negative number"),
     userTimestamp: exports_external.string().datetime().optional()
   });
+  TimebackActivityDataSchema = exports_external.object({
+    activityId: exports_external.string().min(1),
+    activityName: exports_external.string().optional(),
+    grade: TimebackGradeSchema,
+    subject: TimebackSubjectSchema,
+    appName: exports_external.string().optional(),
+    sensorUrl: exports_external.string().url().optional(),
+    courseId: exports_external.string().optional(),
+    courseName: exports_external.string().optional(),
+    studentEmail: exports_external.string().email().optional()
+  });
   EndActivityRequestSchema = exports_external.object({
     gameId: exports_external.string().uuid(),
     studentId: exports_external.string().min(1),
-    activityData: exports_external.object({
-      activityId: exports_external.string().min(1),
-      activityName: exports_external.string().optional(),
-      grade: TimebackGradeSchema,
-      subject: TimebackSubjectSchema,
-      appName: exports_external.string().optional(),
-      sensorUrl: exports_external.string().url().optional(),
-      courseId: exports_external.string().optional(),
-      courseName: exports_external.string().optional(),
-      studentEmail: exports_external.string().email().optional()
-    }),
+    runId: exports_external.string().uuid().optional(),
+    activityData: TimebackActivityDataSchema,
     scoreData: exports_external.object({
       correctQuestions: exports_external.number().int().min(0),
       totalQuestions: exports_external.number().int().min(0)
     }),
     timingData: exports_external.object({
-      durationSeconds: exports_external.number().positive()
+      durationSeconds: exports_external.number().nonnegative()
     }),
+    sessionTimingData: exports_external.object({
+      activeSeconds: exports_external.number().nonnegative(),
+      inactiveSeconds: exports_external.number().nonnegative().optional()
+    }).optional(),
     xpEarned: exports_external.number().optional(),
     masteredUnits: exports_external.number().nonnegative().optional(),
     extensions: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
   });
+  HeartbeatRequestSchema = exports_external.object({
+    gameId: exports_external.string().uuid(),
+    studentId: exports_external.string().min(1),
+    runId: exports_external.string().uuid(),
+    activityData: TimebackActivityDataSchema,
+    timingData: exports_external.object({
+      activeMs: exports_external.number().nonnegative(),
+      pausedMs: exports_external.number().nonnegative()
+    }),
+    windowSequence: exports_external.number().int().nonnegative(),
+    isFinal: exports_external.boolean().optional()
+  });
   PopulateStudentRequestSchema = exports_external.object({
     firstName: exports_external.string().min(1).optional(),
     lastName: exports_external.string().min(1).optional()
@@ -95926,7 +96066,7 @@ var init_sprite_controller = __esm(() => {
 });
 
 // ../api-core/src/controllers/timeback.controller.ts
-var logger63, getTodayXp, getTotalXp, updateTodayXp, getXpHistory, populateStudent, getUser, getUserById, setupIntegration, getIntegrations, verifyIntegration, getConfig2, deleteIntegrations, endActivity, getStudentXp, getRoster, getStudentOverview, getStudentActivity, grantXp, adjustTime, adjustMastery, toggleCompletion, searchStudents, enrollStudent, unenrollStudent, timeback2;
+var logger63, getTodayXp, getTotalXp, updateTodayXp, getXpHistory, populateStudent, getUser, getUserById, setupIntegration, getIntegrations, verifyIntegration, getConfig2, deleteIntegrations, endActivity, heartbeat, getStudentXp, getRoster, getStudentOverview, getStudentActivity, grantXp, adjustTime, adjustMastery, toggleCompletion, searchStudents, enrollStudent, unenrollStudent, timeback2;
 var init_timeback_controller = __esm(() => {
   init_esm();
   init_schemas_index();
@@ -96076,9 +96216,11 @@ var init_timeback_controller = __esm(() => {
     const {
       gameId,
       studentId,
+      runId,
       activityData,
       scoreData,
       timingData,
+      sessionTimingData,
       xpEarned,
       masteredUnits,
       extensions
@@ -96087,15 +96229,50 @@ var init_timeback_controller = __esm(() => {
     return ctx.services.timeback.endActivity({
       gameId,
       studentId,
+      runId,
       activityData,
       scoreData,
       timingData,
+      sessionTimingData,
       xpEarned,
       masteredUnits,
       extensions,
       user: ctx.user
     });
   });
+  heartbeat = requireDeveloper(async (ctx) => {
+    let body2;
+    try {
+      const json4 = await ctx.request.json();
+      body2 = HeartbeatRequestSchema.parse(json4);
+    } catch (error2) {
+      if (error2 instanceof exports_external.ZodError) {
+        const details = formatZodError(error2);
+        logger63.warn("Heartbeat validation failed", { details });
+        throw ApiError.unprocessableEntity("Validation failed", details);
+      }
+      throw ApiError.badRequest("Invalid JSON body");
+    }
+    const { gameId, studentId, runId, activityData, timingData, windowSequence, isFinal } = body2;
+    logger63.debug("Recording heartbeat", {
+      userId: ctx.user.id,
+      gameId,
+      runId,
+      windowSequence,
+      activeMs: timingData.activeMs,
+      isFinal
+    });
+    return ctx.services.timeback.recordHeartbeat({
+      gameId,
+      studentId,
+      runId,
+      activityData,
+      timingData,
+      windowSequence,
+      isFinal,
+      user: ctx.user
+    });
+  });
   getStudentXp = requireDeveloper(async (ctx) => {
     const timebackId = ctx.params.timebackId;
     if (!timebackId) {
@@ -96292,6 +96469,7 @@ var init_timeback_controller = __esm(() => {
     getConfig: getConfig2,
     deleteIntegrations,
     endActivity,
+    heartbeat,
     getStudentXp,
     getRoster,
     getStudentOverview,
@@ -97343,6 +97521,7 @@ var init_timeback6 = __esm(() => {
   timebackRouter.get("/config/:gameId", handle2(timeback2.getConfig));
   timebackRouter.delete("/integrations/:gameId", handle2(timeback2.deleteIntegrations, { status: 204 }));
   timebackRouter.post("/end-activity", handle2(timeback2.endActivity));
+  timebackRouter.post("/heartbeat", handle2(timeback2.heartbeat));
   timebackRouter.get("/user", async (c2) => {
     const user = c2.get("user");
     const gameId = c2.get("gameId");