@playcademy/sdk 0.24.0 → 0.24.1-beta.2

package/dist/internal.d.ts

@@ -81,1950 +81,1234 @@ declare const ASSESSMENT_PURPOSES: readonly ['end_of_course', 'diagnostic', 'rev
 declare const PLAYCADEMY_ASSESSMENT_CONTRACT_VERSION: 2;
 
 /**
- * User Types
+ * TimeBack Enums & Literal Types
  *
- * Enums, DTOs and API response types. Database row types are in @playcademy/data/types.
+ * Basic type definitions used throughout the TimeBack integration. Unions
+ * derive from the canonical value lists in @playcademy/constants (type-only
+ * imports, so this package ships no runtime code).
  *
- * @module types/user
+ * @module types/timeback/types
  */
 
-type UserRoleEnumType = UserRole;
-type DeveloperStatusEnumType = 'none' | 'pending' | 'approved';
-type DeveloperStatusValue = DeveloperStatusEnumType;
-type TimebackUserRole = 'administrator' | 'aide' | 'guardian' | 'parent' | 'proctor' | 'relative' | 'student' | 'teacher';
-type TimebackOrgType = 'department' | 'school' | 'district' | 'local' | 'state' | 'national';
-interface UserEnrollment {
-    gameId?: string;
-    courseId: string;
-    id?: string;
-    grade: number;
-    subject: string;
-    orgId?: string;
-}
-interface UserOrganization {
-    id: string;
-    name: string | null;
-    type: TimebackOrgType | string;
-    isPrimary: boolean;
-}
-interface TimebackStudentProfile {
-    role: TimebackUserRole;
-    organizations: UserOrganization[];
-}
 /**
- * Timeback identity on `/users/me`: who the student is, without enrollments.
- * Enrollments come from `/timeback/user` (or `client.timeback.user`).
+ * The TimeBack subject vocabulary. 'None' is canonical: TimeBack accepts it
+ * on courses and uses it as the fallback for unknown or missing subjects.
  */
-interface UserTimebackProfile extends TimebackStudentProfile {
-    id: string;
-}
-interface UserTimebackData extends UserTimebackProfile {
-    enrollments: UserEnrollment[];
-}
-type LocalDaySource = 'browser_last_seen' | 'platform_default';
-interface LocalDayContext {
-    timeZone: string;
-    source: LocalDaySource;
-    /** ISO 8601 timestamp for the last persisted timezone observation. */
-    observedAt: string | null;
-}
+type TimebackSubject = (typeof TIMEBACK_SUBJECTS)[number];
 /**
- * OpenID Connect UserInfo claims (NOT a database row).
+ * Grade levels per AE OneRoster GradeEnum.
+ * -1 = Pre-K, 0 = Kindergarten, 1-12 = Grades 1-12, 13 = AP
  */
-interface UserInfo {
-    sub: string;
-    email: string;
-    name: string | null;
-    email_verified?: boolean;
-    given_name?: string;
-    family_name?: string;
-    issuer?: string;
-    lti_roles?: unknown;
-    lti_context?: unknown;
-    lti_resource_link?: unknown;
-    timeback_id?: string;
-}
-interface DeveloperStatusResponse {
-    status: DeveloperStatusEnumType;
-}
+type TimebackGrade = (typeof TIMEBACK_GRADES)[number];
 /**
- * Authenticated user for API responses.
- * Differs from UserRow: omits timebackId, adds hasTimebackAccount and timeback.
+ * Platform pedagogy levels for a single lesson of instruction.
+ * E1 teaches, E2/E3 practice and remediate, E4 is the mastery check.
  */
-interface AuthenticatedUser {
-    id: string;
-    email: string;
-    emailVerified: boolean;
-    name: string | null;
-    image: string | null;
-    username: string | null;
-    role: UserRoleEnumType;
-    developerStatus: DeveloperStatusEnumType;
-    createdAt: Date;
-    updatedAt: Date;
-    hasTimebackAccount: boolean;
-    localDay: LocalDayContext;
-    timeback?: UserTimebackProfile;
-}
-interface GameUser {
-    id: string;
-    name: string | null;
-    role: UserRoleEnumType;
-    username: string | null;
-    email: string | null;
-    localDay: LocalDayContext;
-    timeback?: UserTimebackProfile;
-}
+type ELevel = 'E1' | 'E2' | 'E3' | 'E4';
+/**
+ * Valid Caliper subject values. The same vocabulary as OneRoster subjects.
+ */
+type CaliperSubject = (typeof TIMEBACK_SUBJECTS)[number];
+/**
+ * OneRoster organization types.
+ */
+type OrganizationType = 'department' | 'school' | 'district' | 'local' | 'state' | 'national';
+/**
+ * Lesson types for PowerPath integration.
+ */
+type LessonType = 'powerpath-100' | 'quiz' | 'test-out' | 'placement' | 'unit-test' | 'alpha-read-article' | null;
 
 /**
- * Game Types
+ * TimeBack Configuration Types
  *
- * Literal types and API DTOs. Database row types are in @playcademy/data/types.
+ * Configuration interfaces for Organization, Course, Component,
+ * Resource, and complete TimeBack setup.
  *
- * @module types/game
+ * @module types/timeback/config
  */
 
-type GameType = 'hosted' | 'external';
-type GamePlatform = 'web' | 'godot' | (string & {});
 /**
- * Game manifest file format (manifest.json).
- * Note: createdAt is a string here because it's parsed from JSON file.
+ * Organization configuration for TimeBack (user input - optionals allowed)
  */
-interface ManifestV1 {
-    version: '1';
-    platform: string;
-    createdAt: string;
-}
-interface ManifestVersions {
-    vitePlugin?: string;
-    sdk?: string;
-    cli?: string;
-    vite?: string;
-    godotSdk?: string;
-    godot?: string;
-}
-interface ManifestV2 {
-    version: '2';
-    platform: string;
-    createdAt: string;
-    gameVersion?: string;
-    versions: ManifestVersions;
-}
-type GameManifest = ManifestV1 | ManifestV2;
-/** One migration in a migrate-mode deploy payload */
-interface DeployMigration {
-    /** Journal tag, e.g. '0042_brave_hulk' */
-    tag: string;
-    /** Pre-split SQL statements (the CLI splits on drizzle statement-breakpoints) */
-    statements: string[];
-    /** sha-256 of the normalized migration SQL (sha256-v1) */
-    checksum: string;
-}
-/** Push-mode database payload: diff-generated SQL guarded by a baseline CAS */
-interface DeployDatabasePush {
-    mode: 'push';
-    /** Diff-generated DDL to execute (semicolon-separated statements) */
-    sql: string;
-    /** Stored schemaHash the diff was computed against; null only for a first deploy */
-    baselineHash: string | null;
-    /** Drizzle snapshot JSON this deploy moves the schema to */
-    nextSnapshot: unknown;
-    /** Hash of nextSnapshot, stored as the new push baseline on success */
-    nextHash: string;
-    /** Explicit consent for destructive statements (DROP TABLE, dropped columns) */
-    acceptDataLoss?: boolean;
-}
-/** Migrate-mode database payload: the client's complete migration journal */
-interface DeployDatabaseMigrate {
-    mode: 'migrate';
-    /** The full journal in order; the server applies whatever the ledger lacks */
-    migrations: DeployMigration[];
+interface OrganizationConfig {
+    /** Display name for your organization */
+    name?: string;
+    /** Organization type */
+    type?: OrganizationType;
+    /** Unique identifier (defaults to Playcademy's org) */
+    identifier?: string;
 }
 /**
- * Mode-aware database payload (PLA-217 D5). Replaces the legacy `schema`
- * field for adopted games; the server verifies state before executing.
+ * Course goals for daily student targets
  */
-type DeployDatabasePayload = DeployDatabasePush | DeployDatabaseMigrate;
-/** Journal entry in a baseline adoption block */
-interface DeployBaselineJournalEntry {
-    tag: string;
-    checksum: string;
+interface CourseGoals {
+    /** Target XP students should earn per day */
+    dailyXp?: number;
+    /** Target lessons per day */
+    dailyLessons?: number;
+    /** Target active minutes per day */
+    dailyActiveMinutes?: number;
+    /** Target accuracy percentage */
+    dailyAccuracy?: number;
+    /** Target mastered units per day */
+    dailyMasteredUnits?: number;
 }
 /**
- * Baseline adoption block (PLA-217 D7 seed-on-deploy): the client's claimed
- * starting state for a game that predates server-side deployment state.
- * Consumed by the deploy itself — an unadopted game gets its claimed ledger
- * rows, snapshot/hash, and live fingerprint recorded before the database
- * step runs; adopted games skip the block.
+ * Course metrics and totals
  */
-interface DeployBaseline {
-    lastAppliedMigrationTag?: string;
-    journal?: DeployBaselineJournalEntry[];
-    /**
-     * Per-migration snapshot deltas for content validation (D7): the
-     * seed claim is judged against the live database exactly like a
-     * manual `db baseline` claim — the side door uses the front door's
-     * checkpoint.
-     */
-    evidence?: BaselineMigrationEvidence[];
-    schemaSnapshot?: unknown;
-    schemaHash?: string;
-    integrationsHash?: string;
-    buildHash?: string;
+interface CourseMetrics {
+    /** Total XP available in the course */
+    totalXp?: number;
+    /** Total lessons/activities in the course */
+    totalLessons?: number;
+    /** Total number of grade levels covered by this course */
+    totalGrades?: number;
+    /** The type of course (e.g. 'optional', 'hole-filling', 'base') */
+    courseType?: 'base' | 'hole-filling' | 'optional' | 'Base' | 'Hole-Filling' | 'Optional';
+    /** Indicates whether the course is supplemental content */
+    isSupplemental?: boolean;
 }
 /**
- * Git provenance of the working tree a deploy was run from (PLA-294).
- *
- * Captured by the CLI at deploy time and persisted verbatim on the deploy
- * job, so "which commit is running" is answerable from the platform record.
- * Every field is nullable: a tree with no git, no remote, or a detached HEAD
- * is recorded honestly rather than refused. Recorded per deploy, never
- * pinned to the game — a fork deployed under the same slug shows the fork.
+ * Complete course metadata structure
  */
-interface DeploySource {
-    /** Normalized `https://github.com/<org>/<repo>`; null when no remote or unparseable */
-    repository: string | null;
-    /** Full 40-char SHA of HEAD; null when not in a git tree */
-    commit: string | null;
-    /** Current branch name; null on detached HEAD outside CI */
-    branch: string | null;
-    /** True when the tree had uncommitted changes — the SHA does not describe what shipped */
-    dirty: boolean;
-    /**
-     * True when the uploaded build artifact lives outside the git tree the
-     * other fields describe (`--build ~/Downloads/game.zip`). The commit is
-     * still the deployer's tree, but it may not be what produced the artifact.
-     */
-    externalBuild: boolean;
-}
-type DeployJobStatus = 'pending' | 'running' | 'succeeded' | 'failed';
-/** Active game worker state served by the deployment-state endpoint */
-interface DeploymentStateGame {
-    /** Backend bundle hash from the active deployment row */
-    codeHash: string | null;
-    /** Frontend zip hash from game_deployment_state (null when unseeded) */
-    buildHash: string | null;
-    url: string;
-    deployedAt: string;
+interface CourseMetadata {
+    /** Define the type of course and priority for the student */
+    courseType?: 'base' | 'hole-filling' | 'optional';
+    /** Boolean value to determine if a course is supplemental to a base course */
+    isSupplemental?: boolean;
+    /** Boolean value to determine if a course is custom to an individual student */
+    isCustom?: boolean;
+    /** Signals whether a course is in production with students */
+    publishStatus?: 'draft' | 'testing' | 'published' | 'deactivated';
+    /** Whether this course appears in the TimeBack catalog for teachers and parents */
+    timebackVisible?: boolean;
+    /** Who to contact when issues reported with questions */
+    contactEmail?: string;
+    /** Primary app identifier */
+    primaryApp?: string;
+    /** Learning goals for students */
+    goals?: CourseGoals;
+    /** Course metrics and totals */
+    metrics?: CourseMetrics;
+    /** Vendor-specific metadata (e.g., AlphaLearn) */
+    [key: string]: unknown;
 }
-/** Active dashboard worker state served by the deployment-state endpoint */
-interface DeploymentStateDashboard {
-    url: string;
-    deployedAt: string;
+/**
+ * Course configuration for TimeBack (user input)
+ */
+interface CourseConfig {
+    /** Allocated OneRoster sourcedId (set after creation) */
+    sourcedId?: string;
+    /** Course title (defaults to game name) */
+    title?: string;
+    /** Subjects (REQUIRED for TimeBack integration) */
+    subjects: TimebackSubject[];
+    /** Used when recording progress/sessions if not explicitly specified per event. */
+    defaultSubject?: TimebackSubject;
+    /** Grade levels (REQUIRED for TimeBack integration) */
+    grades: TimebackGrade[];
+    /** Short course code (optional, auto-generated) */
+    courseCode?: string;
+    /** Course level (auto-derived from grades) */
+    level?: 'Elementary' | 'Middle' | 'High' | 'AP' | string;
+    /** Grading system */
+    gradingScheme?: 'STANDARD';
+    /** Total XP available in this course (REQUIRED before setup) */
+    totalXp?: number | null;
+    /** Total masterable units in this course (REQUIRED before setup) */
+    masterableUnits?: number | null;
+    /** Custom Playcademy metadata */
+    metadata?: CourseMetadata;
 }
-/** Details of the last failed migration, from the failed deploy job */
-interface DeploymentStateDatabaseFailure {
-    tag: string;
-    error: string;
-    /**
-     * Set only when the failing statement is known exactly (the size
-     * preflight names the statement it measured). Execution failures are
-     * null: D1's byte offset has an unverified reference frame for the
-     * batch array form, so it is never mapped to an index.
-     */
-    statementIndex: number | null;
-    at: string;
+/**
+ * Component configuration for TimeBack (user input)
+ */
+interface ComponentConfig {
+    /** Component title (defaults to "{course.title} Activities") */
+    title?: string;
+    /** Display order */
+    sortOrder?: number;
+    /** Required prior components */
+    prerequisites?: string[];
+    /** How prerequisites work */
+    prerequisiteCriteria?: 'ALL' | 'ANY';
 }
-/** A ledger entry from the game database's applied-migrations ledger */
-interface DeploymentStateAppliedMigration {
-    tag: string;
-    /** Checksum recorded at apply time (normalized SQL, see checksumAlgo) */
-    checksum: string;
-    /** Hash algorithm the checksum was recorded under (e.g. 'sha256-v1') */
-    checksumAlgo: string;
+/**
+ * Playcademy-specific resource extensions
+ */
+interface PlaycademyResourceMetadata {
+    /** Mastery configuration for tracking discrete learning units */
+    mastery?: {
+        /** Total number of masterable units in the resource */
+        masterableUnits: number;
+        /** Type of mastery unit for semantic clarity */
+        unitType?: 'level' | 'rank' | 'skill' | 'module';
+    };
 }
-/** Database schema state served by the deployment-state endpoint */
-interface DeploymentStateDatabase {
-    /** Applied migrations from the live in-D1 ledger (null when the game has no database) */
-    appliedMigrations: DeploymentStateAppliedMigration[] | null;
-    lastFailure: DeploymentStateDatabaseFailure | null;
-    /** Hash of the drizzle snapshot (push-mode baseline) */
-    schemaHash: string | null;
-    /** Hash of the normalized live sqlite_master */
-    schemaFingerprint: string | null;
-    /**
-     * Stored drizzle snapshot (push-mode diffing only). Present only when
-     * the request asked for it with `?include=schemaSnapshot` (D4).
-     */
-    schemaSnapshot?: unknown;
+/**
+ * Resource configuration for TimeBack (user input)
+ */
+interface ResourceConfig {
+    /** Resource title (defaults to "{course.title} Game") */
+    title?: string;
+    /** Internal resource ID (auto-generated from package.json) */
+    vendorResourceId?: string;
+    /** Vendor identifier */
+    vendorId?: string;
+    /** Application identifier */
+    applicationId?: string;
+    /** Resource roles */
+    roles?: ('primary' | 'secondary')[];
+    /** Resource importance */
+    importance?: 'primary' | 'secondary';
+    /** Interactive resource metadata */
+    metadata?: {
+        /** Resource type */
+        type?: 'interactive';
+        /** Launch URL (defaults to Playcademy game URL) */
+        launchUrl?: string;
+        /** Platform name */
+        toolProvider?: string;
+        /** Teaching method */
+        instructionalMethod?: 'exploratory' | 'direct-instruction';
+        /** Subject area */
+        subject?: TimebackSubject;
+        /** Target grades */
+        grades?: TimebackGrade[];
+        /** Content language */
+        language?: string;
+        /** Base XP for completion */
+        xp?: number;
+        /** Playcademy-specific extensions */
+        playcademy?: PlaycademyResourceMetadata;
+    };
 }
-/** Secret key names partitioned by ownership — names only, never hashes */
-interface DeploymentStateSecrets {
-    /** Keys recorded in the server-side secrets manifest */
-    managedKeys: string[];
-    /**
-     * Remote keys not in the manifest (set by SST, wrangler, or hand).
-     * Null when the server has no Cloudflare provider to list remote keys.
-     */
-    unmanagedKeys: string[] | null;
+/**
+ * Component Resource link configuration (user input)
+ */
+interface ComponentResourceConfig {
+    /** Link title (defaults to "{resource.title} Activity") */
+    title?: string;
+    /** Display order */
+    sortOrder?: number;
+    /** Lesson type for PowerPath integration */
+    lessonType?: LessonType;
 }
-interface DeploymentStateLastDeploy {
-    at: string;
-    /** Who deployed: their email, or the raw user id when the account no longer resolves */
-    by: string;
+interface TimebackCourseConfig {
+    subject: string;
+    grade: number;
+}
+interface DerivedPlatformCourseConfig extends TimebackCourseConfig {
+    title: string;
+    courseCode: string;
+    level: string;
+    metadata?: Record<string, unknown>;
+    totalXp?: number | null;
+    masterableUnits?: number | null;
 }
+
 /**
- * Server-side deployment state for a game.
+ * TimeBack Client SDK DTOs
  *
- * Everything CLI deploy prep diffs against, fetched from
- * GET /api/games/:slug/deployment-state so deploys never depend on
- * local state for correctness.
+ * Data transfer objects for the TimeBack client SDK including
+ * progress tracking, session management, and activity completion.
+ *
+ * Note: TimebackClientConfig lives in @playcademy/timeback as it's
+ * SDK configuration, not a DTO.
+ *
+ * @module types/timeback/client
  */
-interface DeploymentStateResponse {
-    gameId: string;
-    /** True iff a game_deployment_state row exists for the game */
-    seeded: boolean;
-    game: DeploymentStateGame | null;
-    dashboard: DeploymentStateDashboard | null;
-    database: DeploymentStateDatabase;
-    secrets: DeploymentStateSecrets;
-    /** Hash of the declared integrations config (null when unseeded) */
-    integrationsHash: string | null;
-    /** Last deployed compatibility date (null when unseeded) */
-    compatibilityDate: string | null;
-    lastDeploy: DeploymentStateLastDeploy | null;
-}
+
 /**
- * Per-key verdict groups from the server-side secrets diff (D6).
- *
- * Key names only — HMAC digests never leave the server. `remoteOnlyManaged`
- * keys are the only legal prune candidates; `remoteOnlyUnmanaged` keys were
- * set outside the platform and are untouchable.
+ * Known extensions for TimeBack Activity Metrics Collection
  */
-interface SecretsDiffResponse {
-    /** Local keys the manifest doesn't know yet */
-    added: string[];
-    /** Keys whose local value's HMAC differs from the manifest's */
-    changed: string[];
-    /** Keys whose local value's HMAC matches the manifest's */
-    unchanged: string[];
-    /** Manifest keys absent locally (prunable) */
-    remoteOnlyManaged: string[];
-    /** Worker keys absent from both the manifest and the local set */
-    remoteOnlyUnmanaged: string[];
+interface TimebackActivityExtensions {
+    /** Percentage complete (0-100) for the app course */
+    pctCompleteApp?: number;
+    /** Allow other arbitrary extensions */
+    [key: string]: unknown;
+}
+interface MasteryWriteWarning {
+    code: 'MASTERY_WRITE_CAPPED';
+    message: string;
+    currentMasteredUnits: number;
+    attemptedMasteredUnits: number;
+    appliedMasteredUnits: number;
+    storedMasteredUnits: number;
+    masterableUnits: number;
 }
 /**
- * Manual baseline adoption request (PLA-217 D7): the fresh-machine path for
- * a game that predates server-side deployment state. Carries the claimed
- * migrate-mode history (tag + journal), the push-mode snapshot, or both.
+ * Activity data for ending an activity
  */
-interface DeploymentStateBaselineRequest {
-    lastAppliedMigrationTag?: string;
-    journal?: DeployBaselineJournalEntry[];
-    schemaSnapshot?: unknown;
-    schemaHash?: string;
-    /**
-     * Per-migration schema-object evidence (creates AND drops) derived
-     * from drizzle's snapshot files. The server replays it up to the
-     * claimed tag into the expected schema and validates that against the
-     * live database (D7): surviving claimed objects must exist,
-     * beyond-claim objects must be absent unless claimed history already
-     * explains them. Absent evidence downgrades every migration to
-     * no-signal.
+interface ActivityData {
+    /** Unique activity identifier (required) */
+    activityId: string;
+    /** Grade level for this activity (required for multi-grade course routing) */
+    grade: number;
+    /** Subject area (required for multi-grade course routing) */
+    subject: CaliperSubject;
+    /** Activity display name (optional) */
+    activityName?: string;
+    /**
+     * Optional course to report against. When omitted, the SDK fills it from
+     * the student's enrollment for this grade/subject (preferring a
+     * hole-filling course). The platform uses it if it's the base course or one
+     * of that grade/subject's hole-filling courses, otherwise the base course.
      */
-    evidence?: BaselineMigrationEvidence[];
+    courseId?: string;
     /**
-     * Waive refusals for no-signal migrations only (content contradictions
-     * are never waivable). Recorded server-side for audit.
+     * The student's enrollment in `courseId`. Filled by the SDK alongside an
+     * automatic `courseId`; recorded on hole-filling Caliper events.
      */
-    allowUnverified?: boolean;
+    enrollmentId?: string;
+    /** Course display name (auto-filled from config if not provided) */
+    courseName?: string;
+    /** Student email address (optional) */
+    studentEmail?: string;
+    /** Application name for Caliper events (defaults to 'Game') */
+    appName?: string;
+    /** Sensor URL for Caliper events (defaults to baseUrl) */
+    sensorUrl?: string;
 }
 /**
- * Schema objects one journal migration introduced and removed (snapshot
- * delta). Drops are as load-bearing as creates: an object created by one
- * migration and dropped by a later one must not be demanded of the live
- * database, and its live presence beyond the claim must not convict a
- * migration whose object is already explained by claimed history.
+ * Score data for ending an activity
  */
-interface BaselineMigrationEvidence {
-    tag: string;
-    /** Journal generation timestamp (drizzle `when`), ISO 8601 */
-    generatedAt: string;
-    createsTables: {
-        name: string;
-        columns: string[];
-    }[];
-    addsColumns: {
-        table: string;
-        column: string;
-    }[];
-    createsIndexes: string[];
-    createsViews: string[];
-    dropsTables: string[];
-    dropsColumns: {
-        table: string;
-        column: string;
-    }[];
-    dropsIndexes: string[];
-    dropsViews: string[];
-}
-/** Outcome of the `db realign <tag>` checksum pardon */
-interface MigrationRealignResponse {
-    tag: string;
-    /** The re-recorded checksum */
-    checksum: string;
-    /** Algorithm stamped alongside it (e.g. 'sha256-v1') */
-    checksumAlgo: string;
-}
-/** How a ledger escape-hatch resolution lands: record the row, or remove it */
-type MigrationResolution = 'applied' | 'rolled-back';
-/** Outcome of the `db resolve <tag>` ledger escape hatch */
-interface MigrationResolveResponse {
-    tag: string;
-    resolution: MigrationResolution;
+interface EndActivityScoreData {
+    /** Number of questions answered correctly */
+    correctQuestions: number;
+    /** Total number of questions */
+    totalQuestions: number;
     /**
-     * Live schema fingerprint captured by the resolve: the developer's
-     * attestation that the current database state is intended, so the next
-     * deploy verifies against it instead of the pre-repair record.
+     * XP earned for this activity.
+     *
+     * Required when the game reports directly (platform, demo, standalone).
+     * A child-launched game may omit it: narrow the client with the SDK's
+     * `isChildLaunched()` for the relaxed signature. The parent game
+     * decides the award, and a value provided here travels only as the
+     * `childXpSuggested` audit suggestion.
      */
-    schemaFingerprint: string;
+    xpAwarded: number;
     /**
-     * Whether the fingerprint was persisted to the game's deployment-state
-     * row. False when the game has no such row (not yet adopted): the
-     * ledger repair still succeeded, but nothing was recorded.
+     * Incremental learning units mastered this session.
+     *
+     * Cannot be used with masteredUnitsAbsolute. When a course has mastery
+     * tracking configured, the platform bounds submissions that would move
+     * the student below 0 or above the configured masterableUnits maximum and
+     * returns warning metadata.
      */
-    fingerprintRecorded: boolean;
-}
-/** One deploy job in a game's execution history (PLA-217 D10) */
-interface GameDeployHistoryDeploy {
-    kind: 'deploy';
-    status: DeployJobStatus;
-    /** When the deploy landed (creation time while pending/running), ISO 8601 */
-    at: string;
-    /** When the job finished (null while pending/running) */
-    completedAt: string | null;
-    /** Who deployed: their email, or DELETED_ACCOUNT_LABEL when the account is gone */
-    by: string;
-    /** Client idempotency key (null for legacy clients) */
-    deployId: string | null;
-    error: string | null;
-}
-/** A Time Travel restore in a game's execution history */
-interface GameDeployHistoryRestore {
-    kind: 'restore';
-    /** When the restore ran, ISO 8601 */
-    at: string;
-    /** Who restored: their email, or DELETED_ACCOUNT_LABEL when the account is gone */
-    by: string;
-    /** The moment the database was rewound to, ISO 8601 */
-    restoredTo: string;
-}
-/** A client-gate refusal in a game's execution history */
-interface GameDeployHistoryBlocked {
-    kind: 'blocked';
-    /** When the gate refused, ISO 8601 */
-    at: string;
-    /** Whose deploy was refused: their email, or DELETED_ACCOUNT_LABEL */
-    by: string;
-    /** Stable `blocked:*` code the gate refused with */
-    code: string;
-    /** The gate's plain-text refusal reason */
-    reason: string;
-}
-/**
- * One entry in a game's execution history: deploy jobs interleaved with
- * the platform-visible events the job system never sees (restores,
- * client-gate refusals), newest first.
- */
-type GameDeployHistoryEntry = GameDeployHistoryDeploy | GameDeployHistoryRestore | GameDeployHistoryBlocked;
-/** Deploy history served by GET /api/games/:slug/deployments */
-interface GameDeployHistoryResponse {
-    deploys: GameDeployHistoryEntry[];
+    masteredUnits?: number;
+    /**
+     * Absolute total of mastered units.
+     *
+     * The platform computes the delta from the current value. Cannot be used
+     * with masteredUnits. When a course has mastery tracking configured, the
+     * platform bounds values outside 0..masterableUnits and returns warning
+     * metadata.
+     */
+    masteredUnitsAbsolute?: number;
+    /** Optional arbitrary extensions to include in the Caliper event */
+    extensions?: TimebackActivityExtensions;
 }
+
 /**
- * One successful deploy of a game's worker, as the open releases surface
- * describes it: what is running and which commit produced it.
+ * Caliper Protocol Types
  *
- * This shape is parsed by external automation. Every field is present on
- * every entry — nullable, never absent — and nothing from the deploy job
- * beyond its git provenance and completion time is exposed. No deployer
- * identity, no schema state, no secrets manifest.
+ * Types for the IMS Caliper Analytics standard used by TimeBack
+ * for learning activity tracking.
+ *
+ * @module types/timeback/caliper
  */
-interface Release {
-    slug: string;
-    /** Where the game is served; null when the platform has no URL for it */
-    url: string | null;
-    /**
-     * Git provenance the deploying CLI captured. Null for deploys that
-     * predate provenance capture, so the fleet list is complete on day one
-     * and a consumer can tell "unknown" from "not in git".
-     */
-    source: DeploySource | null;
-    /** When the deploy succeeded, ISO 8601 */
-    deployedAt: string;
-}
-/** GET /api/releases — the current release of every game */
-interface ReleasesResponse {
-    releases: Release[];
+
+interface TimebackStoredCaliperMetric {
+    type: string;
+    value?: number;
+    subType?: string;
 }
-/** GET /api/releases/:slug — one game's current release and, on request, its recent history */
-interface GameReleaseResponse {
-    /** The current release; null when the game has never deployed successfully */
-    current: Release | null;
-    /**
-     * The last N successful deploys, newest first, current included. Only
-     * present when `?history=N` was requested.
-     */
-    history?: Release[];
+interface TimebackStoredCaliperEntity {
+    id?: string;
+    type?: string;
+    name?: string;
+    email?: string;
+    app?: {
+        id?: string;
+        name?: string;
+    };
+    activity?: {
+        id?: string;
+        name?: string;
+        extensions?: Record<string, unknown> | null;
+    };
+    course?: {
+        id?: string;
+        name?: string;
+    };
+    items?: TimebackStoredCaliperMetric[];
+    extensions?: Record<string, unknown> | null;
+    [key: string]: unknown;
 }
-/** Request body for POST /api/games/:slug/deployments/blocked */
-interface DeployBlockedReport {
-    /** Stable `blocked:*` code the gate refused with */
-    code: string;
-    /** The gate's plain-text refusal reason */
-    reason: string;
+interface TimebackStoredCaliperEvent {
+    id: number;
+    externalId: string;
+    sensor: string;
+    type: string;
+    profile?: string;
+    action: string;
+    eventTime: string;
+    sendTime: string;
+    updated_at: string | null;
+    created_at: string;
+    deleted_at: string | null;
+    actor: TimebackStoredCaliperEntity;
+    object: TimebackStoredCaliperEntity;
+    generated?: TimebackStoredCaliperEntity | null;
+    target?: TimebackStoredCaliperEntity | null;
+    referrer?: TimebackStoredCaliperEntity | null;
+    edApp?: TimebackStoredCaliperEntity | null;
+    group?: TimebackStoredCaliperEntity | null;
+    membership?: TimebackStoredCaliperEntity | null;
+    session?: TimebackStoredCaliperEntity | null;
+    federatedSession?: TimebackStoredCaliperEntity | null;
+    extensions?: Record<string, unknown> | null;
+    clientAppId?: string | null;
 }
+
 /**
- * A restorable pre-deploy database state (D1 Time Travel bookmark).
+ * Game-side learning metrics for a single student.
  *
- * Each schema-bearing deploy captures a bookmark of the database as it was
- * the moment before that deploy's schema changes ran. Only bookmarks
- * belonging to the CURRENT database and within Time Travel's retention
- * window are served — a `db reset` creates a new database (bookmarks do
- * not cross that boundary), and Cloudflare expires bookmarks after the
- * account plan's retention period.
- */
-interface GameRestorePoint {
-    /** Deployment row id — pass to the restore endpoint (or a unique prefix to the CLI) */
-    id: string;
-    /**
-     * When the bookmark was captured (the exact state a restore rewinds
-     * to), ISO 8601. Rows from before capture times were recorded fall
-     * back to the deploy completion time.
-     */
-    capturedAt: string;
-    /** Whether the capturing deployment is the currently active one */
-    active: boolean;
-}
-/** Restore points served by GET /api/games/:slug/database/restore-points */
-interface GameRestorePointsResponse {
-    restorePoints: GameRestorePoint[];
-    /**
-     * True for push-adopted games, whose recorded snapshot cannot rewind
-     * with the data: restore is categorically refused, so the list is
-     * served empty rather than offering points that can never restore.
-     */
-    restoreUnsupported: boolean;
-}
-/** Outcome of a Time Travel restore (PLA-217 D10) */
-interface DatabaseRestoreResponse {
-    restorePointId: string;
-    /** The moment the database was rewound to (the bookmark's capture time), ISO 8601 */
-    restoredTo: string;
-    /**
-     * Live schema fingerprint captured after the restore: the developer's
-     * audited attestation that the rewound state is intended, so the next
-     * deploy verifies against it.
-     */
-    schemaFingerprint: string;
-    /** False when the game has no deployment-state row to re-attest */
-    fingerprintRecorded: boolean;
-    /**
-     * Bookmark of the database as it was just before this restore — the
-     * undo handle. Null only if Cloudflare omits it from the response.
-     */
-    previousBookmark: string | null;
-}
-/** Push-mode reset payload: the full schema that rebuilds the fresh database */
-interface DatabaseResetPush {
-    mode: 'push';
-    /** Full schema DDL (semicolon-separated statements) */
-    sql: string;
-    /** Drizzle snapshot JSON, stored as the new push baseline */
-    nextSnapshot: unknown;
-    /** Hash of nextSnapshot, stored as the new schemaHash */
-    nextHash: string;
-}
-/** Migrate-mode reset payload: the complete journal to replay on the fresh database */
-interface DatabaseResetMigrate {
-    mode: 'migrate';
-    /** The full journal in order; replayed one-by-one, rebuilding the ledger */
-    migrations: DeployMigration[];
-}
-/**
- * Mode-aware reset payload (PLA-217 D2). Reset recreates the database, so
- * the ledger dies with it and there is no baseline to compare against —
- * adopted games must send how to rebuild.
+ * Returned by opted-in game workers from their reserved
+ * `/__playcademy/metrics` route.
  */
-type DatabaseResetDatabasePayload = DatabaseResetPush | DatabaseResetMigrate;
-interface DatabaseResetRequest {
-    /**
-     * Legacy schema info, accepted only while the game's schema state is
-     * unadopted; adopted games must send `database` instead.
-     */
-    schema?: {
-        /** SQL schema statements (DDL: CREATE, ALTER, etc.) */
-        sql: string;
-        /** Hash of the schema for change detection */
-        hash: string;
-    };
-    /** Mode-aware rebuild payload (mandatory for adopted games) */
-    database?: DatabaseResetDatabasePayload;
+interface GameMetricsResponse {
+    /** Student identifier (Playcademy user ID). */
+    studentId: string;
+    /** Student email, when available to the game. */
+    email?: string;
+    /** Per-course metrics grouped by TimeBack grade and subject. */
+    courses: GameCourseMetrics[];
 }
-/** Log entry captured from seed worker console output */
-interface SeedLogEntry {
-    /** Log level (log, warn, error, info) */
-    level: 'log' | 'warn' | 'error' | 'info';
-    /** Log message content */
-    message: string;
-    /** Milliseconds since seed execution started */
-    timestamp: number;
+interface GameCourseMetrics {
+    /** Grade level matching the game's TimeBack integration. */
+    grade: TimebackGrade;
+    /** Subject matching the game's TimeBack integration. */
+    subject: TimebackSubject;
+    /** Total XP the game has recorded for this student in this course. */
+    totalXp?: number;
+    /** Mastered units the game has recorded for this course. */
+    masteredUnits?: number;
+    /** Total active time in seconds the game has recorded for this course. */
+    activeTimeSeconds?: number;
+    /** Optional per-run breakdown keyed by Timeback run ID. */
+    activities?: GameRunMetrics[];
 }
-/** Structured error details from D1/SQLite errors */
-interface SeedErrorDetails {
-    /** Error category code */
-    code?: 'CONSTRAINT_VIOLATION' | 'SQL_ERROR' | 'DATABASE_BUSY';
-    /** Table name involved in the error */
-    table?: string;
-    /** Constraint name or column that caused the error */
-    constraint?: string;
-    /** Specific constraint type */
-    constraintType?: 'UNIQUE' | 'FOREIGN_KEY' | 'NOT_NULL';
-    /** Token near syntax error */
-    nearToken?: string;
-    /** Specific error type within category */
-    errorType?: 'TABLE_NOT_FOUND' | 'SYNTAX_ERROR';
+interface GameRunMetrics {
+    runId: string;
+    activityId: string;
+    activityName?: string;
+    totalXp?: number;
+    masteredUnits?: number;
+    activeTimeSeconds?: number;
+    score?: number;
 }
-/**
- * API response for seed operations (what the API returns to the CLI).
- *
- * Extends the worker response with deployment metadata.
- */
-interface SeedResponse {
-    /** Whether the seed completed successfully */
-    success: boolean;
-    /** Unique identifier for the seed worker deployment */
-    deploymentId: string;
-    /** When the seed was executed (ISO 8601 string from JSON serialization) */
-    executedAt: string;
-    /** Captured console output from the seed script */
-    logs?: SeedLogEntry[];
-    /** Execution duration in milliseconds */
-    duration?: number;
-    /** Error message if seed failed */
-    error?: string;
-    /** Stack trace if seed failed */
-    stack?: string;
-    /** Structured error details if seed failed */
-    details?: SeedErrorDetails;
+type GameMetricsUnsupportedReason = 'no_timeback_integration' | 'no_active_deployment' | 'route_not_implemented' | 'timeout' | 'fetch_failed' | 'invalid_response';
+type GameMetricsProxyResponse = {
+    supported: true;
+    metrics: GameMetricsResponse;
+} | {
+    supported: false;
+    reason: GameMetricsUnsupportedReason;
+    details?: string;
+};
+type GameMetricComparisonMetric = 'xp' | 'mastery' | 'time' | 'score';
+type GameMetricComparisonKind = 'number' | 'time' | 'percent';
+type GameMetricComparisonRowStatus = 'matched' | 'discrepant' | 'not_reported_by_game' | 'not_recorded_by_timeback';
+interface GameMetricComparisonRow {
+    metric: GameMetricComparisonMetric;
+    kind: GameMetricComparisonKind;
+    status: GameMetricComparisonRowStatus;
+    timebackValue?: number;
+    gameValue?: number;
+    delta?: number;
 }
-interface DomainValidationRecords {
-    ownership?: {
-        name?: string;
-        value?: string;
-        type?: string;
-    };
-    ssl?: {
-        txt_name?: string;
-        txt_value?: string;
-    }[];
+type GameRunMetricsComparisonStatus = 'matched' | 'discrepant' | 'not_reported' | 'unavailable';
+interface GameRunMetricsComparisonSummary {
+    runId: string;
+    status: GameRunMetricsComparisonStatus;
+    discrepancyCount: number;
+    reason?: GameMetricsUnsupportedReason;
+}
+interface GameRunMetricsComparison extends GameRunMetricsComparisonSummary {
+    rows: GameMetricComparisonRow[];
 }
 
 /**
- * Leaderboard Types
+ * QTI API Response Types
  *
- * @module types/leaderboard
+ * Types for the QTI assessment content service responses.
+ * These mirror the JSON structure returned by the QTI API
+ * (beyond-qti-2) for assessment tests and items.
+ *
+ * @module types/timeback/qti
  */
-type LeaderboardTimeframe = 'all_time' | 'monthly' | 'weekly' | 'daily';
-interface LeaderboardOptions {
-    timeframe?: LeaderboardTimeframe;
-    limit?: number;
-    offset?: number;
-    gameId?: string;
-}
-interface LeaderboardEntry {
-    rank: number;
-    userId: string;
-    username: string;
-    userImage?: string | null;
-    score: number;
-    achievedAt: Date;
-    metadata?: Record<string, unknown>;
-    gameId?: string;
-    gameTitle?: string;
-    gameSlug?: string;
+interface QtiItemRef {
+    identifier: string;
+    href: string;
+    sequence?: number;
 }
-interface UserRank {
-    rank: number;
-    totalPlayers: number;
-    score: number;
-    percentile: number;
+interface QtiAssessmentSection {
+    identifier: string;
+    title: string;
+    visible?: boolean;
+    required?: boolean;
+    fixed?: boolean;
+    sequence?: number;
+    'qti-assessment-item-ref'?: QtiItemRef[];
 }
-interface UserRankResponse {
-    rank: number;
-    score: number;
-    userId: string;
+interface QtiTestPart {
+    identifier: string;
+    navigationMode: 'linear' | 'nonlinear';
+    submissionMode: 'individual' | 'simultaneous';
+    'qti-assessment-section': QtiAssessmentSection[];
 }
-interface UserScore {
-    id: string;
-    score: number;
-    achievedAt: Date;
-    metadata?: Record<string, unknown>;
-    gameId: string;
-    gameTitle: string;
-    gameSlug: string;
+interface QtiOutcomeDeclaration {
+    identifier: string;
+    cardinality?: 'single' | 'multiple' | 'ordered' | 'record';
+    baseType: 'boolean' | 'directedPair' | 'duration' | 'file' | 'float' | 'identifier' | 'integer' | 'pair' | 'point' | 'string' | 'uri';
+    normalMaximum?: number;
+    normalMinimum?: number;
+    defaultValue?: {
+        value?: unknown;
+    };
 }
-/**
- * Leaderboard entry with required game context.
- * Used when fetching leaderboards for a specific game.
- */
-interface GameLeaderboardEntry {
-    rank: number;
-    userId: string;
-    username: string;
-    userImage?: string | null;
-    score: number;
-    achievedAt: Date;
+interface QtiAssessmentTest {
+    identifier: string;
+    title: string;
+    qtiVersion?: string;
+    timeLimit?: number;
+    maxAttempts?: number;
+    toolsEnabled?: Record<string, boolean>;
+    'qti-test-part': QtiTestPart[];
+    'qti-outcome-declaration'?: QtiOutcomeDeclaration[];
     metadata?: Record<string, unknown>;
-    gameId: string;
-    gameTitle: string;
-    gameSlug: string;
+    rawXml?: string;
+    content?: Record<string, unknown>;
+    createdAt?: string;
+    updatedAt?: string;
+}
+interface QtiAssessmentTestListResponse {
+    items: QtiAssessmentTest[];
+    total: number;
+    page: number;
+    pages: number;
+    limit: number;
+    sort: string;
+    order: 'asc' | 'desc';
+}
+interface QtiResponseDeclaration {
+    identifier: string;
+    cardinality: 'single' | 'multiple' | 'ordered';
+    baseType: string;
+    correctResponse?: {
+        value: string[];
+    };
+}
+interface QtiAssessmentItem {
+    identifier: string;
+    title: string;
+    type?: string;
+    qtiVersion?: string;
+    timeDependent?: boolean;
+    adaptive?: boolean;
+    preInteraction?: string;
+    interaction?: Record<string, unknown>;
+    postInteraction?: string;
+    responseDeclarations?: QtiResponseDeclaration[];
+    outcomeDeclarations?: QtiOutcomeDeclaration[];
+    responseProcessing?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    modalFeedback?: unknown[];
+    feedbackInline?: unknown[];
+    feedbackBlock?: unknown[];
+    rubrics?: unknown[];
+    stimulus?: unknown;
+    rawXml?: string;
+    content?: Record<string, unknown>;
+    createdAt?: string;
+    updatedAt?: string;
+}
+interface QtiAssessmentItemListResponse {
+    items: QtiAssessmentItem[];
+    total: number;
+    page: number;
+    pages: number;
+    limit: number;
+    sort: string;
+    order: 'asc' | 'desc';
+}
+/** Request an exact, independently owned copy through the normal question collection endpoint. */
+interface QtiQuestionCopyCreateInput {
+    mode: 'copy';
+    sourceItemIdentifier: string;
+}
+type QtiQuestionCreateInput = QtiQuestionCopyCreateInput | Record<string, unknown>;
+interface QtiTestQuestionRef {
+    ownership?: 'owned' | 'shared';
+    reference: {
+        identifier: string;
+        href: string;
+        testPart: string;
+        section: string;
+    };
+    question: QtiAssessmentItem;
+}
+interface QtiTestQuestionsResponse {
+    assessmentTest: string;
+    title: string;
+    totalQuestions: number;
+    questions: QtiTestQuestionRef[];
 }
 
 /**
- * Skill Status Types
+ * TimeBack API Request/Response Types
  *
- * Contract for cross-game skill status queries. An answering game exports
- * `getSkillStatus` from `server/lib/skills.ts`; the platform calls its
- * reserved `/__playcademy/skills/status` route on behalf of another game.
+ * Types for TimeBack API endpoints including XP tracking,
+ * setup, verification, and activity completion.
  *
- * @module types/skills
+ * @module types/timeback/api
  */
 
-/**
- * Current status of one skill for one student, as judged by the answering game.
- *
- * - `locked`: the student can't work on the skill yet in this game.
- * - `unlocked`: available to the student, but no progress yet.
- * - `in_progress`: started, not mastered.
- * - `mastered`: currently meets this game's mastery bar, including by placement.
- * - `unknown_skill`: the skill ID isn't recognized. Never report an unrecognized
- *   skill as `locked`.
- */
-type SkillStatus = (typeof SKILL_STATUSES)[number];
-/** How a `mastered` status was reached. */
-type SkillMasterySource = (typeof SKILL_MASTERY_SOURCES)[number];
-interface SkillStatusResult {
-    /** Skill ID, lowercase. */
-    skill: string;
-    /** Current status. */
-    status: SkillStatus;
-    /** How mastery was reached. Only allowed when `status` is `mastered`. */
-    source?: SkillMasterySource;
-    /** ISO 8601 time of the evidence behind this status. */
-    asOf?: string;
+interface PopulateStudentResponse {
+    status: string;
+    message?: string;
 }
-/** Response returned by an answering game's `getSkillStatus` handler. */
-interface SkillStatusResponse {
-    /** Student identifier (Playcademy user ID). Must match the requested student. */
-    studentId: string;
-    /** One result per skill the handler was asked about. */
-    results: SkillStatusResult[];
+interface TimebackSetupRequest {
+    gameId: string;
+    config: {
+        organization: {
+            name: string;
+            type: string;
+            identifier: string;
+        };
+        course: {
+            /**
+             * Client-chosen OneRoster sourcedId for the course. Omit to let
+             * Timeback allocate one. Fixed once the course exists.
+             */
+            sourcedId?: string;
+            title: string;
+            subjects: string[];
+            grades: number[];
+            courseCode: string;
+            level: string;
+            gradingScheme: string;
+            metadata?: Record<string, unknown>;
+        };
+        component: {
+            title: string;
+            sortOrder: number;
+            prerequisites: string[];
+            prerequisiteCriteria: string;
+        };
+        resource: {
+            title: string;
+            vendorResourceId: string;
+            vendorId: string;
+            applicationId: string;
+            roles: string[];
+            importance: string;
+            metadata: {
+                type?: string;
+                launchUrl?: string;
+                toolProvider?: string;
+                instructionalMethod?: string;
+                subject?: string;
+                grades?: number[];
+                language?: string;
+                xp?: number;
+                [key: string]: unknown;
+            };
+        };
+        componentResource: {
+            title: string;
+            sortOrder: number;
+            lessonType: string | null;
+        };
+    };
+    verbose?: boolean;
 }
-/** The game asking for skill status, as identified by the platform. */
-interface SkillStatusRequestingGame {
-    id: string;
-    slug: string;
+interface PlatformTimebackSetupRequest {
+    gameId: string;
+    courses: DerivedPlatformCourseConfig[];
+    baseConfig: {
+        organization: {
+            name: string;
+            type: string;
+            identifier: string;
+        };
+        component: {
+            title: string;
+            titleSuffix?: string;
+            sortOrder: number;
+            prerequisites: string[];
+            prerequisiteCriteria: string;
+        };
+        resource: {
+            title: string;
+            titleSuffix?: string;
+            vendorResourceId: string;
+            vendorId: string;
+            applicationId: string;
+            roles: string[];
+            importance: string;
+            metadata: {
+                type?: string;
+                launchUrl?: string;
+                toolProvider?: string;
+                instructionalMethod?: string;
+                language?: string;
+                [key: string]: unknown;
+            };
+        };
+        componentResource: {
+            title: string;
+            titleSuffix?: string;
+            sortOrder: number;
+            lessonType: string | null;
+        };
+    };
+    verbose?: boolean;
 }
-/** Body of `POST /api/skills/status`, sent by the asking game's worker. */
-interface SkillStatusRequest {
-    /** Slug of the game to ask. */
-    game: string;
-    /** Playcademy user ID of the student. */
-    studentId: string;
-    /** Skill IDs to ask about. Normalized (trimmed, lowercased) and de-duplicated. */
-    skills: string[];
+interface PlatformTimebackSetupResponse {
+    integrations: GameTimebackIntegration[];
+    verbose?: {
+        integration: GameTimebackIntegration;
+        config: {
+            course: unknown;
+            component: unknown;
+            resource: unknown;
+            componentResource: unknown;
+        };
+    }[];
 }
-/** Why the answering game couldn't answer. */
-type SkillStatusUnsupportedReason = 'not_implemented' | 'no_active_deployment' | 'timeout' | 'fetch_failed' | 'invalid_response';
 /**
- * What the asking game gets back. When `supported` is false, fall back to
- * the game's own default (usually: treat the skills as not mastered).
+ * `base` courses form a game's grade ladder (one active per grade and subject).
+ * `hole_filling` courses are remediation courses Timeback enrolls students into
+ * after a failed test; each sits beside a base course.
  */
-type SkillStatusLookupResult = {
-    supported: true;
-    results: SkillStatusResult[];
-} | {
-    supported: false;
-    reason: SkillStatusUnsupportedReason;
-};
-
-/**
- * TimeBack Enums & Literal Types
- *
- * Basic type definitions used throughout the TimeBack integration. Unions
- * derive from the canonical value lists in @playcademy/constants (type-only
- * imports, so this package ships no runtime code).
- *
- * @module types/timeback/types
- */
-
-/**
- * The TimeBack subject vocabulary. 'None' is canonical: TimeBack accepts it
- * on courses and uses it as the fallback for unknown or missing subjects.
- */
-type TimebackSubject = (typeof TIMEBACK_SUBJECTS)[number];
-/**
- * Grade levels per AE OneRoster GradeEnum.
- * -1 = Pre-K, 0 = Kindergarten, 1-12 = Grades 1-12, 13 = AP
- */
-type TimebackGrade = (typeof TIMEBACK_GRADES)[number];
-/**
- * Platform pedagogy levels for a single lesson of instruction.
- * E1 teaches, E2/E3 practice and remediate, E4 is the mastery check.
- */
-type ELevel = 'E1' | 'E2' | 'E3' | 'E4';
-/**
- * Valid Caliper subject values. The same vocabulary as OneRoster subjects.
- */
-type CaliperSubject = (typeof TIMEBACK_SUBJECTS)[number];
-/**
- * OneRoster organization types.
- */
-type OrganizationType = 'department' | 'school' | 'district' | 'local' | 'state' | 'national';
-/**
- * Lesson types for PowerPath integration.
- */
-type LessonType = 'powerpath-100' | 'quiz' | 'test-out' | 'placement' | 'unit-test' | 'alpha-read-article' | null;
-
-/**
- * TimeBack Configuration Types
- *
- * Configuration interfaces for Organization, Course, Component,
- * Resource, and complete TimeBack setup.
- *
- * @module types/timeback/config
- */
-
-/**
- * Organization configuration for TimeBack (user input - optionals allowed)
- */
-interface OrganizationConfig {
-    /** Display name for your organization */
-    name?: string;
-    /** Organization type */
-    type?: OrganizationType;
-    /** Unique identifier (defaults to Playcademy's org) */
-    identifier?: string;
-}
-/**
- * Course goals for daily student targets
- */
-interface CourseGoals {
-    /** Target XP students should earn per day */
-    dailyXp?: number;
-    /** Target lessons per day */
-    dailyLessons?: number;
-    /** Target active minutes per day */
-    dailyActiveMinutes?: number;
-    /** Target accuracy percentage */
-    dailyAccuracy?: number;
-    /** Target mastered units per day */
-    dailyMasteredUnits?: number;
+type GameTimebackIntegrationKind = 'base' | 'hole_filling';
+interface GameTimebackIntegration {
+    id: string;
+    gameId: string;
+    courseId: string;
+    grade: number;
+    subject: string;
+    /** Defaults to `base` when absent (responses from older servers). */
+    kind?: GameTimebackIntegrationKind;
+    /** The base course a hole-filling course belongs to; null for base courses. */
+    baseIntegrationId?: string | null;
+    status?: 'active' | 'deactivated';
+    totalXp?: number | null;
+    lastVerifiedAt?: Date | null;
+    deactivatedAt?: Date | null;
+    reactivatedAt?: Date | null;
+    createdAt: Date;
+    updatedAt: Date;
 }
-/**
- * Course metrics and totals
- */
-interface CourseMetrics {
-    /** Total XP available in the course */
-    totalXp?: number;
-    /** Total lessons/activities in the course */
-    totalLessons?: number;
-    /** Total number of grade levels covered by this course */
-    totalGrades?: number;
-    /** The type of course (e.g. 'optional', 'hole-filling', 'base') */
-    courseType?: 'base' | 'hole-filling' | 'optional' | 'Base' | 'Hole-Filling' | 'Optional';
-    /** Indicates whether the course is supplemental content */
-    isSupplemental?: boolean;
+interface RemovedGameTimebackIntegration {
+    integration: GameTimebackIntegration;
+    title: string;
+    courseCode: string;
+    subject: TimebackSubject;
+    grade: number;
+    totalXp?: number | null;
+    masterableUnits?: number | null;
+    removedAt?: Date | string | null;
+    metadata?: CourseMetadata | null;
 }
-/**
- * Complete course metadata structure
- */
-interface CourseMetadata {
-    /** Define the type of course and priority for the student */
-    courseType?: 'base' | 'hole-filling' | 'optional';
-    /** Boolean value to determine if a course is supplemental to a base course */
-    isSupplemental?: boolean;
-    /** Boolean value to determine if a course is custom to an individual student */
-    isCustom?: boolean;
-    /** Signals whether a course is in production with students */
-    publishStatus?: 'draft' | 'testing' | 'published' | 'deactivated';
-    /** Whether this course appears in the TimeBack catalog for teachers and parents */
-    timebackVisible?: boolean;
-    /** Who to contact when issues reported with questions */
-    contactEmail?: string;
-    /** Primary app identifier */
-    primaryApp?: string;
-    /** Learning goals for students */
-    goals?: CourseGoals;
-    /** Course metrics and totals */
-    metrics?: CourseMetrics;
-    /** Vendor-specific metadata (e.g., AlphaLearn) */
-    [key: string]: unknown;
+interface GameTimebackIntegrationConfig {
+    integration: GameTimebackIntegration;
+    title: string;
+    courseCode: string;
+    subject: TimebackSubject;
+    totalXp?: number | null;
+    masterableUnits?: number | null;
+    metadata?: CourseMetadata | null;
 }
-/**
- * Course configuration for TimeBack (user input)
- */
-interface CourseConfig {
-    /** Allocated OneRoster sourcedId (set after creation) */
-    sourcedId?: string;
-    /** Course title (defaults to game name) */
+interface UpdateGameTimebackIntegrationRequest {
     title?: string;
-    /** Subjects (REQUIRED for TimeBack integration) */
-    subjects: TimebackSubject[];
-    /** Used when recording progress/sessions if not explicitly specified per event. */
-    defaultSubject?: TimebackSubject;
-    /** Grade levels (REQUIRED for TimeBack integration) */
-    grades: TimebackGrade[];
-    /** Short course code (optional, auto-generated) */
     courseCode?: string;
-    /** Course level (auto-derived from grades) */
-    level?: 'Elementary' | 'Middle' | 'High' | 'AP' | string;
-    /** Grading system */
-    gradingScheme?: 'STANDARD';
-    /** Total XP available in this course (REQUIRED before setup) */
+    subject?: TimebackSubject;
     totalXp?: number | null;
-    /** Total masterable units in this course (REQUIRED before setup) */
     masterableUnits?: number | null;
-    /** Custom Playcademy metadata */
-    metadata?: CourseMetadata;
+    goals?: Partial<Record<keyof CourseGoals, number | null>> | null;
+    publishStatus?: string | null;
+    isSupplemental?: boolean;
+    timebackVisible?: boolean | null;
 }
-/**
- * Component configuration for TimeBack (user input)
- */
-interface ComponentConfig {
-    /** Component title (defaults to "{course.title} Activities") */
-    title?: string;
-    /** Display order */
-    sortOrder?: number;
-    /** Required prior components */
-    prerequisites?: string[];
-    /** How prerequisites work */
-    prerequisiteCriteria?: 'ALL' | 'ANY';
+interface CreateGameTimebackIntegrationRequest {
+    title: string;
+    courseCode: string;
+    subject: TimebackSubject;
+    grade: TimebackGrade;
+    totalXp: number;
+    masterableUnits: number;
+    level?: string;
 }
 /**
- * Playcademy-specific resource extensions
+ * Create a hole-filling course beside an existing base course. Subject and
+ * grade come from the base course; everything else defaults to a copy of it.
  */
-interface PlaycademyResourceMetadata {
-    /** Mastery configuration for tracking discrete learning units */
-    mastery?: {
-        /** Total number of masterable units in the resource */
-        masterableUnits: number;
-        /** Type of mastery unit for semantic clarity */
-        unitType?: 'level' | 'rank' | 'skill' | 'module';
-    };
+interface CreateGameTimebackHoleFillingCourseRequest {
+    /** Course ID of the active base course this hole-filling course belongs to. */
+    baseCourseId: string;
+    title: string;
+    courseCode: string;
+    totalXp: number;
+    masterableUnits: number;
+    /**
+     * Optional OneRoster sourcedId for the new course. Fixed once created; when
+     * omitted Timeback allocates one. This is the ID handed to Timeback.
+     */
+    courseId?: string;
 }
-/**
- * Resource configuration for TimeBack (user input)
- */
-interface ResourceConfig {
-    /** Resource title (defaults to "{course.title} Game") */
-    title?: string;
-    /** Internal resource ID (auto-generated from package.json) */
-    vendorResourceId?: string;
-    /** Vendor identifier */
-    vendorId?: string;
-    /** Application identifier */
-    applicationId?: string;
-    /** Resource roles */
-    roles?: ('primary' | 'secondary')[];
-    /** Resource importance */
-    importance?: 'primary' | 'secondary';
-    /** Interactive resource metadata */
-    metadata?: {
-        /** Resource type */
-        type?: 'interactive';
-        /** Launch URL (defaults to Playcademy game URL) */
-        launchUrl?: string;
-        /** Platform name */
-        toolProvider?: string;
-        /** Teaching method */
-        instructionalMethod?: 'exploratory' | 'direct-instruction';
-        /** Subject area */
-        subject?: TimebackSubject;
-        /** Target grades */
-        grades?: TimebackGrade[];
-        /** Content language */
-        language?: string;
-        /** Base XP for completion */
-        xp?: number;
-        /** Playcademy-specific extensions */
-        playcademy?: PlaycademyResourceMetadata;
+interface TimebackVerificationResources {
+    course: {
+        found: boolean;
+        data?: unknown;
+    };
+    component: {
+        found: boolean;
+        data?: unknown;
+    };
+    resource: {
+        found: boolean;
+        data?: unknown;
+    };
+    componentResource: {
+        found: boolean;
+        data?: unknown;
     };
 }
-/**
- * Component Resource link configuration (user input)
- */
-interface ComponentResourceConfig {
-    /** Link title (defaults to "{resource.title} Activity") */
-    title?: string;
-    /** Display order */
-    sortOrder?: number;
-    /** Lesson type for PowerPath integration */
-    lessonType?: LessonType;
-}
-interface TimebackCourseConfig {
-    subject: string;
-    grade: number;
-}
-interface DerivedPlatformCourseConfig extends TimebackCourseConfig {
-    title: string;
-    courseCode: string;
-    level: string;
-    metadata?: Record<string, unknown>;
-    totalXp?: number | null;
-    masterableUnits?: number | null;
-}
-
-/**
- * TimeBack Client SDK DTOs
- *
- * Data transfer objects for the TimeBack client SDK including
- * progress tracking, session management, and activity completion.
- *
- * Note: TimebackClientConfig lives in @playcademy/timeback as it's
- * SDK configuration, not a DTO.
- *
- * @module types/timeback/client
- */
-
-/**
- * Known extensions for TimeBack Activity Metrics Collection
- */
-interface TimebackActivityExtensions {
-    /** Percentage complete (0-100) for the app course */
-    pctCompleteApp?: number;
-    /** Allow other arbitrary extensions */
-    [key: string]: unknown;
+interface TimebackVerifyCourseResult {
+    integration: GameTimebackIntegration;
+    resources: TimebackVerificationResources;
+    status: 'success' | 'error';
+    errors?: string[];
 }
-interface MasteryWriteWarning {
-    code: 'MASTERY_WRITE_CAPPED';
-    message: string;
-    currentMasteredUnits: number;
-    attemptedMasteredUnits: number;
-    appliedMasteredUnits: number;
-    storedMasteredUnits: number;
-    masterableUnits: number;
+interface TimebackVerifyAllResponse {
+    status: 'success' | 'error';
+    results: TimebackVerifyCourseResult[];
 }
-/**
- * Activity data for ending an activity
- */
-interface ActivityData {
-    /** Unique activity identifier (required) */
-    activityId: string;
-    /** Grade level for this activity (required for multi-grade course routing) */
-    grade: number;
-    /** Subject area (required for multi-grade course routing) */
-    subject: CaliperSubject;
-    /** Activity display name (optional) */
-    activityName?: string;
-    /** Course identifier (auto-filled from config if not provided) */
-    courseId?: string;
-    /** Course display name (auto-filled from config if not provided) */
-    courseName?: string;
-    /** Student email address (optional) */
-    studentEmail?: string;
-    /** Application name for Caliper events (defaults to 'Game') */
-    appName?: string;
-    /** Sensor URL for Caliper events (defaults to baseUrl) */
-    sensorUrl?: string;
+interface HeartbeatRequestBase {
+    gameId: string;
+    studentId: string;
+    runId: string;
+    /**
+     * Per-session identifier.
+     *
+     * LEGACY SDK COMPATIBILITY (PR #711): optional because games deployed
+     * against the pre-resumable-sessions SDK do not send one. The
+     * platform falls back to `runId` when absent. Make this required
+     * once legacy SDK support is dropped.
+     */
+    resumeId?: string;
+    activityData: {
+        activityId: string;
+        activityName?: string;
+        grade: TimebackGrade;
+        subject: TimebackSubject;
+        appName?: string;
+        sensorUrl?: string;
+        courseId?: string;
+        /** The student's enrollment in `courseId`, sent by the SDK with the course hint. */
+        enrollmentId?: string;
+        courseName?: string;
+        studentEmail?: string;
+    };
+    timingData: {
+        activeMs: number;
+        pausedMs: number;
+    };
+    isFinal?: boolean;
 }
-/**
- * Score data for ending an activity
- */
-interface EndActivityScoreData {
-    /** Number of questions answered correctly */
-    correctQuestions: number;
-    /** Total number of questions */
-    totalQuestions: number;
+type HeartbeatWindowKey = {
     /**
-     * XP earned for this activity.
+     * Absolute start-of-window timestamp (epoch ms). Preferred dedupe key
+     * for the post-#711 SDK.
      *
-     * Required when the game reports directly (platform, demo, standalone).
-     * A child-launched game may omit it: narrow the client with the SDK's
-     * `isChildLaunched()` for the relaxed signature. The parent game
-     * decides the award, and a value provided here travels only as the
-     * `childXpSuggested` audit suggestion.
+     * LEGACY SDK COMPATIBILITY (PR #711): callers must provide exactly
+     * one of this field or `windowSequence`. Make this the only allowed
+     * field once legacy SDK support is dropped.
      */
-    xpAwarded: number;
+    windowStartedAtMs: number;
+    windowSequence?: never;
+} | {
+    windowStartedAtMs?: never;
     /**
-     * Incremental learning units mastered this session.
+     * LEGACY SDK COMPATIBILITY (PR #711).
      *
-     * Cannot be used with masteredUnitsAbsolute. When a course has mastery
-     * tracking configured, the platform bounds submissions that would move
-     * the student below 0 or above the configured masterableUnits maximum and
-     * returns warning metadata.
+     * Monotonic window counter emitted by the pre-resumable-sessions
+     * SDK. Remove this field once every deployed game has redeployed
+     * against the post-#711 SDK + edge-play runtime.
      */
-    masteredUnits?: number;
+    windowSequence: number;
+};
+type HeartbeatRequest = HeartbeatRequestBase & HeartbeatWindowKey;
+interface EndActivityRequest {
+    gameId: string;
+    studentId: string;
+    runId?: string;
     /**
-     * Absolute total of mastered units.
+     * Per-session identifier.
      *
-     * The platform computes the delta from the current value. Cannot be used
-     * with masteredUnits. When a course has mastery tracking configured, the
-     * platform bounds values outside 0..masterableUnits and returns warning
-     * metadata.
+     * LEGACY SDK COMPATIBILITY (PR #711): optional because games deployed
+     * against the pre-resumable-sessions SDK do not send one. The
+     * platform falls back to `runId`, or mints a server-side UUID, when
+     * absent. Make this required once legacy SDK support is dropped.
      */
+    resumeId?: string;
+    activityData: {
+        activityId: string;
+        activityName?: string;
+        grade: TimebackGrade;
+        subject: TimebackSubject;
+        appName?: string;
+        sensorUrl?: string;
+        courseId?: string;
+        /** The student's enrollment in `courseId`, sent by the SDK with the course hint. */
+        enrollmentId?: string;
+        courseName?: string;
+        studentEmail?: string;
+    };
+    scoreData: {
+        correctQuestions: number;
+        totalQuestions: number;
+    };
+    timingData: {
+        durationSeconds: number;
+    };
+    sessionTimingData?: {
+        activeSeconds: number;
+        inactiveSeconds?: number;
+    };
+    xpEarned: number;
+    masteredUnits?: number;
     masteredUnitsAbsolute?: number;
-    /** Optional arbitrary extensions to include in the Caliper event */
     extensions?: TimebackActivityExtensions;
 }
-
-/**
- * Caliper Protocol Types
- *
- * Types for the IMS Caliper Analytics standard used by TimeBack
- * for learning activity tracking.
- *
- * @module types/timeback/caliper
- */
-
-interface TimebackStoredCaliperMetric {
-    type: string;
-    value?: number;
-    subType?: string;
+interface EndActivityResponse {
+    status: 'ok';
+    /** The course the activity was recorded against. */
+    courseId: string;
+    /**
+     * `'hole_filling'` when the activity was recorded against a hole-filling
+     * course (the student is enrolled there, or the game passed its
+     * `courseId`); `'base'` otherwise.
+     */
+    courseKind?: GameTimebackIntegrationKind;
+    xpAwarded: number;
+    masteredUnits?: number;
+    pctCompleteApp?: number;
+    warnings?: MasteryWriteWarning[];
+    /**
+     * Set when this submission was stopped because a completion for the same
+     * run (`runId`) and activity had already been recorded — the platform's
+     * idempotency guard blocked a duplicate emit (PLA-142). This call awarded
+     * nothing new, but the award may well have happened: if the original
+     * response was lost in transit (e.g. a gateway timeout followed by an SDK
+     * retry), this is the only response the caller ever sees for a run that
+     * fully succeeded. The response therefore echoes what the run earned —
+     * `xpAwarded`, `masteredUnits`, and `pctCompleteApp` are the values
+     * recorded when the completion was confirmed (zeros, with no
+     * `pctCompleteApp`, only for runs recorded before award echoing existed).
+     * Treat it as "already recorded — here's what it earned", and do not
+     * count the run again.
+     */
+    blockedByDedupeGuard?: boolean;
 }
-interface TimebackStoredCaliperEntity {
-    id?: string;
-    type?: string;
-    name?: string;
-    email?: string;
-    app?: {
-        id?: string;
-        name?: string;
+interface StudentHighestGradeMasteredResponse {
+    /** Subject used for the highest-grade-mastered lookup */
+    subject: TimebackSubject;
+    /** EduBridge highestGradeOverall normalized to Playcademy's numeric grade type */
+    highestGradeMastered: TimebackGrade | null;
+    /** Normalized source grades returned by EduBridge for the rollup. */
+    grades: {
+        ritGrade: TimebackGrade | null;
+        edulasticGrade: TimebackGrade | null;
+        placementGrade: TimebackGrade | null;
+        testOutGrade: TimebackGrade | null;
+        highestGradeOverall: TimebackGrade | null;
     };
-    activity?: {
-        id?: string;
-        name?: string;
-        extensions?: Record<string, unknown> | null;
-    };
-    course?: {
-        id?: string;
-        name?: string;
-    };
-    items?: TimebackStoredCaliperMetric[];
-    extensions?: Record<string, unknown> | null;
-    [key: string]: unknown;
-}
-interface TimebackStoredCaliperEvent {
-    id: number;
-    externalId: string;
-    sensor: string;
-    type: string;
-    profile?: string;
-    action: string;
-    eventTime: string;
-    sendTime: string;
-    updated_at: string | null;
-    created_at: string;
-    deleted_at: string | null;
-    actor: TimebackStoredCaliperEntity;
-    object: TimebackStoredCaliperEntity;
-    generated?: TimebackStoredCaliperEntity | null;
-    target?: TimebackStoredCaliperEntity | null;
-    referrer?: TimebackStoredCaliperEntity | null;
-    edApp?: TimebackStoredCaliperEntity | null;
-    group?: TimebackStoredCaliperEntity | null;
-    membership?: TimebackStoredCaliperEntity | null;
-    session?: TimebackStoredCaliperEntity | null;
-    federatedSession?: TimebackStoredCaliperEntity | null;
-    extensions?: Record<string, unknown> | null;
-    clientAppId?: string | null;
 }
-
 /**
- * Game-side learning metrics for a single student.
- *
- * Returned by opted-in game workers from their reserved
- * `/__playcademy/metrics` route.
+ * Highest-ranking OneRoster account role for a user shown in the admin
+ * dashboard. Precedence: administrator > teacher > student. Accounts whose
+ * roles fall outside those three (aide, guardian, …) resolve to `null`.
  */
-interface GameMetricsResponse {
-    /** Student identifier (Playcademy user ID). */
+type TimebackAccountRole = 'administrator' | 'teacher' | 'student';
+interface TimebackRosterStudent {
     studentId: string;
-    /** Student email, when available to the game. */
-    email?: string;
-    /** Per-course metrics grouped by TimeBack grade and subject. */
-    courses: GameCourseMetrics[];
-}
-interface GameCourseMetrics {
-    /** Grade level matching the game's TimeBack integration. */
-    grade: TimebackGrade;
-    /** Subject matching the game's TimeBack integration. */
-    subject: TimebackSubject;
-    /** Total XP the game has recorded for this student in this course. */
-    totalXp?: number;
-    /** Mastered units the game has recorded for this course. */
-    masteredUnits?: number;
-    /** Total active time in seconds the game has recorded for this course. */
-    activeTimeSeconds?: number;
-    /** Optional per-run breakdown keyed by Timeback run ID. */
-    activities?: GameRunMetrics[];
-}
-interface GameRunMetrics {
-    runId: string;
-    activityId: string;
-    activityName?: string;
-    totalXp?: number;
-    masteredUnits?: number;
-    activeTimeSeconds?: number;
-    score?: number;
-}
-type GameMetricsUnsupportedReason = 'no_timeback_integration' | 'no_active_deployment' | 'route_not_implemented' | 'timeout' | 'fetch_failed' | 'invalid_response';
-type GameMetricsProxyResponse = {
-    supported: true;
-    metrics: GameMetricsResponse;
-} | {
-    supported: false;
-    reason: GameMetricsUnsupportedReason;
-    details?: string;
-};
-type GameMetricComparisonMetric = 'xp' | 'mastery' | 'time' | 'score';
-type GameMetricComparisonKind = 'number' | 'time' | 'percent';
-type GameMetricComparisonRowStatus = 'matched' | 'discrepant' | 'not_reported_by_game' | 'not_recorded_by_timeback';
-interface GameMetricComparisonRow {
-    metric: GameMetricComparisonMetric;
-    kind: GameMetricComparisonKind;
-    status: GameMetricComparisonRowStatus;
-    timebackValue?: number;
-    gameValue?: number;
-    delta?: number;
+    enrollmentId: string | null;
+    classId: string | null;
+    className: string | null;
+    name: string;
+    email: string | null;
+    primaryRole: TimebackAccountRole | null;
+    analyticsUnavailable: boolean;
+    totalXp: number;
+    todayXp: number;
+    activeTimeSeconds: number;
+    masteredUnits: number;
+    masterableUnits?: number;
+    pctCompleteApp?: number;
+    inactive?: boolean;
 }
-type GameRunMetricsComparisonStatus = 'matched' | 'discrepant' | 'not_reported' | 'unavailable';
-interface GameRunMetricsComparisonSummary {
-    runId: string;
-    status: GameRunMetricsComparisonStatus;
-    discrepancyCount: number;
-    reason?: GameMetricsUnsupportedReason;
+interface TimebackRosterResponse {
+    gameId: string;
+    courseId: string;
+    students: TimebackRosterStudent[];
 }
-interface GameRunMetricsComparison extends GameRunMetricsComparisonSummary {
-    rows: GameMetricComparisonRow[];
+interface TimebackStudentHistoryPoint {
+    date: string;
+    xpEarned: number;
+    activeTimeSeconds: number;
+    masteredUnits: number;
 }
-
-/**
- * QTI API Response Types
- *
- * Types for the QTI assessment content service responses.
- * These mirror the JSON structure returned by the QTI API
- * (beyond-qti-2) for assessment tests and items.
- *
- * @module types/timeback/qti
- */
-interface QtiItemRef {
-    identifier: string;
-    href: string;
-    sequence?: number;
+type CourseCompletionStatus = 'none' | 'complete' | 'incomplete';
+interface TimebackStudentEnrollmentSummary {
+    enrollmentId: string;
+    status: 'active' | 'tobedeleted';
+    beginDate: string | null;
+    endDate: string | null;
+    analyticsUnavailable: boolean;
+    totalXp: number;
+    todayXp: number;
+    activeTimeSeconds: number;
+    masteredUnits: number;
+    pctCompleteApp?: number;
+    history: TimebackStudentHistoryPoint[];
 }
-interface QtiAssessmentSection {
-    identifier: string;
+interface TimebackStudentCourseOverview {
+    courseId: string;
     title: string;
-    visible?: boolean;
-    required?: boolean;
-    fixed?: boolean;
-    sequence?: number;
-    'qti-assessment-item-ref'?: QtiItemRef[];
+    grade: number;
+    subject: string;
+    enrollmentId: string | null;
+    analyticsUnavailable: boolean;
+    totalXp: number;
+    todayXp: number;
+    activeTimeSeconds: number;
+    masteredUnits: number;
+    masterableUnits?: number;
+    pctCompleteApp?: number;
+    completionStatus: CourseCompletionStatus;
+    history: TimebackStudentHistoryPoint[];
+    inactive?: boolean;
+    /** All enrollment records for this course, sorted active-first then by most recent. */
+    enrollments?: TimebackStudentEnrollmentSummary[];
 }
-interface QtiTestPart {
-    identifier: string;
-    navigationMode: 'linear' | 'nonlinear';
-    submissionMode: 'individual' | 'simultaneous';
-    'qti-assessment-section': QtiAssessmentSection[];
+type TimebackRecentActivityKind = 'activity' | 'activity-in-progress' | 'time-spent' | 'remediation-xp' | 'remediation-time' | 'remediation-mastery' | 'course-completed' | 'course-resumed';
+interface TimebackRecentActivity {
+    id: string;
+    kind: TimebackRecentActivityKind;
+    occurredAt: string;
+    courseId: string;
+    title: string;
+    activityId?: string;
+    appName?: string;
+    reason?: string;
+    score?: number;
+    xpDelta?: number;
+    timeDeltaSeconds?: number;
+    masteredUnitsDelta?: number;
+    runId?: string;
+    sessionCount?: number;
+    gameMetricsComparison?: GameRunMetricsComparisonSummary;
+    gameMetricsVerification?: TimebackMetricDiscrepancyVerification;
 }
-interface QtiOutcomeDeclaration {
-    identifier: string;
-    cardinality?: 'single' | 'multiple' | 'ordered' | 'record';
-    baseType: 'boolean' | 'directedPair' | 'duration' | 'file' | 'float' | 'identifier' | 'integer' | 'pair' | 'point' | 'string' | 'uri';
-    normalMaximum?: number;
-    normalMinimum?: number;
-    defaultValue?: {
-        value?: unknown;
+interface TimebackStudentOverviewResponse {
+    student: {
+        studentId: string;
+        name: string;
+        email: string | null;
     };
+    courses: TimebackStudentCourseOverview[];
 }
-interface QtiAssessmentTest {
-    identifier: string;
-    title: string;
-    qtiVersion?: string;
-    timeLimit?: number;
-    maxAttempts?: number;
-    toolsEnabled?: Record<string, boolean>;
-    'qti-test-part': QtiTestPart[];
-    'qti-outcome-declaration'?: QtiOutcomeDeclaration[];
-    metadata?: Record<string, unknown>;
-    rawXml?: string;
-    content?: Record<string, unknown>;
-    createdAt?: string;
-    updatedAt?: string;
+interface TimebackStudentActivityResponse {
+    activities: TimebackRecentActivity[];
+    hasMore: boolean;
 }
-interface QtiAssessmentTestListResponse {
-    items: QtiAssessmentTest[];
-    total: number;
-    page: number;
-    pages: number;
-    limit: number;
-    sort: string;
-    order: 'asc' | 'desc';
+interface TimebackActivityDetailResponse {
+    activity: TimebackRecentActivity;
+    rawEvents: TimebackStoredCaliperEvent[];
+    gameMetricsComparison?: GameRunMetricsComparison;
 }
-interface QtiResponseDeclaration {
-    identifier: string;
-    cardinality: 'single' | 'multiple' | 'ordered';
-    baseType: string;
-    correctResponse?: {
-        value: string[];
-    };
+interface TimebackGradeLevelTestStudent {
+    studentId: string;
+    name: string;
+    email: string | null;
 }
-interface QtiAssessmentItem {
-    identifier: string;
-    title: string;
-    type?: string;
-    qtiVersion?: string;
-    timeDependent?: boolean;
-    adaptive?: boolean;
-    preInteraction?: string;
-    interaction?: Record<string, unknown>;
-    postInteraction?: string;
-    responseDeclarations?: QtiResponseDeclaration[];
-    outcomeDeclarations?: QtiOutcomeDeclaration[];
-    responseProcessing?: Record<string, unknown>;
-    metadata?: Record<string, unknown>;
-    modalFeedback?: unknown[];
-    feedbackInline?: unknown[];
-    feedbackBlock?: unknown[];
-    rubrics?: unknown[];
-    stimulus?: unknown;
-    rawXml?: string;
-    content?: Record<string, unknown>;
-    createdAt?: string;
-    updatedAt?: string;
-}
-interface QtiAssessmentItemListResponse {
-    items: QtiAssessmentItem[];
-    total: number;
-    page: number;
-    pages: number;
-    limit: number;
-    sort: string;
-    order: 'asc' | 'desc';
+interface TimebackGradeLevelTestStandardRef {
+    source: string;
+    id: string;
+    identifier?: string;
+    name?: string;
+    description?: string;
+    domain?: string;
 }
-/** Request an exact, independently owned copy through the normal question collection endpoint. */
-interface QtiQuestionCopyCreateInput {
-    mode: 'copy';
-    sourceItemIdentifier: string;
+interface TimebackGradeLevelTestStandardSummary extends TimebackGradeLevelTestStandardRef {
+    attempted: number;
+    missed: number;
 }
-type QtiQuestionCreateInput = QtiQuestionCopyCreateInput | Record<string, unknown>;
-interface QtiTestQuestionRef {
-    ownership?: 'owned' | 'shared';
-    reference: {
-        identifier: string;
-        href: string;
-        testPart: string;
-        section: string;
-    };
-    question: QtiAssessmentItem;
+interface TimebackGradeLevelTestSummary {
+    resultId: string;
+    lineItemId: string;
+    studentId: string;
+    testName: string;
+    testType: string;
+    provider: string;
+    subject: string;
+    grade: number | null;
+    score: number | null;
+    scorePercentile: number | null;
+    scoreStatus: string;
+    scoreDate: string | null;
+    assignmentId?: string;
+    qtiTestId?: string;
+    questionCount?: number;
+    correctQuestionCount?: number;
 }
-interface QtiTestQuestionsResponse {
-    assessmentTest: string;
+type TimebackGradeLevelQuestionCorrectness = 'correct' | 'incorrect' | 'partial' | 'unknown';
+interface TimebackGradeLevelTestQuestionResult {
+    lineItemId: string;
+    resultId: string | null;
     title: string;
-    totalQuestions: number;
-    questions: QtiTestQuestionRef[];
-}
-
-/**
- * TimeBack API Request/Response Types
- *
- * Types for TimeBack API endpoints including XP tracking,
- * setup, verification, and activity completion.
- *
- * @module types/timeback/api
- */
-
-interface PopulateStudentResponse {
-    status: string;
-    message?: string;
+    description?: string;
+    correctness: TimebackGradeLevelQuestionCorrectness;
+    score: number | null;
+    scorePercentile: number | null;
+    scoreStatus: string | null;
+    standards: TimebackGradeLevelTestStandardRef[];
+    qtiQuestion?: QtiTestQuestionRef | null;
+    feedback?: string | null;
 }
-interface TimebackSetupRequest {
+interface TimebackGradeLevelTestResultsResponse {
     gameId: string;
-    config: {
-        organization: {
-            name: string;
-            type: string;
-            identifier: string;
-        };
-        course: {
-            title: string;
-            subjects: string[];
-            grades: number[];
-            courseCode: string;
-            level: string;
-            gradingScheme: string;
-            metadata?: Record<string, unknown>;
-        };
-        component: {
-            title: string;
-            sortOrder: number;
-            prerequisites: string[];
-            prerequisiteCriteria: string;
-        };
-        resource: {
-            title: string;
-            vendorResourceId: string;
-            vendorId: string;
-            applicationId: string;
-            roles: string[];
-            importance: string;
-            metadata: {
-                type?: string;
-                launchUrl?: string;
-                toolProvider?: string;
-                instructionalMethod?: string;
-                subject?: string;
-                grades?: number[];
-                language?: string;
-                xp?: number;
-                [key: string]: unknown;
-            };
-        };
-        componentResource: {
-            title: string;
-            sortOrder: number;
-            lessonType: string | null;
-        };
-    };
-    verbose?: boolean;
+    courseId: string;
+    subject: TimebackSubject;
+    grade: TimebackGrade;
+    student: TimebackGradeLevelTestStudent;
+    highestGradeMastered: StudentHighestGradeMasteredResponse | null;
+    results: TimebackGradeLevelTestSummary[];
 }
-interface PlatformTimebackSetupRequest {
-    gameId: string;
-    courses: DerivedPlatformCourseConfig[];
-    baseConfig: {
-        organization: {
-            name: string;
-            type: string;
-            identifier: string;
-        };
-        component: {
-            title: string;
-            titleSuffix?: string;
-            sortOrder: number;
-            prerequisites: string[];
-            prerequisiteCriteria: string;
-        };
-        resource: {
-            title: string;
-            titleSuffix?: string;
-            vendorResourceId: string;
-            vendorId: string;
-            applicationId: string;
-            roles: string[];
-            importance: string;
-            metadata: {
-                type?: string;
-                launchUrl?: string;
-                toolProvider?: string;
-                instructionalMethod?: string;
-                language?: string;
-                [key: string]: unknown;
-            };
-        };
-        componentResource: {
-            title: string;
-            titleSuffix?: string;
-            sortOrder: number;
-            lessonType: string | null;
-        };
-    };
-    verbose?: boolean;
+interface TimebackGradeLevelTestReviewResponse {
+    parentResultId: string;
+    parentLineItemId: string;
+    studentId: string;
+    qtiQuestionCount: number;
+    questions: TimebackGradeLevelTestQuestionResult[];
+    standards: TimebackGradeLevelTestStandardSummary[];
 }
-interface PlatformTimebackSetupResponse {
-    integrations: GameTimebackIntegration[];
-    verbose?: {
-        integration: GameTimebackIntegration;
-        config: {
-            course: unknown;
-            component: unknown;
-            resource: unknown;
-            componentResource: unknown;
-        };
-    }[];
+type TimebackDiscrepancyQueueWindow = 'all' | 'today' | 'yesterday' | 'this-week' | 'last-week' | 'custom';
+interface TimebackDiscrepancyQueueDateRange {
+    startDate?: string;
+    endDate?: string;
 }
-interface GameTimebackIntegration {
-    id: string;
+interface TimebackMetricDiscrepancyVerification {
     gameId: string;
     courseId: string;
-    grade: number;
-    subject: string;
-    status?: 'active' | 'deactivated';
-    totalXp?: number | null;
-    lastVerifiedAt?: Date | null;
-    deactivatedAt?: Date | null;
-    reactivatedAt?: Date | null;
-    createdAt: Date;
-    updatedAt: Date;
+    studentId: string;
+    runId: string;
+    activityId?: string | null;
+    verifiedAt: string;
+    verifiedByUserId?: string | null;
 }
-interface RemovedGameTimebackIntegration {
-    integration: GameTimebackIntegration;
-    title: string;
-    courseCode: string;
-    subject: TimebackSubject;
-    grade: number;
-    totalXp?: number | null;
-    masterableUnits?: number | null;
-    removedAt?: Date | string | null;
-    metadata?: CourseMetadata | null;
+interface TimebackDiscrepancyQueueStudent {
+    studentId: string;
+    name: string;
+    email: string | null;
 }
-interface GameTimebackIntegrationConfig {
-    integration: GameTimebackIntegration;
-    title: string;
-    courseCode: string;
-    subject: TimebackSubject;
-    totalXp?: number | null;
-    masterableUnits?: number | null;
-    metadata?: CourseMetadata | null;
-}
-interface UpdateGameTimebackIntegrationRequest {
-    title?: string;
-    courseCode?: string;
-    subject?: TimebackSubject;
-    totalXp?: number | null;
-    masterableUnits?: number | null;
-    goals?: Partial<Record<keyof CourseGoals, number | null>> | null;
-    publishStatus?: string | null;
-    isSupplemental?: boolean;
-    timebackVisible?: boolean | null;
+interface TimebackDiscrepancyQueueEventPage {
+    offset: number;
+    limit: number;
+    total: number;
+    hasPrevious: boolean;
+    hasNext: boolean;
 }
-interface CreateGameTimebackIntegrationRequest {
-    title: string;
-    courseCode: string;
-    subject: TimebackSubject;
-    grade: TimebackGrade;
-    totalXp: number;
-    masterableUnits: number;
-    level?: string;
+interface TimebackMetricDiscrepancyQueueItem {
+    student: TimebackDiscrepancyQueueStudent;
+    activity: TimebackRecentActivity;
+    gameMetricsComparison: GameRunMetricsComparison;
+    verification?: TimebackMetricDiscrepancyVerification;
+    comparisonSource?: 'hydrated' | 'preliminary';
 }
-interface TimebackVerificationResources {
-    course: {
-        found: boolean;
-        data?: unknown;
-    };
-    component: {
-        found: boolean;
-        data?: unknown;
-    };
-    resource: {
-        found: boolean;
-        data?: unknown;
-    };
-    componentResource: {
-        found: boolean;
-        data?: unknown;
-    };
+interface TimebackMetricDiscrepancyQueueResponse {
+    gameId: string;
+    courseId: string;
+    window: TimebackDiscrepancyQueueWindow;
+    dateRange: TimebackDiscrepancyQueueDateRange;
+    studentId?: string;
+    students: TimebackDiscrepancyQueueStudent[];
+    discrepancyMetricScopes: GameMetricComparisonMetric[];
+    eventPage: TimebackDiscrepancyQueueEventPage;
+    includeVerified: boolean;
+    items: TimebackMetricDiscrepancyQueueItem[];
 }
-interface TimebackVerifyCourseResult {
-    integration: GameTimebackIntegration;
-    resources: TimebackVerificationResources;
-    status: 'success' | 'error';
-    errors?: string[];
+interface VerifyTimebackMetricDiscrepancyRequest {
+    studentId: string;
+    runId: string;
+    activityId?: string;
 }
-interface TimebackVerifyAllResponse {
-    status: 'success' | 'error';
-    results: TimebackVerifyCourseResult[];
+interface VerifyTimebackMetricDiscrepancyResponse {
+    status: 'ok';
+    verification: TimebackMetricDiscrepancyVerification;
 }
-interface HeartbeatRequestBase {
+interface GrantTimebackXpRequest {
     gameId: string;
+    courseId: string;
     studentId: string;
-    runId: string;
-    /**
-     * Per-session identifier.
-     *
-     * LEGACY SDK COMPATIBILITY (PR #711): optional because games deployed
-     * against the pre-resumable-sessions SDK do not send one. The
-     * platform falls back to `runId` when absent. Make this required
-     * once legacy SDK support is dropped.
-     */
-    resumeId?: string;
-    activityData: {
-        activityId: string;
-        activityName?: string;
-        grade: TimebackGrade;
-        subject: TimebackSubject;
-        appName?: string;
-        sensorUrl?: string;
-        courseId?: string;
-        courseName?: string;
-        studentEmail?: string;
-    };
-    timingData: {
-        activeMs: number;
-        pausedMs: number;
-    };
-    isFinal?: boolean;
+    xp: number;
+    reason: string;
+    date?: string;
+    useCurrentTime?: boolean;
 }
-type HeartbeatWindowKey = {
-    /**
-     * Absolute start-of-window timestamp (epoch ms). Preferred dedupe key
-     * for the post-#711 SDK.
-     *
-     * LEGACY SDK COMPATIBILITY (PR #711): callers must provide exactly
-     * one of this field or `windowSequence`. Make this the only allowed
-     * field once legacy SDK support is dropped.
-     */
-    windowStartedAtMs: number;
-    windowSequence?: never;
-} | {
-    windowStartedAtMs?: never;
-    /**
-     * LEGACY SDK COMPATIBILITY (PR #711).
-     *
-     * Monotonic window counter emitted by the pre-resumable-sessions
-     * SDK. Remove this field once every deployed game has redeployed
-     * against the post-#711 SDK + edge-play runtime.
-     */
-    windowSequence: number;
-};
-type HeartbeatRequest = HeartbeatRequestBase & HeartbeatWindowKey;
-interface EndActivityRequest {
+interface AdjustTimebackTimeRequest {
     gameId: string;
+    courseId: string;
     studentId: string;
-    runId?: string;
-    /**
-     * Per-session identifier.
-     *
-     * LEGACY SDK COMPATIBILITY (PR #711): optional because games deployed
-     * against the pre-resumable-sessions SDK do not send one. The
-     * platform falls back to `runId`, or mints a server-side UUID, when
-     * absent. Make this required once legacy SDK support is dropped.
-     */
-    resumeId?: string;
-    activityData: {
-        activityId: string;
-        activityName?: string;
-        grade: TimebackGrade;
-        subject: TimebackSubject;
-        appName?: string;
-        sensorUrl?: string;
-        courseId?: string;
-        courseName?: string;
-        studentEmail?: string;
-    };
-    scoreData: {
-        correctQuestions: number;
-        totalQuestions: number;
-    };
-    timingData: {
-        durationSeconds: number;
-    };
-    sessionTimingData?: {
-        activeSeconds: number;
-        inactiveSeconds?: number;
-    };
-    xpEarned: number;
-    masteredUnits?: number;
-    masteredUnitsAbsolute?: number;
-    extensions?: TimebackActivityExtensions;
+    seconds: number;
+    reason: string;
+    date?: string;
+    /** See {@link GrantTimebackXpRequest.useCurrentTime}. */
+    useCurrentTime?: boolean;
 }
-interface EndActivityResponse {
-    status: 'ok';
+interface AdjustTimebackMasteryRequest {
+    gameId: string;
     courseId: string;
-    xpAwarded: number;
-    masteredUnits?: number;
-    pctCompleteApp?: number;
-    warnings?: MasteryWriteWarning[];
-    /**
-     * Set when this submission was stopped because a completion for the same
-     * run (`runId`) and activity had already been recorded — the platform's
-     * idempotency guard blocked a duplicate emit (PLA-142). This call awarded
-     * nothing new, but the award may well have happened: if the original
-     * response was lost in transit (e.g. a gateway timeout followed by an SDK
-     * retry), this is the only response the caller ever sees for a run that
-     * fully succeeded. The response therefore echoes what the run earned —
-     * `xpAwarded`, `masteredUnits`, and `pctCompleteApp` are the values
-     * recorded when the completion was confirmed (zeros, with no
-     * `pctCompleteApp`, only for runs recorded before award echoing existed).
-     * Treat it as "already recorded — here's what it earned", and do not
-     * count the run again.
-     */
-    blockedByDedupeGuard?: boolean;
+    studentId: string;
+    units: number;
+    reason: string;
+    date?: string;
+    /** See {@link GrantTimebackXpRequest.useCurrentTime}. */
+    useCurrentTime?: boolean;
 }
-interface StudentHighestGradeMasteredResponse {
-    /** Subject used for the highest-grade-mastered lookup */
-    subject: TimebackSubject;
-    /** EduBridge highestGradeOverall normalized to Playcademy's numeric grade type */
-    highestGradeMastered: TimebackGrade | null;
-    /** Normalized source grades returned by EduBridge for the rollup. */
-    grades: {
-        ritGrade: TimebackGrade | null;
-        edulasticGrade: TimebackGrade | null;
-        placementGrade: TimebackGrade | null;
-        testOutGrade: TimebackGrade | null;
-        highestGradeOverall: TimebackGrade | null;
-    };
+interface EnrollStudentRequest {
+    gameId: string;
+    courseId: string;
+    studentIds: string[];
 }
-/**
- * Highest-ranking OneRoster account role for a user shown in the admin
- * dashboard. Precedence: administrator > teacher > student. Accounts whose
- * roles fall outside those three (aide, guardian, …) resolve to `null`.
- */
-type TimebackAccountRole = 'administrator' | 'teacher' | 'student';
-interface TimebackRosterStudent {
+interface EnrollStudentResult {
     studentId: string;
-    enrollmentId: string | null;
-    classId: string | null;
-    className: string | null;
-    name: string;
-    email: string | null;
-    primaryRole: TimebackAccountRole | null;
-    analyticsUnavailable: boolean;
-    totalXp: number;
-    todayXp: number;
-    activeTimeSeconds: number;
-    masteredUnits: number;
-    masterableUnits?: number;
-    pctCompleteApp?: number;
-    inactive?: boolean;
+    status: 'ok' | 'already-enrolled' | 'not-found' | 'error';
+    error?: string;
 }
-interface TimebackRosterResponse {
+interface EnrollStudentResponse {
+    results: EnrollStudentResult[];
+}
+interface ReactivateEnrollmentRequest {
     gameId: string;
     courseId: string;
-    students: TimebackRosterStudent[];
-}
-interface TimebackStudentHistoryPoint {
-    date: string;
-    xpEarned: number;
-    activeTimeSeconds: number;
-    masteredUnits: number;
-}
-type CourseCompletionStatus = 'none' | 'complete' | 'incomplete';
-interface TimebackStudentEnrollmentSummary {
-    enrollmentId: string;
-    status: 'active' | 'tobedeleted';
-    beginDate: string | null;
-    endDate: string | null;
-    analyticsUnavailable: boolean;
-    totalXp: number;
-    todayXp: number;
-    activeTimeSeconds: number;
-    masteredUnits: number;
-    pctCompleteApp?: number;
-    history: TimebackStudentHistoryPoint[];
-}
-interface TimebackStudentCourseOverview {
-    courseId: string;
-    title: string;
-    grade: number;
-    subject: string;
-    enrollmentId: string | null;
-    analyticsUnavailable: boolean;
-    totalXp: number;
-    todayXp: number;
-    activeTimeSeconds: number;
-    masteredUnits: number;
-    masterableUnits?: number;
-    pctCompleteApp?: number;
-    completionStatus: CourseCompletionStatus;
-    history: TimebackStudentHistoryPoint[];
-    inactive?: boolean;
-    /** All enrollment records for this course, sorted active-first then by most recent. */
-    enrollments?: TimebackStudentEnrollmentSummary[];
-}
-type TimebackRecentActivityKind = 'activity' | 'activity-in-progress' | 'time-spent' | 'remediation-xp' | 'remediation-time' | 'remediation-mastery' | 'course-completed' | 'course-resumed';
-interface TimebackRecentActivity {
-    id: string;
-    kind: TimebackRecentActivityKind;
-    occurredAt: string;
-    courseId: string;
-    title: string;
-    activityId?: string;
-    appName?: string;
-    reason?: string;
-    score?: number;
-    xpDelta?: number;
-    timeDeltaSeconds?: number;
-    masteredUnitsDelta?: number;
-    runId?: string;
-    sessionCount?: number;
-    gameMetricsComparison?: GameRunMetricsComparisonSummary;
-    gameMetricsVerification?: TimebackMetricDiscrepancyVerification;
-}
-interface TimebackStudentOverviewResponse {
-    student: {
-        studentId: string;
-        name: string;
-        email: string | null;
-    };
-    courses: TimebackStudentCourseOverview[];
-}
-interface TimebackStudentActivityResponse {
-    activities: TimebackRecentActivity[];
-    hasMore: boolean;
-}
-interface TimebackActivityDetailResponse {
-    activity: TimebackRecentActivity;
-    rawEvents: TimebackStoredCaliperEvent[];
-    gameMetricsComparison?: GameRunMetricsComparison;
-}
-interface TimebackGradeLevelTestStudent {
-    studentId: string;
-    name: string;
-    email: string | null;
-}
-interface TimebackGradeLevelTestStandardRef {
-    source: string;
-    id: string;
-    identifier?: string;
-    name?: string;
-    description?: string;
-    domain?: string;
-}
-interface TimebackGradeLevelTestStandardSummary extends TimebackGradeLevelTestStandardRef {
-    attempted: number;
-    missed: number;
-}
-interface TimebackGradeLevelTestSummary {
-    resultId: string;
-    lineItemId: string;
-    studentId: string;
-    testName: string;
-    testType: string;
-    provider: string;
-    subject: string;
-    grade: number | null;
-    score: number | null;
-    scorePercentile: number | null;
-    scoreStatus: string;
-    scoreDate: string | null;
-    assignmentId?: string;
-    qtiTestId?: string;
-    questionCount?: number;
-    correctQuestionCount?: number;
-}
-type TimebackGradeLevelQuestionCorrectness = 'correct' | 'incorrect' | 'partial' | 'unknown';
-interface TimebackGradeLevelTestQuestionResult {
-    lineItemId: string;
-    resultId: string | null;
-    title: string;
-    description?: string;
-    correctness: TimebackGradeLevelQuestionCorrectness;
-    score: number | null;
-    scorePercentile: number | null;
-    scoreStatus: string | null;
-    standards: TimebackGradeLevelTestStandardRef[];
-    qtiQuestion?: QtiTestQuestionRef | null;
-    feedback?: string | null;
-}
-interface TimebackGradeLevelTestResultsResponse {
-    gameId: string;
-    courseId: string;
-    subject: TimebackSubject;
-    grade: TimebackGrade;
-    student: TimebackGradeLevelTestStudent;
-    highestGradeMastered: StudentHighestGradeMasteredResponse | null;
-    results: TimebackGradeLevelTestSummary[];
-}
-interface TimebackGradeLevelTestReviewResponse {
-    parentResultId: string;
-    parentLineItemId: string;
-    studentId: string;
-    qtiQuestionCount: number;
-    questions: TimebackGradeLevelTestQuestionResult[];
-    standards: TimebackGradeLevelTestStandardSummary[];
-}
-type TimebackDiscrepancyQueueWindow = 'all' | 'today' | 'yesterday' | 'this-week' | 'last-week' | 'custom';
-interface TimebackDiscrepancyQueueDateRange {
-    startDate?: string;
-    endDate?: string;
-}
-interface TimebackMetricDiscrepancyVerification {
-    gameId: string;
-    courseId: string;
-    studentId: string;
-    runId: string;
-    activityId?: string | null;
-    verifiedAt: string;
-    verifiedByUserId?: string | null;
-}
-interface TimebackDiscrepancyQueueStudent {
-    studentId: string;
-    name: string;
-    email: string | null;
-}
-interface TimebackDiscrepancyQueueEventPage {
-    offset: number;
-    limit: number;
-    total: number;
-    hasPrevious: boolean;
-    hasNext: boolean;
-}
-interface TimebackMetricDiscrepancyQueueItem {
-    student: TimebackDiscrepancyQueueStudent;
-    activity: TimebackRecentActivity;
-    gameMetricsComparison: GameRunMetricsComparison;
-    verification?: TimebackMetricDiscrepancyVerification;
-    comparisonSource?: 'hydrated' | 'preliminary';
-}
-interface TimebackMetricDiscrepancyQueueResponse {
-    gameId: string;
-    courseId: string;
-    window: TimebackDiscrepancyQueueWindow;
-    dateRange: TimebackDiscrepancyQueueDateRange;
-    studentId?: string;
-    students: TimebackDiscrepancyQueueStudent[];
-    discrepancyMetricScopes: GameMetricComparisonMetric[];
-    eventPage: TimebackDiscrepancyQueueEventPage;
-    includeVerified: boolean;
-    items: TimebackMetricDiscrepancyQueueItem[];
-}
-interface VerifyTimebackMetricDiscrepancyRequest {
-    studentId: string;
-    runId: string;
-    activityId?: string;
-}
-interface VerifyTimebackMetricDiscrepancyResponse {
-    status: 'ok';
-    verification: TimebackMetricDiscrepancyVerification;
-}
-interface GrantTimebackXpRequest {
-    gameId: string;
-    courseId: string;
-    studentId: string;
-    xp: number;
-    reason: string;
-    date?: string;
-    useCurrentTime?: boolean;
-}
-interface AdjustTimebackTimeRequest {
-    gameId: string;
-    courseId: string;
-    studentId: string;
-    seconds: number;
-    reason: string;
-    date?: string;
-    /** See {@link GrantTimebackXpRequest.useCurrentTime}. */
-    useCurrentTime?: boolean;
-}
-interface AdjustTimebackMasteryRequest {
-    gameId: string;
-    courseId: string;
-    studentId: string;
-    units: number;
-    reason: string;
-    date?: string;
-    /** See {@link GrantTimebackXpRequest.useCurrentTime}. */
-    useCurrentTime?: boolean;
-}
-interface EnrollStudentRequest {
-    gameId: string;
-    courseId: string;
-    studentIds: string[];
-}
-interface EnrollStudentResult {
-    studentId: string;
-    status: 'ok' | 'already-enrolled' | 'not-found' | 'error';
-    error?: string;
-}
-interface EnrollStudentResponse {
-    results: EnrollStudentResult[];
-}
-interface ReactivateEnrollmentRequest {
-    gameId: string;
-    courseId: string;
-    studentId: string;
-    enrollmentId: string;
+    studentId: string;
+    enrollmentId: string;
 }
 interface UnenrollStudentRequest {
     gameId: string;
@@ -2891,230 +2175,1013 @@ interface StartAssessmentInputBase {
     subject?: TimebackSubject;
     grade?: TimebackGrade;
 }
-interface StartFixedAssessmentInput extends StartAssessmentInputBase {
-    purpose: Exclude<UnscopedFixedAssessmentPurpose, 'diagnostic'>;
+interface StartFixedAssessmentInput extends StartAssessmentInputBase {
+    purpose: Exclude<UnscopedFixedAssessmentPurpose, 'diagnostic'>;
+}
+interface StartDiagnosticAssessmentInput extends StartAssessmentInputBase {
+    purpose: 'diagnostic';
+    /** Stable authored diagnostic identity, independent of the selected QTI test identifier. */
+    diagnosticKey: string;
+}
+interface StartMasteryAssessmentInput extends StartAssessmentInputBase {
+    purpose: 'mastery';
+    standard: AssessmentStandardRef;
+}
+interface StartReviewAssessmentInput extends StartAssessmentInputBase {
+    purpose: 'review';
+    /** Serving order; duplicate canonical skills keep their first position. Pinned on start. */
+    standards: AssessmentReviewStandard[];
+    /** Candidate capacity per standard; preloaded candidates are not administered automatically. */
+    candidateItemsPerStandard?: number;
+}
+type StartAssessmentInput = StartFixedAssessmentInput | StartDiagnosticAssessmentInput | StartMasteryAssessmentInput | StartReviewAssessmentInput;
+/** Transport metadata for attempting a prepared new-assessment start. */
+interface StartAssessmentOptions {
+    preparationReceipt?: string;
+}
+/** Result of preparing the immediate next assessment request. */
+type AssessmentPreparationResult = {
+    status: 'prepared';
+    receipt: string;
+    /** Receipt expiry as an ISO-8601 timestamp. */
+    expiresAt: string;
+} | {
+    status: 'unprepared';
+    reason: 'artifact_unavailable' | 'prerequisite_unavailable' | 'local_runtime';
+};
+interface SaveAssessmentInput {
+    expectedResponseVersion: number;
+    /** Complete active draft; success acknowledges its durable parent checkpoint. */
+    transcript: AssessmentTranscript;
+}
+/** Best-effort mastery progress, not an answer commitment or an explicit checkpoint. */
+interface RecordAssessmentProgressInput {
+    assessmentToken: string;
+    expectedResponseVersion: number;
+    /** Current raw draft, including the editable administration being projected. */
+    transcript: AssessmentTranscript;
+    itemIdentifier: string;
+}
+interface SubmitAssessmentItemInputBase {
+    assessmentToken: string;
+    /** The raw prefix preceding this administration (or including it for an exact retry). */
+    transcript: AssessmentTranscript;
+    expectedResponseVersion: number;
+    /** Stable across every retry of this exact item submission. */
+    submissionId: string;
+    itemIdentifier: string;
+    responses: Record<string, AssessmentResponseValue | null>;
+}
+interface SubmitReviewAssessmentItemInput extends SubmitAssessmentItemInputBase {
+    routingNodeKey?: never;
+}
+interface SubmitDiagnosticAssessmentItemInput extends SubmitAssessmentItemInputBase {
+    /** Canonical routing-context identity returned in routing.next. */
+    routingNodeKey: string;
+}
+type SubmitAssessmentItemInput = SubmitReviewAssessmentItemInput | SubmitDiagnosticAssessmentItemInput;
+interface SubmitReviewAssessmentItemResult {
+    attemptId: string;
+    responseVersion: number;
+    status: 'in_progress';
+    responses: AssessmentResponses;
+    /** Canonical ledger after commit or replay; replace local state with it. */
+    itemSubmissions: AssessmentItemSubmission[];
+    submission: AssessmentItemSubmission;
+    transcript: AssessmentTranscript;
+}
+/** Safe acknowledgement for one immutable diagnostic item commitment. */
+interface DiagnosticAssessmentItemReceipt {
+    submissionId: string;
+    routingNodeKey: string;
+    itemIdentifier: string;
+    submittedAt: string;
+    responseVersion: number;
+    answered: boolean;
+    score: AssessmentScore;
+    isCorrect: boolean;
+}
+/** Canonical post-commit routing state plus trusted feedback for this administration. */
+interface SubmitDiagnosticAssessmentItemResult {
+    attemptId: string;
+    responseVersion: number;
+    status: 'in_progress';
+    routing: DiagnosticRoutingSnapshot;
+    submission: DiagnosticAssessmentItemReceipt;
+    transcript: AssessmentTranscript;
+}
+type SubmitAssessmentItemResult = SubmitReviewAssessmentItemResult | SubmitDiagnosticAssessmentItemResult;
+interface SubmitAssessmentInput {
+    expectedResponseVersion: number;
+    submissionId: string;
+    transcript: AssessmentTranscript;
+}
+/** The optional mastery portion of a finalize award; at most one field is set. */
+interface AssessmentMasteryAward {
+    /**
+     * Incremental learning units mastered by this attempt. Cannot be combined
+     * with masteredUnitsAbsolute. The platform bounds the delta against the
+     * course's configured masterableUnits and returns any warning.
+     */
+    masteredUnits?: number;
+    /**
+     * Absolute mastered-unit total after this attempt; the platform computes
+     * the delta. Cannot be combined with masteredUnits.
+     */
+    masteredUnitsAbsolute?: number;
+}
+interface FinalizeAssessmentInput extends AssessmentMasteryAward {
+    submissionId: string;
+    /** Explicit zero is an award; omission is never interpreted as zero. */
+    xpAwarded: number;
+}
+/**
+ * The award a game supplied at finalization, retained verbatim so a retried
+ * finalize can be told apart from a contradictory one even after bounding
+ * changed what was actually applied.
+ */
+interface AssessmentAwardRecord extends AssessmentMasteryAward {
+    xpAwarded: number;
+    /** The bounded mastery delta the platform recorded for this attempt. */
+    masteredUnitsApplied: number;
+    pctCompleteApp?: number;
+    warnings?: MasteryWriteWarning[];
+}
+/** One scored region for host-only point-response fixture scoring. */
+interface AssessmentResponseArea {
+    shape: PlayableAssessmentShape;
+    coords: number[];
+    /** The region's mapped point value (1 when omitted). */
+    value?: number;
+}
+/** One host-only assessment entry exported for the local runtime provider. */
+interface AssessmentRuntimeFixtureTest {
+    id: string;
+    assessmentKey: string;
+    qtiTestIdentifier: string;
+    live: boolean;
+    /** Canonical quiz-level alignment used by mastery selection. */
+    standard: AssessmentStandardRef | null;
+    assessment: PlayableAssessment;
+    /** Private comparison rules retained for hosted-equivalent local scoring when available. */
+    scoring?: AssessmentScoringArtifactV1;
+    /** Correct responses are retained by the host and are never returned to the game. */
+    correctResponses: AssessmentResponses;
+    /**
+     * Host-only scored regions for point responses (select-point, position-object),
+     * keyed by item then response identifier. A point response is correct when every
+     * point lands in a distinct scored region.
+     */
+    responseAreas?: Record<string, Record<string, AssessmentResponseArea[]>>;
+    /** Host-only platform-routing sidecar for one immutable diagnostic bank revision. */
+    diagnostic?: {
+        diagnosticKey: string;
+        /** Calculated from the canonical manifest when the fixture is built. */
+        routingRevision: string;
+        routingManifest: DiagnosticRoutingManifestV1;
+    };
+    /** Host-only standard index derived from this ordinary QTI test when used for review. */
+    reviewBank?: {
+        sourceContentRevision: string;
+        bankRevision: string;
+        items: {
+            itemIdentifier: string;
+            standards: AssessmentStandardRef[];
+        }[];
+    };
+}
+/** Ordered local catalog for one course integration and assessment purpose. */
+interface AssessmentRuntimeFixtureCatalog {
+    id: string;
+    integrationId: string;
+    purpose: AssessmentPurpose;
+    subject: TimebackSubject;
+    grade: TimebackGrade;
+    tests: AssessmentRuntimeFixtureTest[];
+}
+/**
+ * Versioned host-only bundle consumed by the local assessment runtime.
+ *
+ * The version tracks this bundle's own shape, including the shape of the
+ * assessments nested inside it — a bundle is rejected outright when either
+ * differs, so a stale export is re-generated rather than half-read.
+ */
+interface AssessmentRuntimeFixtureBundle {
+    version: 8;
+    gameId: string;
+    /**
+     * The project-config slug the CLI resolved the game by at export time.
+     * Local dev matches on this (the platform gameId and the locally derived
+     * id live in different namespaces, so they can never be compared).
+     */
+    gameSlug?: string;
+    exportedAt: string;
+    catalogs: AssessmentRuntimeFixtureCatalog[];
+}
+
+/**
+ * Must admit exactly the raster set in `QTI_RASTER_IMAGE_MIME_TYPES`
+ * (`@playcademy/utils/timeback`), minus the legacy `image/jpg` spelling
+ * the server never emits.
+ */
+type AssessmentAssetMimeType = 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp' | 'image/bmp';
+type AssessmentAssetUploadStatus = 'uploaded' | 'already_exists';
+/** Assessment assets are production-oriented content; local sandboxes never host them. */
+type AssessmentAssetEnvironment = 'production' | 'staging';
+interface AssessmentAssetUploadResponse {
+    status: AssessmentAssetUploadStatus;
+    environment: AssessmentAssetEnvironment;
+    key: string;
+    url: string;
+    sha256: string;
+    mimeType: AssessmentAssetMimeType;
+    size: number;
+    width: number;
+    height: number;
+}
+
+/**
+ * User Types
+ *
+ * Enums, DTOs and API response types. Database row types are in @playcademy/data/types.
+ *
+ * @module types/user
+ */
+
+type UserRoleEnumType = UserRole;
+type DeveloperStatusEnumType = 'none' | 'pending' | 'approved';
+type DeveloperStatusValue = DeveloperStatusEnumType;
+type TimebackUserRole = 'administrator' | 'aide' | 'guardian' | 'parent' | 'proctor' | 'relative' | 'student' | 'teacher';
+type TimebackOrgType = 'department' | 'school' | 'district' | 'local' | 'state' | 'national';
+interface UserEnrollment {
+    gameId?: string;
+    courseId: string;
+    id?: string;
+    grade: number;
+    subject: string;
+    orgId?: string;
+    /**
+     * `base` for the game's grade courses, `hole_filling` for a remediation
+     * course Timeback enrolled the student in. Absent means `base`.
+     */
+    kind?: GameTimebackIntegrationKind;
+    /** For hole-filling enrollments: the course ID of the base course it belongs to. */
+    baseCourseId?: string;
+    /** For hole-filling enrollments: when the enrollment started (ISO 8601). */
+    beginDate?: string | null;
+    /**
+     * For hole-filling enrollments: enrollment metadata as set by Timeback
+     * (e.g. `assignmentId`, `testType`). Every field is optional.
+     */
+    enrollmentMetadata?: Record<string, unknown>;
+}
+interface UserOrganization {
+    id: string;
+    name: string | null;
+    type: TimebackOrgType | string;
+    isPrimary: boolean;
+}
+interface TimebackStudentProfile {
+    role: TimebackUserRole;
+    organizations: UserOrganization[];
+}
+/**
+ * Timeback identity on `/users/me`: who the student is, without enrollments.
+ * Enrollments come from `/timeback/user` (or `client.timeback.user`).
+ */
+interface UserTimebackProfile extends TimebackStudentProfile {
+    id: string;
+}
+interface UserTimebackData extends UserTimebackProfile {
+    enrollments: UserEnrollment[];
+}
+type LocalDaySource = 'browser_last_seen' | 'platform_default';
+interface LocalDayContext {
+    timeZone: string;
+    source: LocalDaySource;
+    /** ISO 8601 timestamp for the last persisted timezone observation. */
+    observedAt: string | null;
+}
+/**
+ * OpenID Connect UserInfo claims (NOT a database row).
+ */
+interface UserInfo {
+    sub: string;
+    email: string;
+    name: string | null;
+    email_verified?: boolean;
+    given_name?: string;
+    family_name?: string;
+    issuer?: string;
+    lti_roles?: unknown;
+    lti_context?: unknown;
+    lti_resource_link?: unknown;
+    timeback_id?: string;
+}
+interface DeveloperStatusResponse {
+    status: DeveloperStatusEnumType;
+}
+/**
+ * Authenticated user for API responses.
+ * Differs from UserRow: omits timebackId, adds hasTimebackAccount and timeback.
+ */
+interface AuthenticatedUser {
+    id: string;
+    email: string;
+    emailVerified: boolean;
+    name: string | null;
+    image: string | null;
+    username: string | null;
+    role: UserRoleEnumType;
+    developerStatus: DeveloperStatusEnumType;
+    createdAt: Date;
+    updatedAt: Date;
+    hasTimebackAccount: boolean;
+    localDay: LocalDayContext;
+    timeback?: UserTimebackProfile;
+}
+interface GameUser {
+    id: string;
+    name: string | null;
+    role: UserRoleEnumType;
+    username: string | null;
+    email: string | null;
+    localDay: LocalDayContext;
+    timeback?: UserTimebackProfile;
+}
+
+/**
+ * Game Types
+ *
+ * Literal types and API DTOs. Database row types are in @playcademy/data/types.
+ *
+ * @module types/game
+ */
+
+type GameType = 'hosted' | 'external';
+type GamePlatform = 'web' | 'godot' | (string & {});
+/**
+ * Game manifest file format (manifest.json).
+ * Note: createdAt is a string here because it's parsed from JSON file.
+ */
+interface ManifestV1 {
+    version: '1';
+    platform: string;
+    createdAt: string;
+}
+interface ManifestVersions {
+    vitePlugin?: string;
+    sdk?: string;
+    cli?: string;
+    vite?: string;
+    godotSdk?: string;
+    godot?: string;
+}
+interface ManifestV2 {
+    version: '2';
+    platform: string;
+    createdAt: string;
+    gameVersion?: string;
+    versions: ManifestVersions;
+}
+type GameManifest = ManifestV1 | ManifestV2;
+/** One migration in a migrate-mode deploy payload */
+interface DeployMigration {
+    /** Journal tag, e.g. '0042_brave_hulk' */
+    tag: string;
+    /** Pre-split SQL statements (the CLI splits on drizzle statement-breakpoints) */
+    statements: string[];
+    /** sha-256 of the normalized migration SQL (sha256-v1) */
+    checksum: string;
+}
+/** Push-mode database payload: diff-generated SQL guarded by a baseline CAS */
+interface DeployDatabasePush {
+    mode: 'push';
+    /** Diff-generated DDL to execute (semicolon-separated statements) */
+    sql: string;
+    /** Stored schemaHash the diff was computed against; null only for a first deploy */
+    baselineHash: string | null;
+    /** Drizzle snapshot JSON this deploy moves the schema to */
+    nextSnapshot: unknown;
+    /** Hash of nextSnapshot, stored as the new push baseline on success */
+    nextHash: string;
+    /** Explicit consent for destructive statements (DROP TABLE, dropped columns) */
+    acceptDataLoss?: boolean;
+}
+/** Migrate-mode database payload: the client's complete migration journal */
+interface DeployDatabaseMigrate {
+    mode: 'migrate';
+    /** The full journal in order; the server applies whatever the ledger lacks */
+    migrations: DeployMigration[];
+}
+/**
+ * Mode-aware database payload (PLA-217 D5). Replaces the legacy `schema`
+ * field for adopted games; the server verifies state before executing.
+ */
+type DeployDatabasePayload = DeployDatabasePush | DeployDatabaseMigrate;
+/** Journal entry in a baseline adoption block */
+interface DeployBaselineJournalEntry {
+    tag: string;
+    checksum: string;
+}
+/**
+ * Baseline adoption block (PLA-217 D7 seed-on-deploy): the client's claimed
+ * starting state for a game that predates server-side deployment state.
+ * Consumed by the deploy itself — an unadopted game gets its claimed ledger
+ * rows, snapshot/hash, and live fingerprint recorded before the database
+ * step runs; adopted games skip the block.
+ */
+interface DeployBaseline {
+    lastAppliedMigrationTag?: string;
+    journal?: DeployBaselineJournalEntry[];
+    /**
+     * Per-migration snapshot deltas for content validation (D7): the
+     * seed claim is judged against the live database exactly like a
+     * manual `db baseline` claim — the side door uses the front door's
+     * checkpoint.
+     */
+    evidence?: BaselineMigrationEvidence[];
+    schemaSnapshot?: unknown;
+    schemaHash?: string;
+    integrationsHash?: string;
+    buildHash?: string;
+}
+/**
+ * Git provenance of the working tree a deploy was run from (PLA-294).
+ *
+ * Captured by the CLI at deploy time and persisted verbatim on the deploy
+ * job, so "which commit is running" is answerable from the platform record.
+ * Every field is nullable: a tree with no git, no remote, or a detached HEAD
+ * is recorded honestly rather than refused. Recorded per deploy, never
+ * pinned to the game — a fork deployed under the same slug shows the fork.
+ */
+interface DeploySource {
+    /** Normalized `https://github.com/<org>/<repo>`; null when no remote or unparseable */
+    repository: string | null;
+    /** Full 40-char SHA of HEAD; null when not in a git tree */
+    commit: string | null;
+    /** Current branch name; null on detached HEAD outside CI */
+    branch: string | null;
+    /** True when the tree had uncommitted changes — the SHA does not describe what shipped */
+    dirty: boolean;
+    /**
+     * True when the uploaded build artifact lives outside the git tree the
+     * other fields describe (`--build ~/Downloads/game.zip`). The commit is
+     * still the deployer's tree, but it may not be what produced the artifact.
+     */
+    externalBuild: boolean;
+}
+type DeployJobStatus = 'pending' | 'running' | 'succeeded' | 'failed';
+/** Active game worker state served by the deployment-state endpoint */
+interface DeploymentStateGame {
+    /** Backend bundle hash from the active deployment row */
+    codeHash: string | null;
+    /** Frontend zip hash from game_deployment_state (null when unseeded) */
+    buildHash: string | null;
+    url: string;
+    deployedAt: string;
+}
+/** Active dashboard worker state served by the deployment-state endpoint */
+interface DeploymentStateDashboard {
+    url: string;
+    deployedAt: string;
+}
+/** Details of the last failed migration, from the failed deploy job */
+interface DeploymentStateDatabaseFailure {
+    tag: string;
+    error: string;
+    /**
+     * Set only when the failing statement is known exactly (the size
+     * preflight names the statement it measured). Execution failures are
+     * null: D1's byte offset has an unverified reference frame for the
+     * batch array form, so it is never mapped to an index.
+     */
+    statementIndex: number | null;
+    at: string;
+}
+/** A ledger entry from the game database's applied-migrations ledger */
+interface DeploymentStateAppliedMigration {
+    tag: string;
+    /** Checksum recorded at apply time (normalized SQL, see checksumAlgo) */
+    checksum: string;
+    /** Hash algorithm the checksum was recorded under (e.g. 'sha256-v1') */
+    checksumAlgo: string;
+}
+/** Database schema state served by the deployment-state endpoint */
+interface DeploymentStateDatabase {
+    /** Applied migrations from the live in-D1 ledger (null when the game has no database) */
+    appliedMigrations: DeploymentStateAppliedMigration[] | null;
+    lastFailure: DeploymentStateDatabaseFailure | null;
+    /** Hash of the drizzle snapshot (push-mode baseline) */
+    schemaHash: string | null;
+    /** Hash of the normalized live sqlite_master */
+    schemaFingerprint: string | null;
+    /**
+     * Stored drizzle snapshot (push-mode diffing only). Present only when
+     * the request asked for it with `?include=schemaSnapshot` (D4).
+     */
+    schemaSnapshot?: unknown;
+}
+/** Secret key names partitioned by ownership — names only, never hashes */
+interface DeploymentStateSecrets {
+    /** Keys recorded in the server-side secrets manifest */
+    managedKeys: string[];
+    /**
+     * Remote keys not in the manifest (set by SST, wrangler, or hand).
+     * Null when the server has no Cloudflare provider to list remote keys.
+     */
+    unmanagedKeys: string[] | null;
+}
+interface DeploymentStateLastDeploy {
+    at: string;
+    /** Who deployed: their email, or the raw user id when the account no longer resolves */
+    by: string;
+}
+/**
+ * Server-side deployment state for a game.
+ *
+ * Everything CLI deploy prep diffs against, fetched from
+ * GET /api/games/:slug/deployment-state so deploys never depend on
+ * local state for correctness.
+ */
+interface DeploymentStateResponse {
+    gameId: string;
+    /** True iff a game_deployment_state row exists for the game */
+    seeded: boolean;
+    game: DeploymentStateGame | null;
+    dashboard: DeploymentStateDashboard | null;
+    database: DeploymentStateDatabase;
+    secrets: DeploymentStateSecrets;
+    /** Hash of the declared integrations config (null when unseeded) */
+    integrationsHash: string | null;
+    /** Last deployed compatibility date (null when unseeded) */
+    compatibilityDate: string | null;
+    lastDeploy: DeploymentStateLastDeploy | null;
+}
+/**
+ * Per-key verdict groups from the server-side secrets diff (D6).
+ *
+ * Key names only — HMAC digests never leave the server. `remoteOnlyManaged`
+ * keys are the only legal prune candidates; `remoteOnlyUnmanaged` keys were
+ * set outside the platform and are untouchable.
+ */
+interface SecretsDiffResponse {
+    /** Local keys the manifest doesn't know yet */
+    added: string[];
+    /** Keys whose local value's HMAC differs from the manifest's */
+    changed: string[];
+    /** Keys whose local value's HMAC matches the manifest's */
+    unchanged: string[];
+    /** Manifest keys absent locally (prunable) */
+    remoteOnlyManaged: string[];
+    /** Worker keys absent from both the manifest and the local set */
+    remoteOnlyUnmanaged: string[];
+}
+/**
+ * Manual baseline adoption request (PLA-217 D7): the fresh-machine path for
+ * a game that predates server-side deployment state. Carries the claimed
+ * migrate-mode history (tag + journal), the push-mode snapshot, or both.
+ */
+interface DeploymentStateBaselineRequest {
+    lastAppliedMigrationTag?: string;
+    journal?: DeployBaselineJournalEntry[];
+    schemaSnapshot?: unknown;
+    schemaHash?: string;
+    /**
+     * Per-migration schema-object evidence (creates AND drops) derived
+     * from drizzle's snapshot files. The server replays it up to the
+     * claimed tag into the expected schema and validates that against the
+     * live database (D7): surviving claimed objects must exist,
+     * beyond-claim objects must be absent unless claimed history already
+     * explains them. Absent evidence downgrades every migration to
+     * no-signal.
+     */
+    evidence?: BaselineMigrationEvidence[];
+    /**
+     * Waive refusals for no-signal migrations only (content contradictions
+     * are never waivable). Recorded server-side for audit.
+     */
+    allowUnverified?: boolean;
+}
+/**
+ * Schema objects one journal migration introduced and removed (snapshot
+ * delta). Drops are as load-bearing as creates: an object created by one
+ * migration and dropped by a later one must not be demanded of the live
+ * database, and its live presence beyond the claim must not convict a
+ * migration whose object is already explained by claimed history.
+ */
+interface BaselineMigrationEvidence {
+    tag: string;
+    /** Journal generation timestamp (drizzle `when`), ISO 8601 */
+    generatedAt: string;
+    createsTables: {
+        name: string;
+        columns: string[];
+    }[];
+    addsColumns: {
+        table: string;
+        column: string;
+    }[];
+    createsIndexes: string[];
+    createsViews: string[];
+    dropsTables: string[];
+    dropsColumns: {
+        table: string;
+        column: string;
+    }[];
+    dropsIndexes: string[];
+    dropsViews: string[];
+}
+/** Outcome of the `db realign <tag>` checksum pardon */
+interface MigrationRealignResponse {
+    tag: string;
+    /** The re-recorded checksum */
+    checksum: string;
+    /** Algorithm stamped alongside it (e.g. 'sha256-v1') */
+    checksumAlgo: string;
+}
+/** How a ledger escape-hatch resolution lands: record the row, or remove it */
+type MigrationResolution = 'applied' | 'rolled-back';
+/** Outcome of the `db resolve <tag>` ledger escape hatch */
+interface MigrationResolveResponse {
+    tag: string;
+    resolution: MigrationResolution;
+    /**
+     * Live schema fingerprint captured by the resolve: the developer's
+     * attestation that the current database state is intended, so the next
+     * deploy verifies against it instead of the pre-repair record.
+     */
+    schemaFingerprint: string;
+    /**
+     * Whether the fingerprint was persisted to the game's deployment-state
+     * row. False when the game has no such row (not yet adopted): the
+     * ledger repair still succeeded, but nothing was recorded.
+     */
+    fingerprintRecorded: boolean;
+}
+/** One deploy job in a game's execution history (PLA-217 D10) */
+interface GameDeployHistoryDeploy {
+    kind: 'deploy';
+    status: DeployJobStatus;
+    /** When the deploy landed (creation time while pending/running), ISO 8601 */
+    at: string;
+    /** When the job finished (null while pending/running) */
+    completedAt: string | null;
+    /** Who deployed: their email, or DELETED_ACCOUNT_LABEL when the account is gone */
+    by: string;
+    /** Client idempotency key (null for legacy clients) */
+    deployId: string | null;
+    error: string | null;
+}
+/** A Time Travel restore in a game's execution history */
+interface GameDeployHistoryRestore {
+    kind: 'restore';
+    /** When the restore ran, ISO 8601 */
+    at: string;
+    /** Who restored: their email, or DELETED_ACCOUNT_LABEL when the account is gone */
+    by: string;
+    /** The moment the database was rewound to, ISO 8601 */
+    restoredTo: string;
 }
-interface StartDiagnosticAssessmentInput extends StartAssessmentInputBase {
-    purpose: 'diagnostic';
-    /** Stable authored diagnostic identity, independent of the selected QTI test identifier. */
-    diagnosticKey: string;
+/** A client-gate refusal in a game's execution history */
+interface GameDeployHistoryBlocked {
+    kind: 'blocked';
+    /** When the gate refused, ISO 8601 */
+    at: string;
+    /** Whose deploy was refused: their email, or DELETED_ACCOUNT_LABEL */
+    by: string;
+    /** Stable `blocked:*` code the gate refused with */
+    code: string;
+    /** The gate's plain-text refusal reason */
+    reason: string;
 }
-interface StartMasteryAssessmentInput extends StartAssessmentInputBase {
-    purpose: 'mastery';
-    standard: AssessmentStandardRef;
+/**
+ * One entry in a game's execution history: deploy jobs interleaved with
+ * the platform-visible events the job system never sees (restores,
+ * client-gate refusals), newest first.
+ */
+type GameDeployHistoryEntry = GameDeployHistoryDeploy | GameDeployHistoryRestore | GameDeployHistoryBlocked;
+/** Deploy history served by GET /api/games/:slug/deployments */
+interface GameDeployHistoryResponse {
+    deploys: GameDeployHistoryEntry[];
 }
-interface StartReviewAssessmentInput extends StartAssessmentInputBase {
-    purpose: 'review';
-    /** Serving order; duplicate canonical skills keep their first position. Pinned on start. */
-    standards: AssessmentReviewStandard[];
-    /** Candidate capacity per standard; preloaded candidates are not administered automatically. */
-    candidateItemsPerStandard?: number;
+/**
+ * One successful deploy of a game's worker, as the open releases surface
+ * describes it: what is running and which commit produced it.
+ *
+ * This shape is parsed by external automation. Every field is present on
+ * every entry — nullable, never absent — and nothing from the deploy job
+ * beyond its git provenance and completion time is exposed. No deployer
+ * identity, no schema state, no secrets manifest.
+ */
+interface Release {
+    slug: string;
+    /** Where the game is served; null when the platform has no URL for it */
+    url: string | null;
+    /**
+     * Git provenance the deploying CLI captured. Null for deploys that
+     * predate provenance capture, so the fleet list is complete on day one
+     * and a consumer can tell "unknown" from "not in git".
+     */
+    source: DeploySource | null;
+    /** When the deploy succeeded, ISO 8601 */
+    deployedAt: string;
 }
-type StartAssessmentInput = StartFixedAssessmentInput | StartDiagnosticAssessmentInput | StartMasteryAssessmentInput | StartReviewAssessmentInput;
-/** Transport metadata for attempting a prepared new-assessment start. */
-interface StartAssessmentOptions {
-    preparationReceipt?: string;
+/** GET /api/releases — the current release of every game */
+interface ReleasesResponse {
+    releases: Release[];
 }
-/** Result of preparing the immediate next assessment request. */
-type AssessmentPreparationResult = {
-    status: 'prepared';
-    receipt: string;
-    /** Receipt expiry as an ISO-8601 timestamp. */
-    expiresAt: string;
-} | {
-    status: 'unprepared';
-    reason: 'artifact_unavailable' | 'prerequisite_unavailable' | 'local_runtime';
-};
-interface SaveAssessmentInput {
-    expectedResponseVersion: number;
-    /** Complete active draft; success acknowledges its durable parent checkpoint. */
-    transcript: AssessmentTranscript;
+/** GET /api/releases/:slug — one game's current release and, on request, its recent history */
+interface GameReleaseResponse {
+    /** The current release; null when the game has never deployed successfully */
+    current: Release | null;
+    /**
+     * The last N successful deploys, newest first, current included. Only
+     * present when `?history=N` was requested.
+     */
+    history?: Release[];
 }
-/** Best-effort mastery progress, not an answer commitment or an explicit checkpoint. */
-interface RecordAssessmentProgressInput {
-    assessmentToken: string;
-    expectedResponseVersion: number;
-    /** Current raw draft, including the editable administration being projected. */
-    transcript: AssessmentTranscript;
-    itemIdentifier: string;
+/** Request body for POST /api/games/:slug/deployments/blocked */
+interface DeployBlockedReport {
+    /** Stable `blocked:*` code the gate refused with */
+    code: string;
+    /** The gate's plain-text refusal reason */
+    reason: string;
 }
-interface SubmitAssessmentItemInputBase {
-    assessmentToken: string;
-    /** The raw prefix preceding this administration (or including it for an exact retry). */
-    transcript: AssessmentTranscript;
-    expectedResponseVersion: number;
-    /** Stable across every retry of this exact item submission. */
-    submissionId: string;
-    itemIdentifier: string;
-    responses: Record<string, AssessmentResponseValue | null>;
+/**
+ * A restorable pre-deploy database state (D1 Time Travel bookmark).
+ *
+ * Each schema-bearing deploy captures a bookmark of the database as it was
+ * the moment before that deploy's schema changes ran. Only bookmarks
+ * belonging to the CURRENT database and within Time Travel's retention
+ * window are served — a `db reset` creates a new database (bookmarks do
+ * not cross that boundary), and Cloudflare expires bookmarks after the
+ * account plan's retention period.
+ */
+interface GameRestorePoint {
+    /** Deployment row id — pass to the restore endpoint (or a unique prefix to the CLI) */
+    id: string;
+    /**
+     * When the bookmark was captured (the exact state a restore rewinds
+     * to), ISO 8601. Rows from before capture times were recorded fall
+     * back to the deploy completion time.
+     */
+    capturedAt: string;
+    /** Whether the capturing deployment is the currently active one */
+    active: boolean;
 }
-interface SubmitReviewAssessmentItemInput extends SubmitAssessmentItemInputBase {
-    routingNodeKey?: never;
+/** Restore points served by GET /api/games/:slug/database/restore-points */
+interface GameRestorePointsResponse {
+    restorePoints: GameRestorePoint[];
+    /**
+     * True for push-adopted games, whose recorded snapshot cannot rewind
+     * with the data: restore is categorically refused, so the list is
+     * served empty rather than offering points that can never restore.
+     */
+    restoreUnsupported: boolean;
 }
-interface SubmitDiagnosticAssessmentItemInput extends SubmitAssessmentItemInputBase {
-    /** Canonical routing-context identity returned in routing.next. */
-    routingNodeKey: string;
+/** Outcome of a Time Travel restore (PLA-217 D10) */
+interface DatabaseRestoreResponse {
+    restorePointId: string;
+    /** The moment the database was rewound to (the bookmark's capture time), ISO 8601 */
+    restoredTo: string;
+    /**
+     * Live schema fingerprint captured after the restore: the developer's
+     * audited attestation that the rewound state is intended, so the next
+     * deploy verifies against it.
+     */
+    schemaFingerprint: string;
+    /** False when the game has no deployment-state row to re-attest */
+    fingerprintRecorded: boolean;
+    /**
+     * Bookmark of the database as it was just before this restore — the
+     * undo handle. Null only if Cloudflare omits it from the response.
+     */
+    previousBookmark: string | null;
 }
-type SubmitAssessmentItemInput = SubmitReviewAssessmentItemInput | SubmitDiagnosticAssessmentItemInput;
-interface SubmitReviewAssessmentItemResult {
-    attemptId: string;
-    responseVersion: number;
-    status: 'in_progress';
-    responses: AssessmentResponses;
-    /** Canonical ledger after commit or replay; replace local state with it. */
-    itemSubmissions: AssessmentItemSubmission[];
-    submission: AssessmentItemSubmission;
-    transcript: AssessmentTranscript;
+/** Push-mode reset payload: the full schema that rebuilds the fresh database */
+interface DatabaseResetPush {
+    mode: 'push';
+    /** Full schema DDL (semicolon-separated statements) */
+    sql: string;
+    /** Drizzle snapshot JSON, stored as the new push baseline */
+    nextSnapshot: unknown;
+    /** Hash of nextSnapshot, stored as the new schemaHash */
+    nextHash: string;
 }
-/** Safe acknowledgement for one immutable diagnostic item commitment. */
-interface DiagnosticAssessmentItemReceipt {
-    submissionId: string;
-    routingNodeKey: string;
-    itemIdentifier: string;
-    submittedAt: string;
-    responseVersion: number;
-    answered: boolean;
-    score: AssessmentScore;
-    isCorrect: boolean;
+/** Migrate-mode reset payload: the complete journal to replay on the fresh database */
+interface DatabaseResetMigrate {
+    mode: 'migrate';
+    /** The full journal in order; replayed one-by-one, rebuilding the ledger */
+    migrations: DeployMigration[];
 }
-/** Canonical post-commit routing state plus trusted feedback for this administration. */
-interface SubmitDiagnosticAssessmentItemResult {
-    attemptId: string;
-    responseVersion: number;
-    status: 'in_progress';
-    routing: DiagnosticRoutingSnapshot;
-    submission: DiagnosticAssessmentItemReceipt;
-    transcript: AssessmentTranscript;
+/**
+ * Mode-aware reset payload (PLA-217 D2). Reset recreates the database, so
+ * the ledger dies with it and there is no baseline to compare against —
+ * adopted games must send how to rebuild.
+ */
+type DatabaseResetDatabasePayload = DatabaseResetPush | DatabaseResetMigrate;
+interface DatabaseResetRequest {
+    /**
+     * Legacy schema info, accepted only while the game's schema state is
+     * unadopted; adopted games must send `database` instead.
+     */
+    schema?: {
+        /** SQL schema statements (DDL: CREATE, ALTER, etc.) */
+        sql: string;
+        /** Hash of the schema for change detection */
+        hash: string;
+    };
+    /** Mode-aware rebuild payload (mandatory for adopted games) */
+    database?: DatabaseResetDatabasePayload;
 }
-type SubmitAssessmentItemResult = SubmitReviewAssessmentItemResult | SubmitDiagnosticAssessmentItemResult;
-interface SubmitAssessmentInput {
-    expectedResponseVersion: number;
-    submissionId: string;
-    transcript: AssessmentTranscript;
+/** Log entry captured from seed worker console output */
+interface SeedLogEntry {
+    /** Log level (log, warn, error, info) */
+    level: 'log' | 'warn' | 'error' | 'info';
+    /** Log message content */
+    message: string;
+    /** Milliseconds since seed execution started */
+    timestamp: number;
+}
+/** Structured error details from D1/SQLite errors */
+interface SeedErrorDetails {
+    /** Error category code */
+    code?: 'CONSTRAINT_VIOLATION' | 'SQL_ERROR' | 'DATABASE_BUSY';
+    /** Table name involved in the error */
+    table?: string;
+    /** Constraint name or column that caused the error */
+    constraint?: string;
+    /** Specific constraint type */
+    constraintType?: 'UNIQUE' | 'FOREIGN_KEY' | 'NOT_NULL';
+    /** Token near syntax error */
+    nearToken?: string;
+    /** Specific error type within category */
+    errorType?: 'TABLE_NOT_FOUND' | 'SYNTAX_ERROR';
 }
-/** The optional mastery portion of a finalize award; at most one field is set. */
-interface AssessmentMasteryAward {
-    /**
-     * Incremental learning units mastered by this attempt. Cannot be combined
-     * with masteredUnitsAbsolute. The platform bounds the delta against the
-     * course's configured masterableUnits and returns any warning.
-     */
-    masteredUnits?: number;
-    /**
-     * Absolute mastered-unit total after this attempt; the platform computes
-     * the delta. Cannot be combined with masteredUnits.
-     */
-    masteredUnitsAbsolute?: number;
+/**
+ * API response for seed operations (what the API returns to the CLI).
+ *
+ * Extends the worker response with deployment metadata.
+ */
+interface SeedResponse {
+    /** Whether the seed completed successfully */
+    success: boolean;
+    /** Unique identifier for the seed worker deployment */
+    deploymentId: string;
+    /** When the seed was executed (ISO 8601 string from JSON serialization) */
+    executedAt: string;
+    /** Captured console output from the seed script */
+    logs?: SeedLogEntry[];
+    /** Execution duration in milliseconds */
+    duration?: number;
+    /** Error message if seed failed */
+    error?: string;
+    /** Stack trace if seed failed */
+    stack?: string;
+    /** Structured error details if seed failed */
+    details?: SeedErrorDetails;
 }
-interface FinalizeAssessmentInput extends AssessmentMasteryAward {
-    submissionId: string;
-    /** Explicit zero is an award; omission is never interpreted as zero. */
-    xpAwarded: number;
+interface DomainValidationRecords {
+    ownership?: {
+        name?: string;
+        value?: string;
+        type?: string;
+    };
+    ssl?: {
+        txt_name?: string;
+        txt_value?: string;
+    }[];
 }
+
 /**
- * The award a game supplied at finalization, retained verbatim so a retried
- * finalize can be told apart from a contradictory one even after bounding
- * changed what was actually applied.
+ * Leaderboard Types
+ *
+ * @module types/leaderboard
  */
-interface AssessmentAwardRecord extends AssessmentMasteryAward {
-    xpAwarded: number;
-    /** The bounded mastery delta the platform recorded for this attempt. */
-    masteredUnitsApplied: number;
-    pctCompleteApp?: number;
-    warnings?: MasteryWriteWarning[];
+type LeaderboardTimeframe = 'all_time' | 'monthly' | 'weekly' | 'daily';
+interface LeaderboardOptions {
+    timeframe?: LeaderboardTimeframe;
+    limit?: number;
+    offset?: number;
+    gameId?: string;
 }
-/** One scored region for host-only point-response fixture scoring. */
-interface AssessmentResponseArea {
-    shape: PlayableAssessmentShape;
-    coords: number[];
-    /** The region's mapped point value (1 when omitted). */
-    value?: number;
+interface LeaderboardEntry {
+    rank: number;
+    userId: string;
+    username: string;
+    userImage?: string | null;
+    score: number;
+    achievedAt: Date;
+    metadata?: Record<string, unknown>;
+    gameId?: string;
+    gameTitle?: string;
+    gameSlug?: string;
 }
-/** One host-only assessment entry exported for the local runtime provider. */
-interface AssessmentRuntimeFixtureTest {
-    id: string;
-    assessmentKey: string;
-    qtiTestIdentifier: string;
-    live: boolean;
-    /** Canonical quiz-level alignment used by mastery selection. */
-    standard: AssessmentStandardRef | null;
-    assessment: PlayableAssessment;
-    /** Private comparison rules retained for hosted-equivalent local scoring when available. */
-    scoring?: AssessmentScoringArtifactV1;
-    /** Correct responses are retained by the host and are never returned to the game. */
-    correctResponses: AssessmentResponses;
-    /**
-     * Host-only scored regions for point responses (select-point, position-object),
-     * keyed by item then response identifier. A point response is correct when every
-     * point lands in a distinct scored region.
-     */
-    responseAreas?: Record<string, Record<string, AssessmentResponseArea[]>>;
-    /** Host-only platform-routing sidecar for one immutable diagnostic bank revision. */
-    diagnostic?: {
-        diagnosticKey: string;
-        /** Calculated from the canonical manifest when the fixture is built. */
-        routingRevision: string;
-        routingManifest: DiagnosticRoutingManifestV1;
-    };
-    /** Host-only standard index derived from this ordinary QTI test when used for review. */
-    reviewBank?: {
-        sourceContentRevision: string;
-        bankRevision: string;
-        items: {
-            itemIdentifier: string;
-            standards: AssessmentStandardRef[];
-        }[];
-    };
+interface UserRank {
+    rank: number;
+    totalPlayers: number;
+    score: number;
+    percentile: number;
 }
-/** Ordered local catalog for one course integration and assessment purpose. */
-interface AssessmentRuntimeFixtureCatalog {
+interface UserRankResponse {
+    rank: number;
+    score: number;
+    userId: string;
+}
+interface UserScore {
     id: string;
-    integrationId: string;
-    purpose: AssessmentPurpose;
-    subject: TimebackSubject;
-    grade: TimebackGrade;
-    tests: AssessmentRuntimeFixtureTest[];
+    score: number;
+    achievedAt: Date;
+    metadata?: Record<string, unknown>;
+    gameId: string;
+    gameTitle: string;
+    gameSlug: string;
 }
 /**
- * Versioned host-only bundle consumed by the local assessment runtime.
- *
- * The version tracks this bundle's own shape, including the shape of the
- * assessments nested inside it — a bundle is rejected outright when either
- * differs, so a stale export is re-generated rather than half-read.
+ * Leaderboard entry with required game context.
+ * Used when fetching leaderboards for a specific game.
  */
-interface AssessmentRuntimeFixtureBundle {
-    version: 8;
+interface GameLeaderboardEntry {
+    rank: number;
+    userId: string;
+    username: string;
+    userImage?: string | null;
+    score: number;
+    achievedAt: Date;
+    metadata?: Record<string, unknown>;
     gameId: string;
-    /**
-     * The project-config slug the CLI resolved the game by at export time.
-     * Local dev matches on this (the platform gameId and the locally derived
-     * id live in different namespaces, so they can never be compared).
-     */
-    gameSlug?: string;
-    exportedAt: string;
-    catalogs: AssessmentRuntimeFixtureCatalog[];
+    gameTitle: string;
+    gameSlug: string;
 }
 
 /**
- * Must admit exactly the raster set in `QTI_RASTER_IMAGE_MIME_TYPES`
- * (`@playcademy/utils/timeback`), minus the legacy `image/jpg` spelling
- * the server never emits.
+ * Skill Status Types
+ *
+ * Contract for cross-game skill status queries. An answering game exports
+ * `getSkillStatus` from `server/lib/skills.ts`; the platform calls its
+ * reserved `/__playcademy/skills/status` route on behalf of another game.
+ *
+ * @module types/skills
  */
-type AssessmentAssetMimeType = 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp' | 'image/bmp';
-type AssessmentAssetUploadStatus = 'uploaded' | 'already_exists';
-/** Assessment assets are production-oriented content; local sandboxes never host them. */
-type AssessmentAssetEnvironment = 'production' | 'staging';
-interface AssessmentAssetUploadResponse {
-    status: AssessmentAssetUploadStatus;
-    environment: AssessmentAssetEnvironment;
-    key: string;
-    url: string;
-    sha256: string;
-    mimeType: AssessmentAssetMimeType;
-    size: number;
-    width: number;
-    height: number;
+
+/**
+ * Current status of one skill for one student, as judged by the answering game.
+ *
+ * - `locked`: the student can't work on the skill yet in this game.
+ * - `unlocked`: available to the student, but no progress yet.
+ * - `in_progress`: started, not mastered.
+ * - `mastered`: currently meets this game's mastery bar, including by placement.
+ * - `unknown_skill`: the skill ID isn't recognized. Never report an unrecognized
+ *   skill as `locked`.
+ */
+type SkillStatus = (typeof SKILL_STATUSES)[number];
+/** How a `mastered` status was reached. */
+type SkillMasterySource = (typeof SKILL_MASTERY_SOURCES)[number];
+interface SkillStatusResult {
+    /** Skill ID, lowercase. */
+    skill: string;
+    /** Current status. */
+    status: SkillStatus;
+    /** How mastery was reached. Only allowed when `status` is `mastered`. */
+    source?: SkillMasterySource;
+    /** ISO 8601 time of the evidence behind this status. */
+    asOf?: string;
+}
+/** Response returned by an answering game's `getSkillStatus` handler. */
+interface SkillStatusResponse {
+    /** Student identifier (Playcademy user ID). Must match the requested student. */
+    studentId: string;
+    /** One result per skill the handler was asked about. */
+    results: SkillStatusResult[];
+}
+/** The game asking for skill status, as identified by the platform. */
+interface SkillStatusRequestingGame {
+    id: string;
+    slug: string;
+}
+/** Body of `POST /api/skills/status`, sent by the asking game's worker. */
+interface SkillStatusRequest {
+    /** Slug of the game to ask. */
+    game: string;
+    /** Playcademy user ID of the student. */
+    studentId: string;
+    /** Skill IDs to ask about. Normalized (trimmed, lowercased) and de-duplicated. */
+    skills: string[];
 }
+/** Why the answering game couldn't answer. */
+type SkillStatusUnsupportedReason = 'not_implemented' | 'no_active_deployment' | 'timeout' | 'fetch_failed' | 'invalid_response';
+/**
+ * What the asking game gets back. When `supported` is false, fall back to
+ * the game's own default (usually: treat the skills as not mastered).
+ */
+type SkillStatusLookupResult = {
+    supported: true;
+    results: SkillStatusResult[];
+} | {
+    supported: false;
+    reason: SkillStatusUnsupportedReason;
+};
 
 /** A game token for a launch. `POST /api/embed/launches/:launchId/token`. */
 interface EmbedGameToken {
@@ -6033,6 +6100,8 @@ interface EmbedTimebackRecording {
     subject: TimebackSubject;
     /** Course id hint, same semantics as `startActivity()`. */
     courseId?: string;
+    /** The student's enrollment in `courseId`; filled with it automatically. */
+    enrollmentId?: string;
 }
 /**
  * Everything a parent needs to resume an interrupted launch later. The
@@ -7137,6 +7206,8 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
             get: (gameId: string) => Promise<GameTimebackIntegration[]>;
             getRemovedIntegrations: (gameId: string) => Promise<RemovedGameTimebackIntegration[]>;
             createIntegration: (gameId: string, request: CreateGameTimebackIntegrationRequest) => Promise<GameTimebackIntegration>;
+            getHoleFillingCourses: (gameId: string) => Promise<GameTimebackIntegration[]>;
+            createHoleFillingCourse: (gameId: string, request: CreateGameTimebackHoleFillingCourseRequest) => Promise<GameTimebackIntegration>;
             updateIntegration: (gameId: string, courseId: string, request: UpdateGameTimebackIntegrationRequest) => Promise<GameTimebackIntegration>;
             deactivateCourse: (gameId: string, courseId: string) => Promise<GameTimebackIntegration>;
             reactivateCourse: (gameId: string, courseId: string) => Promise<GameTimebackIntegration>;