@playcademy/sdk 0.16.1-beta.13 → 0.16.1-beta.15

package/dist/contracts.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The child-catalog contract: what a child game publishes about its
+ * deliverable lessons, per lesson id and level. A parent course authority
+ * resolves its lesson references against this document at compile time and
+ * fails closed at runtime on anything not `ready` in production.
+ *
+ * Ownership and flow: each child repo generates `.playcademy/catalog.json`
+ * from its own registry (`playcademy catalog generate`); a sync workflow
+ * carries copies into parent repos. Children never read the parent's
+ * compiled authority — this file and the launch payload are the entire
+ * surface between them.
+ *
+ * The document deliberately carries no app identity. The consuming repo
+ * assigns the namespace key (e.g. 'form', 'math-cakes') from sync
+ * provenance via its own repo → app map, so a child cannot misdeclare
+ * who it is and a typo cannot mint a phantom namespace.
+ */
+/** Contract identifier carried by every catalog document. */
+declare const CHILD_CATALOG_CONTRACT: 'playcademy-child-catalog-v1';
+/** The completion-evidence contract a catalog declares its runs report. */
+declare const CHILD_ATTEMPT_CONTRACT: 'playcademy-child-attempt-v1';
+/** Delivery levels a catalog may declare (serving-id dialect, lowercase). */
+declare const CATALOG_LEVELS: readonly ['e1', 'e2', 'e3', 'e4'];
+type CatalogLevel = (typeof CATALOG_LEVELS)[number];
+/**
+ * ready: real content. simulated: placeholder — playable for preview and
+ * simulation, never creditable in production. unavailable: intentionally
+ * absent at this level. Consumers must treat unknown values and missing
+ * levels as unavailable (fail closed).
+ */
+declare const CATALOG_READINESS: readonly ['ready', 'simulated', 'unavailable'];
+type CatalogReadiness = (typeof CATALOG_READINESS)[number];
+interface ChildCatalog {
+    /** The contract identifier. */
+    contract: typeof CHILD_CATALOG_CONTRACT;
+    /** The completion-evidence contract a catalog declares its runs report. */
+    evidence: typeof CHILD_ATTEMPT_CONTRACT;
+    /** The tool that generated this document (repo-relative path). */
+    generatedBy: string;
+    /** The in-repo source of truth the document was derived from. */
+    generatedFrom: string;
+    /** Lesson id → level → readiness. */
+    deliveries: Record<string, Partial<Record<CatalogLevel, CatalogReadiness>>>;
+}
+
+export { CATALOG_LEVELS, CATALOG_READINESS, CHILD_ATTEMPT_CONTRACT, CHILD_CATALOG_CONTRACT };
+export type { CatalogLevel, CatalogReadiness, ChildCatalog };

package/dist/contracts.js

@@ -0,0 +1,23 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+
+// src/contracts/child-catalog.ts
+var CHILD_CATALOG_CONTRACT = "playcademy-child-catalog-v1";
+var CHILD_ATTEMPT_CONTRACT = "playcademy-child-attempt-v1";
+var CATALOG_LEVELS = ["e1", "e2", "e3", "e4"];
+var CATALOG_READINESS = ["ready", "simulated", "unavailable"];
+export {
+  CHILD_CATALOG_CONTRACT,
+  CHILD_ATTEMPT_CONTRACT,
+  CATALOG_READINESS,
+  CATALOG_LEVELS
+};

package/dist/index.d.ts

@@ -1558,6 +1558,9 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
             start: (input: _playcademy_types.StartAssessmentInput) => Promise<_playcademy_types.AssessmentAttemptSnapshot>;
             latest: (options: _playcademy_types.GetLatestAssessmentOptions) => Promise<_playcademy_types.LatestAssessmentResult | null>;
             get: (attemptId: string) => Promise<_playcademy_types.AssessmentAttemptSnapshot>;
+            stop: (attemptId: string) => Promise<{
+                attemptId: string;
+            }>;
             save: (attemptId: string, input: _playcademy_types.SaveAssessmentInput) => Promise<_playcademy_types.AssessmentSaveResult>;
             submitItem: (attemptId: string, input: _playcademy_types.SubmitAssessmentItemInput) => Promise<_playcademy_types.SubmitAssessmentItemResult>;
             submit: (attemptId: string, input: _playcademy_types.SubmitAssessmentInput) => Promise<_playcademy_types.AssessmentSubmitResult>;

package/dist/index.js

@@ -1730,6 +1730,29 @@ function createTimebackActivityTracker(client) {
     const resumeRunId = client["initPayload"]?.parent?.resumeRunId;
     return typeof resumeRunId === "string" && isValidUUID(resumeRunId) ? resumeRunId : undefined;
   }
