@playcademy/sandbox 0.6.1-beta.1 → 0.6.1-beta.3

package/dist/cli.js

@@ -1080,7 +1080,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@playcademy/sandbox",
-    version: "0.6.1-beta.1",
+    version: "0.6.1-beta.3",
     description: "Local development server for Playcademy game development",
     type: "module",
     exports: {
@@ -11330,7 +11330,7 @@ var init_table6 = __esm(() => {
 });
 
 // ../data/src/domains/timeback/table.ts
-var gameTimebackIntegrationStatusEnum, gameTimebackIntegrations, gameTimebackAssessmentTests, gameTimebackMetricDiscrepancyVerifications;
+var gameTimebackIntegrationStatusEnum, gameTimebackIntegrations, gameTimebackAssessmentTests, gameTimebackMetricDiscrepancyVerifications, gameTimebackActivityCompletions;
 var init_table7 = __esm(() => {
   init_drizzle_orm();
   init_pg_core();
@@ -11382,6 +11382,22 @@ var init_table7 = __esm(() => {
     uniqueIndex("game_timeback_metric_discrepancy_verifications_run_idx").on(table3.gameId, table3.courseId, table3.studentId, table3.runId),
     index("game_timeback_metric_discrepancy_verifications_course_idx").on(table3.gameId, table3.courseId, table3.verifiedAt)
   ]);
+  gameTimebackActivityCompletions = pgTable("game_timeback_activity_completions", {
+    id: uuid("id").primaryKey().defaultRandom(),
+    gameId: uuid("game_id").notNull().references(() => games.id, { onDelete: "cascade" }),
+    courseId: text("course_id").notNull(),
+    studentId: text("student_id").notNull(),
+    runId: uuid("run_id").notNull(),
+    activityId: text("activity_id").notNull(),
+    completedAt: timestamp("completed_at", { withTimezone: true }),
+    reservedAt: timestamp("reserved_at", { withTimezone: true, mode: "string" }).notNull().defaultNow(),
+    xpAwarded: doublePrecision("xp_awarded"),
+    masteredUnitsApplied: integer("mastered_units_applied"),
+    pctCompleteApp: doublePrecision("pct_complete_app"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow()
+  }, (table3) => [
+    uniqueIndex("game_timeback_activity_completions_run_idx").on(table3.gameId, table3.courseId, table3.studentId, table3.runId, table3.activityId)
+  ]);
 });
 
 // ../data/src/tables.index.ts
@@ -11399,6 +11415,7 @@ __export(exports_tables_index, {
   gameTimebackIntegrations: () => gameTimebackIntegrations,
   gameTimebackIntegrationStatusEnum: () => gameTimebackIntegrationStatusEnum,
   gameTimebackAssessmentTests: () => gameTimebackAssessmentTests,
+  gameTimebackActivityCompletions: () => gameTimebackActivityCompletions,
   gameScoresRelations: () => gameScoresRelations,
   gameScores: () => gameScores,
   gamePlatformEnum: () => gamePlatformEnum,
@@ -24677,6 +24694,10 @@ var init_constants2 = __esm(() => {
   GAME_WORKER_DOMAIN_PRODUCTION = GAME_WORKER_DOMAINS.production;
   GAME_WORKER_DOMAIN_STAGING = GAME_WORKER_DOMAINS.staging;
 });
+
+// ../cloudflare/src/playcademy/provider/assets-config.ts
+var init_assets_config = () => {};
+
 // ../cloudflare/src/playcademy/provider/bindings.ts
 var init_bindings = __esm(() => {
   init_constants2();
@@ -24693,6 +24714,7 @@ var init_provider = __esm(() => {
   init_src();
   init_core();
   init_constants2();
+  init_assets_config();
   init_bindings();
   init_helpers();
 });
@@ -27135,12 +27157,21 @@ var init_tunnel = __esm(() => {
   METRICS_BASE = `http://127.0.0.1:${TUNNEL_METRICS_PORT}`;
 });
 
+// ../utils/src/stages.ts
+function isPreviewStage(stage) {
+  return PREVIEW_STAGE_PATTERN.test(stage);
+}
+var PREVIEW_STAGE_PATTERN;
+var init_stages = __esm(() => {
+  PREVIEW_STAGE_PATTERN = /^pr-\d+$/;
+});
+
 // ../api-core/src/utils/deployment.util.ts
 function getDeploymentId(gameSlug, sstStage) {
   if (sstStage === "production") {
     return gameSlug;
   }
-  if (sstStage === "dev" || sstStage.startsWith("pr-")) {
+  if (sstStage === "dev" || isPreviewStage(sstStage)) {
     return `${WORKER_NAMING.STAGING_PREFIX}${gameSlug}`;
   }
   return `${WORKER_NAMING.LOCAL_PREFIX}${sstStage}-${gameSlug}`;
@@ -27160,6 +27191,7 @@ async function generateDeploymentHash(code) {
 }
 var init_deployment_util = __esm(() => {
   init_src();
+  init_stages();
 });
 
 // ../api-core/src/services/deploy.service.ts
@@ -31047,7 +31079,7 @@ var init_schemas4 = __esm(() => {
     subject: TimebackSubjectSchema,
     appName: exports_external.string().optional(),
     sensorUrl: exports_external.string().url().optional(),
-    courseId: exports_external.string().optional(),
+    courseId: exports_external.string().min(1).optional(),
     courseName: exports_external.string().optional(),
     studentEmail: exports_external.string().email().optional()
   });
@@ -74823,7 +74855,8 @@ class ActivityRecord {
         courseName,
         subject: progressData.subject,
         appName: progressData.appName,
-        sensorUrl: progressData.sensorUrl
+        sensorUrl: progressData.sensorUrl,
+        eventId: progressData.completionHistoryEventId
       });
     }
     if (masteryProgress?.masteryRevoked) {
@@ -74848,6 +74881,7 @@ class ActivityRecord {
         subject: progressData.subject,
         appName: progressData.appName,
         sensorUrl: progressData.sensorUrl,
+        eventId: progressData.eventId,
         extensions: extensions || progressData.extensions,
         ...progressData.runId ? { runId: progressData.runId } : {}
       }).catch((error88) => {
@@ -74871,6 +74905,7 @@ class ActivityRecord {
   }
   async emitCourseCompletionHistoryEvent(data) {
     await this.events.emitActivityEvent({
+      eventId: data.eventId,
       studentId: data.studentId,
       studentEmail: data.studentEmail,
       gameId: data.gameId,
@@ -74986,6 +75021,7 @@ class ActivitySession {
       subject: sessionData.subject,
       appName: sessionData.appName,
       sensorUrl: sessionData.sensorUrl,
+      eventId: sessionData.eventId,
       ...runId ? { runId } : {},
       ...extensions ? { extensions } : {}
     });
@@ -75252,6 +75288,9 @@ class ActivityEvents {
       } : {},
       ...eventExtensions ? { extensions: eventExtensions } : {}
     });
+    if (data.eventId) {
+      event.id = data.eventId;
+    }
     await this.core.api.caliper.events.send(data.sensorUrl, [event]);
   }
   async emitTimeSpentEvent(data) {
@@ -75283,6 +75322,9 @@ class ActivityEvents {
       ...data.runId ? { session: `urn:uuid:${data.runId}` } : {},
       ...eventExtensions ? { extensions: eventExtensions } : {}
     });
+    if (data.eventId) {
+      event.id = data.eventId;
+    }
     const wireEvent = data.extensions ? { ...event, generated: { ...event.generated, extensions: data.extensions } } : event;
     await this.core.api.caliper.events.send(data.sensorUrl, [wireEvent]);
   }
@@ -80315,6 +80357,7 @@ var init_timeback_removed_integration_util = __esm(() => {
 });
 
 // ../api-core/src/services/timeback.service.ts
+import { createHash as createHash2 } from "node:crypto";
 async function findGameTimebackIntegrationForUpdate(db2, condition) {
   const [integration] = await db2.select().from(gameTimebackIntegrations).where(condition).limit(1).for("update");
   return integration;
@@ -80337,6 +80380,9 @@ var init_timeback_service = __esm(async () => {
     static HEARTBEAT_DEDUPE_TTL_MS = 5 * 60 * 1000;
     static processedHeartbeatWindows = new Map;
     static inFlightHeartbeatWindows = new Map;
+    static COMPLETION_RESERVATION_STALE_SECONDS = 5 * 60;
+    static COMPLETION_IN_FLIGHT_SETTLE_DELAY_MS = 400;
+    static COMPLETION_IN_FLIGHT_SETTLE_ATTEMPTS = 5;
     deps;
     static cleanHeartbeatDedupeCache(now2 = Date.now()) {
       for (const [key, timestamp6] of this.processedHeartbeatWindows) {
@@ -80361,6 +80407,136 @@ var init_timeback_service = __esm(async () => {
     static clearInFlightHeartbeatWindow(key) {
       this.inFlightHeartbeatWindows.delete(key);
     }
+    static buildCompletionCaliperEventId(key, kind, discriminator = "completion") {
+      const hash2 = createHash2("sha256").update([
+        "playcademy",
+        "timeback",
+        kind,
+        key.gameId,
+        key.courseId,
+        key.studentId,
+        key.runId,
+        key.activityId,
+        discriminator
+      ].join("\x00")).digest("hex");
+      const variant = (Number.parseInt(hash2.slice(16, 18), 16) & 63 | 128).toString(16).padStart(2, "0");
+      const uuid9 = [
+        hash2.slice(0, 8),
+        hash2.slice(8, 12),
+        `5${hash2.slice(13, 16)}`,
+        `${variant}${hash2.slice(18, 20)}`,
+        hash2.slice(20, 32)
+      ].join("-");
+      return `urn:uuid:${uuid9}`;
+    }
+    static async reserveCompletion(db2, key) {
+      const [reserved] = await db2.insert(gameTimebackActivityCompletions).values({
+        gameId: key.gameId,
+        courseId: key.courseId,
+        studentId: key.studentId,
+        runId: key.runId,
+        activityId: key.activityId
+      }).onConflictDoUpdate({
+        target: [
+          gameTimebackActivityCompletions.gameId,
+          gameTimebackActivityCompletions.courseId,
+          gameTimebackActivityCompletions.studentId,
+          gameTimebackActivityCompletions.runId,
+          gameTimebackActivityCompletions.activityId
+        ],
+        set: { reservedAt: sql`now()` },
+        setWhere: sql`${gameTimebackActivityCompletions.completedAt} IS NULL AND ${gameTimebackActivityCompletions.reservedAt} < now() - make_interval(secs => ${TimebackService.COMPLETION_RESERVATION_STALE_SECONDS})`
+      }).returning({
+        id: gameTimebackActivityCompletions.id,
+        reservedAt: gameTimebackActivityCompletions.reservedAt,
+        takenOver: sql`${gameTimebackActivityCompletions.reservedAt} <> ${gameTimebackActivityCompletions.createdAt}`
+      });
+      if (reserved) {
+        return {
+          status: "reserved",
+          token: { id: reserved.id, reservedAt: reserved.reservedAt },
+          takenOver: reserved.takenOver
+        };
+      }
+      const existing = await db2.query.gameTimebackActivityCompletions.findFirst({
+        where: and(eq(gameTimebackActivityCompletions.gameId, key.gameId), eq(gameTimebackActivityCompletions.courseId, key.courseId), eq(gameTimebackActivityCompletions.studentId, key.studentId), eq(gameTimebackActivityCompletions.runId, key.runId), eq(gameTimebackActivityCompletions.activityId, key.activityId)),
+        columns: {
+          completedAt: true,
+          xpAwarded: true,
+          masteredUnitsApplied: true,
+          pctCompleteApp: true
+        }
+      });
+      if (!existing?.completedAt) {
+        return { status: "in_flight" };
+      }
+      return {
+        status: "duplicate",
+        award: existing.xpAwarded !== null ? {
+          xpAwarded: existing.xpAwarded,
+          masteredUnitsApplied: existing.masteredUnitsApplied ?? 0,
+          pctCompleteApp: existing.pctCompleteApp
+        } : null
+      };
+    }
+    static async acquireCompletionReservation(db2, key) {
+      let reserveOutcome = await this.reserveCompletion(db2, key);
+      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(db2, key);
+      }
+      if (reserveOutcome.status === "duplicate") {
+        setAttribute("app.timeback.end_activity_status", "blocked_by_dedupe_guard");
+        return reserveOutcome;
+      }
+      if (reserveOutcome.status === "in_flight") {
+        setAttribute("app.timeback.end_activity_status", "completion_reservation_in_flight");
+        throw new ServiceUnavailableError("An end-activity submission for this run is already in flight — retry shortly");
+      }
+      if (reserveOutcome.takenOver) {
+        setAttribute("app.timeback.completion_reservation_takeover", true);
+        addEvent("timeback.completion_reservation_takeover", {
+          "app.timeback.run_id": key.runId,
+          "app.timeback.activity_id": key.activityId
+        });
+      }
+      return { status: "reserved", token: reserveOutcome.token };
+    }
+    static async runWithCompletionReservation(db2, key, emit, awardFromResult) {
+      const acquired = await this.acquireCompletionReservation(db2, key);
+      if (acquired.status === "duplicate") {
+        return acquired;
+      }
+      const logContext = { run_id: key.runId, activity_id: key.activityId };
+      let result;
+      try {
+        result = await emit();
+      } catch (error88) {
+        try {
+          await this.rollbackCompletion(db2, acquired.token);
+        } catch (rollbackError) {
+          logTimebackError("rollback completion reservation", rollbackError, logContext);
+        }
+        throw error88;
+      }
+      try {
+        await this.confirmCompletion(db2, acquired.token, awardFromResult(result));
+      } catch (confirmError) {
+        logTimebackError("confirm completion reservation", confirmError, logContext);
+      }
+      return { status: "emitted", result };
+    }
+    static async confirmCompletion(db2, token, award) {
+      await db2.update(gameTimebackActivityCompletions).set({
+        completedAt: sql`now()`,
+        xpAwarded: award.xpAwarded,
+        masteredUnitsApplied: award.masteredUnitsApplied,
+        pctCompleteApp: award.pctCompleteApp
+      }).where(and(eq(gameTimebackActivityCompletions.id, token.id), eq(gameTimebackActivityCompletions.reservedAt, token.reservedAt), isNull(gameTimebackActivityCompletions.completedAt)));
+    }
+    static async rollbackCompletion(db2, token) {
+      await db2.delete(gameTimebackActivityCompletions).where(and(eq(gameTimebackActivityCompletions.id, token.id), eq(gameTimebackActivityCompletions.reservedAt, token.reservedAt), isNull(gameTimebackActivityCompletions.completedAt)));
+    }
     static addResumeIdToExtensions(extensions, resumeId) {
       const base = extensions ?? {};
       const existingPlaycademy = base.playcademy;
@@ -80373,6 +80549,24 @@ var init_timeback_service = __esm(async () => {
         }
       };
     }
+    static resolveRuntimeCourse(resolvedCourseId, requestedCourseId, courseName) {
+      let requestedCourseIdStatus = "absent";
+      if (requestedCourseId === resolvedCourseId) {
+        requestedCourseIdStatus = "accepted";
+      } else if (requestedCourseId !== undefined) {
+        requestedCourseIdStatus = "ignored_mismatch";
+      }
+      return {
+        courseId: resolvedCourseId,
+        courseName: requestedCourseIdStatus === "ignored_mismatch" ? undefined : courseName,
+        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
+        }
+      };
+    }
     static recordRuntimeContext({
       operation,
       studentId,
@@ -81238,67 +81432,128 @@ var init_timeback_service = __esm(async () => {
         if (!integration) {
           throw new NotFoundError(`Timeback integration for game (grade ${activityData.grade}, subject ${activityData.subject})`);
         }
+        const {
+          courseId: runtimeCourseId,
+          courseName: runtimeCourseName,
+          attributes: courseAttributes
+        } = TimebackService.resolveRuntimeCourse(integration.courseId, activityData.courseId, activityData.courseName);
         const scorePercentage = scoreData.totalQuestions > 0 ? scoreData.correctQuestions / scoreData.totalQuestions * 100 : 0;
-        const result = await client.activity.record(integration.courseId, studentId, {
+        const dedupeKey = runId !== undefined ? {
+          gameId,
+          courseId: runtimeCourseId,
+          studentId,
+          runId,
+          activityId: activityData.activityId
+        } : undefined;
+        setAttributes({
+          ...courseAttributes,
+          "app.timeback.grade": activityData.grade,
+          "app.timeback.subject": activityData.subject,
+          "app.timeback.total_questions": scoreData.totalQuestions,
+          "app.timeback.correct_questions": scoreData.correctQuestions,
+          "app.timeback.score_pct": scorePercentage,
+          "app.timeback.xp_requested": xpEarned
+        });
+        const courseTotalXp = integration.totalXp;
+        const activityEventContext = {
           gameId,
-          score: scorePercentage,
-          totalQuestions: scoreData.totalQuestions,
-          correctQuestions: scoreData.correctQuestions,
-          durationSeconds: timingData.durationSeconds,
-          xpEarned,
-          masteredUnits,
-          masteredUnitsAbsolute,
-          extensions: extensionsWithResumeId,
           activityId: activityData.activityId,
           activityName: activityData.activityName,
           subject: activityData.subject,
           appName: activityData.appName,
           sensorUrl: activityData.sensorUrl,
-          courseId: activityData.courseId,
-          courseName: activityData.courseName,
+          courseId: runtimeCourseId,
+          courseName: runtimeCourseName,
           studentEmail: activityData.studentEmail,
-          courseTotalXp: integration.totalXp,
+          extensions: extensionsWithResumeId,
           ...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;
+        function emitRecord() {
+          return client.activity.record(runtimeCourseId, studentId, {
+            ...activityEventContext,
+            eventId: completionEventId,
+            completionHistoryEventId,
+            score: scorePercentage,
+            totalQuestions: scoreData.totalQuestions,
+            correctQuestions: scoreData.correctQuestions,
+            durationSeconds: timingData.durationSeconds,
+            xpEarned,
+            masteredUnits,
+            masteredUnitsAbsolute,
+            courseTotalXp
+          });
+        }
+        let result;
+        let blockedByDedupeGuard = false;
+        let duplicateAward = null;
+        if (dedupeKey) {
+          const outcome = await TimebackService.runWithCompletionReservation(db2, dedupeKey, emitRecord, (emitted) => ({
+            xpAwarded: emitted.xpAwarded,
+            masteredUnitsApplied: emitted.masteredUnitsApplied,
+            pctCompleteApp: emitted.pctCompleteApp ?? null
+          }));
+          if (outcome.status === "duplicate") {
+            blockedByDedupeGuard = true;
+            duplicateAward = outcome.award;
+          } else {
+            result = outcome.result;
+          }
+        } else {
+          result = await emitRecord();
+        }
         const sessionEndActiveSeconds = sessionTimingData?.activeSeconds ?? timingData.durationSeconds;
         const sessionEndInactiveSeconds = sessionTimingData?.inactiveSeconds;
-        const sessionEndEmitted = sessionEndActiveSeconds > 0 || (sessionEndInactiveSeconds ?? 0) > 0;
-        if (sessionEndEmitted) {
-          await client.activity.session(integration.courseId, studentId, {
-            gameId,
-            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,
-            extensions: extensionsWithResumeId,
-            ...runId ? { runId } : {}
-          });
+        const sessionEndAttempted = sessionEndActiveSeconds > 0 || (sessionEndInactiveSeconds ?? 0) > 0;
+        let sessionEndEmitted = false;
+        if (sessionEndAttempted) {
+          try {
+            await client.activity.session(runtimeCourseId, studentId, {
+              ...activityEventContext,
+              eventId: sessionEndEventId,
+              activeTimeSeconds: sessionEndActiveSeconds,
+              ...sessionEndInactiveSeconds !== undefined ? { inactiveTimeSeconds: sessionEndInactiveSeconds } : {}
+            });
+            sessionEndEmitted = true;
+          } catch (sessionError) {
+            logTimebackError("emit session end after completion", sessionError, {
+              run_id: runId,
+              activity_id: activityData.activityId
+            });
+          }
         }
         setAttributes({
-          "app.timeback.course_id": integration.courseId,
-          "app.timeback.grade": activityData.grade,
-          "app.timeback.subject": activityData.subject,
-          "app.timeback.total_questions": scoreData.totalQuestions,
-          "app.timeback.correct_questions": scoreData.correctQuestions,
-          "app.timeback.score_pct": scorePercentage,
+          "app.timeback.session_end_attempted": sessionEndAttempted,
           "app.timeback.session_end_emitted": sessionEndEmitted,
           "app.timeback.active_time_seconds": sessionEndActiveSeconds,
           "app.timeback.inactive_time_seconds": sessionEndInactiveSeconds ?? 0,
-          "app.timeback.xp_requested": xpEarned,
-          "app.timeback.xp_awarded": result.xpAwarded,
+          "app.timeback.xp_awarded": result?.xpAwarded ?? 0,
           "app.timeback.mastered_units_requested": masteredUnits,
           "app.timeback.mastered_units_absolute_requested": masteredUnitsAbsolute,
-          "app.timeback.mastered_units_applied": result.masteredUnitsApplied
+          "app.timeback.mastered_units_applied": result?.masteredUnitsApplied ?? 0,
+          ...blockedByDedupeGuard ? {
+            "app.timeback.xp_already_awarded": duplicateAward?.xpAwarded ?? 0,
+            "app.timeback.mastered_units_already_applied": duplicateAward?.masteredUnitsApplied ?? 0
+          } : {}
         });
+        if (blockedByDedupeGuard) {
+          return {
+            status: "ok",
+            courseId: runtimeCourseId,
+            xpAwarded: duplicateAward?.xpAwarded ?? 0,
+            masteredUnits: duplicateAward?.masteredUnitsApplied ?? 0,
+            ...duplicateAward?.pctCompleteApp != null ? { pctCompleteApp: duplicateAward.pctCompleteApp } : {},
+            blockedByDedupeGuard: true
+          };
+        }
+        if (!result) {
+          throw new InternalError("Completion emit did not produce a result");
+        }
         return {
           status: "ok",
-          courseId: integration.courseId,
+          courseId: runtimeCourseId,
           xpAwarded: result.xpAwarded,
           masteredUnits: result.masteredUnitsApplied,
           pctCompleteApp: result.pctCompleteApp,
@@ -81509,10 +81764,15 @@ var init_timeback_service = __esm(async () => {
           if (!integration) {
             throw new NotFoundError(`Timeback integration for game (grade ${activityData.grade}, subject ${activityData.subject})`);
           }
+          const {
+            courseId: runtimeCourseId,
+            courseName: runtimeCourseName,
+            attributes: courseAttributes
+          } = TimebackService.resolveRuntimeCourse(integration.courseId, activityData.courseId, activityData.courseName);
           const activeTimeSeconds = timingData.activeMs / 1000;
           const inactiveTimeSeconds = timingData.pausedMs / 1000;
           if (activeTimeSeconds > 0 || inactiveTimeSeconds > 0) {
-            await client.activity.session(integration.courseId, studentId, {
+            await client.activity.session(runtimeCourseId, studentId, {
               gameId,
               activeTimeSeconds,
               ...inactiveTimeSeconds > 0 ? { inactiveTimeSeconds } : {},
@@ -81521,15 +81781,15 @@ var init_timeback_service = __esm(async () => {
               subject: activityData.subject,
               appName: activityData.appName,
               sensorUrl: activityData.sensorUrl,
-              courseId: activityData.courseId,
-              courseName: activityData.courseName,
+              courseId: runtimeCourseId,
+              courseName: runtimeCourseName,
               studentEmail: activityData.studentEmail,
               extensions: TimebackService.addResumeIdToExtensions(undefined, effectiveResumeId),
               ...runId ? { runId } : {}
             });
           }
           setAttributes({
-            "app.timeback.course_id": integration.courseId,
+            ...courseAttributes,
             "app.timeback.grade": activityData.grade,
             "app.timeback.subject": activityData.subject,
             "app.timeback.active_time_seconds": activeTimeSeconds,
@@ -137720,17 +137980,75 @@ The unique index ${source_default.underline.blue(name22)} on the ${source_defaul
 
 // src/database/index.ts
 import fs3 from "node:fs";
-async function createDatabaseSchema(db2) {
+function isDuplicateObjectError(error89) {
+  const code = error89.code;
+  if (code && DUPLICATE_OBJECT_CODES.has(code)) {
+    return true;
+  }
+  return /already exists/i.test(errorMessage(error89));
+}
+async function reconcileMissingColumns(db2, snapshot) {
+  const tables = snapshot.tables ?? {};
+  for (const table9 of Object.values(tables)) {
+    for (const column6 of Object.values(table9.columns ?? {})) {
+      const clauses = [
+        `ALTER TABLE "${table9.name}" ADD COLUMN IF NOT EXISTS "${column6.name}" ${column6.type}`
+      ];
+      if (column6.default !== undefined) {
+        clauses.push(`DEFAULT ${column6.default}`);
+      }
+      if (column6.notNull && !column6.primaryKey) {
+        clauses.push("NOT NULL");
+      }
+      try {
+        await db2.execute(clauses.join(" "));
+      } catch (error89) {
+        console.warn(`[Sandbox] Could not add column ${table9.name}.${column6.name} to the existing database file (${errorMessage(error89)}). Delete the file to rebuild it with the current schema.`);
+      }
+    }
+  }
+}
+async function ensureSchemaMetaTable(client) {
+  await client.query(`CREATE TABLE IF NOT EXISTS ${SCHEMA_META_TABLE} (
+            id integer PRIMARY KEY CHECK (id = 1),
+            snapshot jsonb NOT NULL,
+            updated_at timestamptz NOT NULL DEFAULT now()
+        )`);
+}
+async function readStoredSnapshot(client) {
+  const result = await client.query(`SELECT snapshot FROM ${SCHEMA_META_TABLE} WHERE id = 1`);
+  return result.rows[0]?.snapshot ?? null;
+}
+async function writeStoredSnapshot(client, snapshot) {
+  await client.query(`INSERT INTO ${SCHEMA_META_TABLE} (id, snapshot, updated_at)
+         VALUES (1, $1, now())
+         ON CONFLICT (id) DO UPDATE SET snapshot = $1, updated_at = now()`, [JSON.stringify(snapshot)]);
+}
+async function syncDatabaseSchema(db2, client, isExistingDb) {
   try {
     const { generateDrizzleJson: generateDrizzleJson2, generateMigration: generateMigration2 } = await Promise.resolve().then(() => (init_api4(), exports_api));
-    const prevJson = generateDrizzleJson2({});
+    await ensureSchemaMetaTable(client);
+    const stored = isExistingDb ? await readStoredSnapshot(client) : null;
+    const emptyJson = generateDrizzleJson2({});
+    const prevJson = stored ?? emptyJson;
     const curJson = generateDrizzleJson2(exports_tables_index, prevJson.id, undefined, "snake_case");
     const statements = await generateMigration2(prevJson, curJson);
+    const tolerateExisting = isExistingDb && stored === null;
     for (const statement of statements) {
-      await db2.execute(statement);
+      try {
+        await db2.execute(statement);
+      } catch (error89) {
+        if (!(tolerateExisting && isDuplicateObjectError(error89))) {
+          throw error89;
+        }
+      }
+    }
+    if (tolerateExisting) {
+      await reconcileMissingColumns(db2, curJson);
     }
+    await writeStoredSnapshot(client, curJson);
   } catch (error89) {
-    console.error("[Sandbox] Schema creation failed:", error89);
+    console.error("[Sandbox] Schema sync failed:", error89);
     throw error89;
   }
 }
@@ -137741,16 +138059,16 @@ async function setupDatabase(customPath) {
   const client = dbPath === ":memory:" ? new We2 : new We2(dbPath);
   await client._checkReady();
   const db2 = drizzle(client, { schema: exports_tables_index });
-  if (!dbFileExists) {
-    await createDatabaseSchema(db2);
-  }
+  await syncDatabaseSchema(db2, client, dbFileExists);
   return db2;
 }
+var SCHEMA_META_TABLE = "_sandbox_schema_meta", DUPLICATE_OBJECT_CODES;
 var init_database = __esm(() => {
   init_dist8();
   init_pglite();
   init_tables_index();
   init_path_manager();
+  DUPLICATE_OBJECT_CODES = new Set(["42701", "42710", "42723", "42P06", "42P07"]);
 });
 
 // src/lib/logging/adapter.ts

package/dist/server.js

@@ -1079,7 +1079,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@playcademy/sandbox",
-    version: "0.6.1-beta.1",
+    version: "0.6.1-beta.3",
     description: "Local development server for Playcademy game development",
     type: "module",
     exports: {
@@ -11329,7 +11329,7 @@ var init_table6 = __esm(() => {
 });
 
 // ../data/src/domains/timeback/table.ts
-var gameTimebackIntegrationStatusEnum, gameTimebackIntegrations, gameTimebackAssessmentTests, gameTimebackMetricDiscrepancyVerifications;
+var gameTimebackIntegrationStatusEnum, gameTimebackIntegrations, gameTimebackAssessmentTests, gameTimebackMetricDiscrepancyVerifications, gameTimebackActivityCompletions;
 var init_table7 = __esm(() => {
   init_drizzle_orm();
   init_pg_core();
@@ -11381,6 +11381,22 @@ var init_table7 = __esm(() => {
     uniqueIndex("game_timeback_metric_discrepancy_verifications_run_idx").on(table3.gameId, table3.courseId, table3.studentId, table3.runId),
     index("game_timeback_metric_discrepancy_verifications_course_idx").on(table3.gameId, table3.courseId, table3.verifiedAt)
   ]);
+  gameTimebackActivityCompletions = pgTable("game_timeback_activity_completions", {
+    id: uuid("id").primaryKey().defaultRandom(),
+    gameId: uuid("game_id").notNull().references(() => games.id, { onDelete: "cascade" }),
+    courseId: text("course_id").notNull(),
+    studentId: text("student_id").notNull(),
+    runId: uuid("run_id").notNull(),
+    activityId: text("activity_id").notNull(),
+    completedAt: timestamp("completed_at", { withTimezone: true }),
+    reservedAt: timestamp("reserved_at", { withTimezone: true, mode: "string" }).notNull().defaultNow(),
+    xpAwarded: doublePrecision("xp_awarded"),
+    masteredUnitsApplied: integer("mastered_units_applied"),
+    pctCompleteApp: doublePrecision("pct_complete_app"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow()
+  }, (table3) => [
+    uniqueIndex("game_timeback_activity_completions_run_idx").on(table3.gameId, table3.courseId, table3.studentId, table3.runId, table3.activityId)
+  ]);
 });
 
 // ../data/src/tables.index.ts
@@ -11398,6 +11414,7 @@ __export(exports_tables_index, {
   gameTimebackIntegrations: () => gameTimebackIntegrations,
   gameTimebackIntegrationStatusEnum: () => gameTimebackIntegrationStatusEnum,
   gameTimebackAssessmentTests: () => gameTimebackAssessmentTests,
+  gameTimebackActivityCompletions: () => gameTimebackActivityCompletions,
   gameScoresRelations: () => gameScoresRelations,
   gameScores: () => gameScores,
   gamePlatformEnum: () => gamePlatformEnum,
@@ -24676,6 +24693,10 @@ var init_constants2 = __esm(() => {
   GAME_WORKER_DOMAIN_PRODUCTION = GAME_WORKER_DOMAINS.production;
   GAME_WORKER_DOMAIN_STAGING = GAME_WORKER_DOMAINS.staging;
 });
+
+// ../cloudflare/src/playcademy/provider/assets-config.ts
+var init_assets_config = () => {};
+
 // ../cloudflare/src/playcademy/provider/bindings.ts
 var init_bindings = __esm(() => {
   init_constants2();
@@ -24692,6 +24713,7 @@ var init_provider = __esm(() => {
   init_src();
   init_core();
   init_constants2();
+  init_assets_config();
   init_bindings();
   init_helpers();
 });
@@ -27134,12 +27156,21 @@ var init_tunnel = __esm(() => {
   METRICS_BASE = `http://127.0.0.1:${TUNNEL_METRICS_PORT}`;
 });
 
+// ../utils/src/stages.ts
+function isPreviewStage(stage) {
+  return PREVIEW_STAGE_PATTERN.test(stage);
+}
+var PREVIEW_STAGE_PATTERN;
+var init_stages = __esm(() => {
+  PREVIEW_STAGE_PATTERN = /^pr-\d+$/;
+});
+
 // ../api-core/src/utils/deployment.util.ts
 function getDeploymentId(gameSlug, sstStage) {
   if (sstStage === "production") {
     return gameSlug;
   }
-  if (sstStage === "dev" || sstStage.startsWith("pr-")) {
+  if (sstStage === "dev" || isPreviewStage(sstStage)) {
     return `${WORKER_NAMING.STAGING_PREFIX}${gameSlug}`;
   }
   return `${WORKER_NAMING.LOCAL_PREFIX}${sstStage}-${gameSlug}`;
@@ -27159,6 +27190,7 @@ async function generateDeploymentHash(code) {
 }
 var init_deployment_util = __esm(() => {
   init_src();
+  init_stages();
 });
 
 // ../api-core/src/services/deploy.service.ts
@@ -31046,7 +31078,7 @@ var init_schemas4 = __esm(() => {
     subject: TimebackSubjectSchema,
     appName: exports_external.string().optional(),
     sensorUrl: exports_external.string().url().optional(),
-    courseId: exports_external.string().optional(),
+    courseId: exports_external.string().min(1).optional(),
     courseName: exports_external.string().optional(),
     studentEmail: exports_external.string().email().optional()
   });
@@ -74822,7 +74854,8 @@ class ActivityRecord {
         courseName,
         subject: progressData.subject,
         appName: progressData.appName,
-        sensorUrl: progressData.sensorUrl
+        sensorUrl: progressData.sensorUrl,
+        eventId: progressData.completionHistoryEventId
       });
     }
     if (masteryProgress?.masteryRevoked) {
@@ -74847,6 +74880,7 @@ class ActivityRecord {
         subject: progressData.subject,
         appName: progressData.appName,
         sensorUrl: progressData.sensorUrl,
+        eventId: progressData.eventId,
         extensions: extensions || progressData.extensions,
         ...progressData.runId ? { runId: progressData.runId } : {}
       }).catch((error88) => {
@@ -74870,6 +74904,7 @@ class ActivityRecord {
   }
   async emitCourseCompletionHistoryEvent(data) {
     await this.events.emitActivityEvent({
+      eventId: data.eventId,
       studentId: data.studentId,
       studentEmail: data.studentEmail,
       gameId: data.gameId,
@@ -74985,6 +75020,7 @@ class ActivitySession {
       subject: sessionData.subject,
       appName: sessionData.appName,
       sensorUrl: sessionData.sensorUrl,
+      eventId: sessionData.eventId,
       ...runId ? { runId } : {},
       ...extensions ? { extensions } : {}
     });
@@ -75251,6 +75287,9 @@ class ActivityEvents {
       } : {},
       ...eventExtensions ? { extensions: eventExtensions } : {}
     });
+    if (data.eventId) {
+      event.id = data.eventId;
+    }
     await this.core.api.caliper.events.send(data.sensorUrl, [event]);
   }
   async emitTimeSpentEvent(data) {
@@ -75282,6 +75321,9 @@ class ActivityEvents {
       ...data.runId ? { session: `urn:uuid:${data.runId}` } : {},
       ...eventExtensions ? { extensions: eventExtensions } : {}
     });
+    if (data.eventId) {
+      event.id = data.eventId;
+    }
     const wireEvent = data.extensions ? { ...event, generated: { ...event.generated, extensions: data.extensions } } : event;
     await this.core.api.caliper.events.send(data.sensorUrl, [wireEvent]);
   }
@@ -80314,6 +80356,7 @@ var init_timeback_removed_integration_util = __esm(() => {
 });
 
 // ../api-core/src/services/timeback.service.ts
+import { createHash as createHash2 } from "node:crypto";
 async function findGameTimebackIntegrationForUpdate(db2, condition) {
   const [integration] = await db2.select().from(gameTimebackIntegrations).where(condition).limit(1).for("update");
   return integration;
@@ -80336,6 +80379,9 @@ var init_timeback_service = __esm(async () => {
     static HEARTBEAT_DEDUPE_TTL_MS = 5 * 60 * 1000;
     static processedHeartbeatWindows = new Map;
     static inFlightHeartbeatWindows = new Map;
+    static COMPLETION_RESERVATION_STALE_SECONDS = 5 * 60;
+    static COMPLETION_IN_FLIGHT_SETTLE_DELAY_MS = 400;
+    static COMPLETION_IN_FLIGHT_SETTLE_ATTEMPTS = 5;
     deps;
     static cleanHeartbeatDedupeCache(now2 = Date.now()) {
       for (const [key, timestamp6] of this.processedHeartbeatWindows) {
@@ -80360,6 +80406,136 @@ var init_timeback_service = __esm(async () => {
     static clearInFlightHeartbeatWindow(key) {
       this.inFlightHeartbeatWindows.delete(key);
     }
+    static buildCompletionCaliperEventId(key, kind, discriminator = "completion") {
+      const hash2 = createHash2("sha256").update([
+        "playcademy",
+        "timeback",
+        kind,
+        key.gameId,
+        key.courseId,
+        key.studentId,
+        key.runId,
+        key.activityId,
+        discriminator
+      ].join("\x00")).digest("hex");
+      const variant = (Number.parseInt(hash2.slice(16, 18), 16) & 63 | 128).toString(16).padStart(2, "0");
+      const uuid9 = [
+        hash2.slice(0, 8),
+        hash2.slice(8, 12),
+        `5${hash2.slice(13, 16)}`,
+        `${variant}${hash2.slice(18, 20)}`,
+        hash2.slice(20, 32)
+      ].join("-");
+      return `urn:uuid:${uuid9}`;
+    }
+    static async reserveCompletion(db2, key) {
+      const [reserved] = await db2.insert(gameTimebackActivityCompletions).values({
+        gameId: key.gameId,
+        courseId: key.courseId,
+        studentId: key.studentId,
+        runId: key.runId,
+        activityId: key.activityId
+      }).onConflictDoUpdate({
+        target: [
+          gameTimebackActivityCompletions.gameId,
+          gameTimebackActivityCompletions.courseId,
+          gameTimebackActivityCompletions.studentId,
+          gameTimebackActivityCompletions.runId,
+          gameTimebackActivityCompletions.activityId
+        ],
+        set: { reservedAt: sql`now()` },
+        setWhere: sql`${gameTimebackActivityCompletions.completedAt} IS NULL AND ${gameTimebackActivityCompletions.reservedAt} < now() - make_interval(secs => ${TimebackService.COMPLETION_RESERVATION_STALE_SECONDS})`
+      }).returning({
+        id: gameTimebackActivityCompletions.id,
+        reservedAt: gameTimebackActivityCompletions.reservedAt,
+        takenOver: sql`${gameTimebackActivityCompletions.reservedAt} <> ${gameTimebackActivityCompletions.createdAt}`
+      });
+      if (reserved) {
+        return {
+          status: "reserved",
+          token: { id: reserved.id, reservedAt: reserved.reservedAt },
+          takenOver: reserved.takenOver
+        };
+      }
+      const existing = await db2.query.gameTimebackActivityCompletions.findFirst({
+        where: and(eq(gameTimebackActivityCompletions.gameId, key.gameId), eq(gameTimebackActivityCompletions.courseId, key.courseId), eq(gameTimebackActivityCompletions.studentId, key.studentId), eq(gameTimebackActivityCompletions.runId, key.runId), eq(gameTimebackActivityCompletions.activityId, key.activityId)),
+        columns: {
+          completedAt: true,
+          xpAwarded: true,
+          masteredUnitsApplied: true,
+          pctCompleteApp: true
+        }
+      });
+      if (!existing?.completedAt) {
+        return { status: "in_flight" };
+      }
+      return {
+        status: "duplicate",
+        award: existing.xpAwarded !== null ? {
+          xpAwarded: existing.xpAwarded,
+          masteredUnitsApplied: existing.masteredUnitsApplied ?? 0,
+          pctCompleteApp: existing.pctCompleteApp
+        } : null
+      };
+    }
+    static async acquireCompletionReservation(db2, key) {
+      let reserveOutcome = await this.reserveCompletion(db2, key);
+      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(db2, key);
+      }
+      if (reserveOutcome.status === "duplicate") {
+        setAttribute("app.timeback.end_activity_status", "blocked_by_dedupe_guard");
+        return reserveOutcome;
+      }
+      if (reserveOutcome.status === "in_flight") {
+        setAttribute("app.timeback.end_activity_status", "completion_reservation_in_flight");
+        throw new ServiceUnavailableError("An end-activity submission for this run is already in flight — retry shortly");
+      }
+      if (reserveOutcome.takenOver) {
+        setAttribute("app.timeback.completion_reservation_takeover", true);
+        addEvent("timeback.completion_reservation_takeover", {
+          "app.timeback.run_id": key.runId,
+          "app.timeback.activity_id": key.activityId
+        });
+      }
+      return { status: "reserved", token: reserveOutcome.token };
+    }
+    static async runWithCompletionReservation(db2, key, emit, awardFromResult) {
+      const acquired = await this.acquireCompletionReservation(db2, key);
+      if (acquired.status === "duplicate") {
+        return acquired;
+      }
+      const logContext = { run_id: key.runId, activity_id: key.activityId };
+      let result;
+      try {
+        result = await emit();
+      } catch (error88) {
+        try {
+          await this.rollbackCompletion(db2, acquired.token);
+        } catch (rollbackError) {
+          logTimebackError("rollback completion reservation", rollbackError, logContext);
+        }
+        throw error88;
+      }
+      try {
+        await this.confirmCompletion(db2, acquired.token, awardFromResult(result));
+      } catch (confirmError) {
+        logTimebackError("confirm completion reservation", confirmError, logContext);
+      }
+      return { status: "emitted", result };
+    }
+    static async confirmCompletion(db2, token, award) {
+      await db2.update(gameTimebackActivityCompletions).set({
+        completedAt: sql`now()`,
+        xpAwarded: award.xpAwarded,
+        masteredUnitsApplied: award.masteredUnitsApplied,
+        pctCompleteApp: award.pctCompleteApp
+      }).where(and(eq(gameTimebackActivityCompletions.id, token.id), eq(gameTimebackActivityCompletions.reservedAt, token.reservedAt), isNull(gameTimebackActivityCompletions.completedAt)));
+    }
+    static async rollbackCompletion(db2, token) {
+      await db2.delete(gameTimebackActivityCompletions).where(and(eq(gameTimebackActivityCompletions.id, token.id), eq(gameTimebackActivityCompletions.reservedAt, token.reservedAt), isNull(gameTimebackActivityCompletions.completedAt)));
+    }
     static addResumeIdToExtensions(extensions, resumeId) {
       const base = extensions ?? {};
       const existingPlaycademy = base.playcademy;
@@ -80372,6 +80548,24 @@ var init_timeback_service = __esm(async () => {
         }
       };
     }
+    static resolveRuntimeCourse(resolvedCourseId, requestedCourseId, courseName) {
+      let requestedCourseIdStatus = "absent";
+      if (requestedCourseId === resolvedCourseId) {
+        requestedCourseIdStatus = "accepted";
+      } else if (requestedCourseId !== undefined) {
+        requestedCourseIdStatus = "ignored_mismatch";
+      }
+      return {
+        courseId: resolvedCourseId,
+        courseName: requestedCourseIdStatus === "ignored_mismatch" ? undefined : courseName,
+        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
+        }
+      };
+    }
     static recordRuntimeContext({
       operation,
       studentId,
@@ -81237,67 +81431,128 @@ var init_timeback_service = __esm(async () => {
         if (!integration) {
           throw new NotFoundError(`Timeback integration for game (grade ${activityData.grade}, subject ${activityData.subject})`);
         }
+        const {
+          courseId: runtimeCourseId,
+          courseName: runtimeCourseName,
+          attributes: courseAttributes
+        } = TimebackService.resolveRuntimeCourse(integration.courseId, activityData.courseId, activityData.courseName);
         const scorePercentage = scoreData.totalQuestions > 0 ? scoreData.correctQuestions / scoreData.totalQuestions * 100 : 0;
-        const result = await client.activity.record(integration.courseId, studentId, {
+        const dedupeKey = runId !== undefined ? {
+          gameId,
+          courseId: runtimeCourseId,
+          studentId,
+          runId,
+          activityId: activityData.activityId
+        } : undefined;
+        setAttributes({
+          ...courseAttributes,
+          "app.timeback.grade": activityData.grade,
+          "app.timeback.subject": activityData.subject,
+          "app.timeback.total_questions": scoreData.totalQuestions,
+          "app.timeback.correct_questions": scoreData.correctQuestions,
+          "app.timeback.score_pct": scorePercentage,
+          "app.timeback.xp_requested": xpEarned
+        });
+        const courseTotalXp = integration.totalXp;
+        const activityEventContext = {
           gameId,
-          score: scorePercentage,
-          totalQuestions: scoreData.totalQuestions,
-          correctQuestions: scoreData.correctQuestions,
-          durationSeconds: timingData.durationSeconds,
-          xpEarned,
-          masteredUnits,
-          masteredUnitsAbsolute,
-          extensions: extensionsWithResumeId,
           activityId: activityData.activityId,
           activityName: activityData.activityName,
           subject: activityData.subject,
           appName: activityData.appName,
           sensorUrl: activityData.sensorUrl,
-          courseId: activityData.courseId,
-          courseName: activityData.courseName,
+          courseId: runtimeCourseId,
+          courseName: runtimeCourseName,
           studentEmail: activityData.studentEmail,
-          courseTotalXp: integration.totalXp,
+          extensions: extensionsWithResumeId,
           ...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;
+        function emitRecord() {
+          return client.activity.record(runtimeCourseId, studentId, {
+            ...activityEventContext,
+            eventId: completionEventId,
+            completionHistoryEventId,
+            score: scorePercentage,
+            totalQuestions: scoreData.totalQuestions,
+            correctQuestions: scoreData.correctQuestions,
+            durationSeconds: timingData.durationSeconds,
+            xpEarned,
+            masteredUnits,
+            masteredUnitsAbsolute,
+            courseTotalXp
+          });
+        }
+        let result;
+        let blockedByDedupeGuard = false;
+        let duplicateAward = null;
+        if (dedupeKey) {
+          const outcome = await TimebackService.runWithCompletionReservation(db2, dedupeKey, emitRecord, (emitted) => ({
+            xpAwarded: emitted.xpAwarded,
+            masteredUnitsApplied: emitted.masteredUnitsApplied,
+            pctCompleteApp: emitted.pctCompleteApp ?? null
+          }));
+          if (outcome.status === "duplicate") {
+            blockedByDedupeGuard = true;
+            duplicateAward = outcome.award;
+          } else {
+            result = outcome.result;
+          }
+        } else {
+          result = await emitRecord();
+        }
         const sessionEndActiveSeconds = sessionTimingData?.activeSeconds ?? timingData.durationSeconds;
         const sessionEndInactiveSeconds = sessionTimingData?.inactiveSeconds;
-        const sessionEndEmitted = sessionEndActiveSeconds > 0 || (sessionEndInactiveSeconds ?? 0) > 0;
-        if (sessionEndEmitted) {
-          await client.activity.session(integration.courseId, studentId, {
-            gameId,
-            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,
-            extensions: extensionsWithResumeId,
-            ...runId ? { runId } : {}
-          });
+        const sessionEndAttempted = sessionEndActiveSeconds > 0 || (sessionEndInactiveSeconds ?? 0) > 0;
+        let sessionEndEmitted = false;
+        if (sessionEndAttempted) {
+          try {
+            await client.activity.session(runtimeCourseId, studentId, {
+              ...activityEventContext,
+              eventId: sessionEndEventId,
+              activeTimeSeconds: sessionEndActiveSeconds,
+              ...sessionEndInactiveSeconds !== undefined ? { inactiveTimeSeconds: sessionEndInactiveSeconds } : {}
+            });
+            sessionEndEmitted = true;
+          } catch (sessionError) {
+            logTimebackError("emit session end after completion", sessionError, {
+              run_id: runId,
+              activity_id: activityData.activityId
+            });
+          }
         }
         setAttributes({
-          "app.timeback.course_id": integration.courseId,
-          "app.timeback.grade": activityData.grade,
-          "app.timeback.subject": activityData.subject,
-          "app.timeback.total_questions": scoreData.totalQuestions,
-          "app.timeback.correct_questions": scoreData.correctQuestions,
-          "app.timeback.score_pct": scorePercentage,
+          "app.timeback.session_end_attempted": sessionEndAttempted,
           "app.timeback.session_end_emitted": sessionEndEmitted,
           "app.timeback.active_time_seconds": sessionEndActiveSeconds,
           "app.timeback.inactive_time_seconds": sessionEndInactiveSeconds ?? 0,
-          "app.timeback.xp_requested": xpEarned,
-          "app.timeback.xp_awarded": result.xpAwarded,
+          "app.timeback.xp_awarded": result?.xpAwarded ?? 0,
           "app.timeback.mastered_units_requested": masteredUnits,
           "app.timeback.mastered_units_absolute_requested": masteredUnitsAbsolute,
-          "app.timeback.mastered_units_applied": result.masteredUnitsApplied
+          "app.timeback.mastered_units_applied": result?.masteredUnitsApplied ?? 0,
+          ...blockedByDedupeGuard ? {
+            "app.timeback.xp_already_awarded": duplicateAward?.xpAwarded ?? 0,
+            "app.timeback.mastered_units_already_applied": duplicateAward?.masteredUnitsApplied ?? 0
+          } : {}
         });
+        if (blockedByDedupeGuard) {
+          return {
+            status: "ok",
+            courseId: runtimeCourseId,
+            xpAwarded: duplicateAward?.xpAwarded ?? 0,
+            masteredUnits: duplicateAward?.masteredUnitsApplied ?? 0,
+            ...duplicateAward?.pctCompleteApp != null ? { pctCompleteApp: duplicateAward.pctCompleteApp } : {},
+            blockedByDedupeGuard: true
+          };
+        }
+        if (!result) {
+          throw new InternalError("Completion emit did not produce a result");
+        }
         return {
           status: "ok",
-          courseId: integration.courseId,
+          courseId: runtimeCourseId,
           xpAwarded: result.xpAwarded,
           masteredUnits: result.masteredUnitsApplied,
           pctCompleteApp: result.pctCompleteApp,
@@ -81508,10 +81763,15 @@ var init_timeback_service = __esm(async () => {
           if (!integration) {
             throw new NotFoundError(`Timeback integration for game (grade ${activityData.grade}, subject ${activityData.subject})`);
           }
+          const {
+            courseId: runtimeCourseId,
+            courseName: runtimeCourseName,
+            attributes: courseAttributes
+          } = TimebackService.resolveRuntimeCourse(integration.courseId, activityData.courseId, activityData.courseName);
           const activeTimeSeconds = timingData.activeMs / 1000;
           const inactiveTimeSeconds = timingData.pausedMs / 1000;
           if (activeTimeSeconds > 0 || inactiveTimeSeconds > 0) {
-            await client.activity.session(integration.courseId, studentId, {
+            await client.activity.session(runtimeCourseId, studentId, {
               gameId,
               activeTimeSeconds,
               ...inactiveTimeSeconds > 0 ? { inactiveTimeSeconds } : {},
@@ -81520,15 +81780,15 @@ var init_timeback_service = __esm(async () => {
               subject: activityData.subject,
               appName: activityData.appName,
               sensorUrl: activityData.sensorUrl,
-              courseId: activityData.courseId,
-              courseName: activityData.courseName,
+              courseId: runtimeCourseId,
+              courseName: runtimeCourseName,
               studentEmail: activityData.studentEmail,
               extensions: TimebackService.addResumeIdToExtensions(undefined, effectiveResumeId),
               ...runId ? { runId } : {}
             });
           }
           setAttributes({
-            "app.timeback.course_id": integration.courseId,
+            ...courseAttributes,
             "app.timeback.grade": activityData.grade,
             "app.timeback.subject": activityData.subject,
             "app.timeback.active_time_seconds": activeTimeSeconds,
@@ -137719,17 +137979,75 @@ The unique index ${source_default.underline.blue(name22)} on the ${source_defaul
 
 // src/database/index.ts
 import fs3 from "node:fs";
-async function createDatabaseSchema(db2) {
+function isDuplicateObjectError(error89) {
+  const code = error89.code;
+  if (code && DUPLICATE_OBJECT_CODES.has(code)) {
+    return true;
+  }
+  return /already exists/i.test(errorMessage(error89));
+}
+async function reconcileMissingColumns(db2, snapshot) {
+  const tables = snapshot.tables ?? {};
+  for (const table9 of Object.values(tables)) {
+    for (const column6 of Object.values(table9.columns ?? {})) {
+      const clauses = [
+        `ALTER TABLE "${table9.name}" ADD COLUMN IF NOT EXISTS "${column6.name}" ${column6.type}`
+      ];
+      if (column6.default !== undefined) {
+        clauses.push(`DEFAULT ${column6.default}`);
+      }
+      if (column6.notNull && !column6.primaryKey) {
+        clauses.push("NOT NULL");
+      }
+      try {
+        await db2.execute(clauses.join(" "));
+      } catch (error89) {
+        console.warn(`[Sandbox] Could not add column ${table9.name}.${column6.name} to the existing database file (${errorMessage(error89)}). Delete the file to rebuild it with the current schema.`);
+      }
+    }
+  }
+}
+async function ensureSchemaMetaTable(client) {
+  await client.query(`CREATE TABLE IF NOT EXISTS ${SCHEMA_META_TABLE} (
+            id integer PRIMARY KEY CHECK (id = 1),
+            snapshot jsonb NOT NULL,
+            updated_at timestamptz NOT NULL DEFAULT now()
+        )`);
+}
+async function readStoredSnapshot(client) {
+  const result = await client.query(`SELECT snapshot FROM ${SCHEMA_META_TABLE} WHERE id = 1`);
+  return result.rows[0]?.snapshot ?? null;
+}
+async function writeStoredSnapshot(client, snapshot) {
+  await client.query(`INSERT INTO ${SCHEMA_META_TABLE} (id, snapshot, updated_at)
+         VALUES (1, $1, now())
+         ON CONFLICT (id) DO UPDATE SET snapshot = $1, updated_at = now()`, [JSON.stringify(snapshot)]);
+}
+async function syncDatabaseSchema(db2, client, isExistingDb) {
   try {
     const { generateDrizzleJson: generateDrizzleJson2, generateMigration: generateMigration2 } = await Promise.resolve().then(() => (init_api4(), exports_api));
-    const prevJson = generateDrizzleJson2({});
+    await ensureSchemaMetaTable(client);
+    const stored = isExistingDb ? await readStoredSnapshot(client) : null;
+    const emptyJson = generateDrizzleJson2({});
+    const prevJson = stored ?? emptyJson;
     const curJson = generateDrizzleJson2(exports_tables_index, prevJson.id, undefined, "snake_case");
     const statements = await generateMigration2(prevJson, curJson);
+    const tolerateExisting = isExistingDb && stored === null;
     for (const statement of statements) {
-      await db2.execute(statement);
+      try {
+        await db2.execute(statement);
+      } catch (error89) {
+        if (!(tolerateExisting && isDuplicateObjectError(error89))) {
+          throw error89;
+        }
+      }
+    }
+    if (tolerateExisting) {
+      await reconcileMissingColumns(db2, curJson);
     }
+    await writeStoredSnapshot(client, curJson);
   } catch (error89) {
-    console.error("[Sandbox] Schema creation failed:", error89);
+    console.error("[Sandbox] Schema sync failed:", error89);
     throw error89;
   }
 }
@@ -137740,16 +138058,16 @@ async function setupDatabase(customPath) {
   const client = dbPath === ":memory:" ? new We2 : new We2(dbPath);
   await client._checkReady();
   const db2 = drizzle(client, { schema: exports_tables_index });
-  if (!dbFileExists) {
-    await createDatabaseSchema(db2);
-  }
+  await syncDatabaseSchema(db2, client, dbFileExists);
   return db2;
 }
+var SCHEMA_META_TABLE = "_sandbox_schema_meta", DUPLICATE_OBJECT_CODES;
 var init_database = __esm(() => {
   init_dist8();
   init_pglite();
   init_tables_index();
   init_path_manager();
+  DUPLICATE_OBJECT_CODES = new Set(["42701", "42710", "42723", "42P06", "42P07"]);
 });
 
 // src/lib/logging/adapter.ts

package/package.json

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