@playcademy/sandbox 0.12.2-beta.2 → 0.12.2-beta.3

package/dist/cli.js

@@ -2517,7 +2517,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@playcademy/sandbox",
-    version: "0.12.2-beta.2",
+    version: "0.12.2-beta.3",
     description: "Local development server for Playcademy game development",
     type: "module",
     exports: {
@@ -22888,6 +22888,9 @@ var init_helpers = __esm(() => {
 function isBaseGameTimebackIntegration() {
   return sql`${gameTimebackIntegrations.kind} = ${BASE_GAME_TIMEBACK_INTEGRATION_KIND}`;
 }
+function isBaseGameTimebackIntegrationRow(integration) {
+  return integration.kind === BASE_GAME_TIMEBACK_INTEGRATION_KIND;
+}
 function isActiveGameTimebackIntegrationStatus(statusColumn = gameTimebackIntegrations.status) {
   return sql`${statusColumn} IS DISTINCT FROM ${DEACTIVATED_GAME_TIMEBACK_INTEGRATION_STATUS}`;
 }
@@ -50496,6 +50499,7 @@ var init_schemas4 = __esm(() => {
     appName: stringType().optional(),
     sensorUrl: stringType().url().optional(),
     courseId: stringType().min(1).optional(),
+    enrollmentId: stringType().min(1).optional(),
     courseName: stringType().optional(),
     studentEmail: stringType().email().optional()
   });
@@ -92510,6 +92514,22 @@ var init_timeback_assessments_service = __esm(async () => {
   await init_errors8();
 });
 
+// ../api-core/src/utils/timeback-attribution.util.ts
+function resolveRuntimeAttribution(base, holeFilling, requestedCourseId, recordedCourseId) {
+  const recorded = [base, ...holeFilling].find((integration) => integration.courseId === recordedCourseId);
+  if (recorded) {
+    return { integration: recorded, requestedCourseIdStatus: "pinned_by_run" };
+  }
+  if (requestedCourseId === undefined) {
+    return { integration: base, requestedCourseIdStatus: "absent" };
+  }
+  if (requestedCourseId === base.courseId) {
+    return { integration: base, requestedCourseIdStatus: "accepted" };
+  }
+  const requestedHoleFilling = holeFilling.find((integration) => integration.courseId === requestedCourseId);
+  return requestedHoleFilling ? { integration: requestedHoleFilling, requestedCourseIdStatus: "accepted_hole_filling" } : { integration: base, requestedCourseIdStatus: "ignored_mismatch" };
+}
+
 // ../api-core/src/utils/timeback-create-integration.util.ts
 function buildTimebackBaseConfigFromExistingConfig(config) {
   return {
@@ -92769,13 +92789,13 @@ var init_timeback_service = __esm(async () => {
     static clearInFlightHeartbeatWindow(key) {
       this.inFlightHeartbeatWindows.delete(key);
     }
-    static buildCompletionCaliperEventId(key, kind, discriminator = "completion") {
+    static buildCompletionCaliperEventId(key, kind, baseCourseId, discriminator = "completion") {
       const hash = createHash3("sha256").update([
         "playcademy",
         "timeback",
         kind,
         key.gameId,
-        key.courseId,
+        baseCourseId,
         key.studentId,
         key.runId,
         key.activityId,
@@ -92841,11 +92861,14 @@ var init_timeback_service = __esm(async () => {
         } : null
       };
     }
-    static async acquireCompletionReservation(db, key) {
-      let reserveOutcome = await this.reserveCompletion(db, key);
+    static async acquireCompletionReservation(db, key, otherCourseIds = []) {
+      function reserve() {
+        return otherCourseIds.length > 0 ? TimebackService.reserveCompletionAcrossCourses(db, key, otherCourseIds) : TimebackService.reserveCompletion(db, key);
+      }
+      let reserveOutcome = await reserve();
       for (let settleAttempt = 0;reserveOutcome.status === "in_flight" && settleAttempt < this.COMPLETION_IN_FLIGHT_SETTLE_ATTEMPTS; settleAttempt++) {
         await sleep(this.COMPLETION_IN_FLIGHT_SETTLE_DELAY_MS);
-        reserveOutcome = await this.reserveCompletion(db, key);
+        reserveOutcome = await reserve();
       }
       if (reserveOutcome.status === "duplicate") {
         setAttribute("app.timeback.end_activity_status", "blocked_by_dedupe_guard");
@@ -92864,8 +92887,24 @@ var init_timeback_service = __esm(async () => {
       }
       return { status: "reserved", token: reserveOutcome.token };
     }
-    static async runWithCompletionReservation(db, key, emit, awardFromResult) {
-      const acquired = await this.acquireCompletionReservation(db, key);
+    static async reserveCompletionAcrossCourses(db, key, otherCourseIds) {
+      return db.transaction(async (tx) => {
+        const database = tx;
+        const runKey = `timeback-completion:${key.gameId.toLowerCase()}:${key.studentId}:${key.runId.toLowerCase()}:${key.activityId}`;
+        await database.execute(sql`SELECT pg_advisory_xact_lock(hashtextextended(${runKey}, 0))`);
+        const onOtherCourse = await database.query.gameTimebackActivityCompletions.findFirst({
+          columns: { id: true },
+          where: and(eq(gameTimebackActivityCompletions.gameId, key.gameId), eq(gameTimebackActivityCompletions.studentId, key.studentId), eq(gameTimebackActivityCompletions.runId, key.runId), eq(gameTimebackActivityCompletions.activityId, key.activityId), inArray(gameTimebackActivityCompletions.courseId, [...otherCourseIds]))
+        });
+        if (onOtherCourse) {
+          setAttribute("app.timeback.end_activity_status", "completion_reserved_on_other_course");
+          throw new ServiceUnavailableError("An end-activity submission for this run is already in flight — retry shortly");
+        }
+        return this.reserveCompletion(database, key);
+      });
+    }
+    static async runWithCompletionReservation(db, key, emit, awardFromResult, otherCourseIds = []) {
+      const acquired = await this.acquireCompletionReservation(db, key, otherCourseIds);
       if (acquired.status === "duplicate") {
         return acquired;
       }
@@ -92900,6 +92939,9 @@ var init_timeback_service = __esm(async () => {
       await db.delete(gameTimebackActivityCompletions).where(and(eq(gameTimebackActivityCompletions.id, token.id), eq(gameTimebackActivityCompletions.reservedAt, token.reservedAt), isNull(gameTimebackActivityCompletions.completedAt)));
     }
     static addResumeIdToExtensions(extensions, resumeId) {
+      return TimebackService.addPlaycademyExtensions(extensions, { resumeId });
+    }
+    static addPlaycademyExtensions(extensions, fields) {
       const base = extensions ?? {};
       const existingPlaycademy = base.playcademy;
       const playcademy = typeof existingPlaycademy === "object" && existingPlaycademy !== null && !Array.isArray(existingPlaycademy) ? existingPlaycademy : {};
@@ -92907,28 +92949,71 @@ var init_timeback_service = __esm(async () => {
         ...base,
         playcademy: {
           ...playcademy,
-          resumeId
+          ...fields
         }
       };
     }
-    static resolveRuntimeCourse(resolvedCourseId, requestedCourseId, courseName) {
-      let requestedCourseIdStatus = "absent";
-      if (requestedCourseId === resolvedCourseId) {
-        requestedCourseIdStatus = "accepted";
-      } else if (requestedCourseId !== undefined) {
-        requestedCourseIdStatus = "ignored_mismatch";
+    async resolveRuntimeCourse({
+      gameId,
+      studentId,
+      runId,
+      activityData,
+      extensions
+    }) {
+      const integrations = await this.deps.db.query.gameTimebackIntegrations.findMany({
+        where: and(eq(gameTimebackIntegrations.gameId, gameId), eq(gameTimebackIntegrations.grade, activityData.grade), eq(gameTimebackIntegrations.subject, activityData.subject), isActiveGameTimebackIntegrationStatus())
+      });
+      const base = integrations.find(isBaseGameTimebackIntegrationRow);
+      if (!base) {
+        throw new NotFoundError(`Timeback integration for game (grade ${activityData.grade}, subject ${activityData.subject})`);
       }
+      const holeFilling = integrations.filter((integration) => !isBaseGameTimebackIntegrationRow(integration));
+      const recordedCourseId = holeFilling.length > 0 && runId ? await this.findRecordedRunCourse({
+        gameId,
+        studentId,
+        runId,
+        activityId: activityData.activityId,
+        courseIds: integrations.map((i2) => i2.courseId)
+      }) : undefined;
+      const { integration, requestedCourseIdStatus } = resolveRuntimeAttribution(base, holeFilling, activityData.courseId, recordedCourseId);
+      const hintUsed = activityData.courseId === integration.courseId;
+      const enrollmentId = hintUsed ? activityData.enrollmentId : undefined;
+      const isHoleFilling = !isBaseGameTimebackIntegrationRow(integration);
       return {
-        courseId: resolvedCourseId,
-        courseName: requestedCourseIdStatus === "ignored_mismatch" ? undefined : courseName,
+        integration,
+        courseId: integration.courseId,
+        baseCourseId: base.courseId,
+        otherCourseIds: holeFilling.length > 0 ? integrations.map((other) => other.courseId).filter((courseId) => courseId !== integration.courseId) : [],
+        courseName: activityData.courseId === undefined || hintUsed ? activityData.courseName : undefined,
+        extensions: isHoleFilling ? TimebackService.addPlaycademyExtensions(extensions, {
+          courseKind: HOLE_FILLING_GAME_TIMEBACK_INTEGRATION_KIND,
+          baseCourseId: base.courseId,
+          ...enrollmentId && { enrollmentId }
+        }) : extensions,
         attributes: {
-          "app.timeback.course_id": resolvedCourseId,
-          "app.timeback.resolved_course_id": resolvedCourseId,
-          "app.timeback.requested_course_id": requestedCourseId,
-          "app.timeback.requested_course_id_status": requestedCourseIdStatus
+          "app.timeback.course_id": integration.courseId,
+          "app.timeback.resolved_course_id": integration.courseId,
+          "app.timeback.requested_course_id": activityData.courseId,
+          "app.timeback.requested_course_id_status": requestedCourseIdStatus,
+          "app.timeback.course_kind": integration.kind,
+          "app.timeback.enrollment_id": enrollmentId
         }
       };
     }
+    async findRecordedRunCourse({
+      gameId,
+      studentId,
+      runId,
+      activityId,
+      courseIds
+    }) {
+      const recorded = await this.deps.db.query.gameTimebackActivityCompletions.findFirst({
+        columns: { courseId: true },
+        where: and(eq(gameTimebackActivityCompletions.gameId, gameId), eq(gameTimebackActivityCompletions.studentId, studentId), eq(gameTimebackActivityCompletions.runId, runId), eq(gameTimebackActivityCompletions.activityId, activityId), inArray(gameTimebackActivityCompletions.courseId, courseIds)),
+        orderBy: (table, { asc }) => [asc(table.createdAt)]
+      });
+      return recorded?.courseId;
+    }
     static recordRuntimeContext({
       operation,
       studentId,
@@ -93910,17 +93995,21 @@ var init_timeback_service = __esm(async () => {
           activityData
         });
         await this.deps.validateDeveloperAccess(user, gameId);
-        const integration = await db.query.gameTimebackIntegrations.findFirst({
-          where: and(eq(gameTimebackIntegrations.gameId, gameId), eq(gameTimebackIntegrations.grade, activityData.grade), eq(gameTimebackIntegrations.subject, activityData.subject), isActiveBaseGameTimebackIntegration())
-        });
-        if (!integration) {
-          throw new NotFoundError(`Timeback integration for game (grade ${activityData.grade}, subject ${activityData.subject})`);
-        }
         const {
+          integration,
           courseId: runtimeCourseId,
+          baseCourseId,
+          otherCourseIds,
           courseName: runtimeCourseName,
+          extensions: runtimeExtensions,
           attributes: courseAttributes
-        } = TimebackService.resolveRuntimeCourse(integration.courseId, activityData.courseId, activityData.courseName);
+        } = await this.resolveRuntimeCourse({
+          gameId,
+          studentId,
+          runId,
+          activityData,
+          extensions: extensionsWithResumeId
+        });
         const scorePercentage = scoreData.totalQuestions > 0 ? scoreData.correctQuestions / scoreData.totalQuestions * 100 : 0;
         const dedupeKey = runId !== undefined ? {
           gameId,
@@ -93949,12 +94038,12 @@ var init_timeback_service = __esm(async () => {
           courseId: runtimeCourseId,
           courseName: runtimeCourseName,
           studentEmail: activityData.studentEmail,
-          extensions: extensionsWithResumeId,
+          extensions: runtimeExtensions,
           ...runId ? { runId } : {}
         };
-        const completionEventId = dedupeKey ? TimebackService.buildCompletionCaliperEventId(dedupeKey, "completion") : undefined;
-        const sessionEndEventId = dedupeKey ? TimebackService.buildCompletionCaliperEventId(dedupeKey, "session-end", effectiveResumeId) : undefined;
-        const completionHistoryEventId = dedupeKey ? TimebackService.buildCompletionCaliperEventId(dedupeKey, "course-completed") : undefined;
+        const completionEventId = dedupeKey ? TimebackService.buildCompletionCaliperEventId(dedupeKey, "completion", baseCourseId) : undefined;
+        const sessionEndEventId = dedupeKey ? TimebackService.buildCompletionCaliperEventId(dedupeKey, "session-end", baseCourseId, effectiveResumeId) : undefined;
+        const completionHistoryEventId = dedupeKey ? TimebackService.buildCompletionCaliperEventId(dedupeKey, "course-completed", baseCourseId) : undefined;
         function emitRecord() {
           return client.activity.record(runtimeCourseId, studentId, {
             ...activityEventContext,
@@ -93978,7 +94067,7 @@ var init_timeback_service = __esm(async () => {
             xpAwarded: emitted.xpAwarded,
             masteredUnitsApplied: emitted.masteredUnitsApplied,
             pctCompleteApp: emitted.pctCompleteApp ?? null
-          }));
+          }), otherCourseIds);
           if (outcome.status === "duplicate") {
             blockedByDedupeGuard = true;
             duplicateAward = outcome.award;
@@ -94026,6 +94115,7 @@ var init_timeback_service = __esm(async () => {
           return {
             status: "ok",
             courseId: runtimeCourseId,
+            courseKind: integration.kind,
             xpAwarded: duplicateAward?.xpAwarded ?? 0,
             masteredUnits: duplicateAward?.masteredUnitsApplied ?? 0,
             ...duplicateAward?.pctCompleteApp != null ? { pctCompleteApp: duplicateAward.pctCompleteApp } : {},
@@ -94038,6 +94128,7 @@ var init_timeback_service = __esm(async () => {
         return {
           status: "ok",
           courseId: runtimeCourseId,
+          courseKind: integration.kind,
           xpAwarded: result.xpAwarded,
           masteredUnits: result.masteredUnitsApplied,
           pctCompleteApp: result.pctCompleteApp,
@@ -94214,7 +94305,6 @@ var init_timeback_service = __esm(async () => {
     }) {
       return this.withClientTelemetry(async () => {
         const client = this.requireClient();
-        const db = this.deps.db;
         const hasWindowStartedAtMs = windowStartedAtMs !== undefined;
         const hasWindowSequence = windowSequence !== undefined;
         if (hasWindowStartedAtMs === hasWindowSequence) {
@@ -94242,17 +94332,17 @@ var init_timeback_service = __esm(async () => {
           return inFlightHeartbeat;
         }
         const pendingHeartbeat = (async () => {
-          const integration = await db.query.gameTimebackIntegrations.findFirst({
-            where: and(eq(gameTimebackIntegrations.gameId, gameId), eq(gameTimebackIntegrations.grade, activityData.grade), eq(gameTimebackIntegrations.subject, activityData.subject), isActiveBaseGameTimebackIntegration())
-          });
-          if (!integration) {
-            throw new NotFoundError(`Timeback integration for game (grade ${activityData.grade}, subject ${activityData.subject})`);
-          }
           const {
             courseId: runtimeCourseId,
             courseName: runtimeCourseName,
+            extensions: runtimeExtensions,
             attributes: courseAttributes
-          } = TimebackService.resolveRuntimeCourse(integration.courseId, activityData.courseId, activityData.courseName);
+          } = await this.resolveRuntimeCourse({
+            gameId,
+            studentId,
+            activityData,
+            extensions: TimebackService.addResumeIdToExtensions(undefined, effectiveResumeId)
+          });
           const activeTimeSeconds = timingData.activeMs / 1000;
           const inactiveTimeSeconds = timingData.pausedMs / 1000;
           if (activeTimeSeconds > 0 || inactiveTimeSeconds > 0) {
@@ -94268,7 +94358,7 @@ var init_timeback_service = __esm(async () => {
               courseId: runtimeCourseId,
               courseName: runtimeCourseName,
               studentEmail: activityData.studentEmail,
-              extensions: TimebackService.addResumeIdToExtensions(undefined, effectiveResumeId),
+              extensions: runtimeExtensions,
               ...runId ? { runId } : {}
             });
           }

package/dist/server.js

@@ -697,7 +697,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@playcademy/sandbox",
-    version: "0.12.2-beta.2",
+    version: "0.12.2-beta.3",
     description: "Local development server for Playcademy game development",
     type: "module",
     exports: {
@@ -21068,6 +21068,9 @@ var init_helpers = __esm(() => {
 function isBaseGameTimebackIntegration() {
   return sql`${gameTimebackIntegrations.kind} = ${BASE_GAME_TIMEBACK_INTEGRATION_KIND}`;
 }
+function isBaseGameTimebackIntegrationRow(integration) {
+  return integration.kind === BASE_GAME_TIMEBACK_INTEGRATION_KIND;
+}
 function isActiveGameTimebackIntegrationStatus(statusColumn = gameTimebackIntegrations.status) {
   return sql`${statusColumn} IS DISTINCT FROM ${DEACTIVATED_GAME_TIMEBACK_INTEGRATION_STATUS}`;
 }
@@ -48676,6 +48679,7 @@ var init_schemas4 = __esm(() => {
     appName: stringType().optional(),
     sensorUrl: stringType().url().optional(),
     courseId: stringType().min(1).optional(),
+    enrollmentId: stringType().min(1).optional(),
     courseName: stringType().optional(),
     studentEmail: stringType().email().optional()
   });
@@ -90690,6 +90694,22 @@ var init_timeback_assessments_service = __esm(async () => {
   await init_errors8();
 });
 
+// ../api-core/src/utils/timeback-attribution.util.ts
+function resolveRuntimeAttribution(base, holeFilling, requestedCourseId, recordedCourseId) {
+  const recorded = [base, ...holeFilling].find((integration) => integration.courseId === recordedCourseId);
+  if (recorded) {
+    return { integration: recorded, requestedCourseIdStatus: "pinned_by_run" };
+  }
+  if (requestedCourseId === undefined) {
+    return { integration: base, requestedCourseIdStatus: "absent" };
+  }
+  if (requestedCourseId === base.courseId) {
+    return { integration: base, requestedCourseIdStatus: "accepted" };
+  }
+  const requestedHoleFilling = holeFilling.find((integration) => integration.courseId === requestedCourseId);
+  return requestedHoleFilling ? { integration: requestedHoleFilling, requestedCourseIdStatus: "accepted_hole_filling" } : { integration: base, requestedCourseIdStatus: "ignored_mismatch" };
+}
+
 // ../api-core/src/utils/timeback-create-integration.util.ts
 function buildTimebackBaseConfigFromExistingConfig(config) {
   return {
@@ -90949,13 +90969,13 @@ var init_timeback_service = __esm(async () => {
     static clearInFlightHeartbeatWindow(key) {
       this.inFlightHeartbeatWindows.delete(key);
     }
-    static buildCompletionCaliperEventId(key, kind, discriminator = "completion") {
+    static buildCompletionCaliperEventId(key, kind, baseCourseId, discriminator = "completion") {
       const hash = createHash3("sha256").update([
         "playcademy",
         "timeback",
         kind,
         key.gameId,
-        key.courseId,
+        baseCourseId,
         key.studentId,
         key.runId,
         key.activityId,
@@ -91021,11 +91041,14 @@ var init_timeback_service = __esm(async () => {
         } : null
       };
     }
-    static async acquireCompletionReservation(db, key) {
-      let reserveOutcome = await this.reserveCompletion(db, key);
+    static async acquireCompletionReservation(db, key, otherCourseIds = []) {
+      function reserve() {
+        return otherCourseIds.length > 0 ? TimebackService.reserveCompletionAcrossCourses(db, key, otherCourseIds) : TimebackService.reserveCompletion(db, key);
+      }
+      let reserveOutcome = await reserve();
       for (let settleAttempt = 0;reserveOutcome.status === "in_flight" && settleAttempt < this.COMPLETION_IN_FLIGHT_SETTLE_ATTEMPTS; settleAttempt++) {
         await sleep(this.COMPLETION_IN_FLIGHT_SETTLE_DELAY_MS);
-        reserveOutcome = await this.reserveCompletion(db, key);
+        reserveOutcome = await reserve();
       }
       if (reserveOutcome.status === "duplicate") {
         setAttribute("app.timeback.end_activity_status", "blocked_by_dedupe_guard");
@@ -91044,8 +91067,24 @@ var init_timeback_service = __esm(async () => {
       }
       return { status: "reserved", token: reserveOutcome.token };
     }
-    static async runWithCompletionReservation(db, key, emit, awardFromResult) {
-      const acquired = await this.acquireCompletionReservation(db, key);
+    static async reserveCompletionAcrossCourses(db, key, otherCourseIds) {
+      return db.transaction(async (tx) => {
+        const database = tx;
+        const runKey = `timeback-completion:${key.gameId.toLowerCase()}:${key.studentId}:${key.runId.toLowerCase()}:${key.activityId}`;
+        await database.execute(sql`SELECT pg_advisory_xact_lock(hashtextextended(${runKey}, 0))`);
+        const onOtherCourse = await database.query.gameTimebackActivityCompletions.findFirst({
+          columns: { id: true },
+          where: and(eq(gameTimebackActivityCompletions.gameId, key.gameId), eq(gameTimebackActivityCompletions.studentId, key.studentId), eq(gameTimebackActivityCompletions.runId, key.runId), eq(gameTimebackActivityCompletions.activityId, key.activityId), inArray(gameTimebackActivityCompletions.courseId, [...otherCourseIds]))
+        });
+        if (onOtherCourse) {
+          setAttribute("app.timeback.end_activity_status", "completion_reserved_on_other_course");
+          throw new ServiceUnavailableError("An end-activity submission for this run is already in flight — retry shortly");
+        }
+        return this.reserveCompletion(database, key);
+      });
+    }
+    static async runWithCompletionReservation(db, key, emit, awardFromResult, otherCourseIds = []) {
+      const acquired = await this.acquireCompletionReservation(db, key, otherCourseIds);
       if (acquired.status === "duplicate") {
         return acquired;
       }
@@ -91080,6 +91119,9 @@ var init_timeback_service = __esm(async () => {
       await db.delete(gameTimebackActivityCompletions).where(and(eq(gameTimebackActivityCompletions.id, token.id), eq(gameTimebackActivityCompletions.reservedAt, token.reservedAt), isNull(gameTimebackActivityCompletions.completedAt)));
     }
     static addResumeIdToExtensions(extensions, resumeId) {
+      return TimebackService.addPlaycademyExtensions(extensions, { resumeId });
+    }
+    static addPlaycademyExtensions(extensions, fields) {
       const base = extensions ?? {};
       const existingPlaycademy = base.playcademy;
       const playcademy = typeof existingPlaycademy === "object" && existingPlaycademy !== null && !Array.isArray(existingPlaycademy) ? existingPlaycademy : {};
@@ -91087,28 +91129,71 @@ var init_timeback_service = __esm(async () => {
         ...base,
         playcademy: {
           ...playcademy,
-          resumeId
+          ...fields
         }
       };
     }
-    static resolveRuntimeCourse(resolvedCourseId, requestedCourseId, courseName) {
-      let requestedCourseIdStatus = "absent";
-      if (requestedCourseId === resolvedCourseId) {
-        requestedCourseIdStatus = "accepted";
-      } else if (requestedCourseId !== undefined) {
-        requestedCourseIdStatus = "ignored_mismatch";
+    async resolveRuntimeCourse({
+      gameId,
+      studentId,
+      runId,
+      activityData,
+      extensions
+    }) {
+      const integrations = await this.deps.db.query.gameTimebackIntegrations.findMany({
+        where: and(eq(gameTimebackIntegrations.gameId, gameId), eq(gameTimebackIntegrations.grade, activityData.grade), eq(gameTimebackIntegrations.subject, activityData.subject), isActiveGameTimebackIntegrationStatus())
+      });
+      const base = integrations.find(isBaseGameTimebackIntegrationRow);
+      if (!base) {
+        throw new NotFoundError(`Timeback integration for game (grade ${activityData.grade}, subject ${activityData.subject})`);
       }
+      const holeFilling = integrations.filter((integration) => !isBaseGameTimebackIntegrationRow(integration));
+      const recordedCourseId = holeFilling.length > 0 && runId ? await this.findRecordedRunCourse({
+        gameId,
+        studentId,
+        runId,
+        activityId: activityData.activityId,
+        courseIds: integrations.map((i2) => i2.courseId)
+      }) : undefined;
+      const { integration, requestedCourseIdStatus } = resolveRuntimeAttribution(base, holeFilling, activityData.courseId, recordedCourseId);
+      const hintUsed = activityData.courseId === integration.courseId;
+      const enrollmentId = hintUsed ? activityData.enrollmentId : undefined;
+      const isHoleFilling = !isBaseGameTimebackIntegrationRow(integration);
       return {
-        courseId: resolvedCourseId,
-        courseName: requestedCourseIdStatus === "ignored_mismatch" ? undefined : courseName,
+        integration,
+        courseId: integration.courseId,
+        baseCourseId: base.courseId,
+        otherCourseIds: holeFilling.length > 0 ? integrations.map((other) => other.courseId).filter((courseId) => courseId !== integration.courseId) : [],
+        courseName: activityData.courseId === undefined || hintUsed ? activityData.courseName : undefined,
+        extensions: isHoleFilling ? TimebackService.addPlaycademyExtensions(extensions, {
+          courseKind: HOLE_FILLING_GAME_TIMEBACK_INTEGRATION_KIND,
+          baseCourseId: base.courseId,
+          ...enrollmentId && { enrollmentId }
+        }) : extensions,
         attributes: {
-          "app.timeback.course_id": resolvedCourseId,
-          "app.timeback.resolved_course_id": resolvedCourseId,
-          "app.timeback.requested_course_id": requestedCourseId,
-          "app.timeback.requested_course_id_status": requestedCourseIdStatus
+          "app.timeback.course_id": integration.courseId,
+          "app.timeback.resolved_course_id": integration.courseId,
+          "app.timeback.requested_course_id": activityData.courseId,
+          "app.timeback.requested_course_id_status": requestedCourseIdStatus,
+          "app.timeback.course_kind": integration.kind,
+          "app.timeback.enrollment_id": enrollmentId
         }
       };
     }
+    async findRecordedRunCourse({
+      gameId,
+      studentId,
+      runId,
+      activityId,
+      courseIds
+    }) {
+      const recorded = await this.deps.db.query.gameTimebackActivityCompletions.findFirst({
+        columns: { courseId: true },
+        where: and(eq(gameTimebackActivityCompletions.gameId, gameId), eq(gameTimebackActivityCompletions.studentId, studentId), eq(gameTimebackActivityCompletions.runId, runId), eq(gameTimebackActivityCompletions.activityId, activityId), inArray(gameTimebackActivityCompletions.courseId, courseIds)),
+        orderBy: (table, { asc }) => [asc(table.createdAt)]
+      });
+      return recorded?.courseId;
+    }
     static recordRuntimeContext({
       operation,
       studentId,
@@ -92090,17 +92175,21 @@ var init_timeback_service = __esm(async () => {
           activityData
         });
         await this.deps.validateDeveloperAccess(user, gameId);
-        const integration = await db.query.gameTimebackIntegrations.findFirst({
-          where: and(eq(gameTimebackIntegrations.gameId, gameId), eq(gameTimebackIntegrations.grade, activityData.grade), eq(gameTimebackIntegrations.subject, activityData.subject), isActiveBaseGameTimebackIntegration())
-        });
-        if (!integration) {
-          throw new NotFoundError(`Timeback integration for game (grade ${activityData.grade}, subject ${activityData.subject})`);
-        }
         const {
+          integration,
           courseId: runtimeCourseId,
+          baseCourseId,
+          otherCourseIds,
           courseName: runtimeCourseName,
+          extensions: runtimeExtensions,
           attributes: courseAttributes
-        } = TimebackService.resolveRuntimeCourse(integration.courseId, activityData.courseId, activityData.courseName);
+        } = await this.resolveRuntimeCourse({
+          gameId,
+          studentId,
+          runId,
+          activityData,
+          extensions: extensionsWithResumeId
+        });
         const scorePercentage = scoreData.totalQuestions > 0 ? scoreData.correctQuestions / scoreData.totalQuestions * 100 : 0;
         const dedupeKey = runId !== undefined ? {
           gameId,
@@ -92129,12 +92218,12 @@ var init_timeback_service = __esm(async () => {
           courseId: runtimeCourseId,
           courseName: runtimeCourseName,
           studentEmail: activityData.studentEmail,
-          extensions: extensionsWithResumeId,
+          extensions: runtimeExtensions,
           ...runId ? { runId } : {}
         };
-        const completionEventId = dedupeKey ? TimebackService.buildCompletionCaliperEventId(dedupeKey, "completion") : undefined;
-        const sessionEndEventId = dedupeKey ? TimebackService.buildCompletionCaliperEventId(dedupeKey, "session-end", effectiveResumeId) : undefined;
-        const completionHistoryEventId = dedupeKey ? TimebackService.buildCompletionCaliperEventId(dedupeKey, "course-completed") : undefined;
+        const completionEventId = dedupeKey ? TimebackService.buildCompletionCaliperEventId(dedupeKey, "completion", baseCourseId) : undefined;
+        const sessionEndEventId = dedupeKey ? TimebackService.buildCompletionCaliperEventId(dedupeKey, "session-end", baseCourseId, effectiveResumeId) : undefined;
+        const completionHistoryEventId = dedupeKey ? TimebackService.buildCompletionCaliperEventId(dedupeKey, "course-completed", baseCourseId) : undefined;
         function emitRecord() {
           return client.activity.record(runtimeCourseId, studentId, {
             ...activityEventContext,
@@ -92158,7 +92247,7 @@ var init_timeback_service = __esm(async () => {
             xpAwarded: emitted.xpAwarded,
             masteredUnitsApplied: emitted.masteredUnitsApplied,
             pctCompleteApp: emitted.pctCompleteApp ?? null
-          }));
+          }), otherCourseIds);
           if (outcome.status === "duplicate") {
             blockedByDedupeGuard = true;
             duplicateAward = outcome.award;
@@ -92206,6 +92295,7 @@ var init_timeback_service = __esm(async () => {
           return {
             status: "ok",
             courseId: runtimeCourseId,
+            courseKind: integration.kind,
             xpAwarded: duplicateAward?.xpAwarded ?? 0,
             masteredUnits: duplicateAward?.masteredUnitsApplied ?? 0,
             ...duplicateAward?.pctCompleteApp != null ? { pctCompleteApp: duplicateAward.pctCompleteApp } : {},
@@ -92218,6 +92308,7 @@ var init_timeback_service = __esm(async () => {
         return {
           status: "ok",
           courseId: runtimeCourseId,
+          courseKind: integration.kind,
           xpAwarded: result.xpAwarded,
           masteredUnits: result.masteredUnitsApplied,
           pctCompleteApp: result.pctCompleteApp,
@@ -92394,7 +92485,6 @@ var init_timeback_service = __esm(async () => {
     }) {
       return this.withClientTelemetry(async () => {
         const client = this.requireClient();
-        const db = this.deps.db;
         const hasWindowStartedAtMs = windowStartedAtMs !== undefined;
         const hasWindowSequence = windowSequence !== undefined;
         if (hasWindowStartedAtMs === hasWindowSequence) {
@@ -92422,17 +92512,17 @@ var init_timeback_service = __esm(async () => {
           return inFlightHeartbeat;
         }
         const pendingHeartbeat = (async () => {
-          const integration = await db.query.gameTimebackIntegrations.findFirst({
-            where: and(eq(gameTimebackIntegrations.gameId, gameId), eq(gameTimebackIntegrations.grade, activityData.grade), eq(gameTimebackIntegrations.subject, activityData.subject), isActiveBaseGameTimebackIntegration())
-          });
-          if (!integration) {
-            throw new NotFoundError(`Timeback integration for game (grade ${activityData.grade}, subject ${activityData.subject})`);
-          }
           const {
             courseId: runtimeCourseId,
             courseName: runtimeCourseName,
+            extensions: runtimeExtensions,
             attributes: courseAttributes
-          } = TimebackService.resolveRuntimeCourse(integration.courseId, activityData.courseId, activityData.courseName);
+          } = await this.resolveRuntimeCourse({
+            gameId,
+            studentId,
+            activityData,
+            extensions: TimebackService.addResumeIdToExtensions(undefined, effectiveResumeId)
+          });
           const activeTimeSeconds = timingData.activeMs / 1000;
           const inactiveTimeSeconds = timingData.pausedMs / 1000;
           if (activeTimeSeconds > 0 || inactiveTimeSeconds > 0) {
@@ -92448,7 +92538,7 @@ var init_timeback_service = __esm(async () => {
               courseId: runtimeCourseId,
               courseName: runtimeCourseName,
               studentEmail: activityData.studentEmail,
-              extensions: TimebackService.addResumeIdToExtensions(undefined, effectiveResumeId),
+              extensions: runtimeExtensions,
               ...runId ? { runId } : {}
             });
           }

package/package.json

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