@playcademy/vite-plugin 1.2.1-beta.24 → 1.2.1-beta.25

package/dist/index.js

@@ -24315,7 +24315,7 @@ import path2 from "node:path";
 // package.json
 var package_default = {
   name: "@playcademy/vite-plugin",
-  version: "1.2.1-beta.24",
+  version: "1.2.1-beta.25",
   type: "module",
   exports: {
     ".": {
@@ -25921,7 +25921,7 @@ var package_default2;
 var init_package = __esm(() => {
   package_default2 = {
     name: "@playcademy/sandbox",
-    version: "0.7.1-beta.22",
+    version: "0.7.1-beta.23",
     description: "Local development server for Playcademy game development",
     type: "module",
     exports: {
@@ -34376,6 +34376,9 @@ function isAssessmentAttemptOpen(attempt) {
 function isAssessmentAttemptCompleted(attempt) {
   return attempt.inProgress === ASSESSMENT_ATTEMPT_COMPLETED.inProgress && attempt.scoreStatus === ASSESSMENT_ATTEMPT_COMPLETED.scoreStatus;
 }
+function isAssessmentAttemptSuperseded(attempt) {
+  return attempt.inProgress === ASSESSMENT_ATTEMPT_SUPERSEDED.inProgress && attempt.scoreStatus === ASSESSMENT_ATTEMPT_SUPERSEDED.scoreStatus;
+}
 function classifyAssessmentSubmission(attempt, submissionId) {
   if (isAssessmentAttemptCompleted(attempt)) {
     return attempt.submissionId === submissionId ? "replay" : "reject";
@@ -34433,6 +34436,15 @@ function assessmentReviewBankShortage(fulfillment) {
 function assessmentFlowForPurpose(purpose) {
   return purpose === "review" ? "item-submit" : "attempt-submit";
 }
+function compareCodeUnits(left, right) {
+  if (left < right) {
+    return -1;
+  }
+  if (left > right) {
+    return 1;
+  }
+  return 0;
+}
 function canonicalJson(value) {
   if (value === null || typeof value !== "object") {
     return JSON.stringify(value) ?? "null";
@@ -34440,18 +34452,9 @@ function canonicalJson(value) {
   if (Array.isArray(value)) {
     return `[${value.map((item) => canonicalJson(item)).join(",")}]`;
   }
-  const entries = Object.entries(value).filter(([, entryValue]) => entryValue !== undefined).toSorted(([left], [right]) => compareCanonicalKeys(left, right)).map(([key, entryValue]) => `${JSON.stringify(key)}:${canonicalJson(entryValue)}`);
+  const entries = Object.entries(value).filter(([, entryValue]) => entryValue !== undefined).toSorted(([left], [right]) => compareCodeUnits(left, right)).map(([key, entryValue]) => `${JSON.stringify(key)}:${canonicalJson(entryValue)}`);
   return `{${entries.join(",")}}`;
 }
-function compareCanonicalKeys(left, right) {
-  if (left < right) {
-    return -1;
-  }
-  if (left > right) {
-    return 1;
-  }
-  return 0;
-}
 async function diagnosticRoutingRevision(manifest) {
   const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(canonicalJson(manifest)));
   return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
@@ -35751,15 +35754,6 @@ function assessmentPresentationForAttempt(assessment, attemptId) {
   });
   return { ...assessment, items };
 }
-function compareCodeUnits(left, right) {
-  if (left < right) {
-    return -1;
-  }
-  if (left > right) {
-    return 1;
-  }
-  return 0;
-}
 function reviewStandardFieldsWithinLimits(input) {
   return input.framework.trim().length <= TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.standardFieldLength && input.identifier.trim().length <= TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.standardFieldLength;
 }
@@ -35770,6 +35764,19 @@ function canonicalReviewStandardRef(input) {
   }
   return standard.framework && standard.identifier ? standard : null;
 }
+function isKnownDescriptiveCurriculumFramework(framework) {
+  return framework === "CCSS" || framework.startsWith("CCSS.");
+}
+function reviewRoutingStandardRefsFromMetadata(metadata2, options = {}) {
+  const refs = new Map;
+  for (const authored of qtiAssessmentStandardRefsFromMetadata(metadata2)) {
+    const standard = canonicalReviewStandardRef(authored);
+    if (standard && (!options.customOnly || !isKnownDescriptiveCurriculumFramework(standard.framework))) {
+      refs.set(assessmentStandardRefKey(standard), standard);
+    }
+  }
+  return [...refs.values()];
+}
 function canonicalRequestStandards(standards) {
   if (standards.length > TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.standards) {
     throw new RangeError(`A review request may contain at most ${TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.standards} standards`);
@@ -35825,42 +35832,172 @@ function qtiQuestionByIdentifier(questions) {
   }
   return byIdentifier;
 }
-async function buildReviewBankIndex(assessment, questions) {
+async function reviewBankRevision(input) {
+  const alignmentSignature = input.items.map((item) => ({
+    itemIdentifier: item.itemIdentifier,
+    standardKeys: item.standards.map(assessmentStandardRefKey)
+  }));
+  const bankRevisionUuid = await deterministicUUID(`playcademy:review-bank:v1:${JSON.stringify({
+    bankIdentifier: input.bankIdentifier,
+    contentRevision: input.sourceContentRevision,
+    alignments: alignmentSignature
+  })}`);
+  return `review-bank-v1:${bankRevisionUuid}`;
+}
+async function reviewBankIndex(input) {
+  return {
+    ...input,
+    bankRevision: await reviewBankRevision(input)
+  };
+}
+async function reviewBankSourceFingerprint(input) {
+  const fingerprintUuid = await deterministicUUID(`playcademy:review-bank-source:v1:${JSON.stringify({
+    bankIdentifier: input.bankIdentifier,
+    items: input.items.map((item) => ({
+      itemIdentifier: item.itemIdentifier,
+      standardKeys: item.standards.map(assessmentStandardRefKey)
+    }))
+  })}`);
+  return `review-bank-source-v1:${fingerprintUuid}`;
+}
+async function buildReviewBankIndex(assessment, questions, options = {}) {
   if (assessment.identifier !== questions.assessmentTest) {
     throw new Error(`QTI questions for ${questions.assessmentTest} do not describe assessment ${assessment.identifier}`);
   }
   const questionByIdentifier = qtiQuestionByIdentifier(questions);
   const items = assessment.items.map((item) => {
     const question = questionByIdentifier.get(item.identifier);
-    const canonical = new Map;
-    for (const authored of qtiAssessmentStandardRefsFromMetadata(question?.metadata)) {
-      const standard = canonicalReviewStandardRef(authored);
-      if (standard) {
-        canonical.set(assessmentStandardRefKey(standard), standard);
-      }
-    }
-    const standards = [...canonical.values()].toSorted((left, right) => compareCodeUnits(assessmentStandardRefKey(left), assessmentStandardRefKey(right)));
+    const standards = reviewRoutingStandardRefsFromMetadata(question?.metadata, options).toSorted((left, right) => compareCodeUnits(assessmentStandardRefKey(left), assessmentStandardRefKey(right)));
     return {
       itemIdentifier: item.identifier,
       standards
     };
   });
-  const alignmentSignature = items.map((item) => ({
-    itemIdentifier: item.itemIdentifier,
-    standardKeys: item.standards.map(assessmentStandardRefKey)
-  }));
-  const bankRevisionUuid = await deterministicUUID(`playcademy:review-bank:v1:${JSON.stringify({
-    bankIdentifier: assessment.identifier,
-    contentRevision: assessment.contentRevision,
-    alignments: alignmentSignature
-  })}`);
-  return {
+  return reviewBankIndex({
     bankIdentifier: assessment.identifier,
     sourceContentRevision: assessment.contentRevision,
-    bankRevision: `review-bank-v1:${bankRevisionUuid}`,
     items
+  });
+}
+function emptyReviewBankManifest(bankIdentifier) {
+  return {
+    version: PLAYCADEMY_REVIEW_BANK_MANIFEST_VERSION,
+    bankIdentifier,
+    sourceFingerprint: null,
+    sourceContentRevision: null,
+    bankRevision: null,
+    itemsByStandard: {}
+  };
+}
+function reviewBankMappingIssues(bank) {
+  return {
+    missingOrInvalidItemIdentifiers: bank.items.filter((item) => item.standards.length === 0).map((item) => item.itemIdentifier),
+    multipleStandardItemIdentifiers: bank.items.filter((item) => item.standards.length > 1).map((item) => item.itemIdentifier)
+  };
+}
+async function buildReviewBankManifest(bank) {
+  const itemsByStandard = new Map;
+  for (const item of bank.items) {
+    for (const standard of item.standards) {
+      const key = assessmentStandardRefKey(standard);
+      const identifiers = itemsByStandard.get(key) ?? [];
+      identifiers.push(item.itemIdentifier);
+      itemsByStandard.set(key, identifiers);
+    }
+  }
+  return {
+    version: PLAYCADEMY_REVIEW_BANK_MANIFEST_VERSION,
+    bankIdentifier: bank.bankIdentifier,
+    sourceFingerprint: await reviewBankSourceFingerprint(bank),
+    sourceContentRevision: bank.sourceContentRevision,
+    bankRevision: bank.bankRevision,
+    itemsByStandard: Object.fromEntries([...itemsByStandard.entries()].toSorted(([left], [right]) => compareCodeUnits(left, right)))
   };
 }
+function requiredManifestString(record, field) {
+  const value = record[field];
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`Review-bank manifest requires ${field}`);
+  }
+  return value.trim();
+}
+function standardFromManifestKey(key) {
+  try {
+    const parsed = JSON.parse(key);
+    if (!Array.isArray(parsed) || parsed.length !== 2 || typeof parsed[0] !== "string" || typeof parsed[1] !== "string") {
+      return null;
+    }
+    const standard = canonicalReviewStandardRef({
+      framework: parsed[0],
+      identifier: parsed[1]
+    });
+    return standard && assessmentStandardRefKey(standard) === key ? standard : null;
+  } catch {
+    return null;
+  }
+}
+async function reviewBankIndexFromManifest(metadata2, input) {
+  const raw = isRecord(metadata2) ? metadata2[PLAYCADEMY_REVIEW_BANK_MANIFEST_METADATA_KEY] : undefined;
+  if (raw === undefined) {
+    return null;
+  }
+  if (!isRecord(raw) || raw.version !== PLAYCADEMY_REVIEW_BANK_MANIFEST_VERSION) {
+    throw new Error("Review-bank manifest has an unsupported version or shape");
+  }
+  const manifest = raw;
+  const bankIdentifier = requiredManifestString(manifest, "bankIdentifier");
+  if (bankIdentifier !== input.bankIdentifier) {
+    throw new Error(`Review-bank manifest for ${bankIdentifier} does not describe ${input.bankIdentifier}`);
+  }
+  if (manifest.sourceFingerprint === null && manifest.sourceContentRevision === null && manifest.bankRevision === null) {
+    return null;
+  }
+  const sourceFingerprint = requiredManifestString(manifest, "sourceFingerprint");
+  const sourceContentRevision = requiredManifestString(manifest, "sourceContentRevision");
+  const declaredBankRevision = requiredManifestString(manifest, "bankRevision");
+  const itemsByStandard = manifest.itemsByStandard;
+  if (!isRecord(itemsByStandard)) {
+    throw new Error("Review-bank manifest requires an itemsByStandard mapping");
+  }
+  const membership = new Set(input.membershipItemIdentifiers);
+  const standardsByItem = new Map;
+  for (const [standardKey, rawItemIdentifiers] of Object.entries(itemsByStandard)) {
+    const standard = standardFromManifestKey(standardKey);
+    if (!standard || !Array.isArray(rawItemIdentifiers)) {
+      throw new Error("Review-bank manifest contains an invalid standard mapping");
+    }
+    for (const rawItemIdentifier of rawItemIdentifiers) {
+      if (typeof rawItemIdentifier !== "string" || !rawItemIdentifier.trim()) {
+        throw new Error("Review-bank manifest contains an invalid item identifier");
+      }
+      const itemIdentifier = rawItemIdentifier.trim();
+      if (membership.has(itemIdentifier)) {
+        const standards = standardsByItem.get(itemIdentifier) ?? new Map;
+        standards.set(assessmentStandardRefKey(standard), standard);
+        standardsByItem.set(itemIdentifier, standards);
+      }
+    }
+  }
+  const index = await reviewBankIndex({
+    bankIdentifier,
+    sourceContentRevision,
+    items: input.membershipItemIdentifiers.map((itemIdentifier) => ({
+      itemIdentifier,
+      standards: [...standardsByItem.get(itemIdentifier)?.values() ?? []].toSorted((left, right) => compareCodeUnits(assessmentStandardRefKey(left), assessmentStandardRefKey(right)))
+    }))
+  });
+  const issues = reviewBankMappingIssues(index);
+  if (issues.missingOrInvalidItemIdentifiers.length > 0 || issues.multipleStandardItemIdentifiers.length > 0) {
+    throw new Error("Review-bank manifest must map every member to exactly one standard/node key");
+  }
+  if (await reviewBankSourceFingerprint(index) !== sourceFingerprint) {
+    throw new Error("Review-bank manifest source fingerprint is stale");
+  }
+  if (index.bankRevision !== declaredBankRevision) {
+    throw new Error("Review-bank manifest revision does not match its candidate index");
+  }
+  return index;
+}
 function exposureTimestamp(value) {
   const timestamp = Date.parse(value);
   return Number.isFinite(timestamp) ? timestamp : 0;
@@ -36348,6 +36485,7 @@ var COMMON_CORE_ELA_FRAMEWORK_ALIASES;
 var COMMON_CORE_FRAMEWORK_ALIASES;
 var ASSESSMENT_ATTEMPT_OPEN;
 var ASSESSMENT_ATTEMPT_COMPLETED;
+var ASSESSMENT_ATTEMPT_SUPERSEDED;
 var ASSESSMENT_RUNTIME_ERROR_STATUS;
 var ROUTING_KEY_MAX_LENGTH = 128;
 var ROUTING_RESULT_KEY_MAX_LENGTH = 256;
@@ -36367,6 +36505,8 @@ var DiagnosticRoutingManifestV1Schema;
 var GRADE_VALUES;
 var POINT_RESPONSE_PATTERN;
 var REVIEW_SELECTION_POLICY_VERSION = "unseen-first-least-recently-delivered-v1";
+var PLAYCADEMY_REVIEW_BANK_MANIFEST_METADATA_KEY = "playcademyReviewBank";
+var PLAYCADEMY_REVIEW_BANK_MANIFEST_VERSION = 1;
 var DEFAULT_REVIEW_SELECTION_POLICY;
 var RuntimeSubjectSchema;
 var RuntimeGradeSchema;
@@ -36571,6 +36711,10 @@ var init_assessment_runtime2 = __esm(() => {
     inProgress: "false",
     scoreStatus: "fully graded"
   };
+  ASSESSMENT_ATTEMPT_SUPERSEDED = {
+    inProgress: "false",
+    scoreStatus: "not submitted"
+  };
   ASSESSMENT_RUNTIME_ERROR_STATUS = {
     NO_ELIGIBLE_TESTS: 404,
     REVIEW_BANK_SHORTAGE: 422,
@@ -115025,73 +115169,6 @@ function stringField2(value) {
 function firstStringField2(...values) {
   return values.map(stringField2).find(Boolean) ?? "";
 }
-function normalizedWhitespace2(value) {
-  return value.normalize("NFKC").trim().replace(/\s+/g, " ");
-}
-function normalizedIdentityCase2(value) {
-  return value.toLocaleUpperCase("en-US");
-}
-function frameworkAliasKey2(value) {
-  return value.normalize("NFKC").toLocaleLowerCase("en-US").replace(/[^a-z0-9]+/g, "");
-}
-function isUuidShaped2(value) {
-  return UUID_PATTERN2.test(value.trim());
-}
-function isCommonCoreMathIdentifier2(identifier) {
-  const canonical = normalizedIdentityCase2(normalizedWhitespace2(identifier));
-  return canonical.startsWith("CCSS.MATH.") || /^(?:K|[1-8])\.(?:CC|OA|NBT|NF|MD|RP|NS|EE|F|G|SP)\./.test(canonical) || /^(?:HS)?(?:N|A|F|G|S)-[A-Z]+\./.test(canonical) || /^MP\.?\d/.test(canonical);
-}
-function isCommonCoreElaIdentifier2(identifier) {
-  const canonical = normalizedIdentityCase2(normalizedWhitespace2(identifier));
-  return canonical.startsWith("CCSS.ELA-LITERACY.") || /^(?:RL|RI|RF|W|SL|L)\.(?:K|[1-9]|1[0-2])\./.test(canonical) || /^(?:RH|RST|WHST)\.(?:6-8|9-10|11-12)\./.test(canonical) || /^CCRA\.(?:R|W|SL|L)\./.test(canonical);
-}
-function canonicalFramework2(authoredFramework, identifier) {
-  const aliasKey = frameworkAliasKey2(authoredFramework);
-  if (COMMON_CORE_MATH_FRAMEWORK_ALIASES2.has(aliasKey) || COMMON_CORE_FRAMEWORK_ALIASES2.has(aliasKey) && isCommonCoreMathIdentifier2(identifier)) {
-    return "CCSS.Math";
-  }
-  if (COMMON_CORE_ELA_FRAMEWORK_ALIASES2.has(aliasKey) || COMMON_CORE_FRAMEWORK_ALIASES2.has(aliasKey) && isCommonCoreElaIdentifier2(identifier)) {
-    return "CCSS.ELA-Literacy";
-  }
-  if (COMMON_CORE_FRAMEWORK_ALIASES2.has(aliasKey)) {
-    return "CCSS";
-  }
-  return normalizedIdentityCase2(authoredFramework);
-}
-function canonicalIdentifier2(framework, authoredIdentifier) {
-  const identifier = normalizedIdentityCase2(normalizedWhitespace2(authoredIdentifier));
-  if (framework === "CCSS.Math") {
-    return identifier.replace(/^CCSS\.MATH\.CONTENT\./, "").replace(/^CCSS\.MATH\.PRACTICE\./, "").replace(/^CCSS\.MATH\./, "");
-  }
-  if (framework === "CCSS.ELA-Literacy") {
-    return identifier.replace(/^CCSS\.ELA-LITERACY\./, "");
-  }
-  return identifier;
-}
-function readableAlignmentIdentifier2(alignment) {
-  const identifier = alignment.identifier?.trim() ?? "";
-  if (identifier && !isUuidShaped2(identifier)) {
-    return identifier;
-  }
-  const id = alignment.id.trim();
-  return id && !isUuidShaped2(id) ? id : "";
-}
-function canonicalAssessmentStandardRef2(standard) {
-  const authoredFramework = normalizedWhitespace2(standard.framework);
-  const framework = canonicalFramework2(authoredFramework, standard.identifier);
-  const identifier = canonicalIdentifier2(framework, standard.identifier);
-  return {
-    framework,
-    identifier
-  };
-}
-function assessmentStandardRefKey2(standard) {
-  const canonical = canonicalAssessmentStandardRef2(standard);
-  return JSON.stringify([
-    normalizedIdentityCase2(canonical.framework),
-    normalizedIdentityCase2(canonical.identifier)
-  ]);
-}
 function dedupeStandards2(standards) {
   const deduped = new Map;
   for (const standard of standards) {
@@ -115182,22 +115259,6 @@ function qtiStandardsFromMetadata(metadata2) {
   standards.push(...qtiAlignmentStandardsFromMetadata2(metadata2));
   return dedupeStandards2(standards);
 }
-function qtiAssessmentStandardRefsFromMetadata2(metadata2) {
-  const refs = new Map;
-  for (const alignment of qtiAlignmentStandardsFromMetadata2(metadata2)) {
-    const identifier = readableAlignmentIdentifier2(alignment);
-    if (identifier) {
-      const canonical = canonicalAssessmentStandardRef2({
-        framework: alignment.source,
-        identifier
-      });
-      if (canonical.framework && canonical.identifier) {
-        refs.set(assessmentStandardRefKey2(canonical), canonical);
-      }
-    }
-  }
-  return [...refs.values()];
-}
 var EVENT_HANDLER_ATTRIBUTE;
 var SCRIPT_SCHEMES2;
 var DATA_RASTER_IMAGE_PATTERN2;
@@ -115242,7 +115303,6 @@ var BLANK_SENTINEL22 = "
 var PLAYABLE_POINT_VALUE;
 var POINT_INTERACTION_TYPES2;
 var INDEPENDENT_PROCESSING_TAGS2;
-var UUID_PATTERN2;
 var COMMON_CORE_MATH_FRAMEWORK_ALIASES2;
 var COMMON_CORE_ELA_FRAMEWORK_ALIASES2;
 var COMMON_CORE_FRAMEWORK_ALIASES2;
@@ -115495,7 +115555,6 @@ var init_qti = __esm(() => {
     "qti-sum",
     "qti-base-value"
   ]);
-  UUID_PATTERN2 = /^(?:urn:uuid:)?\{?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\}?$/i;
   COMMON_CORE_MATH_FRAMEWORK_ALIASES2 = new Set([
     "ccssm",
     "ccssmath",
@@ -117895,8 +117954,8 @@ function assertAssessmentHasQuestions(questions) {
   }
 }
 function assertReviewAssessmentHasStandards(standardCounts) {
-  if (standardCounts.some((count) => count <= 0)) {
-    throw new ValidationError("Every question in a review assessment must have a standards alignment");
+  if (standardCounts.some((count) => count !== 1)) {
+    throw new ValidationError("Every question in a review assessment must have exactly one standards alignment");
   }
 }
 function planAssessmentRemoval(status) {
@@ -117959,6 +118018,41 @@ function orderLiveAssessmentRows(liveRows, purpose, testIdentifiers) {
 var init_timeback_assessment_rules_util = __esm(() => {
   init_errors2();
 });
+function stageAssessmentAttemptSupersession(attempt) {
+  Object.assign(attempt.result, ASSESSMENT_ATTEMPT_SUPERSEDED);
+  Object.assign(attempt.selection, ASSESSMENT_ATTEMPT_SUPERSEDED);
+}
+function shouldConfirmAssessmentVersionUnavailable(details) {
+  return typeof details === "object" && details !== null && "expectedRevision" in details && typeof details.expectedRevision === "string" && !("currentRevision" in details);
+}
+function buildAssessmentAttemptSupersessionUpdate(result) {
+  if (result.status !== "active" || !isAssessmentAttemptOpen({
+    inProgress: result.inProgress ?? "",
+    scoreStatus: result.scoreStatus
+  })) {
+    return null;
+  }
+  return {
+    status: "active",
+    assessmentLineItem: result.assessmentLineItem,
+    student: result.student,
+    score: result.score ?? 0,
+    scoreDate: result.scoreDate,
+    ...ASSESSMENT_ATTEMPT_SUPERSEDED,
+    metadata: result.metadata ?? {}
+  };
+}
+async function resolveAvailableAssessmentAttempt(initialDecision, select3, resume) {
+  let decision = initialDecision;
+  while (decision?.kind === "resume") {
+    const snapshot = await resume(decision);
+    if (snapshot !== null) {
+      return { kind: "resumed", snapshot };
+    }
+    decision = select3();
+  }
+  return { kind: "continue", decision };
+}
 function buildReviewItemResultMetadata(input) {
   const administration = itemAdministration(input.metadata.itemSubmissions, input.selection.itemIdentifier);
   if (!administration) {
@@ -118403,8 +118497,8 @@ function parsePlayableItem(question) {
 function assessmentContentRevision(test, questions) {
   return sha256Hex(canonicalJson2({
     identifier: test.identifier,
+    title: test.title,
     qtiVersion: test.qtiVersion,
-    rawXml: test.rawXml,
     parts: test["qti-test-part"],
     questions: questions.questions.map(({ reference, question }) => ({
       identifier: reference.identifier,
@@ -118560,11 +118654,30 @@ async function hydrateQtiTestQuestions(client2, references) {
   }));
   return { ...references, questions };
 }
-async function loadHydratedQtiTest(client2, identifier) {
+async function hydrateQtiTestQuestionSelection(client2, references, itemIdentifiers) {
+  const referenceByIdentifier = new Map(references.questions.map((reference) => [reference.reference.identifier, reference]));
+  const selectedReferences = itemIdentifiers.map((itemIdentifier) => {
+    const reference = referenceByIdentifier.get(itemIdentifier);
+    if (!reference) {
+      throw new Error(`QTI assessment ${references.assessmentTest} does not contain item ${itemIdentifier}`);
+    }
+    return reference;
+  });
+  return hydrateQtiTestQuestions(client2, {
+    ...references,
+    totalQuestions: selectedReferences.length,
+    questions: selectedReferences
+  });
+}
+async function loadQtiTestReferences(client2, identifier) {
   const [test, references] = await Promise.all([
     client2.qtiApi.assessmentTests.get(identifier),
     client2.qtiApi.assessmentTests.getQuestions(identifier)
   ]);
+  return { test, references };
+}
+async function loadHydratedQtiTest(client2, identifier) {
+  const { test, references } = await loadQtiTestReferences(client2, identifier);
   return {
     test,
     questions: await hydrateQtiTestQuestions(client2, references)
@@ -118578,6 +118691,7 @@ class TimebackAssessmentRuntimeService {
   static ASSESSMENT_CACHE_TTL_MS = 60000;
   static EXPORT_CONCURRENCY = 4;
   static ITEM_SUBMISSION_MAX_PREPARATION_ATTEMPTS = 3;
+  static ASSESSMENT_VERSION_CONFIRMATION_DELAY_MS = 25;
   static PROJECTION_BARRIER_MAX_ATTEMPTS = 5;
   static PROJECTION_BARRIER_RETRY_DELAY_MS = 25;
   static SCORING_CONCURRENCY = 4;
@@ -118590,6 +118704,10 @@ class TimebackAssessmentRuntimeService {
     defaultTTL: TimebackAssessmentRuntimeService.ASSESSMENT_CACHE_TTL_MS,
     maxSize: TimebackAssessmentRuntimeService.ASSESSMENT_CACHE_LIMIT
   });
+  reviewSelectionCache = new TimebackCache({
+    defaultTTL: TimebackAssessmentRuntimeService.ASSESSMENT_CACHE_TTL_MS,
+    maxSize: TimebackAssessmentRuntimeService.ASSESSMENT_CACHE_LIMIT
+  });
   constructor(deps) {
     this.deps = deps;
   }
@@ -118608,6 +118726,7 @@ class TimebackAssessmentRuntimeService {
     }
     const masteryStandard = input.purpose === "mastery" ? normalizeMasteryStandard(input.standard) : undefined;
     const requestFingerprint = this.startRequestFingerprint(input);
+    const pendingSupersessions = new Set;
     const candidates = await this.candidateIntegrations(gameId, studentId, input);
     const lockKeys = candidates.rows.map((row) => assessmentRuntimeStartLockKey({
       studentId,
@@ -118630,20 +118749,21 @@ class TimebackAssessmentRuntimeService {
         this.listAttempts(attemptScope)
       ]);
       const attempts = listing.attempts;
-      const compatibleAttempts = this.attemptsMatchingRequest(attempts, requestFingerprint);
-      let decision = this.requireDecision(selectRuntimeAssessment(tests, [...compatibleAttempts.values()].map((entry2) => entry2.selection)), input.purpose);
-      if (decision.kind === "resume") {
-        return this.resumeSnapshot(decision, attempts, context2.integration);
+      const initialResolution = await this.resumeAvailableAttempt(tests, attempts, requestFingerprint, pendingSupersessions, (resumeDecision) => this.resumeSnapshot(resumeDecision, attempts, context2.integration));
+      if (initialResolution.kind === "resumed") {
+        await this.persistPendingSupersessionsBestEffort(pendingSupersessions);
+        return initialResolution.snapshot;
       }
+      let decision = this.requireDecision(initialResolution.decision, input.purpose);
       let assessment = await this.loadAssessment(decision.test.qtiTestIdentifier);
       const refreshedListing = await this.listAttempts(attemptScope);
       const refreshed = refreshedListing.attempts;
-      const refreshedCompatible = this.attemptsMatchingRequest(refreshed, requestFingerprint);
-      const refreshedDecision = this.requireDecision(selectRuntimeAssessment(tests, [...refreshedCompatible.values()].map((entry2) => entry2.selection)), input.purpose);
-      if (refreshedDecision.kind === "resume") {
-        return this.resumeSnapshot(refreshedDecision, refreshed, context2.integration);
+      const refreshedResolution = await this.resumeAvailableAttempt(tests, refreshed, requestFingerprint, pendingSupersessions, (resumeDecision) => this.resumeSnapshot(resumeDecision, refreshed, context2.integration));
+      if (refreshedResolution.kind === "resumed") {
+        await this.persistPendingSupersessionsBestEffort(pendingSupersessions);
+        return refreshedResolution.snapshot;
       }
-      decision = refreshedDecision;
+      decision = this.requireDecision(refreshedResolution.decision, input.purpose);
       if (assessment.identifier !== decision.test.qtiTestIdentifier) {
         assessment = await this.loadAssessment(decision.test.qtiTestIdentifier);
       }
@@ -118701,6 +118821,7 @@ class TimebackAssessmentRuntimeService {
           grade: context2.integration.grade
         })
       });
+      await this.persistPendingSupersessionsBestEffort(pendingSupersessions);
       return this.snapshot(result, metadata2, assessment, context2.integration);
     });
   }
@@ -118710,6 +118831,7 @@ class TimebackAssessmentRuntimeService {
     input
   }) {
     const requestFingerprint = this.startRequestFingerprint(input);
+    const pendingSupersessions = new Set;
     const candidates = await this.candidateIntegrations(gameId, studentId, input);
     const lockKeys = candidates.rows.map((row) => assessmentRuntimeStartLockKey({
       studentId,
@@ -118731,22 +118853,23 @@ class TimebackAssessmentRuntimeService {
         this.liveTests(context2.integration.id, input.purpose, db2, undefined, input.diagnosticKey),
         this.listAttempts(attemptScope)
       ]);
-      const compatible = this.attemptsMatchingRequest(listing.attempts, requestFingerprint);
-      let decision = this.requireDecision(selectRuntimeAssessment(tests, [...compatible.values()].map((entry2) => entry2.selection)), input.purpose);
-      if (decision.kind === "resume") {
-        return this.resumeDiagnosticSnapshot(decision, listing.attempts, context2.integration, db2);
+      const initialResolution = await this.resumeAvailableAttempt(tests, listing.attempts, requestFingerprint, pendingSupersessions, (resumeDecision) => this.resumeDiagnosticSnapshot(resumeDecision, listing.attempts, context2.integration, db2));
+      if (initialResolution.kind === "resumed") {
+        await this.persistPendingSupersessionsBestEffort(pendingSupersessions);
+        return initialResolution.snapshot;
       }
+      let decision = this.requireDecision(initialResolution.decision, input.purpose);
       let definition = await this.requireDiagnosticDefinition(decision.test.id, context2.integration.id, db2, true);
       let assessment = await this.loadAssessment(definition.qtiTestIdentifier);
       let routing = await this.initializeHostedDiagnostic(definition, assessment);
       const refreshedListing = await this.listAttempts(attemptScope);
       const refreshed = refreshedListing.attempts;
-      const refreshedCompatible = this.attemptsMatchingRequest(refreshed, requestFingerprint);
-      const refreshedDecision = this.requireDecision(selectRuntimeAssessment(tests, [...refreshedCompatible.values()].map((entry2) => entry2.selection)), input.purpose);
-      if (refreshedDecision.kind === "resume") {
-        return this.resumeDiagnosticSnapshot(refreshedDecision, refreshed, context2.integration, db2);
+      const refreshedResolution = await this.resumeAvailableAttempt(tests, refreshed, requestFingerprint, pendingSupersessions, (resumeDecision) => this.resumeDiagnosticSnapshot(resumeDecision, refreshed, context2.integration, db2));
+      if (refreshedResolution.kind === "resumed") {
+        await this.persistPendingSupersessionsBestEffort(pendingSupersessions);
+        return refreshedResolution.snapshot;
       }
-      decision = refreshedDecision;
+      decision = this.requireDecision(refreshedResolution.decision, input.purpose);
       if (definition.id !== decision.test.id) {
         definition = await this.requireDiagnosticDefinition(decision.test.id, context2.integration.id, db2, true);
         assessment = await this.loadAssessment(definition.qtiTestIdentifier);
@@ -118815,6 +118938,7 @@ class TimebackAssessmentRuntimeService {
           grade: context2.integration.grade
         })
       });
+      await this.persistPendingSupersessionsBestEffort(pendingSupersessions);
       return this.diagnosticSnapshot(result, metadata2, assessment, context2.integration, routing.state);
     });
   }
@@ -118823,7 +118947,9 @@ class TimebackAssessmentRuntimeService {
     studentId,
     input
   }) {
+    const preparationStartedAt = Date.now();
     const requestFingerprint = reviewRequestFingerprint(input, DEFAULT_REVIEW_SELECTION_POLICY);
+    const pendingSupersessions = new Set;
     const normalizedRequest = normalizeReviewRequest(input);
     const candidates = await this.candidateIntegrations(gameId, studentId, input);
     const lockKeys = candidates.rows.map((row) => assessmentRuntimeStartLockKey({
@@ -118847,38 +118973,44 @@ class TimebackAssessmentRuntimeService {
         this.listAttempts(attemptScope)
       ]);
       const attempts = listing.attempts;
-      const compatible = this.attemptsMatchingRequest(attempts, requestFingerprint);
-      let decision = selectRuntimeAssessment(tests, [...compatible.values()].map((entry2) => entry2.selection));
-      if (decision?.kind === "resume") {
-        return this.resumeReviewSnapshot(decision, compatible, listing.reviewChildren, context2);
+      const initialResolution = await this.resumeAvailableAttempt(tests, attempts, requestFingerprint, pendingSupersessions, (resumeDecision) => this.resumeReviewSnapshot(resumeDecision, attempts, listing.reviewChildren, context2));
+      if (initialResolution.kind === "resumed") {
+        await this.persistPendingSupersessionsBestEffort(pendingSupersessions);
+        return initialResolution.snapshot;
       }
+      let decision = initialResolution.decision;
       if (tests.length === 0 || !decision) {
         throw AssessmentRuntimeError.from(assessmentNoEligibleTests(input.purpose));
       }
       if (tests.length > 1) {
         throw new ValidationError("Standards review requires exactly one live review-bank assessment.");
       }
-      let source = await this.loadReviewBank(decision.test.qtiTestIdentifier);
+      const manifestStartedAt = Date.now();
+      let catalog = await this.loadReviewBankCatalog(decision.test.qtiTestIdentifier);
+      this.recordReviewPreparationPhase("manifest_load", manifestStartedAt, {
+        candidateCount: catalog.bank.items.length
+      });
       const refreshedListing = await this.listAttempts(attemptScope);
       const refreshed = refreshedListing.attempts;
-      const refreshedCompatible = this.attemptsMatchingRequest(refreshed, requestFingerprint);
-      const refreshedDecision = selectRuntimeAssessment(tests, [...refreshedCompatible.values()].map((entry2) => entry2.selection));
-      if (refreshedDecision?.kind === "resume") {
-        return this.resumeReviewSnapshot(refreshedDecision, refreshedCompatible, refreshedListing.reviewChildren, context2);
+      const refreshedResolution = await this.resumeAvailableAttempt(tests, refreshed, requestFingerprint, pendingSupersessions, (resumeDecision) => this.resumeReviewSnapshot(resumeDecision, refreshed, refreshedListing.reviewChildren, context2));
+      if (refreshedResolution.kind === "resumed") {
+        await this.persistPendingSupersessionsBestEffort(pendingSupersessions);
+        return refreshedResolution.snapshot;
       }
+      const refreshedDecision = refreshedResolution.decision;
       if (!refreshedDecision || refreshedDecision.kind !== "start") {
         throw AssessmentRuntimeError.from(assessmentNoEligibleTests(input.purpose));
       }
       decision = refreshedDecision;
-      if (source.assessment.identifier !== decision.test.qtiTestIdentifier) {
-        source = await this.loadReviewBank(decision.test.qtiTestIdentifier);
+      if (catalog.test.identifier !== decision.test.qtiTestIdentifier) {
+        catalog = await this.loadReviewBankCatalog(decision.test.qtiTestIdentifier);
       }
       const exposures = this.reviewExposures(refreshedListing.reviewChildren.values(), {
-        bankRevision: source.bank.bankRevision
+        bankRevision: catalog.bank.bankRevision
       });
       const selected = selectReviewItems({
         request: input,
-        bank: source.bank,
+        bank: catalog.bank,
         exposures
       });
       if (selected.selections.length === 0) {
@@ -118887,7 +119019,13 @@ class TimebackAssessmentRuntimeService {
         }
         throw AssessmentRuntimeError.from(assessmentReviewBankShortage(selected.fulfillment));
       }
+      const hydrationStartedAt = Date.now();
+      const source = await this.hydrateReviewBankSelection(catalog, selected.selections.map((selection) => selection.itemIdentifier));
+      this.recordReviewPreparationPhase("selected_hydration", hydrationStartedAt, {
+        selectedCount: selected.selections.length
+      });
       const assessment = projectReviewAssessment(source.assessment, source.bank, selected.selections);
+      const provisioningStartedAt = Date.now();
       const parentLineItemId = await this.ensureReviewBankLineItem({
         integration: context2.integration,
         activityId: input.activityId,
@@ -118950,6 +119088,12 @@ class TimebackAssessmentRuntimeService {
         existingChildResults: refreshedListing.reviewChildren,
         lookupMissingResults: false
       });
+      await this.persistPendingSupersessionsBestEffort(pendingSupersessions);
+      this.recordReviewPreparationPhase("provisioning", provisioningStartedAt);
+      this.recordReviewPreparationPhase("total", preparationStartedAt, {
+        candidateCount: catalog.bank.items.length,
+        selectedCount: selected.selections.length
+      });
       return this.snapshot(result, metadata2, assessment, context2.integration);
     });
   }
@@ -119303,7 +119447,7 @@ class TimebackAssessmentRuntimeService {
         preparationAttempts += 1;
         preview = await this.scoreDiagnosticItemSubmission(params, input);
       } else {
-        await this.projectDiagnosticItemResponse(committed.projection);
+        await this.projectDiagnosticItemResponse(committed.projection, preview?.assessment);
         return committed.response;
       }
     }
@@ -119717,7 +119861,7 @@ class TimebackAssessmentRuntimeService {
             where: and(eq(gameTimebackAssessmentTests.id, test.id), eq(gameTimebackAssessmentTests.integrationId, integration.id))
           }) : undefined;
           const diagnostic = definition?.diagnosticKey ? await this.initializeHostedDiagnostic(definition, loaded.assessment) : null;
-          const reviewBank = purpose === "review" ? await buildReviewBankIndex(loaded.assessment, loaded.questions) : null;
+          const reviewBank = purpose === "review" ? await buildReviewBankIndex(loaded.assessment, loaded.questions, { customOnly: true }) : null;
           return {
             ...test,
             live: true,
@@ -119780,7 +119924,13 @@ class TimebackAssessmentRuntimeService {
     const enrollmentByCourse = new Map(enrollments.map((enrollment) => [enrollment.course.id, enrollment]));
     const candidateRows = integrations.filter((integration) => enrollmentByCourse.has(integration.courseId));
     const liveTestRows = candidateRows.length === 0 ? [] : await db2.query.gameTimebackAssessmentTests.findMany({
-      where: and(inArray(gameTimebackAssessmentTests.integrationId, candidateRows.map((row) => row.id)), eq(gameTimebackAssessmentTests.purpose, input.purpose), eq(gameTimebackAssessmentTests.status, "live"))
+      where: and(inArray(gameTimebackAssessmentTests.integrationId, candidateRows.map((row) => row.id)), eq(gameTimebackAssessmentTests.purpose, input.purpose), eq(gameTimebackAssessmentTests.status, "live")),
+      columns: {
+        integrationId: true,
+        standardFramework: true,
+        standardIdentifier: true,
+        diagnosticKey: true
+      }
     });
     const matchesMasteryStandard = input.purpose === "mastery" ? masteryStandardMatcher(input.standard) : undefined;
     const integrationIdsWithLiveTests = new Set(liveTestRows.filter((row) => (!matchesMasteryStandard || matchesMasteryStandard(assessmentStandardForRow(row))) && (input.purpose !== "diagnostic" || row.diagnosticKey === input.diagnosticKey)).map((row) => row.integrationId));
@@ -119973,6 +120123,75 @@ class TimebackAssessmentRuntimeService {
     });
     return this.diagnosticSnapshot(resumed.result, resumed.metadata, assessment, integration, routing.state);
   }
+  async resumeAvailableAttempt(tests, attempts, requestFingerprint, pendingSupersessions, resume) {
+    const select3 = () => selectRuntimeAssessment(tests, [...this.attemptsMatchingRequest(attempts, requestFingerprint).values()].map((entry2) => entry2.selection));
+    return resolveAvailableAssessmentAttempt(select3(), select3, (decision) => this.resumeSnapshotOrStageSupersession(decision, attempts, pendingSupersessions, () => resume(decision)));
+  }
+  async resumeSnapshotOrStageSupersession(decision, attempts, pendingSupersessions, resume) {
+    try {
+      return await resume();
+    } catch (error88) {
+      if (!(error88 instanceof AssessmentRuntimeError) || error88.runtimeCode !== "SELECTED_TEST_VERSION_UNAVAILABLE") {
+        throw error88;
+      }
+      if (shouldConfirmAssessmentVersionUnavailable(error88.details)) {
+        await sleep(TimebackAssessmentRuntimeService.ASSESSMENT_VERSION_CONFIRMATION_DELAY_MS);
+        try {
+          return await resume();
+        } catch (confirmationError) {
+          if (!(confirmationError instanceof AssessmentRuntimeError) || confirmationError.runtimeCode !== "SELECTED_TEST_VERSION_UNAVAILABLE") {
+            throw confirmationError;
+          }
+        }
+      }
+      const staged = attempts.get(decision.attempt.attemptId);
+      pendingSupersessions.add(staged.result.sourcedId);
+      stageAssessmentAttemptSupersession(staged);
+      addEvent("assessment.attempt_supersession_staged", {
+        "app.assessment.attempt_id": decision.attempt.attemptId,
+        "app.assessment.reason": "selected_test_version_unavailable"
+      });
+      return null;
+    }
+  }
+  async persistPendingSupersessions(attemptIds) {
+    for (const attemptId of [...attemptIds].toSorted()) {
+      await this.deps.assessmentRuntimeLock(this.deps.db, assessmentRuntimeAttemptLockKey(attemptId), async () => {
+        let result;
+        try {
+          result = await this.requireClient().api.oneroster.assessmentResults.get(attemptId);
+        } catch (error88) {
+          if (isApiError(error88) && error88.statusCode === 404) {
+            return;
+          }
+          throw error88;
+        }
+        const update2 = buildAssessmentAttemptSupersessionUpdate(result);
+        if (!update2) {
+          return;
+        }
+        await this.requireClient().api.oneroster.assessmentResults.upsert(attemptId, update2);
+        addEvent("assessment.attempt_superseded", {
+          "app.assessment.attempt_id": attemptId,
+          "app.assessment.reason": "selected_test_version_unavailable"
+        });
+      });
+    }
+  }
+  async persistPendingSupersessionsBestEffort(attemptIds) {
+    if (attemptIds.size === 0) {
+      return;
+    }
+    try {
+      await this.persistPendingSupersessions(attemptIds);
+    } catch (error88) {
+      addEvent("assessment.attempt_supersession_persist_failed", {
+        "app.assessment.attempt_ids": [...attemptIds].toSorted().join(","),
+        "exception.type": errorType(error88),
+        "app.error.message": errorMessage2(error88)
+      });
+    }
+  }
   async resumeReviewSnapshot(decision, attempts, existingChildResults, context2) {
     if (decision.additionalResumableAttemptIds.length > 0) {
       addEvent("assessment.multiple_resumable_attempts", {
@@ -119984,7 +120203,8 @@ class TimebackAssessmentRuntimeService {
     if (resumed.metadata.purpose !== "review") {
       throw new Error("A standards-review request selected a non-review attempt");
     }
-    const currentSource = await this.loadReviewBank(resumed.metadata.selectedTest.identifier, resumed.metadata.selectedTest.contentRevision);
+    const catalog = await this.loadReviewBankCatalog(resumed.metadata.selectedTest.identifier, resumed.metadata.selectedTest.contentRevision);
+    const currentSource = await this.hydrateReviewBankSelection(catalog, resumed.metadata.review.selections.map((selection) => selection.itemIdentifier));
     const source = this.pinnedReviewBankSource(currentSource, resumed.metadata);
     const assessment = projectReviewAssessment(source.assessment, source.bank, resumed.metadata.review.selections);
     await this.ensureReviewChildResults({
@@ -119998,20 +120218,68 @@ class TimebackAssessmentRuntimeService {
     });
     return this.snapshot(resumed.result, resumed.metadata, assessment, context2.integration);
   }
-  async loadReviewBank(identifier, expectedSourceRevision) {
+  recordReviewPreparationPhase(phase, startedAt, counts = {}) {
+    addEvent("assessment.review_preparation_phase", {
+      "app.assessment.review_phase": phase,
+      "app.assessment.duration_ms": Date.now() - startedAt,
+      ...counts.candidateCount === undefined ? {} : { "app.assessment.candidate_count": counts.candidateCount },
+      ...counts.selectedCount === undefined ? {} : { "app.assessment.selected_count": counts.selectedCount }
+    });
+  }
+  async loadReviewBankCatalog(identifier, expectedSourceRevision) {
     if (expectedSourceRevision) {
       const cached3 = this.reviewBankCache.get(`${identifier}\x00${expectedSourceRevision}`);
       if (cached3) {
         return cached3;
       }
     }
-    const loaded = await this.loadAssessmentSource(identifier, expectedSourceRevision);
-    const source = {
-      assessment: loaded.assessment,
-      bank: await buildReviewBankIndex(loaded.assessment, loaded.questions)
-    };
-    this.reviewBankCache.set(`${identifier}\x00${source.assessment.contentRevision}`, source);
-    return source;
+    let loaded;
+    try {
+      loaded = await loadQtiTestReferences(this.requireClient(), identifier);
+    } catch (error88) {
+      if (expectedSourceRevision && isApiError(error88) && error88.statusCode === 404) {
+        throw new AssessmentRuntimeError("SELECTED_TEST_VERSION_UNAVAILABLE", `The selected assessment version for ${identifier} is no longer available.`, { identifier, expectedRevision: expectedSourceRevision });
+      }
+      throw error88;
+    }
+    let bank;
+    try {
+      bank = await reviewBankIndexFromManifest(loaded.test.metadata, {
+        bankIdentifier: identifier,
+        membershipItemIdentifiers: loaded.references.questions.map((question) => question.reference.identifier)
+      });
+    } catch (error88) {
+      throw new ServiceUnavailableError(`Review bank ${identifier} has stale or invalid routing metadata. Use Update Mapping in assessment authoring.`, { reason: errorMessage2(error88) });
+    }
+    if (!bank) {
+      throw new ServiceUnavailableError(`Review bank ${identifier} needs its authoring mapping updated before it can serve review questions.`);
+    }
+    if (expectedSourceRevision && bank.sourceContentRevision !== expectedSourceRevision) {
+      throw new AssessmentRuntimeError("SELECTED_TEST_VERSION_UNAVAILABLE", `The selected assessment version for ${identifier} is no longer available.`, {
+        identifier,
+        expectedRevision: expectedSourceRevision,
+        currentRevision: bank.sourceContentRevision
+      });
+    }
+    const catalog = { ...loaded, bank };
+    this.reviewBankCache.set(`${identifier}\x00${bank.sourceContentRevision}`, catalog);
+    return catalog;
+  }
+  async hydrateReviewBankSelection(catalog, itemIdentifiers) {
+    const cacheKey2 = [
+      catalog.test.identifier,
+      catalog.bank.sourceContentRevision,
+      ...itemIdentifiers
+    ].join("\x00");
+    const cached3 = this.reviewSelectionCache.get(cacheKey2);
+    if (cached3) {
+      return { assessment: cached3, bank: catalog.bank };
+    }
+    const questions = await hydrateQtiTestQuestionSelection(this.requireClient(), catalog.references, itemIdentifiers);
+    const assessment = await buildPlayableAssessment(catalog.test, questions);
+    assessment.contentRevision = catalog.bank.sourceContentRevision;
+    this.reviewSelectionCache.set(cacheKey2, assessment);
+    return { assessment, bank: catalog.bank };
   }
   pinnedReviewBankSource(source, metadata2) {
     return {
@@ -120042,7 +120310,8 @@ class TimebackAssessmentRuntimeService {
     if (metadata2.purpose !== "review") {
       return this.loadAssessment(metadata2.selectedTest.identifier, metadata2.selectedTest.contentRevision);
     }
-    const currentSource = await this.loadReviewBank(metadata2.selectedTest.identifier, metadata2.selectedTest.contentRevision);
+    const catalog = await this.loadReviewBankCatalog(metadata2.selectedTest.identifier, metadata2.selectedTest.contentRevision);
+    const currentSource = await this.hydrateReviewBankSelection(catalog, metadata2.review.selections.map((selection) => selection.itemIdentifier));
     const source = this.pinnedReviewBankSource(currentSource, metadata2);
     return projectReviewAssessment(source.assessment, source.bank, metadata2.review.selections);
   }
@@ -120665,6 +120934,14 @@ class TimebackAssessmentRuntimeService {
     return AssessmentRuntimeError.from(assessmentAttemptUnauthorized(attemptId));
   }
   async snapshotForResult(result, metadata2, integration) {
+    if (isAssessmentAttemptSuperseded({
+      inProgress: result.inProgress ?? "",
+      scoreStatus: result.scoreStatus
+    })) {
+      throw new GoneError("This assessment attempt has been superseded.", {
+        attemptId: result.sourcedId
+      });
+    }
     const assessment = await this.loadAttemptAssessment(metadata2);
     if (this.isPlatformRoutedDiagnosticMetadata(metadata2)) {
       const routing = await this.loadAttemptDiagnosticRouting(metadata2, assessment);
@@ -122010,6 +122287,60 @@ function buildQtiLibraryListPlan(params) {
 }
 var PLAYCADEMY_QTI_SOURCE_PREFIX = "playcademy-test-";
 var PLAYCADEMY_QTI_SOURCE_UPPER_BOUND = "playcademy-test.";
+function reviewMappingIssueSummary(label, identifiers) {
+  if (identifiers.length === 0) {
+    return null;
+  }
+  const displayed = identifiers.slice(0, 10).join(", ");
+  const remainder = identifiers.length > 10 ? `, and ${identifiers.length - 10} more` : "";
+  return `${label} (${identifiers.length}): ${displayed}${remainder}`;
+}
+async function prepareReviewMappingUpdate(test, questions) {
+  const contentRevision = await assessmentContentRevision(test, questions);
+  const assessment = {
+    identifier: test.identifier,
+    contractVersion: 1,
+    contentRevision,
+    title: test.title,
+    items: questions.questions.map(({ question }) => ({
+      identifier: question.identifier,
+      title: question.title,
+      prompt: "",
+      maxScore: 1,
+      interactions: []
+    }))
+  };
+  const bank = await buildReviewBankIndex(assessment, questions, { customOnly: true });
+  const issues = reviewBankMappingIssues(bank);
+  if (issues.missingOrInvalidItemIdentifiers.length > 0 || issues.multipleStandardItemIdentifiers.length > 0) {
+    const details = [
+      reviewMappingIssueSummary("missing or invalid associations", issues.missingOrInvalidItemIdentifiers),
+      reviewMappingIssueSummary("multiple associations", issues.multipleStandardItemIdentifiers)
+    ].filter((detail) => detail !== null);
+    throw new ValidationError(`Every review question must have exactly one valid standard/node association. ${details.join("; ")}.`);
+  }
+  const manifest = await buildReviewBankManifest(bank);
+  return {
+    update: {
+      ...buildQtiTestUpdateInput(test, test.title),
+      metadata: {
+        ...test.metadata,
+        [PLAYCADEMY_REVIEW_BANK_MANIFEST_METADATA_KEY]: manifest
+      }
+    },
+    summary: {
+      itemCount: bank.items.length,
+      standardCount: Object.keys(manifest.itemsByStandard).length,
+      sourceFingerprint: manifest.sourceFingerprint
+    }
+  };
+}
+var init_timeback_review_mapping_util = __esm(() => {
+  init_assessment_runtime2();
+  init_errors2();
+  init_timeback_assessment_runtime_util();
+  init_timeback_qti_authoring_util();
+});
 function databaseConstraintName(error88) {
   if (typeof error88 !== "object" || error88 === null) {
     return;
@@ -122091,7 +122422,8 @@ class TimebackAssessmentsService {
         ownerGameSlug: ownership.gameSlug,
         integrationId,
         subject: integration.subject,
-        grade: String(integration.grade)
+        grade: String(integration.grade),
+        [PLAYCADEMY_REVIEW_BANK_MANIFEST_METADATA_KEY]: emptyReviewBankManifest(input.qtiTestIdentifier)
       }
     });
     try {
@@ -122160,7 +122492,9 @@ class TimebackAssessmentsService {
         assertAssessmentHasQuestions(loaded.questions.questions);
         assertPlayableAssessmentImportQuestions(manifest.targetStatus, loaded.questions.questions.map(({ question }) => question));
         if (entry2.purpose === "review") {
-          assertReviewAssessmentHasStandards(loaded.questions.questions.map(({ question }) => qtiAssessmentStandardRefsFromMetadata2(question.metadata).filter((standard) => canonicalReviewStandardRef(standard) !== null).length));
+          assertReviewAssessmentHasStandards(loaded.questions.questions.map(({ question }) => reviewRoutingStandardRefsFromMetadata(question.metadata, {
+            customOnly: true
+          }).length));
         }
         return { entry: entry2, test: loaded.test };
       } catch (error88) {
@@ -122312,6 +122646,10 @@ class TimebackAssessmentsService {
         if (input.status !== undefined) {
           validateAssessmentStatusTransition(row.status, input.status);
         }
+        if (!publishing && !activatingReview && nextPurpose === "review" && row.purpose !== "review") {
+          const ownership = await this.requireQtiTestOwnershipContext(integrationId, tx);
+          await this.rebuildReviewMapping(this.requireClient(), qtiTestIdentifier, ownership.gameSlug);
+        }
         if (input.title !== undefined) {
           assertDraftAssessment(row);
           assertAllAssessmentAssociationsDraft(associations);
@@ -122330,7 +122668,8 @@ class TimebackAssessmentsService {
             updates.diagnosticKey = nextDiagnostic.diagnosticKey;
             updates.diagnosticRoutingManifest = nextDiagnostic.routingManifest;
           } else {
-            await this.validateAssessmentHasQuestions(qtiTestIdentifier, nextPurpose === "review" && nextStatus === "live");
+            const reviewOwnership = nextPurpose === "review" && nextStatus === "live" ? await this.requireQtiTestOwnershipContext(integrationId, tx) : undefined;
+            await this.validateAssessmentHasQuestions(qtiTestIdentifier, reviewOwnership?.gameSlug);
           }
         }
         let updated = row;
@@ -122425,6 +122764,19 @@ class TimebackAssessmentsService {
     });
     return { ...result, questions };
   }
+  async updateReviewMapping(integrationId, qtiTestIdentifier) {
+    return this.withLockedAssessmentAssociations(integrationId, qtiTestIdentifier, async (row, tx, associations) => {
+      if (!associations.some((association) => association.purpose === "review")) {
+        throw new ValidationError("Review mapping is available only for standards-review assessments.");
+      }
+      const client2 = this.requireClient();
+      const ownership = await this.requireQtiTestOwnershipContext(integrationId, tx);
+      const result = await this.rebuildReviewMapping(client2, qtiTestIdentifier, ownership.gameSlug);
+      setAttribute("app.assessment.operation", "update_review_mapping");
+      setAttribute("app.assessment.review_mapping_item_count", result.itemCount);
+      return result;
+    });
+  }
   async listQuestionLibrary(integrationId, params) {
     const client2 = this.requireClient();
     await this.requireIntegration(integrationId);
@@ -122465,7 +122817,8 @@ class TimebackAssessmentsService {
       integrationId,
       subject: integration.subject,
       grade: String(integration.grade),
-      copiedFromTestIdentifier: sourceTestIdentifier
+      copiedFromTestIdentifier: sourceTestIdentifier,
+      [PLAYCADEMY_REVIEW_BANK_MANIFEST_METADATA_KEY]: emptyReviewBankManifest(targetTestIdentifier)
     }, itemPlan);
     const attemptedItemIdentifiers = [];
     let testCreationAttempted = false;
@@ -122853,16 +123206,20 @@ class TimebackAssessmentsService {
     const plan = buildQtiLibraryListPlan(params);
     return list(plan.params);
   }
-  async validateAssessmentHasQuestions(qtiTestIdentifier, requireReviewStandards = false) {
+  async validateAssessmentHasQuestions(qtiTestIdentifier, reviewGameSlug) {
     const client2 = this.requireClient();
-    const result = await client2.qtiApi.assessmentTests.getQuestions(qtiTestIdentifier);
+    const [test, result] = await Promise.all([
+      client2.qtiApi.assessmentTests.get(qtiTestIdentifier),
+      client2.qtiApi.assessmentTests.getQuestions(qtiTestIdentifier)
+    ]);
     assertAssessmentHasQuestions(result.questions);
     const hydrated = await hydrateQtiTestQuestions(client2, result);
     for (const { question } of hydrated.questions) {
       assertPlayableQtiQuestion(question);
     }
-    if (requireReviewStandards) {
-      assertReviewAssessmentHasStandards(hydrated.questions.map(({ question }) => qtiAssessmentStandardRefsFromMetadata2(question.metadata).filter((standard) => canonicalReviewStandardRef(standard) !== null).length));
+    if (reviewGameSlug) {
+      assertQtiTestOwnedByGame(test, reviewGameSlug);
+      await this.writeReviewMapping(client2, test, hydrated);
     }
   }
   async prepareDiagnosticAssociationChanges(row, nextPurpose, requested) {
@@ -122927,6 +123284,19 @@ class TimebackAssessmentsService {
       routingManifest: validation.manifest
     };
   }
+  async rebuildReviewMapping(client2, qtiTestIdentifier, gameSlug) {
+    const [test, references] = await Promise.all([
+      client2.qtiApi.assessmentTests.get(qtiTestIdentifier),
+      client2.qtiApi.assessmentTests.getQuestions(qtiTestIdentifier)
+    ]);
+    assertQtiTestOwnedByGame(test, gameSlug);
+    return this.writeReviewMapping(client2, test, await hydrateQtiTestQuestions(client2, references));
+  }
+  async writeReviewMapping(client2, test, questions) {
+    const prepared = await prepareReviewMappingUpdate(test, questions);
+    await client2.qtiApi.assessmentTests.update(test.identifier, prepared.update);
+    return prepared.summary;
+  }
 }
 var init_timeback_assessments_service = __esm(async () => {
   init_drizzle_orm();
@@ -122934,7 +123304,6 @@ var init_timeback_assessments_service = __esm(async () => {
   init_tables_index();
   init_spans();
   init_assessment_runtime2();
-  init_qti();
   init_timeback3();
   init_errors2();
   init_timeback_assessment_import_util();
@@ -122942,6 +123311,7 @@ var init_timeback_assessments_service = __esm(async () => {
   init_timeback_assessment_runtime_util();
   init_timeback_qti_authoring_util();
   init_timeback_qti_hydration_util();
+  init_timeback_review_mapping_util();
   await init_errors8();
 });
 function buildTimebackBaseConfigFromExistingConfig(config5) {
@@ -185557,6 +185927,7 @@ var listAssessments;
 var createAssessment;
 var attachExistingAssessments;
 var updateAssessment;
+var updateReviewMapping;
 var reorderAssessments;
 var reorderQuestions;
 var removeAssessment;
@@ -186241,6 +186612,14 @@ var init_timeback_controller = __esm(() => {
     const body2 = await parseRequestBody(ctx.request, UpdateAssessmentRequestSchema);
     return ctx.services.timebackAssessments.updateAssessment(integrationId, testIdentifier, body2);
   });
+  updateReviewMapping = requireDeveloper(async (ctx) => {
+    const { gameId, courseId, testIdentifier } = ctx.params;
+    if (!gameId || !courseId || !testIdentifier) {
+      throw ApiError.badRequest("Missing gameId, courseId, or testIdentifier parameter");
+    }
+    const integrationId = await ctx.services.timebackAssessments.resolveIntegrationId(gameId, courseId, ctx.user);
+    return ctx.services.timebackAssessments.updateReviewMapping(integrationId, testIdentifier);
+  });
   reorderAssessments = requireDeveloper(async (ctx) => {
     const { gameId, courseId } = ctx.params;
     if (!gameId || !courseId) {
@@ -186383,6 +186762,7 @@ var init_timeback_controller = __esm(() => {
     createAssessment,
     attachExistingAssessments,
     updateAssessment,
+    updateReviewMapping,
     reorderAssessments,
     removeAssessment,
     reorderQuestions,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@playcademy/vite-plugin",
-    "version": "1.2.1-beta.24",
+    "version": "1.2.1-beta.25",
     "type": "module",
     "exports": {
         ".": {
@@ -19,14 +19,14 @@
     "dependencies": {
         "archiver": "^7.0.1",
         "picocolors": "^1.1.1",
-        "playcademy": "0.28.1-beta.24"
+        "playcademy": "0.28.1-beta.25"
     },
     "devDependencies": {
         "@electric-sql/pglite": "^0.3.16",
         "@inquirer/prompts": "^7.8.6",
         "@playcademy/constants": "0.0.1",
-        "@playcademy/sandbox": "0.7.1-beta.22",
-        "@playcademy/sdk": "0.16.1-beta.23",
+        "@playcademy/sandbox": "0.7.1-beta.23",
+        "@playcademy/sdk": "0.16.1-beta.24",
         "@playcademy/types": "0.0.1",
         "@playcademy/utils": "0.0.1",
         "@types/archiver": "^6.0.3",