+  function clockAvailability(owner) {
+    if (owner.kind === "assessment" && currentActivity?.owner.kind === "assessment" && currentActivity.owner.attemptId === owner.attemptId) {
+      return "held-by-this-owner";
+    }
+    if (hasLiveSession(client)) {
+      return { unavailable: "embedded-child" };
+    }
+    if (!currentActivity) {
+      return "available";
+    }
+    if (owner.kind === "activity") {
+      return currentActivity.owner.kind === "assessment" ? {
+        unavailable: "other-assessment",
+        runId: currentActivity.runId,
+        attemptId: currentActivity.owner.attemptId
+      } : "available";
+    }
+    return currentActivity.owner.kind === "assessment" ? {
+      unavailable: "other-assessment",
+      runId: currentActivity.runId,
+      attemptId: currentActivity.owner.attemptId
+    } : { unavailable: "ordinary-activity", runId: currentActivity.runId };
+  }
   function startHeartbeatInterval(activity) {
     if (activity.heartbeatIntervalMs === Infinity || activity.heartbeatIntervalId !== null) {
       return;
@@ -2041,6 +2064,110 @@ function createTimebackActivityTracker(client) {
     }
     stopRelayInterval();
   }
+  async function finishCurrentActivity(discardRelayedTiming) {
+    const activity = currentActivity;
+    if (activity.finishInFlight) {
+      return activity.finishInFlight;
+    }
+    activity.finishInFlight = (async () => {
+      applyOverdueInactivity();
+      cleanupListeners();
+      const relayedWithoutReconciliation = discardRelayedTiming && relaysToParent();
+      await flushHeartbeat(true);
+      if (activity.pauseStartTime !== null) {
+        activity.pausedTime += Date.now() - activity.pauseStartTime;
+        activity.pauseStartTime = null;
+      }
+      const endTime = Date.now();
+      const totalElapsed = endTime - activity.startTime;
+      const activeTime = Math.max(0, totalElapsed - activity.pausedTime);
+      const unreportedActiveMs = Math.max(0, activeTime - activity.totalPersistedActiveMs);
+      const unreportedPausedMs = Math.max(0, activity.pausedTime - activity.totalPersistedPausedMs);
+      if (currentActivity === activity) {
+        currentActivity = null;
+      }
+      return {
+        runId: activity.runId,
+        resumeId: activity.resumeId,
+        activityData: activity.metadata,
+        durationSeconds: Math.floor(activeTime / 1000),
+        sessionTimingData: relayedWithoutReconciliation ? { activeSeconds: 0 } : {
+          activeSeconds: unreportedActiveMs / 1000,
+          ...unreportedPausedMs > 0 ? { inactiveSeconds: unreportedPausedMs / 1000 } : {}
+        }
+      };
+    })();
+    return activity.finishInFlight;
+  }
+  function assertValidRunId(options) {
+    if (options?.runId !== undefined && !isValidUUID(options.runId)) {
+      throw new Error(`startActivity: \`runId\` must be a UUID (received \`${JSON.stringify(options.runId)}\`). Use crypto.randomUUID() or persist a previously-generated UUID.`);
+    }
+  }
+  function beginActivity(rawMetadata, options, owner) {
+    const metadata = jsonProjection(rawMetadata);
+    cleanupListeners();
+    const now = Date.now();
+    const runId = owner.kind === "assessment" ? owner.attemptId : options?.runId ?? adoptResumedRunId() ?? crypto.randomUUID();
+    const heartbeatIntervalMs = normalizeDelayMs(options?.heartbeatIntervalMs, DEFAULT_HEARTBEAT_INTERVAL_MS, false);
+    const pausedHeartbeatTimeoutMs = normalizeDelayMs(options?.pausedHeartbeatTimeoutMs ?? options?.hiddenTimeoutMs, DEFAULT_PAUSED_HEARTBEAT_TIMEOUT_MS, false);
+    const inactivityTimeoutMs = normalizeDelayMs(options?.inactivityTimeoutMs, DEFAULT_INACTIVITY_TIMEOUT_MS, false);
+    currentActivity = {
+      runId,
+      resumeId: crypto.randomUUID(),
+      owner,
+      startTime: now,
+      metadata,
+      pausedTime: 0,
+      pauseStartTime: null,
+      pauseReasons: new Set,
+      pausedHeartbeatTimeoutId: null,
+      pausedHeartbeatTimedOut: false,
+      pausedHeartbeatTimeoutMs,
+      windowStartTime: now,
+      windowPausedAtStart: 0,
+      heartbeatIntervalId: null,
+      heartbeatIntervalMs,
+      inactivityTimeoutId: null,
+      inactivityTimeoutMs,
+      inactivityTimerStartedAt: null,
+      remainingInactivityMs: inactivityTimeoutMs,
+      flushInFlight: null,
+      finishInFlight: null,
+      totalPersistedActiveMs: 0,
+      totalPersistedPausedMs: 0
+    };
+    if (typeof document !== "undefined") {
+      boundVisibilityHandler = handleVisibilityChange;
+      document.addEventListener("visibilitychange", boundVisibilityHandler);
+      boundUserInteractionHandler = handleUserInteraction;
+      for (const eventName of USER_ACTIVITY_EVENTS) {
+        document.addEventListener(eventName, boundUserInteractionHandler, USER_ACTIVITY_LISTENER_OPTIONS);
+      }
+      if (document.visibilityState === "hidden") {
+        handleVisibilityChange();
+      }
+    }
+    startHeartbeatInterval(currentActivity);
+    startRelayInterval();
+    if (typeof globalThis.window !== "undefined") {
+      boundPageHideHandler = handlePageHide;
+      globalThis.window.addEventListener("pagehide", boundPageHideHandler);
+    }
+    boundShellPauseHandler = handleShellPause;
+    boundShellResumeHandler = handleShellResume;
+    messaging.listen("PLAYCADEMY_PAUSE" /* PAUSE */, boundShellPauseHandler);
+    messaging.listen("PLAYCADEMY_RESUME" /* RESUME */, boundShellResumeHandler);
+    syncInactivityTracking();
+    if (relaysToParent()) {
+      messaging.send("PLAYCADEMY_TIMEBACK_ACTIVITY_START" /* TIMEBACK_ACTIVITY_START */, {
+        runId,
+        resumeId: currentActivity.resumeId,
+        activityData: metadata
+      });
+    }
+    return { runId };
+  }
   return {
     currentRunId() {
       return currentActivity?.runId;
@@ -2048,74 +2175,40 @@ function createTimebackActivityTracker(client) {
     isActivityManuallyPaused() {
       return currentActivity?.pauseReasons.has("manual") ?? false;
     },
-    startActivity(rawMetadata, options) {
-      if (hasLiveSession(client)) {
+    startActivity(rawMetadata, options, owner = { kind: "activity" }) {
+      const availability = clockAvailability(owner);
+      if (typeof availability === "object" && availability.unavailable === "embedded-child") {
         throw new PlaycademyError("startActivity() is unavailable while an embedded child session is live: the child owns the clock, and a second clock would double-count the lesson. Await the session's finished (or close() it) first.");
       }
-      if (options?.runId !== undefined && !isValidUUID(options.runId)) {
-        throw new Error(`startActivity: \`runId\` must be a UUID (received \`${JSON.stringify(options.runId)}\`). Use crypto.randomUUID() or persist a previously-generated UUID.`);
+      assertValidRunId(options);
+      if (availability === "held-by-this-owner") {
+        return { runId: currentActivity.runId };
       }
-      const metadata = jsonProjection(rawMetadata);
-      cleanupListeners();
-      const now = Date.now();
-      const resumedRunId = adoptResumedRunId();
-      const runId = options?.runId ?? resumedRunId ?? crypto.randomUUID();
-      const heartbeatIntervalMs = normalizeDelayMs(options?.heartbeatIntervalMs, DEFAULT_HEARTBEAT_INTERVAL_MS, false);
-      const pausedHeartbeatTimeoutMs = normalizeDelayMs(options?.pausedHeartbeatTimeoutMs ?? options?.hiddenTimeoutMs, DEFAULT_PAUSED_HEARTBEAT_TIMEOUT_MS, false);
-      const inactivityTimeoutMs = normalizeDelayMs(options?.inactivityTimeoutMs, DEFAULT_INACTIVITY_TIMEOUT_MS, false);
-      currentActivity = {
-        runId,
-        resumeId: crypto.randomUUID(),
-        startTime: now,
-        metadata,
-        pausedTime: 0,
-        pauseStartTime: null,
-        pauseReasons: new Set,
-        pausedHeartbeatTimeoutId: null,
-        pausedHeartbeatTimedOut: false,
-        pausedHeartbeatTimeoutMs,
-        windowStartTime: now,
-        windowPausedAtStart: 0,
-        heartbeatIntervalId: null,
-        heartbeatIntervalMs,
-        inactivityTimeoutId: null,
-        inactivityTimeoutMs,
-        inactivityTimerStartedAt: null,
-        remainingInactivityMs: inactivityTimeoutMs,
-        flushInFlight: null,
-        totalPersistedActiveMs: 0,
-        totalPersistedPausedMs: 0
-      };
-      if (typeof document !== "undefined") {
-        boundVisibilityHandler = handleVisibilityChange;
-        document.addEventListener("visibilitychange", boundVisibilityHandler);
-        boundUserInteractionHandler = handleUserInteraction;
-        for (const eventName of USER_ACTIVITY_EVENTS) {
-          document.addEventListener(eventName, boundUserInteractionHandler, USER_ACTIVITY_LISTENER_OPTIONS);
-        }
-        if (document.visibilityState === "hidden") {
-          handleVisibilityChange();
+      if (typeof availability === "object") {
+        if (owner.kind === "assessment") {
+          throw new Error(`Cannot track assessment ${owner.attemptId} while activity run ${availability.runId} is active. End the current activity first.`);
         }
+        const blockingAssessment = availability;
+        throw new Error(`Cannot start an activity while assessment ${blockingAssessment.attemptId} is in progress. Submit the assessment first.`);
       }
-      startHeartbeatInterval(currentActivity);
-      startRelayInterval();
-      if (typeof globalThis.window !== "undefined") {
-        boundPageHideHandler = handlePageHide;
-        globalThis.window.addEventListener("pagehide", boundPageHideHandler);
-      }
-      boundShellPauseHandler = handleShellPause;
-      boundShellResumeHandler = handleShellResume;
-      messaging.listen("PLAYCADEMY_PAUSE" /* PAUSE */, boundShellPauseHandler);
-      messaging.listen("PLAYCADEMY_RESUME" /* RESUME */, boundShellResumeHandler);
-      syncInactivityTracking();
-      if (relaysToParent()) {
-        messaging.send("PLAYCADEMY_TIMEBACK_ACTIVITY_START" /* TIMEBACK_ACTIVITY_START */, {
-          runId,
-          resumeId: currentActivity.resumeId,
-          activityData: metadata
-        });
+      return beginActivity(rawMetadata, options, owner);
+    },
+    tryStartAssessmentTracking(metadata, attemptId) {
+      if (!isValidUUID(attemptId)) {
+        return { status: "untrackable", reason: "invalid-attempt-id" };
+      }
+      const owner = { kind: "assessment", attemptId };
+      const availability = clockAvailability(owner);
+      if (typeof availability === "object") {
+        return { status: "unavailable", reason: availability.unavailable };
       }
-      return { runId };
+      if (availability === "held-by-this-owner") {
+        return { status: "already-attached", runId: currentActivity.runId };
+      }
+      return {
+        status: "attached",
+        runId: beginActivity(metadata, { runId: attemptId }, owner).runId
+      };
     },
     pauseActivity() {
       if (!currentActivity) {
@@ -2138,47 +2231,40 @@ function createTimebackActivityTracker(client) {
       }
       removePauseReason("manual");
     },
+    async finishAssessmentTracking(expectedAttemptId) {
+      if (!currentActivity || currentActivity.owner.kind !== "assessment" || currentActivity.owner.attemptId !== expectedAttemptId) {
+        return;
+      }
+      return finishCurrentActivity(true);
+    },
     async endActivity(rawData) {
       if (!currentActivity) {
         throw new Error("No activity in progress. Call startActivity() before endActivity().");
       }
+      if (currentActivity.owner.kind === "assessment") {
+        throw new Error(`endActivity() cannot finalize assessment ${currentActivity.owner.attemptId}. Submit it with timeback.assessments.submit() instead.`);
+      }
       const data = jsonProjection(rawData);
       if (!relaysToParent() && typeof data.xpAwarded !== "number") {
         throw new Error("endActivity() requires xpAwarded when reporting directly. It is optional only in child mode, where the parent game decides the award.");
       }
-      const activity = currentActivity;
-      applyOverdueInactivity();
-      cleanupListeners();
-      await flushHeartbeat(true);
-      if (activity.pauseStartTime !== null) {
-        activity.pausedTime += Date.now() - activity.pauseStartTime;
-        activity.pauseStartTime = null;
-      }
-      const endTime = Date.now();
-      const totalElapsed = endTime - activity.startTime;
-      const activeTime = Math.max(0, totalElapsed - activity.pausedTime);
-      const durationSeconds = Math.floor(activeTime / 1000);
-      const unreportedActiveMs = Math.max(0, activeTime - activity.totalPersistedActiveMs);
-      const unreportedPausedMs = Math.max(0, activity.pausedTime - activity.totalPersistedPausedMs);
       const { correctQuestions, totalQuestions } = data;
       if (data.masteredUnits !== undefined && data.masteredUnitsAbsolute !== undefined) {
         throw new Error("Cannot provide both masteredUnits and masteredUnitsAbsolute — use one or the other");
       }
+      const tracking = await finishCurrentActivity(false);
       const request = {
-        runId: activity.runId,
-        resumeId: activity.resumeId,
-        activityData: activity.metadata,
+        runId: tracking.runId,
+        resumeId: tracking.resumeId,
+        activityData: tracking.activityData,
         scoreData: {
           correctQuestions,
           totalQuestions
         },
         timingData: {
-          durationSeconds
-        },
-        sessionTimingData: {
-          activeSeconds: unreportedActiveMs / 1000,
-          ...unreportedPausedMs > 0 ? { inactiveSeconds: unreportedPausedMs / 1000 } : {}
+          durationSeconds: tracking.durationSeconds
         },
+        sessionTimingData: tracking.sessionTimingData,
         xpEarned: data.xpAwarded,
         masteredUnits: data.masteredUnits,
         masteredUnitsAbsolute: data.masteredUnitsAbsolute,
@@ -2186,23 +2272,9 @@ function createTimebackActivityTracker(client) {
       };
       if (relaysToParent()) {
         messaging.send("PLAYCADEMY_TIMEBACK_ACTIVITY_END" /* TIMEBACK_ACTIVITY_END */, request);
-        if (currentActivity === activity) {
-          currentActivity = null;
-        }
-        return { status: "relayed", runId: activity.runId };
-      }
-      try {
-        const response = await client["requestGameBackend"](TIMEBACK_ROUTES.END_ACTIVITY, "POST", request, undefined, { retryPolicy: END_ACTIVITY_RETRY_POLICY });
-        if (currentActivity === activity) {
-          currentActivity = null;
-        }
-        return response;
-      } catch (error) {
-        if (currentActivity === activity) {
-          currentActivity = null;
-        }
-        throw error;
+        return { status: "relayed", runId: tracking.runId };
       }
+      return client["requestGameBackend"](TIMEBACK_ROUTES.END_ACTIVITY, "POST", request, undefined, { retryPolicy: END_ACTIVITY_RETRY_POLICY });
     }
   };
 }
@@ -2935,8 +3007,10 @@ function createTimebackEngine(client) {
       currentRunId: activityTracker.currentRunId,
       isManuallyPaused: activityTracker.isActivityManuallyPaused,
       start: activityTracker.startActivity,
+      tryStartAssessment: activityTracker.tryStartAssessmentTracking,
       pause: activityTracker.pauseActivity,
       resume: activityTracker.resumeActivity,
+      finishAssessment: activityTracker.finishAssessmentTracking,
       end: activityTracker.endActivity
     },
     course: {
@@ -2963,6 +3037,7 @@ function createTimebackEngine(client) {
 var VALID_XP_INCLUDE_OPTIONS = ["perCourse", "today"];
 var VALID_MASTERY_INCLUDE_OPTIONS = ["perCourse"];
 var ASSESSMENTS_ROUTE = TIMEBACK_ROUTES.ASSESSMENTS;
+var ASSESSMENT_SUBMIT_RETRY_POLICY = END_ACTIVITY_RETRY_POLICY;
 function validateAssessmentFilters(options) {
   if (!isAssessmentPurpose(options?.purpose)) {
     throw new Error("purpose must be end_of_course, diagnostic, review, or mastery");
@@ -2987,6 +3062,85 @@ function validateAssessmentFilters(options) {
 }
 function createTimebackNamespace(client) {
   const engine = createTimebackEngine(client);
+  const pendingAssessmentSubmissions = new Map;
+  const warnedAssessmentTrackingSkips = new Map;
+  function clearAssessmentTrackingWarnings(attemptId) {
+    warnedAssessmentTrackingSkips.delete(attemptId);
+  }
+  function warnAssessmentTrackingSkipped(attemptId, reason) {
+    const warnedReasons = warnedAssessmentTrackingSkips.get(attemptId) ?? new Set;
+    if (warnedReasons.has(reason)) {
+      return;
+    }
+    warnedReasons.add(reason);
+    warnedAssessmentTrackingSkips.set(attemptId, warnedReasons);
+    const remedy = reason === "invalid-attempt-id" ? "The canonical attempt remains usable and submittable, but this sitting cannot be timed. Report the malformed id." : "The canonical attempt remains available; release the current clock owner, then call timeback.assessments.get(attemptId) to retry tracking.";
+    console.warn(`[Playcademy SDK] timeback.assessments: active-time tracking was not attached to assessment ${attemptId} (${reason}). ${remedy}`);
+  }
+  function releasePendingSubmission(attemptId, submissionId) {
+    if (pendingAssessmentSubmissions.get(attemptId)?.submissionId === submissionId) {
+      pendingAssessmentSubmissions.delete(attemptId);
+    }
+  }
+  function loadAttemptSnapshot(attemptId) {
+    return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/${encodeURIComponent(attemptId)}`, "GET");
+  }
+  async function syncAssessmentTracking(snapshot) {
+    if (pendingAssessmentSubmissions.has(snapshot.attemptId)) {
+      return snapshot;
+    }
+    if (snapshot.status === "completed") {
+      await engine.activity.finishAssessment(snapshot.attemptId);
+      clearAssessmentTrackingWarnings(snapshot.attemptId);
+      return snapshot;
+    }
+    if (!snapshot.activityData) {
+      return snapshot;
+    }
+    const attachment = engine.activity.tryStartAssessment(snapshot.activityData, snapshot.attemptId);
+    if (attachment.status === "unavailable" || attachment.status === "untrackable") {
+      warnAssessmentTrackingSkipped(snapshot.attemptId, attachment.reason);
+    } else {
+      clearAssessmentTrackingWarnings(snapshot.attemptId);
+    }
+    return snapshot;
+  }
+  async function resumeAfterDefinitiveFailure(attemptId, submissionId) {
+    if (pendingAssessmentSubmissions.get(attemptId)?.submissionId !== submissionId) {
+      return;
+    }
+    pendingAssessmentSubmissions.delete(attemptId);
+    try {
+      await syncAssessmentTracking(await loadAttemptSnapshot(attemptId));
+    } catch {}
+  }
+  async function assessmentSubmissionContext(attemptId, submissionId) {
+    const pending = pendingAssessmentSubmissions.get(attemptId);
+    if (pending) {
+      if (pending.submissionId !== submissionId && !pending.detached) {
+        throw new Error(`Assessment ${attemptId} already has a pending submission. Retry with the original submissionId.`);
+      }
+      pending.detached = false;
+      return {
+        submissionId: pending.submissionId,
+        session: await pending.session
+      };
+    }
+    const session = engine.activity.finishAssessment(attemptId).then((finished) => finished ? {
+      runId: finished.runId,
+      resumeId: finished.resumeId,
+      ...finished.sessionTimingData
+    } : undefined).catch((error) => {
+      releasePendingSubmission(attemptId, submissionId);
+      throw error;
+    });
+    pendingAssessmentSubmissions.set(attemptId, {
+      submissionId,
+      session,
+      detached: false
+    });
+    return { submissionId, session: await session };
+  }
   registerPauseProbe(client, () => engine.activity.isManuallyPaused());
   return {
     assessments: {
@@ -3015,7 +3169,8 @@ function createTimebackNamespace(client) {
             throw new Error(`itemsPerStandard must be a positive integer at most ${TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.itemsPerStandard}`);
           }
         }
-        return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/start`, "POST", input);
+        const snapshot = await client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/start`, "POST", input);
+        return syncAssessmentTracking(snapshot);
       },
       latest: async (options) => {
         assertPlatformMode(client, "timeback.assessments.latest()");
@@ -3038,7 +3193,20 @@ function createTimebackNamespace(client) {
         if (!attemptId?.trim()) {
           throw new Error("attemptId is required");
         }
-        return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/${encodeURIComponent(attemptId)}`, "GET");
+        return syncAssessmentTracking(await loadAttemptSnapshot(attemptId));
+      },
+      stop: async (attemptId) => {
+        assertPlatformMode(client, "timeback.assessments.stop()");
+        if (!attemptId?.trim()) {
+          throw new Error("attemptId is required");
+        }
+        const pending = pendingAssessmentSubmissions.get(attemptId);
+        if (pending) {
+          pending.detached = true;
+        }
+        await engine.activity.finishAssessment(attemptId);
+        clearAssessmentTrackingWarnings(attemptId);
+        return { attemptId };
       },
       save: async (attemptId, input) => {
         assertPlatformMode(client, "timeback.assessments.save()");
@@ -3077,7 +3245,25 @@ function createTimebackNamespace(client) {
         if (!input.submissionId?.trim()) {
           throw new Error("submissionId is required");
         }
-        return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/${encodeURIComponent(attemptId)}/submit`, "POST", input);
+        const { expectedResponseVersion } = input;
+        const { submissionId, session } = await assessmentSubmissionContext(attemptId, input.submissionId);
+        const request = {
+          expectedResponseVersion,
+          submissionId,
+          ...session ? { session } : {}
+        };
+        try {
+          const result = await client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/${encodeURIComponent(attemptId)}/submit`, "POST", request, undefined, { retryPolicy: ASSESSMENT_SUBMIT_RETRY_POLICY });
+          releasePendingSubmission(attemptId, submissionId);
+          await engine.activity.finishAssessment(attemptId);
+          clearAssessmentTrackingWarnings(attemptId);
+          return result;
+        } catch (error) {
+          if (error instanceof ApiError && !error.isRetryable()) {
+            await resumeAfterDefinitiveFailure(attemptId, submissionId);
+          }
+          throw error;
+        }
       }
     },
     get user() {
@@ -3484,7 +3670,7 @@ async function request({
   return rawText && rawText.length > 0 ? rawText : undefined;
 }
 // src/version.ts
-var SDK_VERSION = "0.16.1-beta.13";
+var SDK_VERSION = "0.16.1-beta.15";
 
 // src/clients/base.ts
 class PlaycademyBaseClient {

package/dist/internal.d.ts

@@ -3489,6 +3489,19 @@ interface DashboardThemeConfig {
     /** Secondary/accent color as a hex string, e.g. '#ffd166' */
     secondary?: string;
 }
+/**
+ * Child-catalog contract generation (see @playcademy/sdk/contracts).
+ * The extractor is a repo-local script (run with the CLI's runtime) that
+ * prints `{ generatedFrom, deliveries }` as JSON on stdout; the CLI
+ * validates, stamps the contract fields, and writes
+ * `.playcademy/catalog.json` deterministically. The document carries no
+ * app identity — consuming repos assign the namespace key from sync
+ * provenance.
+ */
+interface CatalogConfig {
+    /** Path to the extractor script, relative to the config file. */
+    extractor: string;
+}
 /**
  * Unified Playcademy configuration
  * Used for playcademy.config.{js,json}
@@ -3521,6 +3534,8 @@ interface PlaycademyConfig {
     dashboard?: DashboardConfig | boolean;
     /** Integrations (database, custom routes, external services) */
     integrations?: IntegrationsConfig;
+    /** Child-catalog contract generation (`playcademy catalog`) */
+    catalog?: CatalogConfig;
 }
 
 /**

package/dist/internal.js

@@ -1730,6 +1730,29 @@ function createTimebackActivityTracker(client) {
     const resumeRunId = client["initPayload"]?.parent?.resumeRunId;
     return typeof resumeRunId === "string" && isValidUUID(resumeRunId) ? resumeRunId : undefined;
   }
+  function clockAvailability(owner) {
+    if (owner.kind === "assessment" && currentActivity?.owner.kind === "assessment" && currentActivity.owner.attemptId === owner.attemptId) {
+      return "held-by-this-owner";
+    }
+    if (hasLiveSession(client)) {
+      return { unavailable: "embedded-child" };
+    }
+    if (!currentActivity) {
+      return "available";
+    }
+    if (owner.kind === "activity") {
+      return currentActivity.owner.kind === "assessment" ? {
+        unavailable: "other-assessment",
+        runId: currentActivity.runId,
+        attemptId: currentActivity.owner.attemptId
+      } : "available";
+    }
+    return currentActivity.owner.kind === "assessment" ? {
+      unavailable: "other-assessment",
+      runId: currentActivity.runId,
+      attemptId: currentActivity.owner.attemptId
+    } : { unavailable: "ordinary-activity", runId: currentActivity.runId };
+  }
   function startHeartbeatInterval(activity) {
     if (activity.heartbeatIntervalMs === Infinity || activity.heartbeatIntervalId !== null) {
       return;
@@ -2041,6 +2064,110 @@ function createTimebackActivityTracker(client) {
     }
     stopRelayInterval();
   }
+  async function finishCurrentActivity(discardRelayedTiming) {
+    const activity = currentActivity;
+    if (activity.finishInFlight) {
+      return activity.finishInFlight;
+    }
+    activity.finishInFlight = (async () => {
+      applyOverdueInactivity();
+      cleanupListeners();
+      const relayedWithoutReconciliation = discardRelayedTiming && relaysToParent();
+      await flushHeartbeat(true);
+      if (activity.pauseStartTime !== null) {
+        activity.pausedTime += Date.now() - activity.pauseStartTime;
+        activity.pauseStartTime = null;
+      }
+      const endTime = Date.now();
+      const totalElapsed = endTime - activity.startTime;
+      const activeTime = Math.max(0, totalElapsed - activity.pausedTime);
+      const unreportedActiveMs = Math.max(0, activeTime - activity.totalPersistedActiveMs);
+      const unreportedPausedMs = Math.max(0, activity.pausedTime - activity.totalPersistedPausedMs);
+      if (currentActivity === activity) {
+        currentActivity = null;
+      }
+      return {
+        runId: activity.runId,
+        resumeId: activity.resumeId,
+        activityData: activity.metadata,
+        durationSeconds: Math.floor(activeTime / 1000),
+        sessionTimingData: relayedWithoutReconciliation ? { activeSeconds: 0 } : {
+          activeSeconds: unreportedActiveMs / 1000,
+          ...unreportedPausedMs > 0 ? { inactiveSeconds: unreportedPausedMs / 1000 } : {}
+        }
+      };
+    })();
+    return activity.finishInFlight;
+  }
+  function assertValidRunId(options) {
+    if (options?.runId !== undefined && !isValidUUID(options.runId)) {
+      throw new Error(`startActivity: \`runId\` must be a UUID (received \`${JSON.stringify(options.runId)}\`). Use crypto.randomUUID() or persist a previously-generated UUID.`);
+    }
+  }
+  function beginActivity(rawMetadata, options, owner) {
+    const metadata = jsonProjection(rawMetadata);
+    cleanupListeners();
+    const now = Date.now();
+    const runId = owner.kind === "assessment" ? owner.attemptId : options?.runId ?? adoptResumedRunId() ?? crypto.randomUUID();
+    const heartbeatIntervalMs = normalizeDelayMs(options?.heartbeatIntervalMs, DEFAULT_HEARTBEAT_INTERVAL_MS, false);
+    const pausedHeartbeatTimeoutMs = normalizeDelayMs(options?.pausedHeartbeatTimeoutMs ?? options?.hiddenTimeoutMs, DEFAULT_PAUSED_HEARTBEAT_TIMEOUT_MS, false);
+    const inactivityTimeoutMs = normalizeDelayMs(options?.inactivityTimeoutMs, DEFAULT_INACTIVITY_TIMEOUT_MS, false);
+    currentActivity = {
+      runId,
+      resumeId: crypto.randomUUID(),
+      owner,
+      startTime: now,
+      metadata,
+      pausedTime: 0,
+      pauseStartTime: null,
+      pauseReasons: new Set,
+      pausedHeartbeatTimeoutId: null,
+      pausedHeartbeatTimedOut: false,
+      pausedHeartbeatTimeoutMs,
+      windowStartTime: now,
+      windowPausedAtStart: 0,
+      heartbeatIntervalId: null,
+      heartbeatIntervalMs,
+      inactivityTimeoutId: null,
+      inactivityTimeoutMs,
+      inactivityTimerStartedAt: null,
+      remainingInactivityMs: inactivityTimeoutMs,
+      flushInFlight: null,
+      finishInFlight: null,
+      totalPersistedActiveMs: 0,
+      totalPersistedPausedMs: 0
+    };
+    if (typeof document !== "undefined") {
+      boundVisibilityHandler = handleVisibilityChange;
+      document.addEventListener("visibilitychange", boundVisibilityHandler);
+      boundUserInteractionHandler = handleUserInteraction;
+      for (const eventName of USER_ACTIVITY_EVENTS) {
+        document.addEventListener(eventName, boundUserInteractionHandler, USER_ACTIVITY_LISTENER_OPTIONS);
+      }
+      if (document.visibilityState === "hidden") {
+        handleVisibilityChange();
+      }
+    }
+    startHeartbeatInterval(currentActivity);
+    startRelayInterval();
+    if (typeof globalThis.window !== "undefined") {
+      boundPageHideHandler = handlePageHide;
+      globalThis.window.addEventListener("pagehide", boundPageHideHandler);
+    }
+    boundShellPauseHandler = handleShellPause;
+    boundShellResumeHandler = handleShellResume;
+    messaging.listen("PLAYCADEMY_PAUSE" /* PAUSE */, boundShellPauseHandler);
+    messaging.listen("PLAYCADEMY_RESUME" /* RESUME */, boundShellResumeHandler);
+    syncInactivityTracking();
+    if (relaysToParent()) {
+      messaging.send("PLAYCADEMY_TIMEBACK_ACTIVITY_START" /* TIMEBACK_ACTIVITY_START */, {
+        runId,
+        resumeId: currentActivity.resumeId,
+        activityData: metadata
+      });
+    }
+    return { runId };
+  }
   return {
     currentRunId() {
       return currentActivity?.runId;
@@ -2048,74 +2175,40 @@ function createTimebackActivityTracker(client) {
     isActivityManuallyPaused() {
       return currentActivity?.pauseReasons.has("manual") ?? false;
     },
-    startActivity(rawMetadata, options) {
-      if (hasLiveSession(client)) {
+    startActivity(rawMetadata, options, owner = { kind: "activity" }) {
+      const availability = clockAvailability(owner);
+      if (typeof availability === "object" && availability.unavailable === "embedded-child") {
         throw new PlaycademyError("startActivity() is unavailable while an embedded child session is live: the child owns the clock, and a second clock would double-count the lesson. Await the session's finished (or close() it) first.");
       }
-      if (options?.runId !== undefined && !isValidUUID(options.runId)) {
-        throw new Error(`startActivity: \`runId\` must be a UUID (received \`${JSON.stringify(options.runId)}\`). Use crypto.randomUUID() or persist a previously-generated UUID.`);
+      assertValidRunId(options);
+      if (availability === "held-by-this-owner") {
+        return { runId: currentActivity.runId };
       }
-      const metadata = jsonProjection(rawMetadata);
-      cleanupListeners();
-      const now = Date.now();
-      const resumedRunId = adoptResumedRunId();
-      const runId = options?.runId ?? resumedRunId ?? crypto.randomUUID();
-      const heartbeatIntervalMs = normalizeDelayMs(options?.heartbeatIntervalMs, DEFAULT_HEARTBEAT_INTERVAL_MS, false);
-      const pausedHeartbeatTimeoutMs = normalizeDelayMs(options?.pausedHeartbeatTimeoutMs ?? options?.hiddenTimeoutMs, DEFAULT_PAUSED_HEARTBEAT_TIMEOUT_MS, false);
-      const inactivityTimeoutMs = normalizeDelayMs(options?.inactivityTimeoutMs, DEFAULT_INACTIVITY_TIMEOUT_MS, false);
-      currentActivity = {
-        runId,
-        resumeId: crypto.randomUUID(),
-        startTime: now,
-        metadata,
-        pausedTime: 0,
-        pauseStartTime: null,
-        pauseReasons: new Set,
-        pausedHeartbeatTimeoutId: null,
-        pausedHeartbeatTimedOut: false,
-        pausedHeartbeatTimeoutMs,
-        windowStartTime: now,
-        windowPausedAtStart: 0,
-        heartbeatIntervalId: null,
-        heartbeatIntervalMs,
-        inactivityTimeoutId: null,
-        inactivityTimeoutMs,
-        inactivityTimerStartedAt: null,
-        remainingInactivityMs: inactivityTimeoutMs,
-        flushInFlight: null,
-        totalPersistedActiveMs: 0,
-        totalPersistedPausedMs: 0
-      };
-      if (typeof document !== "undefined") {
-        boundVisibilityHandler = handleVisibilityChange;
-        document.addEventListener("visibilitychange", boundVisibilityHandler);
-        boundUserInteractionHandler = handleUserInteraction;
-        for (const eventName of USER_ACTIVITY_EVENTS) {
-          document.addEventListener(eventName, boundUserInteractionHandler, USER_ACTIVITY_LISTENER_OPTIONS);
-        }
-        if (document.visibilityState === "hidden") {
-          handleVisibilityChange();
+      if (typeof availability === "object") {
+        if (owner.kind === "assessment") {
+          throw new Error(`Cannot track assessment ${owner.attemptId} while activity run ${availability.runId} is active. End the current activity first.`);
         }
+        const blockingAssessment = availability;
+        throw new Error(`Cannot start an activity while assessment ${blockingAssessment.attemptId} is in progress. Submit the assessment first.`);
       }
-      startHeartbeatInterval(currentActivity);
-      startRelayInterval();
-      if (typeof globalThis.window !== "undefined") {
-        boundPageHideHandler = handlePageHide;
-        globalThis.window.addEventListener("pagehide", boundPageHideHandler);
+      return beginActivity(rawMetadata, options, owner);
+    },
+    tryStartAssessmentTracking(metadata, attemptId) {
+      if (!isValidUUID(attemptId)) {
+        return { status: "untrackable", reason: "invalid-attempt-id" };
       }
-      boundShellPauseHandler = handleShellPause;
-      boundShellResumeHandler = handleShellResume;
-      messaging.listen("PLAYCADEMY_PAUSE" /* PAUSE */, boundShellPauseHandler);
-      messaging.listen("PLAYCADEMY_RESUME" /* RESUME */, boundShellResumeHandler);
-      syncInactivityTracking();
-      if (relaysToParent()) {
-        messaging.send("PLAYCADEMY_TIMEBACK_ACTIVITY_START" /* TIMEBACK_ACTIVITY_START */, {
-          runId,
-          resumeId: currentActivity.resumeId,
-          activityData: metadata
-        });
+      const owner = { kind: "assessment", attemptId };
+      const availability = clockAvailability(owner);
+      if (typeof availability === "object") {
+        return { status: "unavailable", reason: availability.unavailable };
+      }
+      if (availability === "held-by-this-owner") {
+        return { status: "already-attached", runId: currentActivity.runId };
       }
-      return { runId };
+      return {
+        status: "attached",
+        runId: beginActivity(metadata, { runId: attemptId }, owner).runId
+      };
     },
     pauseActivity() {
       if (!currentActivity) {
@@ -2138,47 +2231,40 @@ function createTimebackActivityTracker(client) {
       }
       removePauseReason("manual");
     },
+    async finishAssessmentTracking(expectedAttemptId) {
+      if (!currentActivity || currentActivity.owner.kind !== "assessment" || currentActivity.owner.attemptId !== expectedAttemptId) {
+        return;
+      }
+      return finishCurrentActivity(true);
+    },
     async endActivity(rawData) {
       if (!currentActivity) {
         throw new Error("No activity in progress. Call startActivity() before endActivity().");
       }
+      if (currentActivity.owner.kind === "assessment") {
+        throw new Error(`endActivity() cannot finalize assessment ${currentActivity.owner.attemptId}. Submit it with timeback.assessments.submit() instead.`);
+      }
       const data = jsonProjection(rawData);
       if (!relaysToParent() && typeof data.xpAwarded !== "number") {
         throw new Error("endActivity() requires xpAwarded when reporting directly. It is optional only in child mode, where the parent game decides the award.");
       }
-      const activity = currentActivity;
-      applyOverdueInactivity();
-      cleanupListeners();
-      await flushHeartbeat(true);
-      if (activity.pauseStartTime !== null) {
-        activity.pausedTime += Date.now() - activity.pauseStartTime;
-        activity.pauseStartTime = null;
-      }
-      const endTime = Date.now();
-      const totalElapsed = endTime - activity.startTime;
-      const activeTime = Math.max(0, totalElapsed - activity.pausedTime);
-      const durationSeconds = Math.floor(activeTime / 1000);
-      const unreportedActiveMs = Math.max(0, activeTime - activity.totalPersistedActiveMs);
-      const unreportedPausedMs = Math.max(0, activity.pausedTime - activity.totalPersistedPausedMs);
       const { correctQuestions, totalQuestions } = data;
       if (data.masteredUnits !== undefined && data.masteredUnitsAbsolute !== undefined) {
         throw new Error("Cannot provide both masteredUnits and masteredUnitsAbsolute — use one or the other");
       }
+      const tracking = await finishCurrentActivity(false);
       const request = {
-        runId: activity.runId,
-        resumeId: activity.resumeId,
-        activityData: activity.metadata,
+        runId: tracking.runId,
+        resumeId: tracking.resumeId,
+        activityData: tracking.activityData,
         scoreData: {
           correctQuestions,
           totalQuestions
         },
         timingData: {
-          durationSeconds
-        },
-        sessionTimingData: {
-          activeSeconds: unreportedActiveMs / 1000,
-          ...unreportedPausedMs > 0 ? { inactiveSeconds: unreportedPausedMs / 1000 } : {}
+          durationSeconds: tracking.durationSeconds
         },
+        sessionTimingData: tracking.sessionTimingData,
         xpEarned: data.xpAwarded,
         masteredUnits: data.masteredUnits,
         masteredUnitsAbsolute: data.masteredUnitsAbsolute,
@@ -2186,23 +2272,9 @@ function createTimebackActivityTracker(client) {
       };
       if (relaysToParent()) {
         messaging.send("PLAYCADEMY_TIMEBACK_ACTIVITY_END" /* TIMEBACK_ACTIVITY_END */, request);
-        if (currentActivity === activity) {
-          currentActivity = null;
-        }
-        return { status: "relayed", runId: activity.runId };
-      }
-      try {
-        const response = await client["requestGameBackend"](TIMEBACK_ROUTES.END_ACTIVITY, "POST", request, undefined, { retryPolicy: END_ACTIVITY_RETRY_POLICY });
-        if (currentActivity === activity) {
-          currentActivity = null;
-        }
-        return response;
-      } catch (error) {
-        if (currentActivity === activity) {
-          currentActivity = null;
-        }
-        throw error;
+        return { status: "relayed", runId: tracking.runId };
       }
+      return client["requestGameBackend"](TIMEBACK_ROUTES.END_ACTIVITY, "POST", request, undefined, { retryPolicy: END_ACTIVITY_RETRY_POLICY });
     }
   };
 }
@@ -2935,8 +3007,10 @@ function createTimebackEngine(client) {
       currentRunId: activityTracker.currentRunId,
       isManuallyPaused: activityTracker.isActivityManuallyPaused,
       start: activityTracker.startActivity,
+      tryStartAssessment: activityTracker.tryStartAssessmentTracking,
       pause: activityTracker.pauseActivity,
       resume: activityTracker.resumeActivity,
+      finishAssessment: activityTracker.finishAssessmentTracking,
       end: activityTracker.endActivity
     },
     course: {
@@ -2963,6 +3037,7 @@ function createTimebackEngine(client) {
 var VALID_XP_INCLUDE_OPTIONS = ["perCourse", "today"];
 var VALID_MASTERY_INCLUDE_OPTIONS = ["perCourse"];
 var ASSESSMENTS_ROUTE = TIMEBACK_ROUTES.ASSESSMENTS;
+var ASSESSMENT_SUBMIT_RETRY_POLICY = END_ACTIVITY_RETRY_POLICY;
 function validateAssessmentFilters(options) {
   if (!isAssessmentPurpose(options?.purpose)) {
     throw new Error("purpose must be end_of_course, diagnostic, review, or mastery");
@@ -2987,6 +3062,85 @@ function validateAssessmentFilters(options) {
 }
 function createTimebackNamespace(client) {
   const engine = createTimebackEngine(client);
+  const pendingAssessmentSubmissions = new Map;
+  const warnedAssessmentTrackingSkips = new Map;
+  function clearAssessmentTrackingWarnings(attemptId) {
+    warnedAssessmentTrackingSkips.delete(attemptId);
+  }
+  function warnAssessmentTrackingSkipped(attemptId, reason) {
+    const warnedReasons = warnedAssessmentTrackingSkips.get(attemptId) ?? new Set;
+    if (warnedReasons.has(reason)) {
+      return;
+    }
+    warnedReasons.add(reason);
+    warnedAssessmentTrackingSkips.set(attemptId, warnedReasons);
+    const remedy = reason === "invalid-attempt-id" ? "The canonical attempt remains usable and submittable, but this sitting cannot be timed. Report the malformed id." : "The canonical attempt remains available; release the current clock owner, then call timeback.assessments.get(attemptId) to retry tracking.";
+    console.warn(`[Playcademy SDK] timeback.assessments: active-time tracking was not attached to assessment ${attemptId} (${reason}). ${remedy}`);
+  }
+  function releasePendingSubmission(attemptId, submissionId) {
+    if (pendingAssessmentSubmissions.get(attemptId)?.submissionId === submissionId) {
+      pendingAssessmentSubmissions.delete(attemptId);
+    }
+  }
+  function loadAttemptSnapshot(attemptId) {
+    return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/${encodeURIComponent(attemptId)}`, "GET");
+  }
+  async function syncAssessmentTracking(snapshot) {
+    if (pendingAssessmentSubmissions.has(snapshot.attemptId)) {
+      return snapshot;
+    }
+    if (snapshot.status === "completed") {
+      await engine.activity.finishAssessment(snapshot.attemptId);
+      clearAssessmentTrackingWarnings(snapshot.attemptId);
+      return snapshot;
+    }
+    if (!snapshot.activityData) {
+      return snapshot;
+    }
+    const attachment = engine.activity.tryStartAssessment(snapshot.activityData, snapshot.attemptId);
+    if (attachment.status === "unavailable" || attachment.status === "untrackable") {
+      warnAssessmentTrackingSkipped(snapshot.attemptId, attachment.reason);
+    } else {
+      clearAssessmentTrackingWarnings(snapshot.attemptId);
+    }
+    return snapshot;
+  }
+  async function resumeAfterDefinitiveFailure(attemptId, submissionId) {
+    if (pendingAssessmentSubmissions.get(attemptId)?.submissionId !== submissionId) {
+      return;
+    }
+    pendingAssessmentSubmissions.delete(attemptId);
+    try {
+      await syncAssessmentTracking(await loadAttemptSnapshot(attemptId));
+    } catch {}
+  }
+  async function assessmentSubmissionContext(attemptId, submissionId) {
+    const pending = pendingAssessmentSubmissions.get(attemptId);
+    if (pending) {
+      if (pending.submissionId !== submissionId && !pending.detached) {
+        throw new Error(`Assessment ${attemptId} already has a pending submission. Retry with the original submissionId.`);
+      }
+      pending.detached = false;
+      return {
+        submissionId: pending.submissionId,
+        session: await pending.session
+      };
+    }
+    const session = engine.activity.finishAssessment(attemptId).then((finished) => finished ? {
+      runId: finished.runId,
+      resumeId: finished.resumeId,
+      ...finished.sessionTimingData
+    } : undefined).catch((error) => {
+      releasePendingSubmission(attemptId, submissionId);
+      throw error;
+    });
+    pendingAssessmentSubmissions.set(attemptId, {
+      submissionId,
+      session,
+      detached: false
+    });
+    return { submissionId, session: await session };
+  }
   registerPauseProbe(client, () => engine.activity.isManuallyPaused());
   return {
     assessments: {
@@ -3015,7 +3169,8 @@ function createTimebackNamespace(client) {
             throw new Error(`itemsPerStandard must be a positive integer at most ${TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.itemsPerStandard}`);
           }
         }
-        return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/start`, "POST", input);
+        const snapshot = await client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/start`, "POST", input);
+        return syncAssessmentTracking(snapshot);
       },
       latest: async (options) => {
         assertPlatformMode(client, "timeback.assessments.latest()");
@@ -3038,7 +3193,20 @@ function createTimebackNamespace(client) {
         if (!attemptId?.trim()) {
           throw new Error("attemptId is required");
         }
-        return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/${encodeURIComponent(attemptId)}`, "GET");
+        return syncAssessmentTracking(await loadAttemptSnapshot(attemptId));
+      },
+      stop: async (attemptId) => {
+        assertPlatformMode(client, "timeback.assessments.stop()");
+        if (!attemptId?.trim()) {
+          throw new Error("attemptId is required");
+        }
+        const pending = pendingAssessmentSubmissions.get(attemptId);
+        if (pending) {
+          pending.detached = true;
+        }
+        await engine.activity.finishAssessment(attemptId);
+        clearAssessmentTrackingWarnings(attemptId);
+        return { attemptId };
       },
       save: async (attemptId, input) => {
         assertPlatformMode(client, "timeback.assessments.save()");
@@ -3077,7 +3245,25 @@ function createTimebackNamespace(client) {
         if (!input.submissionId?.trim()) {
           throw new Error("submissionId is required");
         }
-        return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/${encodeURIComponent(attemptId)}/submit`, "POST", input);
+        const { expectedResponseVersion } = input;
+        const { submissionId, session } = await assessmentSubmissionContext(attemptId, input.submissionId);
+        const request = {
+          expectedResponseVersion,
+          submissionId,
+          ...session ? { session } : {}
+        };
+        try {
+          const result = await client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/${encodeURIComponent(attemptId)}/submit`, "POST", request, undefined, { retryPolicy: ASSESSMENT_SUBMIT_RETRY_POLICY });
+          releasePendingSubmission(attemptId, submissionId);
+          await engine.activity.finishAssessment(attemptId);
+          clearAssessmentTrackingWarnings(attemptId);
+          return result;
+        } catch (error) {
+          if (error instanceof ApiError && !error.isRetryable()) {
+            await resumeAfterDefinitiveFailure(attemptId, submissionId);
+          }
+          throw error;
+        }
       }
     },
     get user() {
@@ -4360,7 +4546,7 @@ async function request({
   return rawText && rawText.length > 0 ? rawText : undefined;
 }
 // src/version.ts
-var SDK_VERSION = "0.16.1-beta.13";
+var SDK_VERSION = "0.16.1-beta.15";
 
 // src/clients/base.ts
 class PlaycademyBaseClient {

package/dist/server/edge.d.ts

@@ -142,6 +142,19 @@ interface DashboardThemeConfig {
     /** Secondary/accent color as a hex string, e.g. '#ffd166' */
     secondary?: string;
 }
+/**
+ * Child-catalog contract generation (see @playcademy/sdk/contracts).
+ * The extractor is a repo-local script (run with the CLI's runtime) that
+ * prints `{ generatedFrom, deliveries }` as JSON on stdout; the CLI
+ * validates, stamps the contract fields, and writes
+ * `.playcademy/catalog.json` deterministically. The document carries no
+ * app identity — consuming repos assign the namespace key from sync
+ * provenance.
+ */
+interface CatalogConfig {
+    /** Path to the extractor script, relative to the config file. */
+    extractor: string;
+}
 /**
  * Unified Playcademy configuration
  * Used for playcademy.config.{js,json}
@@ -174,6 +187,8 @@ interface PlaycademyConfig {
     dashboard?: DashboardConfig | boolean;
     /** Integrations (database, custom routes, external services) */
     integrations?: IntegrationsConfig;
+    /** Child-catalog contract generation (`playcademy catalog`) */
+    catalog?: CatalogConfig;
 }
 
 /**
@@ -360,7 +375,7 @@ declare class PlaycademyClient {
             get: (studentId: string, attemptId: string) => Promise<_playcademy_types.AssessmentAttemptSnapshot>;
             save: (studentId: string, attemptId: string, input: _playcademy_types.SaveAssessmentInput) => Promise<_playcademy_types.AssessmentSaveResult>;
             submitItem: (studentId: string, attemptId: string, input: _playcademy_types.SubmitAssessmentItemInput) => Promise<_playcademy_types.SubmitAssessmentItemResult>;
-            submit: (studentId: string, attemptId: string, input: _playcademy_types.SubmitAssessmentInput, context: {
+            submit: (studentId: string, attemptId: string, input: _playcademy_types.SubmitAssessmentRequest, context: {
                 sensorUrl: string;
             }) => Promise<_playcademy_types.AssessmentSubmitResult>;
         };

package/dist/server/edge.js

@@ -313,7 +313,7 @@ function extractApiErrorInfo(error) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.16.1-beta.13";
+var SDK_VERSION = "0.16.1-beta.15";
 
 // src/server/request.ts
 async function makeApiRequest(opts) {

package/dist/server.d.ts

@@ -142,6 +142,19 @@ interface DashboardThemeConfig {
     /** Secondary/accent color as a hex string, e.g. '#ffd166' */
     secondary?: string;
 }
+/**
+ * Child-catalog contract generation (see @playcademy/sdk/contracts).
+ * The extractor is a repo-local script (run with the CLI's runtime) that
+ * prints `{ generatedFrom, deliveries }` as JSON on stdout; the CLI
+ * validates, stamps the contract fields, and writes
+ * `.playcademy/catalog.json` deterministically. The document carries no
+ * app identity — consuming repos assign the namespace key from sync
+ * provenance.
+ */
+interface CatalogConfig {
+    /** Path to the extractor script, relative to the config file. */
+    extractor: string;
+}
 /**
  * Unified Playcademy configuration
  * Used for playcademy.config.{js,json}
@@ -174,6 +187,8 @@ interface PlaycademyConfig {
     dashboard?: DashboardConfig | boolean;
     /** Integrations (database, custom routes, external services) */
     integrations?: IntegrationsConfig;
+    /** Child-catalog contract generation (`playcademy catalog`) */
+    catalog?: CatalogConfig;
 }
 
 /**
@@ -360,7 +375,7 @@ declare class PlaycademyClient$1 {
             get: (studentId: string, attemptId: string) => Promise<_playcademy_types.AssessmentAttemptSnapshot>;
             save: (studentId: string, attemptId: string, input: _playcademy_types.SaveAssessmentInput) => Promise<_playcademy_types.AssessmentSaveResult>;
             submitItem: (studentId: string, attemptId: string, input: _playcademy_types.SubmitAssessmentItemInput) => Promise<_playcademy_types.SubmitAssessmentItemResult>;
-            submit: (studentId: string, attemptId: string, input: _playcademy_types.SubmitAssessmentInput, context: {
+            submit: (studentId: string, attemptId: string, input: _playcademy_types.SubmitAssessmentRequest, context: {
                 sensorUrl: string;
             }) => Promise<_playcademy_types.AssessmentSubmitResult>;
         };

package/dist/server.js

@@ -502,7 +502,7 @@ function extractApiErrorInfo(error) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.16.1-beta.13";
+var SDK_VERSION = "0.16.1-beta.15";
 
 // src/server/request.ts
 async function makeApiRequest(opts) {

package/dist/types.d.ts

@@ -363,6 +363,19 @@ interface DashboardThemeConfig {
     /** Secondary/accent color as a hex string, e.g. '#ffd166' */
     secondary?: string;
 }
+/**
+ * Child-catalog contract generation (see @playcademy/sdk/contracts).
+ * The extractor is a repo-local script (run with the CLI's runtime) that
+ * prints `{ generatedFrom, deliveries }` as JSON on stdout; the CLI
+ * validates, stamps the contract fields, and writes
+ * `.playcademy/catalog.json` deterministically. The document carries no
+ * app identity — consuming repos assign the namespace key from sync
+ * provenance.
+ */
+interface CatalogConfig {
+    /** Path to the extractor script, relative to the config file. */
+    extractor: string;
+}
 /**
  * Unified Playcademy configuration
  * Used for playcademy.config.{js,json}
@@ -395,6 +408,8 @@ interface PlaycademyConfig {
     dashboard?: DashboardConfig | boolean;
     /** Integrations (database, custom routes, external services) */
     integrations?: IntegrationsConfig;
+    /** Child-catalog contract generation (`playcademy catalog`) */
+    catalog?: CatalogConfig;
 }
 
 /**
@@ -1999,6 +2014,9 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
             start: (input: _playcademy_types.StartAssessmentInput) => Promise<_playcademy_types.AssessmentAttemptSnapshot>;
             latest: (options: _playcademy_types.GetLatestAssessmentOptions) => Promise<_playcademy_types.LatestAssessmentResult | null>;
             get: (attemptId: string) => Promise<_playcademy_types.AssessmentAttemptSnapshot>;
+            stop: (attemptId: string) => Promise<{
+                attemptId: string;
+            }>;
             save: (attemptId: string, input: _playcademy_types.SaveAssessmentInput) => Promise<_playcademy_types.AssessmentSaveResult>;
             submitItem: (attemptId: string, input: _playcademy_types.SubmitAssessmentItemInput) => Promise<_playcademy_types.SubmitAssessmentItemResult>;
             submit: (attemptId: string, input: _playcademy_types.SubmitAssessmentInput) => Promise<_playcademy_types.AssessmentSubmitResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@playcademy/sdk",
-    "version": "0.16.1-beta.13",
+    "version": "0.16.1-beta.15",
     "type": "module",
     "exports": {
         ".": {
@@ -21,6 +21,12 @@
             "import": "./dist/types.js",
             "require": "./dist/types.js"
         },
+        "./contracts": {
+            "source": "./src/contracts.ts",
+            "types": "./dist/contracts.d.ts",
+            "import": "./dist/contracts.js",
+            "require": "./dist/contracts.js"
+        },
         "./internal": {
             "source": "./src/internal.ts",
             "types": "./dist/internal.d.ts",