@playcademy/sandbox 0.7.1-beta.20 → 0.7.1-beta.21

package/dist/cli.js

@@ -1123,7 +1123,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@playcademy/sandbox",
-    version: "0.7.1-beta.20",
+    version: "0.7.1-beta.21",
     description: "Local development server for Playcademy game development",
     type: "module",
     exports: {
@@ -39631,7 +39631,7 @@ function requireMasteryStandard(input, context2) {
     });
   }
 }
-var TimebackGradeSchema, TimebackSubjectSchema, CourseGoalsSchema, UpdateGameTimebackIntegrationRequestSchema, CreateGameTimebackIntegrationRequestSchema, TimebackActivityDataSchema, EndActivityRequestSchema, GameRunMetricsSchema, GameCourseMetricsSchema, GameMetricsResponseSchema, AdvanceCourseRequestSchema, UnenrollCourseRequestSchema, HeartbeatRequestSchema, PopulateStudentRequestSchema, DerivedPlatformCourseConfigSchema, TimebackBaseConfigSchema, PlatformTimebackSetupRequestSchema, AdminTimebackMutationBaseSchema, AdminAttributionDateSchema, ADMIN_GRANT_XP_MIN = -1e5, ADMIN_GRANT_XP_MAX = 1e5, ADMIN_GRANT_XP_AMOUNT_RANGE_MESSAGE, GrantTimebackXpRequestSchema, AdjustTimebackTimeRequestSchema, AdjustTimebackMasteryRequestSchema, ReconcileMasteryForConfigChangeSchema, EnrollStudentRequestSchema, UnenrollStudentRequestSchema, ReactivateEnrollmentRequestSchema, VerifyTimebackMetricDiscrepancyRequestSchema, AssessmentPurposeSchema, AssessmentStatusSchema, AssessmentStandardRefSchema2, CreateAssessmentRequestSchema, UpdateAssessmentRequestSchema, CopyAssessmentRequestSchema, ReorderAssessmentsRequestSchema, ReorderQuestionsRequestSchema;
+var TimebackGradeSchema, TimebackSubjectSchema, CourseGoalsSchema, UpdateGameTimebackIntegrationRequestSchema, CreateGameTimebackIntegrationRequestSchema, TimebackActivityDataSchema, EndActivityRequestSchema, GameRunMetricsSchema, GameCourseMetricsSchema, GameMetricsResponseSchema, AdvanceCourseRequestSchema, UnenrollCourseRequestSchema, HeartbeatRequestSchema, PopulateStudentRequestSchema, DerivedPlatformCourseConfigSchema, TimebackBaseConfigSchema, PlatformTimebackSetupRequestSchema, AdminTimebackMutationBaseSchema, AdminAttributionDateSchema, ADMIN_GRANT_XP_MIN = -1e5, ADMIN_GRANT_XP_MAX = 1e5, ADMIN_GRANT_XP_AMOUNT_RANGE_MESSAGE, GrantTimebackXpRequestSchema, AdjustTimebackTimeRequestSchema, AdjustTimebackMasteryRequestSchema, ReconcileMasteryForConfigChangeSchema, EnrollStudentRequestSchema, UnenrollStudentRequestSchema, ReactivateEnrollmentRequestSchema, VerifyTimebackMetricDiscrepancyRequestSchema, AssessmentPurposeSchema, AssessmentStatusSchema, AssessmentStandardRefSchema2, CreateAssessmentRequestSchema, UpdateAssessmentRequestSchema, CopyAssessmentRequestSchema, AssessmentAssociationImportEntrySchema, AttachExistingAssessmentsRequestSchema, ReorderAssessmentsRequestSchema, ReorderQuestionsRequestSchema;
 var init_schemas4 = __esm(() => {
   init_esm();
   init_src();
@@ -39898,6 +39898,43 @@ var init_schemas4 = __esm(() => {
     purpose: AssessmentPurposeSchema,
     standard: AssessmentStandardRefSchema2.optional()
   }).superRefine(requireMasteryStandard);
+  AssessmentAssociationImportEntrySchema = exports_external.object({
+    qtiTestIdentifier: exports_external.string().trim().min(1, "Assessment identifier is required"),
+    purpose: AssessmentPurposeSchema,
+    standard: AssessmentStandardRefSchema2.optional(),
+    sortOrder: exports_external.number().int().nonnegative().nullable()
+  }).superRefine((input, context2) => {
+    requireMasteryStandard(input, context2);
+    if (input.purpose !== "mastery" && input.standard !== undefined) {
+      context2.addIssue({
+        code: "custom",
+        path: ["standard"],
+        message: "Only mastery assessments may have a quiz-level standard"
+      });
+    }
+  });
+  AttachExistingAssessmentsRequestSchema = exports_external.object({
+    version: exports_external.literal(1),
+    sourceGameId: exports_external.string().trim().min(1),
+    sourceGameSlug: exports_external.string().trim().min(1).optional(),
+    sourceIntegrationId: exports_external.string().trim().min(1),
+    subject: TimebackSubjectSchema,
+    grade: TimebackGradeSchema,
+    targetStatus: exports_external.enum(["draft", "live"]),
+    assessments: exports_external.array(AssessmentAssociationImportEntrySchema).min(1, "At least one assessment is required").max(500, "A bulk import can contain at most 500 assessments")
+  }).superRefine((input, context2) => {
+    const seen = new Set;
+    input.assessments.forEach((assessment, index2) => {
+      if (seen.has(assessment.qtiTestIdentifier)) {
+        context2.addIssue({
+          code: "custom",
+          path: ["assessments", index2, "qtiTestIdentifier"],
+          message: "Assessment identifiers must be unique"
+        });
+      }
+      seen.add(assessment.qtiTestIdentifier);
+    });
+  });
   ReorderAssessmentsRequestSchema = exports_external.object({
     purpose: AssessmentPurposeSchema,
     testIdentifiers: exports_external.array(exports_external.string().trim().min(1, "Assessment identifier is required")).min(1, "At least one assessment is required")
@@ -94151,6 +94188,76 @@ var init_timeback_qti_authoring_util = __esm(() => {
   ];
 });
 
+// ../api-core/src/utils/timeback-assessment-import.util.ts
+function assertPlayableAssessmentImportQuestions(targetStatus, questions) {
+  if (targetStatus === "draft") {
+    return;
+  }
+  for (const question of questions) {
+    assertPlayableQtiQuestion(question);
+  }
+}
+function assertAssessmentImportCourseMatches(manifest, integration) {
+  if (integration.subject !== manifest.subject || integration.grade !== manifest.grade) {
+    throw new ValidationError(`This manifest is for ${manifest.subject} grade ${manifest.grade}, not ${integration.subject} grade ${integration.grade}.`);
+  }
+}
+function associationMetadataMatches(row, entry) {
+  return row.purpose === entry.purpose && (row.standardFramework ?? undefined) === entry.standard?.framework && (row.standardIdentifier ?? undefined) === entry.standard?.identifier;
+}
+function targetStatusSatisfied(row, targetStatus) {
+  return row.status === targetStatus || targetStatus === "draft" && row.status === "live";
+}
+function classifyExistingAssessmentImport(row, entry, targetStatus) {
+  if (!associationMetadataMatches(row, entry)) {
+    return {
+      status: "failed",
+      message: "Already attached with different purpose or standard metadata."
+    };
+  }
+  if (targetStatusSatisfied(row, targetStatus)) {
+    return { status: "skipped", message: `Already attached as ${row.status}.` };
+  }
+  if (row.status === "archived") {
+    return {
+      status: "failed",
+      message: "Already attached as archived and cannot be imported again."
+    };
+  }
+  if (targetStatus === "live" && row.status === "draft") {
+    return {
+      status: "failed",
+      message: "Already attached as a draft. Publish it from the assessment editor before retrying."
+    };
+  }
+  return {
+    status: "failed",
+    message: `Already attached as ${row.status}, which does not match the requested ${targetStatus} status.`
+  };
+}
+function attachedAssessmentImportMessage(targetStatus, editable) {
+  if (targetStatus === "live") {
+    return editable ? "Attached live." : "Attached live. QTI content is read-only because another app owns it.";
+  }
+  return editable ? "Attached as a draft." : "Attached as a read-only draft owned by another app.";
+}
+function liveReviewAssessmentImportFailures(targetStatus, candidates, existingRows) {
+  if (targetStatus === "draft") {
+    return new Map;
+  }
+  const reviews = candidates.filter((candidate) => candidate.purpose === "review");
+  const hasExistingLiveReview = existingRows.some((row) => row.purpose === "review" && row.status === "live");
+  if (reviews.length <= 1 && !hasExistingLiveReview) {
+    return new Map;
+  }
+  const message = hasExistingLiveReview ? "Another review assessment is already live for this course." : "Only one review assessment can be imported live at a time.";
+  return new Map(reviews.map((review) => [review.qtiTestIdentifier, message]));
+}
+var init_timeback_assessment_import_util = __esm(() => {
+  init_errors2();
+  init_timeback_qti_authoring_util();
+});
+
 // ../api-core/src/utils/timeback-qti-library.util.ts
 function newPlaycademyTestIdentifier() {
   return `${PLAYCADEMY_QTI_SOURCE_PREFIX}${crypto.randomUUID()}`;
@@ -94298,6 +94405,150 @@ class TimebackAssessmentsService {
       throw error88;
     }
   }
+  async attachExistingAssessments(integrationId, manifest) {
+    const client2 = this.requireClient();
+    const { integration, gameSlug } = await this.requireQtiTestOwnershipContext(integrationId);
+    assertAssessmentImportCourseMatches(manifest, integration);
+    validateUniqueAssessmentIdentifiers(manifest.assessments.map((assessment) => assessment.qtiTestIdentifier));
+    const entries = manifest.assessments.map((assessment, index2) => ({
+      ...assessment,
+      index: index2,
+      standard: this.requirePurposeStandard(assessment.purpose, assessment.standard)
+    }));
+    const existingRows = await this.deps.db.query.gameTimebackAssessmentTests.findMany({
+      where: eq(gameTimebackAssessmentTests.integrationId, integrationId)
+    });
+    const existingByIdentifier = new Map(existingRows.map((row) => [row.qtiTestIdentifier, row]));
+    const validated = await runWithConcurrency(entries, QTI_HYDRATION_CONCURRENCY, async (entry) => {
+      try {
+        const loaded = await loadHydratedQtiTest(client2, entry.qtiTestIdentifier);
+        assertAssessmentHasQuestions(loaded.questions.questions);
+        assertPlayableAssessmentImportQuestions(manifest.targetStatus, loaded.questions.questions.map(({ question }) => question));
+        if (entry.purpose === "review") {
+          assertReviewAssessmentHasStandards(loaded.questions.questions.map(({ question }) => qtiAssessmentStandardRefsFromMetadata2(question.metadata).filter((standard) => canonicalReviewStandardRef(standard) !== null).length));
+        }
+        return { entry, test: loaded.test };
+      } catch (error88) {
+        return { entry, error: error88 };
+      }
+    });
+    const results = [];
+    const pending = [];
+    for (const validation of validated) {
+      const { entry } = validation;
+      const { index: index2 } = entry;
+      const base = {
+        qtiTestIdentifier: entry.qtiTestIdentifier,
+        purpose: entry.purpose,
+        ...entry.standard ? { standard: entry.standard } : {},
+        sourceSortOrder: entry.sortOrder
+      };
+      if ("error" in validation) {
+        results[index2] = {
+          ...base,
+          status: "failed",
+          message: `QTI validation failed: ${errorMessage(validation.error)}`
+        };
+      } else {
+        const existing = existingByIdentifier.get(entry.qtiTestIdentifier);
+        const editable = isQtiTestOwnedByGame(validation.test, gameSlug);
+        const hydratedBase = { ...base, title: validation.test.title, editable };
+        if (!existing) {
+          pending.push({ entry, test: validation.test });
+        } else {
+          const decision = classifyExistingAssessmentImport(existing, {
+            purpose: entry.purpose,
+            ...entry.standard ? { standard: entry.standard } : {}
+          }, manifest.targetStatus);
+          results[index2] = {
+            ...hydratedBase,
+            status: decision.status,
+            association: this.associationImportSummary(existing),
+            message: decision.message
+          };
+        }
+      }
+    }
+    const liveReviewFailures = liveReviewAssessmentImportFailures(manifest.targetStatus, pending.map(({ entry }) => entry), existingRows);
+    for (const { entry, test } of pending) {
+      const message = liveReviewFailures.get(entry.qtiTestIdentifier);
+      if (message) {
+        results[entry.index] = {
+          qtiTestIdentifier: entry.qtiTestIdentifier,
+          title: test.title,
+          purpose: entry.purpose,
+          ...entry.standard ? { standard: entry.standard } : {},
+          sourceSortOrder: entry.sortOrder,
+          editable: isQtiTestOwnedByGame(test, gameSlug),
+          status: "failed",
+          message
+        };
+      }
+    }
+    const attachablePending = pending.filter(({ entry }) => !liveReviewFailures.has(entry.qtiTestIdentifier));
+    for (const validation of attachablePending) {
+      const { entry, test } = validation;
+      const { index: index2 } = entry;
+      const base = {
+        qtiTestIdentifier: entry.qtiTestIdentifier,
+        title: test.title,
+        purpose: entry.purpose,
+        ...entry.standard ? { standard: entry.standard } : {},
+        sourceSortOrder: entry.sortOrder,
+        editable: isQtiTestOwnedByGame(test, gameSlug)
+      };
+      try {
+        const [row] = await this.deps.db.insert(gameTimebackAssessmentTests).values({
+          integrationId,
+          qtiTestIdentifier: entry.qtiTestIdentifier,
+          purpose: entry.purpose,
+          status: manifest.targetStatus,
+          sortOrder: entry.sortOrder,
+          standardFramework: entry.standard?.framework,
+          standardIdentifier: entry.standard?.identifier
+        }).returning();
+        if (!row) {
+          throw new Error("Assessment association create returned no row");
+        }
+        results[index2] = {
+          ...base,
+          status: "created",
+          association: this.associationImportSummary(row),
+          message: attachedAssessmentImportMessage(manifest.targetStatus, base.editable)
+        };
+      } catch (error88) {
+        results[index2] = {
+          ...base,
+          status: "failed",
+          message: `Association attach failed: ${errorMessage(error88)}`
+        };
+        if (isUniqueViolation(error88)) {
+          let concurrentAssociation;
+          try {
+            concurrentAssociation = await this.deps.db.query.gameTimebackAssessmentTests.findFirst({
+              where: and(eq(gameTimebackAssessmentTests.integrationId, integrationId), eq(gameTimebackAssessmentTests.qtiTestIdentifier, entry.qtiTestIdentifier))
+            });
+          } catch {}
+          if (concurrentAssociation) {
+            const decision = classifyExistingAssessmentImport(concurrentAssociation, {
+              purpose: entry.purpose,
+              ...entry.standard ? { standard: entry.standard } : {}
+            }, manifest.targetStatus);
+            results[index2] = {
+              ...base,
+              status: decision.status,
+              association: this.associationImportSummary(concurrentAssociation),
+              message: decision.message
+            };
+          }
+        }
+      }
+    }
+    setAttribute("app.assessment.operation", "bulk_attach_existing");
+    setAttribute("app.assessment.bulk_attach.target_status", manifest.targetStatus);
+    setAttribute("app.assessment.bulk_attach.created", results.filter((result) => result.status === "created").length);
+    return { results };
+  }
   async updateAssessment(integrationId, qtiTestIdentifier, input) {
     try {
       return await this.withLockedAssessmentAssociations(integrationId, qtiTestIdentifier, async (row, tx, associations) => {
@@ -94811,6 +95062,13 @@ class TimebackAssessmentsService {
       updatedAt: row.updatedAt
     };
   }
+  associationImportSummary(row) {
+    return {
+      ...this.associationSummary(row),
+      createdAt: row.createdAt.toISOString(),
+      updatedAt: row.updatedAt.toISOString()
+    };
+  }
   canonicalAssessmentStandard(input) {
     const standard = canonicalReviewStandardRef(input);
     if (!standard) {
@@ -94857,6 +95115,7 @@ var init_timeback_assessments_service = __esm(async () => {
   init_qti();
   init_timeback3();
   init_errors2();
+  init_timeback_assessment_import_util();
   init_timeback_assessment_rules_util();
   init_timeback_qti_authoring_util();
   init_timeback_qti_hydration_util();
@@ -154837,7 +155096,7 @@ function parseQtiLibraryParams(searchParams) {
     limit
   };
 }
-var populateStudent, getUser, getUserEnrollments, getUserById, setupIntegration, getIntegrations, getRemovedIntegrations, createIntegration, updateIntegration, deactivateCourse, reactivateCourse, getIntegrationConfig, verifyIntegration, getConfig, deleteIntegrations, endActivity, heartbeat, advanceCourse, unenrollCourse, startRuntimeAssessment, getRuntimeAssessment, getLatestRuntimeAssessment, saveRuntimeAssessment, submitRuntimeAssessmentItem, submitRuntimeAssessment, exportRuntimeAssessmentFixture, getStudentXp, getStudentMastery, getStudentHighestGradeMastered, getRoster, getStudentOverview, getGameMetrics, getStudentActivity, getGradeLevelTestResults, getGradeLevelTestReview, getActivityDetail, listMetricDiscrepancies, verifyMetricDiscrepancy, grantXp, adjustTime, adjustMastery, reconcileMasteryForConfigChange, searchStudents, enrollStudent, unenrollStudent, reactivateEnrollment, listAssessments, createAssessment, updateAssessment, reorderAssessments, reorderQuestions, removeAssessment, listQuestions, listQuestionLibrary, listTestLibrary, copyAssessment, createQuestion, updateQuestion, removeQuestion, timeback2;
+var populateStudent, getUser, getUserEnrollments, getUserById, setupIntegration, getIntegrations, getRemovedIntegrations, createIntegration, updateIntegration, deactivateCourse, reactivateCourse, getIntegrationConfig, verifyIntegration, getConfig, deleteIntegrations, endActivity, heartbeat, advanceCourse, unenrollCourse, startRuntimeAssessment, getRuntimeAssessment, getLatestRuntimeAssessment, saveRuntimeAssessment, submitRuntimeAssessmentItem, submitRuntimeAssessment, exportRuntimeAssessmentFixture, getStudentXp, getStudentMastery, getStudentHighestGradeMastered, getRoster, getStudentOverview, getGameMetrics, getStudentActivity, getGradeLevelTestResults, getGradeLevelTestReview, getActivityDetail, listMetricDiscrepancies, verifyMetricDiscrepancy, grantXp, adjustTime, adjustMastery, reconcileMasteryForConfigChange, searchStudents, enrollStudent, unenrollStudent, reactivateEnrollment, listAssessments, createAssessment, attachExistingAssessments, updateAssessment, reorderAssessments, reorderQuestions, removeAssessment, listQuestions, listQuestionLibrary, listTestLibrary, copyAssessment, createQuestion, updateQuestion, removeQuestion, timeback2;
 var init_timeback_controller = __esm(() => {
   init_esm();
   init_src();
@@ -155492,6 +155751,15 @@ var init_timeback_controller = __esm(() => {
       qtiTestIdentifier
     });
   });
+  attachExistingAssessments = requireDeveloper(async (ctx) => {
+    const { gameId, courseId } = ctx.params;
+    if (!gameId || !courseId) {
+      throw ApiError.badRequest("Missing gameId or courseId parameter");
+    }
+    const manifest = await parseRequestBody(ctx.request, AttachExistingAssessmentsRequestSchema);
+    const integrationId = await ctx.services.timebackAssessments.resolveIntegrationId(gameId, courseId, ctx.user);
+    return ctx.services.timebackAssessments.attachExistingAssessments(integrationId, manifest);
+  });
   updateAssessment = requireDeveloper(async (ctx) => {
     const { gameId, courseId, testIdentifier } = ctx.params;
     if (!gameId || !courseId || !testIdentifier) {
@@ -155641,6 +155909,7 @@ var init_timeback_controller = __esm(() => {
     reactivateEnrollment,
     listAssessments,
     createAssessment,
+    attachExistingAssessments,
     updateAssessment,
     reorderAssessments,
     removeAssessment,

package/dist/server.js

@@ -1122,7 +1122,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@playcademy/sandbox",
-    version: "0.7.1-beta.20",
+    version: "0.7.1-beta.21",
     description: "Local development server for Playcademy game development",
     type: "module",
     exports: {
@@ -39630,7 +39630,7 @@ function requireMasteryStandard(input, context2) {
     });
   }
 }
-var TimebackGradeSchema, TimebackSubjectSchema, CourseGoalsSchema, UpdateGameTimebackIntegrationRequestSchema, CreateGameTimebackIntegrationRequestSchema, TimebackActivityDataSchema, EndActivityRequestSchema, GameRunMetricsSchema, GameCourseMetricsSchema, GameMetricsResponseSchema, AdvanceCourseRequestSchema, UnenrollCourseRequestSchema, HeartbeatRequestSchema, PopulateStudentRequestSchema, DerivedPlatformCourseConfigSchema, TimebackBaseConfigSchema, PlatformTimebackSetupRequestSchema, AdminTimebackMutationBaseSchema, AdminAttributionDateSchema, ADMIN_GRANT_XP_MIN = -1e5, ADMIN_GRANT_XP_MAX = 1e5, ADMIN_GRANT_XP_AMOUNT_RANGE_MESSAGE, GrantTimebackXpRequestSchema, AdjustTimebackTimeRequestSchema, AdjustTimebackMasteryRequestSchema, ReconcileMasteryForConfigChangeSchema, EnrollStudentRequestSchema, UnenrollStudentRequestSchema, ReactivateEnrollmentRequestSchema, VerifyTimebackMetricDiscrepancyRequestSchema, AssessmentPurposeSchema, AssessmentStatusSchema, AssessmentStandardRefSchema2, CreateAssessmentRequestSchema, UpdateAssessmentRequestSchema, CopyAssessmentRequestSchema, ReorderAssessmentsRequestSchema, ReorderQuestionsRequestSchema;
+var TimebackGradeSchema, TimebackSubjectSchema, CourseGoalsSchema, UpdateGameTimebackIntegrationRequestSchema, CreateGameTimebackIntegrationRequestSchema, TimebackActivityDataSchema, EndActivityRequestSchema, GameRunMetricsSchema, GameCourseMetricsSchema, GameMetricsResponseSchema, AdvanceCourseRequestSchema, UnenrollCourseRequestSchema, HeartbeatRequestSchema, PopulateStudentRequestSchema, DerivedPlatformCourseConfigSchema, TimebackBaseConfigSchema, PlatformTimebackSetupRequestSchema, AdminTimebackMutationBaseSchema, AdminAttributionDateSchema, ADMIN_GRANT_XP_MIN = -1e5, ADMIN_GRANT_XP_MAX = 1e5, ADMIN_GRANT_XP_AMOUNT_RANGE_MESSAGE, GrantTimebackXpRequestSchema, AdjustTimebackTimeRequestSchema, AdjustTimebackMasteryRequestSchema, ReconcileMasteryForConfigChangeSchema, EnrollStudentRequestSchema, UnenrollStudentRequestSchema, ReactivateEnrollmentRequestSchema, VerifyTimebackMetricDiscrepancyRequestSchema, AssessmentPurposeSchema, AssessmentStatusSchema, AssessmentStandardRefSchema2, CreateAssessmentRequestSchema, UpdateAssessmentRequestSchema, CopyAssessmentRequestSchema, AssessmentAssociationImportEntrySchema, AttachExistingAssessmentsRequestSchema, ReorderAssessmentsRequestSchema, ReorderQuestionsRequestSchema;
 var init_schemas4 = __esm(() => {
   init_esm();
   init_src();
@@ -39897,6 +39897,43 @@ var init_schemas4 = __esm(() => {
     purpose: AssessmentPurposeSchema,
     standard: AssessmentStandardRefSchema2.optional()
   }).superRefine(requireMasteryStandard);
+  AssessmentAssociationImportEntrySchema = exports_external.object({
+    qtiTestIdentifier: exports_external.string().trim().min(1, "Assessment identifier is required"),
+    purpose: AssessmentPurposeSchema,
+    standard: AssessmentStandardRefSchema2.optional(),
+    sortOrder: exports_external.number().int().nonnegative().nullable()
+  }).superRefine((input, context2) => {
+    requireMasteryStandard(input, context2);
+    if (input.purpose !== "mastery" && input.standard !== undefined) {
+      context2.addIssue({
+        code: "custom",
+        path: ["standard"],
+        message: "Only mastery assessments may have a quiz-level standard"
+      });
+    }
+  });
+  AttachExistingAssessmentsRequestSchema = exports_external.object({
+    version: exports_external.literal(1),
+    sourceGameId: exports_external.string().trim().min(1),
+    sourceGameSlug: exports_external.string().trim().min(1).optional(),
+    sourceIntegrationId: exports_external.string().trim().min(1),
+    subject: TimebackSubjectSchema,
+    grade: TimebackGradeSchema,
+    targetStatus: exports_external.enum(["draft", "live"]),
+    assessments: exports_external.array(AssessmentAssociationImportEntrySchema).min(1, "At least one assessment is required").max(500, "A bulk import can contain at most 500 assessments")
+  }).superRefine((input, context2) => {
+    const seen = new Set;
+    input.assessments.forEach((assessment, index2) => {
+      if (seen.has(assessment.qtiTestIdentifier)) {
+        context2.addIssue({
+          code: "custom",
+          path: ["assessments", index2, "qtiTestIdentifier"],
+          message: "Assessment identifiers must be unique"
+        });
+      }
+      seen.add(assessment.qtiTestIdentifier);
+    });
+  });
   ReorderAssessmentsRequestSchema = exports_external.object({
     purpose: AssessmentPurposeSchema,
     testIdentifiers: exports_external.array(exports_external.string().trim().min(1, "Assessment identifier is required")).min(1, "At least one assessment is required")
@@ -94150,6 +94187,76 @@ var init_timeback_qti_authoring_util = __esm(() => {
   ];
 });
 
+// ../api-core/src/utils/timeback-assessment-import.util.ts
+function assertPlayableAssessmentImportQuestions(targetStatus, questions) {
+  if (targetStatus === "draft") {
+    return;
+  }
+  for (const question of questions) {
+    assertPlayableQtiQuestion(question);
+  }
+}
+function assertAssessmentImportCourseMatches(manifest, integration) {
+  if (integration.subject !== manifest.subject || integration.grade !== manifest.grade) {
+    throw new ValidationError(`This manifest is for ${manifest.subject} grade ${manifest.grade}, not ${integration.subject} grade ${integration.grade}.`);
+  }
+}
+function associationMetadataMatches(row, entry) {
+  return row.purpose === entry.purpose && (row.standardFramework ?? undefined) === entry.standard?.framework && (row.standardIdentifier ?? undefined) === entry.standard?.identifier;
+}
+function targetStatusSatisfied(row, targetStatus) {
+  return row.status === targetStatus || targetStatus === "draft" && row.status === "live";
+}
+function classifyExistingAssessmentImport(row, entry, targetStatus) {
+  if (!associationMetadataMatches(row, entry)) {
+    return {
+      status: "failed",
+      message: "Already attached with different purpose or standard metadata."
+    };
+  }
+  if (targetStatusSatisfied(row, targetStatus)) {
+    return { status: "skipped", message: `Already attached as ${row.status}.` };
+  }
+  if (row.status === "archived") {
+    return {
+      status: "failed",
+      message: "Already attached as archived and cannot be imported again."
+    };
+  }
+  if (targetStatus === "live" && row.status === "draft") {
+    return {
+      status: "failed",
+      message: "Already attached as a draft. Publish it from the assessment editor before retrying."
+    };
+  }
+  return {
+    status: "failed",
+    message: `Already attached as ${row.status}, which does not match the requested ${targetStatus} status.`
+  };
+}
+function attachedAssessmentImportMessage(targetStatus, editable) {
+  if (targetStatus === "live") {
+    return editable ? "Attached live." : "Attached live. QTI content is read-only because another app owns it.";
+  }
+  return editable ? "Attached as a draft." : "Attached as a read-only draft owned by another app.";
+}
+function liveReviewAssessmentImportFailures(targetStatus, candidates, existingRows) {
+  if (targetStatus === "draft") {
+    return new Map;
+  }
+  const reviews = candidates.filter((candidate) => candidate.purpose === "review");
+  const hasExistingLiveReview = existingRows.some((row) => row.purpose === "review" && row.status === "live");
+  if (reviews.length <= 1 && !hasExistingLiveReview) {
+    return new Map;
+  }
+  const message = hasExistingLiveReview ? "Another review assessment is already live for this course." : "Only one review assessment can be imported live at a time.";
+  return new Map(reviews.map((review) => [review.qtiTestIdentifier, message]));
+}
+var init_timeback_assessment_import_util = __esm(() => {
+  init_errors2();
+  init_timeback_qti_authoring_util();
+});
+
 // ../api-core/src/utils/timeback-qti-library.util.ts
 function newPlaycademyTestIdentifier() {
   return `${PLAYCADEMY_QTI_SOURCE_PREFIX}${crypto.randomUUID()}`;
@@ -94297,6 +94404,150 @@ class TimebackAssessmentsService {
       throw error88;
     }
   }
+  async attachExistingAssessments(integrationId, manifest) {
+    const client2 = this.requireClient();
+    const { integration, gameSlug } = await this.requireQtiTestOwnershipContext(integrationId);
+    assertAssessmentImportCourseMatches(manifest, integration);
+    validateUniqueAssessmentIdentifiers(manifest.assessments.map((assessment) => assessment.qtiTestIdentifier));
+    const entries = manifest.assessments.map((assessment, index2) => ({
+      ...assessment,
+      index: index2,
+      standard: this.requirePurposeStandard(assessment.purpose, assessment.standard)
+    }));
+    const existingRows = await this.deps.db.query.gameTimebackAssessmentTests.findMany({
+      where: eq(gameTimebackAssessmentTests.integrationId, integrationId)
+    });
+    const existingByIdentifier = new Map(existingRows.map((row) => [row.qtiTestIdentifier, row]));
+    const validated = await runWithConcurrency(entries, QTI_HYDRATION_CONCURRENCY, async (entry) => {
+      try {
+        const loaded = await loadHydratedQtiTest(client2, entry.qtiTestIdentifier);
+        assertAssessmentHasQuestions(loaded.questions.questions);
+        assertPlayableAssessmentImportQuestions(manifest.targetStatus, loaded.questions.questions.map(({ question }) => question));
+        if (entry.purpose === "review") {
+          assertReviewAssessmentHasStandards(loaded.questions.questions.map(({ question }) => qtiAssessmentStandardRefsFromMetadata2(question.metadata).filter((standard) => canonicalReviewStandardRef(standard) !== null).length));
+        }
+        return { entry, test: loaded.test };
+      } catch (error88) {
+        return { entry, error: error88 };
+      }
+    });
+    const results = [];
+    const pending = [];
+    for (const validation of validated) {
+      const { entry } = validation;
+      const { index: index2 } = entry;
+      const base = {
+        qtiTestIdentifier: entry.qtiTestIdentifier,
+        purpose: entry.purpose,
+        ...entry.standard ? { standard: entry.standard } : {},
+        sourceSortOrder: entry.sortOrder
+      };
+      if ("error" in validation) {
+        results[index2] = {
+          ...base,
+          status: "failed",
+          message: `QTI validation failed: ${errorMessage(validation.error)}`
+        };
+      } else {
+        const existing = existingByIdentifier.get(entry.qtiTestIdentifier);
+        const editable = isQtiTestOwnedByGame(validation.test, gameSlug);
+        const hydratedBase = { ...base, title: validation.test.title, editable };
+        if (!existing) {
+          pending.push({ entry, test: validation.test });
+        } else {
+          const decision = classifyExistingAssessmentImport(existing, {
+            purpose: entry.purpose,
+            ...entry.standard ? { standard: entry.standard } : {}
+          }, manifest.targetStatus);
+          results[index2] = {
+            ...hydratedBase,
+            status: decision.status,
+            association: this.associationImportSummary(existing),
+            message: decision.message
+          };
+        }
+      }
+    }
+    const liveReviewFailures = liveReviewAssessmentImportFailures(manifest.targetStatus, pending.map(({ entry }) => entry), existingRows);
+    for (const { entry, test } of pending) {
+      const message = liveReviewFailures.get(entry.qtiTestIdentifier);
+      if (message) {
+        results[entry.index] = {
+          qtiTestIdentifier: entry.qtiTestIdentifier,
+          title: test.title,
+          purpose: entry.purpose,
+          ...entry.standard ? { standard: entry.standard } : {},
+          sourceSortOrder: entry.sortOrder,
+          editable: isQtiTestOwnedByGame(test, gameSlug),
+          status: "failed",
+          message
+        };
+      }
+    }
+    const attachablePending = pending.filter(({ entry }) => !liveReviewFailures.has(entry.qtiTestIdentifier));
+    for (const validation of attachablePending) {
+      const { entry, test } = validation;
+      const { index: index2 } = entry;
+      const base = {
+        qtiTestIdentifier: entry.qtiTestIdentifier,
+        title: test.title,
+        purpose: entry.purpose,
+        ...entry.standard ? { standard: entry.standard } : {},
+        sourceSortOrder: entry.sortOrder,
+        editable: isQtiTestOwnedByGame(test, gameSlug)
+      };
+      try {
+        const [row] = await this.deps.db.insert(gameTimebackAssessmentTests).values({
+          integrationId,
+          qtiTestIdentifier: entry.qtiTestIdentifier,
+          purpose: entry.purpose,
+          status: manifest.targetStatus,
+          sortOrder: entry.sortOrder,
+          standardFramework: entry.standard?.framework,
+          standardIdentifier: entry.standard?.identifier
+        }).returning();
+        if (!row) {
+          throw new Error("Assessment association create returned no row");
+        }
+        results[index2] = {
+          ...base,
+          status: "created",
+          association: this.associationImportSummary(row),
+          message: attachedAssessmentImportMessage(manifest.targetStatus, base.editable)
+        };
+      } catch (error88) {
+        results[index2] = {
+          ...base,
+          status: "failed",
+          message: `Association attach failed: ${errorMessage(error88)}`
+        };
+        if (isUniqueViolation(error88)) {
+          let concurrentAssociation;
+          try {
+            concurrentAssociation = await this.deps.db.query.gameTimebackAssessmentTests.findFirst({
+              where: and(eq(gameTimebackAssessmentTests.integrationId, integrationId), eq(gameTimebackAssessmentTests.qtiTestIdentifier, entry.qtiTestIdentifier))
+            });
+          } catch {}
+          if (concurrentAssociation) {
+            const decision = classifyExistingAssessmentImport(concurrentAssociation, {
+              purpose: entry.purpose,
+              ...entry.standard ? { standard: entry.standard } : {}
+            }, manifest.targetStatus);
+            results[index2] = {
+              ...base,
+              status: decision.status,
+              association: this.associationImportSummary(concurrentAssociation),
+              message: decision.message
+            };
+          }
+        }
+      }
+    }
+    setAttribute("app.assessment.operation", "bulk_attach_existing");
+    setAttribute("app.assessment.bulk_attach.target_status", manifest.targetStatus);
+    setAttribute("app.assessment.bulk_attach.created", results.filter((result) => result.status === "created").length);
+    return { results };
+  }
   async updateAssessment(integrationId, qtiTestIdentifier, input) {
     try {
       return await this.withLockedAssessmentAssociations(integrationId, qtiTestIdentifier, async (row, tx, associations) => {
@@ -94810,6 +95061,13 @@ class TimebackAssessmentsService {
       updatedAt: row.updatedAt
     };
   }
+  associationImportSummary(row) {
+    return {
+      ...this.associationSummary(row),
+      createdAt: row.createdAt.toISOString(),
+      updatedAt: row.updatedAt.toISOString()
+    };
+  }
   canonicalAssessmentStandard(input) {
     const standard = canonicalReviewStandardRef(input);
     if (!standard) {
@@ -94856,6 +95114,7 @@ var init_timeback_assessments_service = __esm(async () => {
   init_qti();
   init_timeback3();
   init_errors2();
+  init_timeback_assessment_import_util();
   init_timeback_assessment_rules_util();
   init_timeback_qti_authoring_util();
   init_timeback_qti_hydration_util();
@@ -154836,7 +155095,7 @@ function parseQtiLibraryParams(searchParams) {
     limit
   };
 }
-var populateStudent, getUser, getUserEnrollments, getUserById, setupIntegration, getIntegrations, getRemovedIntegrations, createIntegration, updateIntegration, deactivateCourse, reactivateCourse, getIntegrationConfig, verifyIntegration, getConfig, deleteIntegrations, endActivity, heartbeat, advanceCourse, unenrollCourse, startRuntimeAssessment, getRuntimeAssessment, getLatestRuntimeAssessment, saveRuntimeAssessment, submitRuntimeAssessmentItem, submitRuntimeAssessment, exportRuntimeAssessmentFixture, getStudentXp, getStudentMastery, getStudentHighestGradeMastered, getRoster, getStudentOverview, getGameMetrics, getStudentActivity, getGradeLevelTestResults, getGradeLevelTestReview, getActivityDetail, listMetricDiscrepancies, verifyMetricDiscrepancy, grantXp, adjustTime, adjustMastery, reconcileMasteryForConfigChange, searchStudents, enrollStudent, unenrollStudent, reactivateEnrollment, listAssessments, createAssessment, updateAssessment, reorderAssessments, reorderQuestions, removeAssessment, listQuestions, listQuestionLibrary, listTestLibrary, copyAssessment, createQuestion, updateQuestion, removeQuestion, timeback2;
+var populateStudent, getUser, getUserEnrollments, getUserById, setupIntegration, getIntegrations, getRemovedIntegrations, createIntegration, updateIntegration, deactivateCourse, reactivateCourse, getIntegrationConfig, verifyIntegration, getConfig, deleteIntegrations, endActivity, heartbeat, advanceCourse, unenrollCourse, startRuntimeAssessment, getRuntimeAssessment, getLatestRuntimeAssessment, saveRuntimeAssessment, submitRuntimeAssessmentItem, submitRuntimeAssessment, exportRuntimeAssessmentFixture, getStudentXp, getStudentMastery, getStudentHighestGradeMastered, getRoster, getStudentOverview, getGameMetrics, getStudentActivity, getGradeLevelTestResults, getGradeLevelTestReview, getActivityDetail, listMetricDiscrepancies, verifyMetricDiscrepancy, grantXp, adjustTime, adjustMastery, reconcileMasteryForConfigChange, searchStudents, enrollStudent, unenrollStudent, reactivateEnrollment, listAssessments, createAssessment, attachExistingAssessments, updateAssessment, reorderAssessments, reorderQuestions, removeAssessment, listQuestions, listQuestionLibrary, listTestLibrary, copyAssessment, createQuestion, updateQuestion, removeQuestion, timeback2;
 var init_timeback_controller = __esm(() => {
   init_esm();
   init_src();
@@ -155491,6 +155750,15 @@ var init_timeback_controller = __esm(() => {
       qtiTestIdentifier
     });
   });
+  attachExistingAssessments = requireDeveloper(async (ctx) => {
+    const { gameId, courseId } = ctx.params;
+    if (!gameId || !courseId) {
+      throw ApiError.badRequest("Missing gameId or courseId parameter");
+    }
+    const manifest = await parseRequestBody(ctx.request, AttachExistingAssessmentsRequestSchema);
+    const integrationId = await ctx.services.timebackAssessments.resolveIntegrationId(gameId, courseId, ctx.user);
+    return ctx.services.timebackAssessments.attachExistingAssessments(integrationId, manifest);
+  });
   updateAssessment = requireDeveloper(async (ctx) => {
     const { gameId, courseId, testIdentifier } = ctx.params;
     if (!gameId || !courseId || !testIdentifier) {
@@ -155640,6 +155908,7 @@ var init_timeback_controller = __esm(() => {
     reactivateEnrollment,
     listAssessments,
     createAssessment,
+    attachExistingAssessments,
     updateAssessment,
     reorderAssessments,
     removeAssessment,

package/package.json

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