@playcademy/sdk 0.20.1-beta.2 → 0.20.1-beta.3

package/dist/internal.d.ts

@@ -1,14 +1,5 @@
-import { SchemaInfo } from '@playcademy/cloudflare';
-import { GamePermission, AUTH_PROVIDER_IDS } from '@playcademy/constants';
-import { TimebackGrade, TimebackSubject, ELevel, HeartbeatRequest, EndActivityRequest, EndActivityScoreData, EndActivityResponse, TimebackCourseConfig, CourseConfig, OrganizationConfig, ComponentConfig, ResourceConfig, ComponentResourceConfig } from '@playcademy/types/timeback';
-export { AssessmentAttemptSnapshot, AssessmentAwardRecord, AssessmentFinalizeResult, AssessmentFlow, AssessmentItemGrading, AssessmentItemOutcome, AssessmentItemSubmission, AssessmentMasteryAward, AssessmentPreparationResult, AssessmentResponseUpdate, AssessmentResponseValue, AssessmentResponses, AssessmentReviewStandard, AssessmentSaveResult, AssessmentScore, AssessmentStandardRef, AssessmentSubmitResult, AssessmentTranscript, ConventionalAssessmentAttemptSnapshot, ConventionalAssessmentSubmitResult, DiagnosticAssessmentItemReceipt, DiagnosticAssessmentSubmitResult, DiagnosticRoutingSnapshot, DiagnosticRoutingTrackSnapshot, ELevel, FinalizeAssessmentInput, MasteryAssessmentSubmitResult, PlatformRoutedDiagnosticAttemptSnapshot, PlatformRoutedDiagnosticSelectionContext, PlayableAssessment, PlayableAssessmentAttemptSnapshot, PlayableAssessmentChoice, PlayableAssessmentGraphic, PlayableAssessmentHotspot, PlayableAssessmentInteraction, PlayableAssessmentItem, PlayableChoiceInteraction, PlayableContentNode, PlayableGapMatchChoice, PlayableGapMatchInteraction, PlayableInlineChoiceInteraction, PlayableMatchChoice, PlayableMatchInteraction, PlayableOrderInteraction, RecordAssessmentProgressInput, ResumeAssessmentInput, SaveAssessmentInput, SettledAssessmentAttemptSnapshot, StandardsReviewSelectionContext, StartAssessmentInput, StartAssessmentOptions, StartDiagnosticAssessmentInput, SubmitAssessmentInput, SubmitAssessmentItemInput, SubmitAssessmentItemResult, SubmitDiagnosticAssessmentItemInput, SubmitDiagnosticAssessmentItemResult } from '@playcademy/types/timeback';
-import * as _playcademy_types from '@playcademy/types';
-import { GameManifest, LocalDayContext } from '@playcademy/types';
-export { AuthenticatedUser, DeploySource, DeveloperStatusEnumType, DeveloperStatusResponse, DeveloperStatusValue, GameCourseMetrics, GameLeaderboardEntry, GameManifest, GameMetricComparisonKind, GameMetricComparisonMetric, GameMetricComparisonRow, GameMetricComparisonRowStatus, GameMetricsProxyResponse, GameMetricsResponse, GameMetricsUnsupportedReason, GamePlatform, GameReleaseResponse, GameRunMetrics, GameRunMetricsComparison, GameRunMetricsComparisonStatus, GameRunMetricsComparisonSummary, GameTimebackIntegration, GameType, GameUser, LeaderboardEntry, LeaderboardOptions, LeaderboardTimeframe, LocalDayContext, LocalDaySource, ManifestV1, ManifestV2, ManifestVersions, PopulateStudentResponse, Release, ReleasesResponse, SkillMasterySource, SkillStatus, SkillStatusLookupResult, SkillStatusRequest, SkillStatusRequestingGame, SkillStatusResponse, SkillStatusResult, SkillStatusUnsupportedReason, UserEnrollment, UserInfo, UserOrganization, UserRank, UserRankResponse, UserRoleEnumType, UserScore, UserTimebackData } from '@playcademy/types';
 import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
-import { DomainValidationRecords } from '@playcademy/types/game';
 import { z } from 'zod';
-import { TimebackUserRole, UserEnrollment, UserOrganization, UserInfo } from '@playcademy/types/user';
 
 /** Permitted HTTP verbs */
 type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
@@ -17,6 +8,3108 @@ interface RetryPolicy {
     retryDelaysMs?: readonly number[];
 }
 
+/**
+ * Authentication Constants
+ *
+ * Constants related to authentication providers.
+ */
+/**
+ * Auth Provider Constants
+ */
+declare const AUTH_PROVIDER_IDS: {
+    readonly TIMEBACK: 'timeback';
+    readonly TIMEBACK_LTI: 'timeback-lti';
+    readonly PLAYCADEMY: 'playcademy';
+};
+/**
+ * Platform user roles.
+ */
+declare const USER_ROLES: {
+    readonly ADMIN: 'admin';
+    readonly PLAYER: 'player';
+    readonly DEVELOPER: 'developer';
+    readonly TEACHER: 'teacher';
+};
+type UserRole = (typeof USER_ROLES)[keyof typeof USER_ROLES];
+
+/**
+ * Browser permissions a game may declare and the hub may delegate to its
+ * iframe. Opt-in per game because a delegated grant keys to the hub's
+ * top-level origin: one player grant would otherwise reach every embedded
+ * game. Baseline features (fullscreen, autoplay, gamepad) are delegated to
+ * all games and are not part of this set.
+ */
+declare const GAME_PERMISSIONS: readonly ['microphone', 'camera'];
+type GamePermission = (typeof GAME_PERMISSIONS)[number];
+
+/** Every status an answering game may report for a skill. */
+declare const SKILL_STATUSES: readonly ['locked', 'unlocked', 'in_progress', 'mastered', 'unknown_skill'];
+/** Every way a `mastered` status may have been reached. */
+declare const SKILL_MASTERY_SOURCES: readonly ['assessment', 'placement', 'test_out', 'manual'];
+
+/**
+ * Valid grade levels per AE OneRoster GradeEnum.
+ * -1 = Pre-K, 0 = Kindergarten, 1-12 = Grades 1-12, 13 = AP
+ */
+declare const TIMEBACK_GRADES: readonly [-1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13];
+/**
+ * The TimeBack subject vocabulary, carried on courses, activity data, and
+ * Caliper events alike. 'None' is canonical: TimeBack accepts it as a course
+ * subject and uses it as the fallback for unknown or missing subjects.
+ */
+declare const TIMEBACK_SUBJECTS: readonly ['Reading', 'Language', 'Vocabulary', 'Social Studies', 'Writing', 'Science', 'FastMath', 'Math', 'None'];
+/**
+ * Playcademy's course-specific meaning for reusable QTI test content.
+ * Result writers translate this to OneRoster assessment-result
+ * `metadata.testType`; it intentionally does not become metadata on the QTI
+ * test itself.
+ */
+declare const ASSESSMENT_PURPOSES: readonly ['end_of_course', 'diagnostic', 'review', 'mastery'];
+/**
+ * Schema version of the playable assessment payload handed to a game.
+ *
+ * Distinct from an assessment's content revision: this identifies the shape of
+ * the contract, not the content inside it. Bumped when the payload gains a
+ * field or changes the meaning of one — never for content edits.
+ *
+ * Intended for diagnostics and for telling "this host does not support the
+ * field" apart from "this item does not use it". Games should branch on whether
+ * a field is present, not on this number: the content vocabularies are open by
+ * design, so feature detection keeps working across versions where a comparison
+ * does not.
+ */
+declare const PLAYCADEMY_ASSESSMENT_CONTRACT_VERSION: 2;
+
+/**
+ * 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;
+}
+interface UserOrganization {
+    id: string;
+    name: string | null;
+    type: TimebackOrgType | string;
+    isPrimary: boolean;
+}
+interface TimebackStudentProfile {
+    role: TimebackUserRole;
+    organizations: UserOrganization[];
+}
+interface UserTimebackData extends TimebackStudentProfile {
+    id: string;
+    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?: UserTimebackData;
+}
+interface GameUser {
+    id: string;
+    name: string | null;
+    role: UserRoleEnumType;
+    username: string | null;
+    email: string | null;
+    localDay: LocalDayContext;
+    timeback?: UserTimebackData;
+}
+
+/**
+ * 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;
+}
+/** 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[];
+}
+/**
+ * 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;
+}
+/** GET /api/releases — the current release of every game */
+interface ReleasesResponse {
+    releases: Release[];
+}
+/** 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[];
+}
+/** 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;
+}
+/**
+ * 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;
+}
+/** 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.
+ */
+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;
+}
+/** 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';
+}
+/**
+ * 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 DomainValidationRecords {
+    ownership?: {
+        name?: string;
+        value?: string;
+        type?: string;
+    };
+    ssl?: {
+        txt_name?: string;
+        txt_value?: string;
+    }[];
+}
+
+/**
+ * Leaderboard Types
+ *
+ * @module types/leaderboard
+ */
+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 UserRank {
+    rank: number;
+    totalPlayers: number;
+    score: number;
+    percentile: number;
+}
+interface UserRankResponse {
+    rank: number;
+    score: number;
+    userId: string;
+}
+interface UserScore {
+    id: string;
+    score: number;
+    achievedAt: Date;
+    metadata?: Record<string, unknown>;
+    gameId: string;
+    gameTitle: string;
+    gameSlug: string;
+}
+/**
+ * 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;
+    metadata?: Record<string, unknown>;
+    gameId: string;
+    gameTitle: string;
+    gameSlug: string;
+}
+
+/**
+ * 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
+ */
+
+/**
+ * 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;
+};
+
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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';
+}
+/**
+ * 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';
+    };
+}
+/**
+ * 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;
+    };
+}
+/**
+ * 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 MasteryWriteWarning {
+    code: 'MASTERY_WRITE_CAPPED';
+    message: string;
+    currentMasteredUnits: number;
+    attemptedMasteredUnits: number;
+    appliedMasteredUnits: number;
+    storedMasteredUnits: number;
+    masterableUnits: number;
+}
+/**
+ * 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;
+}
+/**
+ * Score data for ending an activity
+ */
+interface EndActivityScoreData {
+    /** Number of questions answered correctly */
+    correctQuestions: number;
+    /** Total number of questions */
+    totalQuestions: number;
+    /**
+     * 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.
+     */
+    xpAwarded: number;
+    /**
+     * 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.
+     */
+    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;
+}
+
+/**
+ * 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 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;
+}
+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.
+ */
+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[];
+}
+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;
+}
+type GameRunMetricsComparisonStatus = 'matched' | 'discrepant' | 'not_reported' | 'unavailable';
+interface GameRunMetricsComparisonSummary {
+    runId: string;
+    status: GameRunMetricsComparisonStatus;
+    discrepancyCount: number;
+    reason?: GameMetricsUnsupportedReason;
+}
+interface GameRunMetricsComparison extends GameRunMetricsComparisonSummary {
+    rows: GameMetricComparisonRow[];
+}
+
+/**
+ * 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;
+}
+interface QtiAssessmentSection {
+    identifier: string;
+    title: string;
+    visible?: boolean;
+    required?: boolean;
+    fixed?: boolean;
+    sequence?: number;
+    'qti-assessment-item-ref'?: QtiItemRef[];
+}
+interface QtiTestPart {
+    identifier: string;
+    navigationMode: 'linear' | 'nonlinear';
+    submissionMode: 'individual' | 'simultaneous';
+    'qti-assessment-section': QtiAssessmentSection[];
+}
+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 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 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[];
+}
+
+/**
+ * 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;
+}
+interface TimebackSetupRequest {
+    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;
+}
+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 PlatformTimebackSetupResponse {
+    integrations: GameTimebackIntegration[];
+    verbose?: {
+        integration: GameTimebackIntegration;
+        config: {
+            course: unknown;
+            component: unknown;
+            resource: unknown;
+            componentResource: unknown;
+        };
+    }[];
+}
+interface GameTimebackIntegration {
+    id: string;
+    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;
+}
+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 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 CreateGameTimebackIntegrationRequest {
+    title: string;
+    courseCode: string;
+    subject: TimebackSubject;
+    grade: TimebackGrade;
+    totalXp: number;
+    masterableUnits: number;
+    level?: string;
+}
+interface TimebackVerificationResources {
+    course: {
+        found: boolean;
+        data?: unknown;
+    };
+    component: {
+        found: boolean;
+        data?: unknown;
+    };
+    resource: {
+        found: boolean;
+        data?: unknown;
+    };
+    componentResource: {
+        found: boolean;
+        data?: unknown;
+    };
+}
+interface TimebackVerifyCourseResult {
+    integration: GameTimebackIntegration;
+    resources: TimebackVerificationResources;
+    status: 'success' | 'error';
+    errors?: string[];
+}
+interface TimebackVerifyAllResponse {
+    status: 'success' | 'error';
+    results: TimebackVerifyCourseResult[];
+}
+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;
+        courseName?: string;
+        studentEmail?: string;
+    };
+    timingData: {
+        activeMs: number;
+        pausedMs: number;
+    };
+    isFinal?: 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 {
+    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`, 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;
+}
+interface EndActivityResponse {
+    status: 'ok';
+    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;
+}
+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;
+    };
+}
+/**
+ * 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 {
+    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;
+}
+interface TimebackRosterResponse {
+    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;
+}
+interface UnenrollStudentRequest {
+    gameId: string;
+    courseId: string;
+    studentId: string;
+}
+interface SearchStudentPastEnrollment {
+    enrollmentId: string;
+    beginDate: string | null;
+    endDate: string | null;
+}
+interface SearchStudentResult {
+    studentId: string;
+    name: string;
+    email: string | null;
+    /** Always set: search only returns accounts holding a supported role. */
+    primaryRole: TimebackAccountRole;
+    alreadyEnrolled: boolean;
+    pastEnrollments?: SearchStudentPastEnrollment[];
+}
+interface SearchStudentsResponse {
+    students: SearchStudentResult[];
+}
+interface TimebackAdminMutationResponse {
+    status: 'ok';
+}
+interface ReconcileMasteryForConfigChangeRequest {
+    gameId: string;
+    courseId: string;
+    oldMasterableUnits: number;
+    newMasterableUnits: number;
+    affectedStudentIds: string[];
+}
+interface ReconcileMasteryForConfigChangeResponse {
+    processed: number;
+    failed: string[];
+}
+
+/** Schema version for the declarative platform-routed diagnostic manifest. */
+declare const DIAGNOSTIC_ROUTING_MANIFEST_VERSION: 1;
+declare const DIAGNOSTIC_TRACK_OUTCOMES: readonly ['provisional', 'unresolved', 'route-to-instruction', 'not-assessed'];
+type DiagnosticTrackOutcome = (typeof DIAGNOSTIC_TRACK_OUTCOMES)[number];
+interface DiagnosticRoutingGroupV1 {
+    key: string;
+    title?: string;
+}
+interface DiagnosticRoundRobinScheduleV1 {
+    type: 'round-robin';
+}
+type DiagnosticActivationPredicateV1 = {
+    type: 'node-result';
+    nodeKey: string;
+    isCorrect: boolean;
+} | {
+    /** Gates route on graph identity, never on the game-facing semantic result. */
+    type: 'track-terminal';
+    trackKey: string;
+    terminalKey: string;
+} | {
+    type: 'all' | 'any';
+    predicates: DiagnosticActivationPredicateV1[];
+};
+interface DiagnosticRoutingStageV1 {
+    key: string;
+    schedule: DiagnosticRoundRobinScheduleV1;
+    trackKeys: string[];
+    /** Gates may reference only nodes or tracks from an earlier stage. */
+    activateWhen?: DiagnosticActivationPredicateV1;
+}
+interface DiagnosticRoutingTrackV1 {
+    key: string;
+    groupKey?: string;
+    entryNodeKey: string;
+    /** Required for a track in a gated stage; must resolve to a not-assessed terminal. */
+    inactiveTerminalKey?: string;
+}
+type DiagnosticRoutingTransitionV1 = {
+    type: 'goto';
+    nodeKey: string;
+} | {
+    type: 'complete';
+    terminalKey: string;
+};
+interface DiagnosticRoutingNodeV1 {
+    /** Routing-context identity; deliberately distinct from the QTI item identifier. */
+    key: string;
+    trackKey: string;
+    itemIdentifier: string;
+    transitions: {
+        correct: DiagnosticRoutingTransitionV1;
+        incorrect: DiagnosticRoutingTransitionV1;
+    };
+}
+interface DiagnosticRoutingTerminalV1 {
+    /** Internal routing-graph stop identity. */
+    key: string;
+    trackKey: string;
+    outcome: DiagnosticTrackOutcome;
+    /** Stable semantic result consumed by the game after diagnostic completion. */
+    resultKey: string;
+}
+/** Immutable sidecar attached to one exact diagnostic QTI bank revision. */
+interface DiagnosticRoutingManifestV1 {
+    version: typeof DIAGNOSTIC_ROUTING_MANIFEST_VERSION;
+    groups?: DiagnosticRoutingGroupV1[];
+    stages: DiagnosticRoutingStageV1[];
+    tracks: DiagnosticRoutingTrackV1[];
+    nodes: DiagnosticRoutingNodeV1[];
+    terminals: DiagnosticRoutingTerminalV1[];
+}
+type DiagnosticRoutingTrackStatus = 'pending' | 'active' | 'completed' | 'skipped';
+type DiagnosticRoutingStatus = 'in-progress' | 'ready-to-complete';
+interface DiagnosticRoutingNextItem {
+    stageKey: string;
+    trackKey: string;
+    nodeKey: string;
+    itemIdentifier: string;
+}
+/** Deliberately small semantic result exposed to normal game completion handlers. */
+interface DiagnosticTrackResult {
+    trackKey: string;
+    groupKey?: string;
+    outcome: DiagnosticTrackOutcome;
+    resultKey: string;
+}
+
+/** Stable curriculum-standard identity used to align and select assessment content. */
+interface AssessmentStandardRef {
+    framework: string;
+    identifier: string;
+}
+/**
+ * Playcademy's course-specific meaning for reusable QTI test content.
+ * Result writers translate this to OneRoster assessment-result `metadata.testType`;
+ * it intentionally does not become metadata on the QTI test itself.
+ */
+type AssessmentPurpose = (typeof ASSESSMENT_PURPOSES)[number];
+type AssessmentStatus = 'draft' | 'live' | 'archived';
+/** Immutable routing definition attached to one diagnostic assessment association. */
+interface DiagnosticAssessmentDefinition {
+    diagnosticKey: string;
+    routingManifest: DiagnosticRoutingManifestV1;
+}
+/** Caller-authored diagnostic sidecar. */
+type DiagnosticAssessmentDefinitionInput = DiagnosticAssessmentDefinition;
+interface AssessmentSummary {
+    id: string;
+    integrationId: string;
+    /** Stable logical identity. Null for unmanaged, read-only QTI drafts. */
+    assessmentKey: string | null;
+    qtiTestIdentifier: string;
+    purpose: AssessmentPurpose;
+    status: AssessmentStatus;
+    standard: AssessmentStandardRef | null;
+    /** Null for non-diagnostics and historical fixed diagnostic associations. */
+    diagnostic: DiagnosticAssessmentDefinition | null;
+    createdAt: string;
+    updatedAt: string;
+    title: string;
+    questionCount: number;
+    available: boolean;
+    editable: boolean;
+}
+interface AssessmentRow {
+    id: string;
+    integrationId: string;
+    /** Stable logical identity. Null for unmanaged, read-only QTI drafts. */
+    assessmentKey: string | null;
+    qtiTestIdentifier: string;
+    purpose: AssessmentPurpose;
+    status: AssessmentStatus;
+    standard: AssessmentStandardRef | null;
+    /** Null for non-diagnostics and historical fixed diagnostic associations. */
+    diagnostic: DiagnosticAssessmentDefinition | null;
+    createdAt: string;
+    updatedAt: string;
+    /** Non-fatal warning produced by the requested assessment operation. */
+    warning?: string;
+}
+/** Request body for replacing a live assessment's content in place. */
+interface AssessmentRevisionRequest {
+    /**
+     * The publication the author last saw. Doubles as an optimistic-concurrency token: if the
+     * assessment was revised in the meantime the request fails with a conflict.
+     */
+    currentQtiTestIdentifier: string;
+    title: string;
+    /** Structured question payloads, in order, as accepted by question creation. */
+    questions: Record<string, unknown>[];
+}
+/** Result of revising a live assessment. `qtiTestIdentifier` is the publication now live. */
+interface AssessmentRevisionResult extends AssessmentRow {
+    /** The publication that was live before this call; equals `qtiTestIdentifier` when unchanged. */
+    previousQtiTestIdentifier: string;
+    /** True when the new content hashed to the current publication and nothing changed. */
+    unchanged: boolean;
+}
+/** One shared-QTI test reference carried by an association promotion manifest. */
+interface AssessmentAssociationImportEntry {
+    /** Stable logical identity used to attach this publication to the target course. */
+    assessmentKey: string;
+    qtiTestIdentifier: string;
+    purpose: AssessmentPurpose;
+    standard?: AssessmentStandardRef;
+}
+/** Portable Playcademy association metadata derived from an assessment fixture export. */
+interface AssessmentAssociationImportManifest {
+    version: 1;
+    sourceGameId: string;
+    sourceGameSlug?: string;
+    sourceIntegrationId: string;
+    subject: TimebackSubject;
+    grade: TimebackGrade;
+    /** Lifecycle state assigned to newly attached target associations. */
+    targetStatus: Extract<AssessmentStatus, 'draft' | 'live'>;
+    assessments: AssessmentAssociationImportEntry[];
+}
+type AssessmentAssociationImportResultStatus = 'created' | 'skipped' | 'failed';
+/** Per-test outcome from attaching existing shared QTI content to another course. */
+interface AssessmentAssociationImportResult {
+    assessmentKey: string;
+    qtiTestIdentifier: string;
+    title?: string;
+    purpose: AssessmentPurpose;
+    standard?: AssessmentStandardRef;
+    status: AssessmentAssociationImportResultStatus;
+    association?: AssessmentRow;
+    editable?: boolean;
+    message?: string;
+}
+interface AssessmentAssociationImportResponse {
+    results: AssessmentAssociationImportResult[];
+}
+/** One shared item was claimed by multiple mastery standards; only the first assignment stands. */
+interface ReviewBankSyncWarning {
+    code: 'QUESTION_STANDARD_CONFLICT';
+    itemIdentifier: string;
+    retainedStandard: AssessmentStandardRef;
+    skippedStandard: AssessmentStandardRef;
+    skippedQtiTestIdentifier: string;
+    message: string;
+}
+/** Optimized artifacts could not be prepared, so QTI remains the runtime fallback. */
+interface AssessmentArtifactsUnavailableWarning {
+    code: 'ASSESSMENT_ARTIFACTS_UNAVAILABLE';
+    message: string;
+}
+type ReviewBankSynchronizationWarning = ReviewBankSyncWarning | AssessmentArtifactsUnavailableWarning;
+/** Wire result of synchronizing the review-bank sink to the live mastery catalog. */
+interface ReviewBankSynchronizationResult {
+    qtiTestIdentifier: string;
+    itemCount: number;
+    standardCount: number;
+    contributorCount: number;
+    sourceFingerprint: string;
+    addedItemCount: number;
+    removedItemCount: number;
+    unchanged: boolean;
+    warnings: readonly ReviewBankSynchronizationWarning[];
+}
+
+/** Private, declarative scoring content compiled from one immutable QTI publication. */
+/** QTI response shapes the platform grader can compare without a QTI engine. */
+type AssessmentScoringBaseTypeV1 = 'string' | 'identifier' | 'integer' | 'float' | 'directedPair';
+type AssessmentScoringCardinalityV1 = 'single' | 'multiple' | 'ordered';
+/** Exact QTI match semantics, interpreted according to `baseType` and `cardinality`. */
+interface AssessmentScoringMatchComparisonV1 {
+    kind: 'match';
+    /** Single string responses may list TimeBack-compatible accepted alternatives. */
+    correctValues: string[];
+}
+/** Numeric equality after parsing both operands as the rule's declared numeric base type. */
+interface AssessmentScoringNumericEqualComparisonV1 {
+    kind: 'numeric-equal';
+    correctValue: number;
+}
+/** Numeric equality after applying the QTI equal-rounded comparison to both operands. */
+interface AssessmentScoringNumericEqualRoundedComparisonV1 {
+    kind: 'numeric-equal-rounded';
+    correctValue: number;
+    roundingMode: 'decimalPlaces' | 'significantFigures';
+    figures: number;
+}
+type AssessmentScoringComparisonV1 = AssessmentScoringMatchComparisonV1 | AssessmentScoringNumericEqualComparisonV1 | AssessmentScoringNumericEqualRoundedComparisonV1;
+/** One independently scored response. Correct-answer material never enters the playable artifact. */
+interface AssessmentScoringRuleV1 {
+    responseIdentifier: string;
+    cardinality: AssessmentScoringCardinalityV1;
+    baseType: AssessmentScoringBaseTypeV1;
+    points: number;
+    comparison: AssessmentScoringComparisonV1;
+}
+/** Stable reason codes for routing an item back through authoritative QTI grading. */
+type AssessmentQtiScoringFallbackReasonV1 = 'response-mapping' | 'area-mapping' | 'unsupported-base-type' | 'unsupported-cardinality' | 'invalid-correct-response' | 'no-scorable-response' | 'unsupported-processing-template' | 'unsupported-response-processing' | 'cross-response-processing' | 'inconsistent-max-score';
+interface PlatformAssessmentScoringArtifactItemV1 {
+    strategy: 'platform';
+    itemIdentifier: string;
+    maxScore: number;
+    rules: AssessmentScoringRuleV1[];
+}
+/** No answers are retained for a fallback item; the QTI source remains authoritative. */
+interface QtiAssessmentScoringArtifactItemV1 {
+    strategy: 'qti';
+    itemIdentifier: string;
+    maxScore: number;
+    reason: AssessmentQtiScoringFallbackReasonV1;
+}
+type AssessmentScoringArtifactItemV1 = PlatformAssessmentScoringArtifactItemV1 | QtiAssessmentScoringArtifactItemV1;
+/** Private grader payload assembled in deterministic QTI question order. */
+interface AssessmentScoringArtifactV1 {
+    items: AssessmentScoringArtifactItemV1[];
+}
+
+/** One answer value accepted by the supported QTI runtime interactions. */
+type AssessmentResponseValue = string | string[];
+/** Canonical response state persisted on an assessment attempt. */
+type AssessmentResponses = Record<string, Record<string, AssessmentResponseValue>>;
+/**
+ * Partial update accepted by save(), merged into the stored responses at both
+ * levels: an omitted question keeps its answers, and an omitted response keeps
+ * its value. Null clears one response, and clearing the last response of a
+ * question drops the question.
+ *
+ * Merging rather than replacing is what makes the obvious write safe. An item
+ * may hold several interactions, so saving the one a student just answered —
+ * `{ item: { RESPONSE_2: 'B' } }` — must not disturb its siblings. Under
+ * replacement it silently discarded them, and nothing in the payload said so.
+ */
+type AssessmentResponseUpdate = Record<string, Record<string, AssessmentResponseValue | null>>;
+/**
+ * One node of the rich-content vocabulary, which is OPEN: kinds are added as
+ * content that plain text would misrepresent appears, so a consumer must not
+ * treat this union as exhaustive.
+ *
+ * Structured content is projected from sanitized QTI on the host — never raw
+ * XML/HTML — and always travels alongside a flattened plain-text equivalent, so
+ * simple clients can ignore it entirely.
+ *
+ * A node carries no field common to every kind, so there is nothing to
+ * introspect on an unrecognized one. The supported fallback is one level up:
+ * abandon the whole subtree and render the enclosing `prompt` / `content`
+ * string, which is always present.
+ *
+ * Say so on screen when that happens. A question whose diagram or expression
+ * carried what was being asked still reads as complete prose once the structure
+ * is gone, so a silent fallback can leave a student an unanswerable question
+ * with nothing to indicate why.
+ */
+type PlayableContentNode = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'math';
+    /** Sanitized MathML source for clients that can render it. */
+    mathMl: string;
+    /** Plain-text approximation for clients that cannot. */
+    fallbackText: string;
+} | {
+    kind: 'image';
+    src: string;
+    width?: number;
+    height?: number;
+    description?: string;
+} | {
+    kind: 'paragraph';
+    children: PlayableContentNode[];
+} | {
+    kind: 'emphasis';
+    children: PlayableContentNode[];
+} | {
+    kind: 'strong';
+    children: PlayableContentNode[];
+} | {
+    kind: 'table';
+    rows: {
+        header: boolean;
+        cells: PlayableContentNode[][];
+    }[];
+}
+/**
+ * A bulleted or numbered list. Modelled because flattening one to plain text
+ * genuinely changes its meaning — "one two" is not a list — unlike inline
+ * emphasis, which reads correctly either way and so is not carried.
+ */
+ | {
+    kind: 'list';
+    /** Numbered (`ol`) rather than bulleted (`ul`). */
+    ordered: boolean;
+    items: PlayableContentNode[][];
+}
+/**
+ * Where one inline interaction belongs in the prose, naming the interaction
+ * it stands for rather than relying on its position among sibling blanks.
+ *
+ * The identifier is what makes this robust: matching blanks to interactions
+ * by order silently mispairs them when either sequence shifts, and a
+ * mispaired dropdown produces a wrong answer rather than a visible error.
+ */
+ | {
+    kind: 'blank';
+    responseIdentifier: string;
+}
+/** One named target inside a gap-match passage. */
+ | {
+    kind: 'gap';
+    identifier: string;
+};
+interface PlayableAssessmentChoice {
+    identifier: string;
+    content: string;
+    /** Keep this choice in its authored slot when the interaction is shuffled. */
+    fixed?: boolean;
+    /** Rich content when the choice carries more than plain text. */
+    contentNodes?: PlayableContentNode[];
+}
+/** A Match choice, which unlike an ordinary choice carries an association capacity. */
+interface PlayableMatchChoice extends PlayableAssessmentChoice {
+    /** Associations this choice accepts (0 means unlimited). */
+    matchMax: number;
+}
+interface PlayableAssessmentInteractionBase {
+    responseIdentifier: string;
+    /** Prompt declared inside the interaction (QTI qti-prompt), when present. */
+    prompt?: string;
+}
+interface PlayableChoiceInteraction extends PlayableAssessmentInteractionBase {
+    type: 'choice';
+    choices: PlayableAssessmentChoice[];
+    /** The host has already applied attempt-stable ordering; render the received array. */
+    shuffle: boolean;
+    minChoices: number;
+    maxChoices: number;
+}
+interface PlayableInlineChoiceInteraction extends PlayableAssessmentInteractionBase {
+    type: 'inline-choice';
+    choices: PlayableAssessmentChoice[];
+    /** The host has already applied attempt-stable ordering; render the received array. */
+    shuffle: boolean;
+}
+interface PlayableTextEntryInteraction extends PlayableAssessmentInteractionBase {
+    type: 'text-entry';
+    expectedLength?: number;
+    placeholder?: string;
+}
+interface PlayableOrderInteraction extends PlayableAssessmentInteractionBase {
+    type: 'order';
+    choices: PlayableAssessmentChoice[];
+    /** Whether the host applies attempt-stable presentation ordering. */
+    shuffle: boolean;
+}
+interface PlayableMatchInteraction extends PlayableAssessmentInteractionBase {
+    type: 'match';
+    sourceChoices: PlayableMatchChoice[];
+    targetChoices: PlayableMatchChoice[];
+    maxAssociations: number;
+    /** Whether the host applies independent attempt-stable ordering to both choice sets. */
+    shuffle: boolean;
+}
+interface PlayableHottextSegment {
+    identifier?: string;
+    content: string;
+    selectable: boolean;
+}
+interface PlayableHottextInteraction extends PlayableAssessmentInteractionBase {
+    type: 'hottext';
+    segments: PlayableHottextSegment[];
+    maxChoices: number;
+}
+/** A sanitized graphic reference rendered by graphic interactions. */
+interface PlayableAssessmentGraphic {
+    src: string;
+    width?: number;
+    height?: number;
+    /** Accessible description carried from the source QTI. */
+    description?: string;
+}
+/** The QTI region shape vocabulary shared by hotspots and scored areas. */
+declare const PLAYABLE_ASSESSMENT_SHAPES: readonly ['circle', 'ellipse', 'rect', 'poly', 'default'];
+type PlayableAssessmentShape = (typeof PLAYABLE_ASSESSMENT_SHAPES)[number];
+/** A clickable or associable region positioned on a graphic. */
+interface PlayableAssessmentHotspot {
+    identifier: string;
+    shape: PlayableAssessmentShape;
+    coords: number[];
+    /** Maximum associations this region accepts (0 or absent means unlimited). */
+    matchMax?: number;
+    description?: string;
+}
+interface PlayableHotspotInteraction extends PlayableAssessmentInteractionBase {
+    type: 'hotspot';
+    image: PlayableAssessmentGraphic;
+    hotspots: PlayableAssessmentHotspot[];
+    minChoices: number;
+    /** Always a concrete cap: an authored 0 (QTI: unlimited) resolves to the region count. */
+    maxChoices: number;
+}
+interface PlayableGapMatchChoice {
+    identifier: string;
+    content: string;
+    /** Keep this token in its authored bank slot, not a passage gap. */
+    fixed?: boolean;
+    /** Times this token may be placed (0 means unlimited). */
+    matchMax: number;
+}
+interface PlayableGapMatchInteraction extends PlayableAssessmentInteractionBase {
+    type: 'gap-match';
+    /** Shuffle the token bank without moving passage gaps. */
+    shuffle: boolean;
+    /** Passage containing each gap as a `___` blank, in `gaps` order. */
+    content: string;
+    /** Structured passage retaining each named gap at its authored inline position. */
+    contentNodes: PlayableContentNode[];
+    gapTexts: PlayableGapMatchChoice[];
+    /** Ordered gap identifiers matching the passage blanks. */
+    gaps: string[];
+    /** Overall pair limit (0 means unlimited). */
+    maxAssociations: number;
+}
+interface PlayableGapImageChoice {
+    identifier: string;
+    image?: PlayableAssessmentGraphic;
+    /** Times this token may be placed (0 means unlimited). */
+    matchMax: number;
+    description?: string;
+}
+interface PlayableGraphicGapMatchInteraction extends PlayableAssessmentInteractionBase {
+    type: 'graphic-gap-match';
+    image: PlayableAssessmentGraphic;
+    gapImages: PlayableGapImageChoice[];
+    hotspots: PlayableAssessmentHotspot[];
+    /** Overall pair limit (0 means unlimited). */
+    maxAssociations: number;
+}
+interface PlayableSelectPointInteraction extends PlayableAssessmentInteractionBase {
+    type: 'select-point';
+    image: PlayableAssessmentGraphic;
+    minChoices: number;
+    maxChoices: number;
+}
+interface PlayableGraphicAssociateInteraction extends PlayableAssessmentInteractionBase {
+    type: 'graphic-associate';
+    image: PlayableAssessmentGraphic;
+    hotspots: PlayableAssessmentHotspot[];
+    maxAssociations: number;
+}
+interface PlayablePositionObjectInteraction extends PlayableAssessmentInteractionBase {
+    type: 'position-object';
+    /** Background stage the object is placed onto. */
+    stage: PlayableAssessmentGraphic;
+    /** The movable object image. */
+    object: PlayableAssessmentGraphic;
+    /** Maximum number of placements. */
+    maxPlacements: number;
+}
+type PlayableAssessmentInteraction = PlayableChoiceInteraction | PlayableInlineChoiceInteraction | PlayableTextEntryInteraction | PlayableOrderInteraction | PlayableMatchInteraction | PlayableHottextInteraction | PlayableHotspotInteraction | PlayableGapMatchInteraction | PlayableGraphicGapMatchInteraction | PlayableSelectPointInteraction | PlayableGraphicAssociateInteraction | PlayablePositionObjectInteraction;
+interface PlayableAssessmentItem {
+    identifier: string;
+    title: string;
+    /**
+     * Shared item stem, flattened to plain text. Inline interactions appear as
+     * `___`, and block interactions belong after the prompt in `interactions`
+     * order.
+     *
+     * The `___` marks that a blank is there, not which interaction fills it or
+     * exactly where it sits: word offsets into this string are not part of the
+     * contract. Prose is translated, re-wrapped, and tokenized differently by
+     * language — a position counted in words does not survive any of that, and
+     * languages that do not separate words with spaces have no such position to
+     * count. Read `promptContent` to place blanks precisely; a client that
+     * ignores it should render inline interactions after the prompt.
+     */
+    prompt: string;
+    /**
+     * Structured prompt content, present whenever the stem holds an inline
+     * interaction or anything plain text would misrepresent — images, tables,
+     * lists, MathML. Absent means `prompt` says everything.
+     *
+     * Inline interactions appear as `blank` nodes carrying the response
+     * identifier they belong to.
+     */
+    promptContent?: PlayableContentNode[];
+    /** Maximum points awarded by the item's declared outcome (1 when undeclared). */
+    maxScore: number;
+    /** Document-ordered interactions with item-unique response identifiers. */
+    interactions: PlayableAssessmentInteraction[];
+}
+/** Sanitized assessment content safe to return to a sandboxed game. */
+interface PlayableAssessment {
+    identifier: string;
+    /**
+     * Schema version of this payload's shape, never of its content.
+     *
+     * Present so a game can tell a field the host does not send from one this
+     * item does not use, and so a mismatch is legible in a bug report. Branch on
+     * whether a field is present rather than on this number — the content
+     * vocabularies are deliberately open, so feature detection survives
+     * versions that a comparison against a fixed number does not.
+     */
+    contractVersion: typeof PLAYCADEMY_ASSESSMENT_CONTRACT_VERSION;
+    /**
+     * Opaque revision of this assessment's content, used to ensure a resumed
+     * attempt loads what it started with. Changes when an author edits the
+     * assessment; unrelated to `contractVersion`.
+     */
+    contentRevision: string;
+    title: string;
+    items: PlayableAssessmentItem[];
+}
+interface AssessmentScore {
+    earned: number;
+    possible: number;
+    /** Aggregate score normalized to the inclusive 0..1 range. */
+    normalized: number;
+}
+type FixedAssessmentPurpose = Exclude<AssessmentPurpose, 'review'>;
+/** Fixed-test purposes that do not select their catalog by curriculum standard. */
+type UnscopedFixedAssessmentPurpose = Exclude<FixedAssessmentPurpose, 'mastery'>;
+/** One requested standard slot and the playable bank item selected for it. */
+interface AssessmentReviewItemSelection {
+    standard: AssessmentStandardRef;
+    itemIdentifier: string;
+}
+/** Why one requested standard could not be fully served by the current bank. */
+interface AssessmentReviewShortage {
+    standard: AssessmentStandardRef;
+    requested: number;
+    selected: number;
+    eligible: number;
+}
+/**
+ * Explicit review-request fulfillment. A partial result still starts a normal
+ * assessment attempt with every selectable item; no missing standard is
+ * silently omitted.
+ */
+type AssessmentReviewFulfillment = {
+    status: 'complete';
+    requestedItemCount: number;
+    selectedItemCount: number;
+    shortages: [];
+} | {
+    status: 'partial';
+    requestedItemCount: number;
+    selectedItemCount: number;
+    shortages: AssessmentReviewShortage[];
+};
+interface FixedAssessmentSelectionContext {
+    kind: 'fixed-test';
+    purpose: UnscopedFixedAssessmentPurpose;
+}
+/** A complete fixed quiz selected from the catalog for one canonical standard. */
+interface StandardQuizSelectionContext {
+    kind: 'standard-quiz';
+    purpose: 'mastery';
+    standard: AssessmentStandardRef;
+}
+/** Administration policy for one requested review skill, separate from its identity. */
+interface AssessmentReviewStandard extends AssessmentStandardRef {
+    /** Require this skill's second selected question, subject to the player's cap. */
+    requireBothQuestions?: boolean;
+}
+interface StandardsReviewSelectionContext {
+    kind: 'standards-review';
+    purpose: 'review';
+    standards: AssessmentReviewStandard[];
+    candidateItemsPerStandard: number;
+    selections: AssessmentReviewItemSelection[];
+    fulfillment: AssessmentReviewFulfillment;
+}
+/** Immutable identity pinned when the host starts a platform-routed diagnostic. */
+interface PlatformRoutedDiagnosticSelectionContext {
+    kind: 'platform-routed-diagnostic';
+    purpose: 'diagnostic';
+    definitionId: string;
+    diagnosticKey: string;
+    routingRevision: string;
+}
+/** How the host assembled the playable assessment returned for this attempt. */
+type AssessmentSelectionContext = FixedAssessmentSelectionContext | StandardQuizSelectionContext | StandardsReviewSelectionContext | PlatformRoutedDiagnosticSelectionContext;
+/** Server-derived assessment interaction model; callers select it only through purpose. */
+type AssessmentFlow = 'attempt-submit' | 'item-submit' | 'platform-routed-item-submit';
+/** Safe feedback persisted when one item is committed in an item-submit flow. */
+type AssessmentItemGrading = {
+    source: 'timeback-qti';
+    graderVersion: string;
+} | {
+    source: 'platform-qti-adapter';
+    graderVersion: string;
+    qtiGraderVersion: string;
+} | {
+    source: 'platform-artifact';
+    artifactVersion: string;
+    graderVersion: string;
+};
+interface AssessmentItemSubmission {
+    /** Stable caller-generated key used to replay a lost success response. */
+    submissionId: string;
+    itemIdentifier: string;
+    /** Stable administration timestamp used for exposure ordering and resume reconciliation. */
+    submittedAt: string;
+    /** One-based position in the validated administration sequence. */
+    responseVersion: number;
+    answered: boolean;
+    score: AssessmentScore;
+    isCorrect: boolean | null;
+    /**
+     * Trusted grading provenance pinned at grading time so child-result repair
+     * reproduces the corresponding child projection. Absent only on attempts
+     * committed before provenance was introduced.
+     */
+    grading?: AssessmentItemGrading;
+}
+/** Raw answers only. Array order is the administration sequence; no grades are trusted. */
+interface AssessmentTranscript {
+    version: 1;
+    attemptId: string;
+    /** The selected source revision, not a review subset's presentation revision. */
+    contentRevision: string;
+    administrations: {
+        submissionId: string;
+        itemIdentifier: string;
+        routingNodeKey?: string;
+        /** An empty response is still an administered question. */
+        responses: Record<string, AssessmentResponseValue>;
+    }[];
+}
+interface ResumeAssessmentInput {
+    /** Omit to recover the parent checkpoint, or best-effort child progress if none exists. */
+    transcript?: AssessmentTranscript;
+}
+/**
+ * Canonical activity context the SDK uses to track time for this attempt. A
+ * narrowed `ActivityData`, so it can be handed straight to the shared clock:
+ * the course routing fields are resolved rather than optional.
+ */
+type AssessmentActivityData = Pick<ActivityData, 'activityId' | 'courseId'> & {
+    activityName: string;
+    grade: TimebackGrade;
+    subject: TimebackSubject;
+};
+interface AssessmentAttemptSnapshotBase {
+    attemptId: string;
+    responseVersion: number;
+    status: 'in_progress';
+    /** Resolved server context for the shared activity-session clock, when valid. */
+    activityData?: AssessmentActivityData;
+    assessment: PlayableAssessment;
+    /** Opaque, attempt-scoped authorization. Renew through start/resume, not per answer. */
+    assessmentToken: string;
+    transcript: AssessmentTranscript;
+}
+/** Existing fixed, mastery, and review attempt shape. */
+interface ConventionalAssessmentAttemptSnapshot extends AssessmentAttemptSnapshotBase {
+    /** Historical fixed diagnostics remain attempt-submit and are never reinterpreted. */
+    flow: Exclude<AssessmentFlow, 'platform-routed-item-submit'>;
+    responses: AssessmentResponses;
+    /** Ordered committed-item ledger. Empty for attempt-submit flows. */
+    itemSubmissions: AssessmentItemSubmission[];
+    score: AssessmentScore | null;
+    selection: Exclude<AssessmentSelectionContext, PlatformRoutedDiagnosticSelectionContext>;
+}
+/** Safe public track progress; authored terminal semantics stay host-only until completion. */
+interface DiagnosticRoutingTrackSnapshot {
+    trackKey: string;
+    groupKey?: string;
+    status: DiagnosticRoutingTrackStatus;
+    administeredCount: number;
+}
+/** Safe canonical routing projection returned while a diagnostic is in progress. */
+interface DiagnosticRoutingSnapshot {
+    kind: 'platform-routed-diagnostic';
+    revision: string;
+    status: DiagnosticRoutingStatus;
+    next: DiagnosticRoutingNextItem | null;
+    tracks: DiagnosticRoutingTrackSnapshot[];
+}
+/** Small semantic diagnostic result consumed by the game after finalization. */
+interface DiagnosticAssessmentSubmitResult {
+    purpose: 'diagnostic';
+    attemptId: string;
+    submissionId: string;
+    diagnosticKey: string;
+    responseVersion: number;
+    status: 'awaiting_award';
+    tracks: DiagnosticTrackResult[];
+}
+/** Platform-routed diagnostics never expose grading, feedback, or their committed ledger. */
+interface PlatformRoutedDiagnosticAttemptSnapshot extends AssessmentAttemptSnapshotBase {
+    flow: 'platform-routed-item-submit';
+    selection: PlatformRoutedDiagnosticSelectionContext;
+    routing: DiagnosticRoutingSnapshot;
+    completion: null;
+}
+interface AssessmentSaveResult {
+    attemptId: string;
+    responseVersion: number;
+    status: 'in_progress';
+    responses: AssessmentResponses;
+    transcript: AssessmentTranscript;
+}
+interface AssessmentSubmitResultBase {
+    attemptId: string;
+    submissionId: string;
+    responseVersion: number;
+    status: 'awaiting_award';
+    responses: AssessmentResponses;
+    score: AssessmentScore;
+}
+interface FixedAssessmentSubmitResult extends AssessmentSubmitResultBase {
+    purpose: UnscopedFixedAssessmentPurpose;
+}
+/** Safe final item grade, exposed only after the assessment is submitted. */
+interface AssessmentItemOutcome {
+    itemIdentifier: string;
+    standard: AssessmentStandardRef;
+    answered: boolean;
+    score: AssessmentScore;
+    isCorrect: boolean | null;
+}
+interface ReviewAssessmentSubmitResult extends AssessmentSubmitResultBase {
+    purpose: 'review';
+    /** Final outcomes in committed transcript order, excluding unused candidates. */
+    itemOutcomes: AssessmentItemOutcome[];
+}
+interface MasteryAssessmentSubmitResult extends AssessmentSubmitResultBase {
+    purpose: 'mastery';
+    /** One final outcome per question in test order, including unanswered questions. */
+    itemOutcomes: AssessmentItemOutcome[];
+}
+type ConventionalAssessmentSubmitResult = FixedAssessmentSubmitResult | ReviewAssessmentSubmitResult | MasteryAssessmentSubmitResult;
+type AssessmentSubmitResult = ConventionalAssessmentSubmitResult | DiagnosticAssessmentSubmitResult;
+type CompletedAssessmentResult<TResult extends AssessmentSubmitResult> = Omit<TResult, 'status'> & {
+    status: 'completed';
+    /** XP durably recorded on the authoritative OneRoster AssessmentResult. */
+    xpAwarded: number;
+    /**
+     * The mastery delta durably recorded on the authoritative result after
+     * platform bounding. Zero when the game awarded no mastery.
+     */
+    masteredUnitsApplied: number;
+    /** Course completion percentage after this award, when mastery tracking is configured. */
+    pctCompleteApp?: number;
+    /** Non-fatal bounding warnings raised while applying the award. */
+    warnings?: MasteryWriteWarning[];
+};
+/** Terminal result returned only after the game's award has been recorded. */
+type AssessmentFinalizeResult = CompletedAssessmentResult<FixedAssessmentSubmitResult> | CompletedAssessmentResult<ReviewAssessmentSubmitResult> | CompletedAssessmentResult<MasteryAssessmentSubmitResult> | CompletedAssessmentResult<DiagnosticAssessmentSubmitResult>;
+/** Minimal recovery snapshot; no QTI content load is required after answers are locked. */
+type SettledAssessmentAttemptSnapshot = {
+    attemptId: string;
+    responseVersion: number;
+    status: 'awaiting_award';
+    result: AssessmentSubmitResult;
+} | {
+    attemptId: string;
+    responseVersion: number;
+    status: 'completed';
+    result: AssessmentFinalizeResult;
+};
+/** Snapshot states that are still open for responses. */
+type PlayableAssessmentAttemptSnapshot = ConventionalAssessmentAttemptSnapshot | PlatformRoutedDiagnosticAttemptSnapshot;
+type AssessmentAttemptSnapshot = PlayableAssessmentAttemptSnapshot | SettledAssessmentAttemptSnapshot;
+interface StartAssessmentInputBase {
+    activityId: string;
+    subject?: TimebackSubject;
+    grade?: TimebackGrade;
+}
+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;
+}
+
 /**
  * Base error class for Cademy SDK specific errors.
  */
@@ -2162,7 +5255,7 @@ declare abstract class PlaycademyBaseClient {
      * - `me()` - Get authenticated user profile
      */
     users: {
-        me: () => Promise<_playcademy_types.AuthenticatedUser>;
+        me: () => Promise<AuthenticatedUser>;
     };
 }
 
@@ -3353,6 +6446,23 @@ interface PlatformTimebackUser extends PlatformTimebackUserContext {
     }): Promise<PlatformTimebackUserContext>;
 }
 
+/**
+ * D1 Database types
+ */
+
+
+
+/**
+ * Schema information for database migrations
+ * Generated by comparing previous and current schema snapshots
+ */
+interface SchemaInfo {
+    /** SQL migration statements (DDL: CREATE, ALTER, etc.) */
+    sql: string
+    /** Hash of the schema for change detection (stringified Drizzle schema JSON) */
+    hash: string
+}
+
 /**
  * @fileoverview Server SDK Type Definitions
  *
@@ -3779,43 +6889,43 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
     dev: {
         status: {
             apply: () => Promise<void>;
-            get: () => Promise<_playcademy_types.DeveloperStatusValue>;
+            get: () => Promise<DeveloperStatusValue>;
         };
         games: {
             list: () => Promise<Game[]>;
             deploymentState: (slug: string, options?: {
                 include?: 'schemaSnapshot';
-            }) => Promise<_playcademy_types.DeploymentStateResponse>;
+            }) => Promise<DeploymentStateResponse>;
             deployments: (slug: string, options?: {
                 limit?: number;
-            }) => Promise<_playcademy_types.GameDeployHistoryResponse>;
-            reportDeployBlocked: (slug: string, report: _playcademy_types.DeployBlockedReport) => Promise<{
+            }) => Promise<GameDeployHistoryResponse>;
+            reportDeployBlocked: (slug: string, report: DeployBlockedReport) => Promise<{
                 recorded: boolean;
             }>;
-            deploymentStateBaseline: (slug: string, body: _playcademy_types.DeploymentStateBaselineRequest) => Promise<_playcademy_types.DeploymentStateResponse>;
-            migrationRealign: (slug: string, tag: string, checksum: string) => Promise<_playcademy_types.MigrationRealignResponse>;
-            migrationResolve: (slug: string, tag: string, resolution: _playcademy_types.MigrationResolution, checksum?: string) => Promise<_playcademy_types.MigrationResolveResponse>;
+            deploymentStateBaseline: (slug: string, body: DeploymentStateBaselineRequest) => Promise<DeploymentStateResponse>;
+            migrationRealign: (slug: string, tag: string, checksum: string) => Promise<MigrationRealignResponse>;
+            migrationResolve: (slug: string, tag: string, resolution: MigrationResolution, checksum?: string) => Promise<MigrationResolveResponse>;
             deploy: (slug: string, options: {
                 metadata?: UpsertGameMetadataInput;
                 file?: File | Blob | null;
                 worker?: WorkerDeploymentBundle;
                 hooks?: DevUploadHooks;
                 deployId?: string;
-                database?: _playcademy_types.DeployDatabasePayload;
-                baseline?: _playcademy_types.DeployBaseline;
+                database?: DeployDatabasePayload;
+                baseline?: DeployBaseline;
                 buildHash?: string;
                 integrationsHash?: string;
                 pruneSecrets?: string[];
-                source?: _playcademy_types.DeploySource;
+                source?: DeploySource;
             }) => Promise<Game>;
-            seed: (slug: string, code: string, environment?: 'local' | 'staging' | 'production', secrets?: Record<string, string>) => Promise<_playcademy_types.SeedResponse>;
+            seed: (slug: string, code: string, environment?: 'local' | 'staging' | 'production', secrets?: Record<string, string>) => Promise<SeedResponse>;
             upsert: (slug: string, metadata: UpsertGameMetadataInput) => Promise<Game>;
             delete: (gameId: string) => Promise<void>;
             secrets: {
                 set: (slug: string, secrets: Record<string, string>) => Promise<string[]>;
                 list: (slug: string) => Promise<string[]>;
                 delete: (slug: string, key: string) => Promise<void>;
-                diff: (slug: string, secrets: Record<string, string>) => Promise<_playcademy_types.SecretsDiffResponse>;
+                diff: (slug: string, secrets: Record<string, string>) => Promise<SecretsDiffResponse>;
             };
             dashboard: {
                 deploy: (slug: string, options: {
@@ -3838,16 +6948,16 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
                 };
             };
             database: {
-                reset: (slug: string, body?: _playcademy_types.DatabaseResetRequest) => Promise<{
+                reset: (slug: string, body?: DatabaseResetRequest) => Promise<{
                     success: boolean;
                     deploymentId: string;
                     resetAt: string;
                     schemaPushed: boolean;
                 }>;
-                restorePoints: (slug: string) => Promise<_playcademy_types.GameRestorePointsResponse>;
+                restorePoints: (slug: string) => Promise<GameRestorePointsResponse>;
                 restore: (slug: string, body: {
                     restorePointId: string;
-                }) => Promise<_playcademy_types.DatabaseRestoreResponse>;
+                }) => Promise<DatabaseRestoreResponse>;
             };
             bucket: {
                 list: (slug: string, prefix?: string) => Promise<BucketFile[]>;
@@ -3913,7 +7023,7 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
             get: (gameId: string, options?: {
                 limit?: number;
                 offset?: number;
-            }) => Promise<_playcademy_types.LeaderboardEntry[]>;
+            }) => Promise<LeaderboardEntry[]>;
         };
     };
     /**
@@ -3922,8 +7032,8 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
      * - `submit(leaderboardId, score)` - Submit score to leaderboard
      */
     leaderboard: {
-        fetch: (options?: _playcademy_types.LeaderboardOptions) => Promise<_playcademy_types.GameLeaderboardEntry[]>;
-        getUserRank: (gameId: string, userId: string) => Promise<_playcademy_types.UserRank | null>;
+        fetch: (options?: LeaderboardOptions) => Promise<GameLeaderboardEntry[]>;
+        getUserRank: (gameId: string, userId: string) => Promise<UserRank | null>;
     };
     /**
      * Open deploy provenance: which commit is running for each game.
@@ -3931,10 +7041,10 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
      * - `get(slug, { history })` - One game's release and recent deploys
      */
     releases: {
-        list: () => Promise<_playcademy_types.ReleasesResponse>;
+        list: () => Promise<ReleasesResponse>;
         get: (slug: string, options?: {
             history?: number;
-        }) => Promise<_playcademy_types.GameReleaseResponse>;
+        }) => Promise<GameReleaseResponse>;
     };
     /**
      * Score submission and user score queries.
@@ -3945,7 +7055,7 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
         submit: (gameId: string, score: number, metadata?: Record<string, unknown>) => Promise<ScoreSubmission>;
         getByUser: (gameId: string, userId: string, options?: {
             limit?: number;
-        }) => Promise<_playcademy_types.UserScore[]>;
+        }) => Promise<UserScore[]>;
     };
     /**
      * TimeBack integration for user context and course management.
@@ -3965,101 +7075,101 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
         populateStudent: (names?: {
             firstName?: string;
             lastName?: string;
-        }) => Promise<_playcademy_types.PopulateStudentResponse>;
+        }) => Promise<PopulateStudentResponse>;
         readonly currentRunId: string | undefined;
-        startActivity: (_metadata: _playcademy_types.ActivityData, _options?: StartActivityOptions) => StartActivityResult;
+        startActivity: (_metadata: ActivityData, _options?: StartActivityOptions) => StartActivityResult;
         pauseActivity: () => void;
         resumeActivity: () => void;
-        endActivity: (_data: _playcademy_types.EndActivityScoreData) => Promise<_playcademy_types.EndActivityResponse>;
+        endActivity: (_data: EndActivityScoreData) => Promise<EndActivityResponse>;
         management: {
-            setup: (request: _playcademy_types.PlatformTimebackSetupRequest) => Promise<_playcademy_types.PlatformTimebackSetupResponse>;
-            verify: (gameId: string) => Promise<_playcademy_types.TimebackVerifyAllResponse>;
+            setup: (request: PlatformTimebackSetupRequest) => Promise<PlatformTimebackSetupResponse>;
+            verify: (gameId: string) => Promise<TimebackVerifyAllResponse>;
             cleanup: (gameId: string) => Promise<void>;
-            get: (gameId: string) => Promise<_playcademy_types.GameTimebackIntegration[]>;
-            getRemovedIntegrations: (gameId: string) => Promise<_playcademy_types.RemovedGameTimebackIntegration[]>;
-            createIntegration: (gameId: string, request: _playcademy_types.CreateGameTimebackIntegrationRequest) => Promise<_playcademy_types.GameTimebackIntegration>;
-            updateIntegration: (gameId: string, courseId: string, request: _playcademy_types.UpdateGameTimebackIntegrationRequest) => Promise<_playcademy_types.GameTimebackIntegration>;
-            deactivateCourse: (gameId: string, courseId: string) => Promise<_playcademy_types.GameTimebackIntegration>;
-            reactivateCourse: (gameId: string, courseId: string) => Promise<_playcademy_types.GameTimebackIntegration>;
-            getIntegrationConfig: (gameId: string, courseId: string) => Promise<_playcademy_types.GameTimebackIntegrationConfig>;
-            getConfig: (gameId: string) => Promise<_playcademy_types.TimebackSetupRequest['config']>;
-            exportAssessmentFixtures: (gameId: string) => Promise<_playcademy_types.AssessmentRuntimeFixtureBundle>;
+            get: (gameId: string) => Promise<GameTimebackIntegration[]>;
+            getRemovedIntegrations: (gameId: string) => Promise<RemovedGameTimebackIntegration[]>;
+            createIntegration: (gameId: string, request: CreateGameTimebackIntegrationRequest) => 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>;
+            getIntegrationConfig: (gameId: string, courseId: string) => Promise<GameTimebackIntegrationConfig>;
+            getConfig: (gameId: string) => Promise<TimebackSetupRequest['config']>;
+            exportAssessmentFixtures: (gameId: string) => Promise<AssessmentRuntimeFixtureBundle>;
         };
         students: {
             get: (timebackId: string, options?: TTLCacheConfig) => Promise<PlatformTimebackUserContext>;
             clearCache: (timebackId?: string) => void;
         };
         admin: {
-            getRoster: (gameId: string, courseId: string) => Promise<_playcademy_types.TimebackRosterResponse>;
+            getRoster: (gameId: string, courseId: string) => Promise<TimebackRosterResponse>;
             getStudentOverview: (timebackId: string, options: {
                 gameId: string;
                 courseId?: string;
-            }) => Promise<_playcademy_types.TimebackStudentOverviewResponse>;
+            }) => Promise<TimebackStudentOverviewResponse>;
             getGameMetrics: (timebackId: string, options: {
                 gameId: string;
                 runIds?: string[];
-            }) => Promise<_playcademy_types.GameMetricsProxyResponse>;
+            }) => Promise<GameMetricsProxyResponse>;
             getStudentActivity: (timebackId: string, courseId: string, options: {
                 gameId: string;
                 limit?: number;
                 offset?: number;
-            }) => Promise<_playcademy_types.TimebackStudentActivityResponse>;
-            getGradeLevelTestResults: (gameId: string, courseId: string, studentId: string) => Promise<_playcademy_types.TimebackGradeLevelTestResultsResponse>;
-            getGradeLevelTestReview: (gameId: string, courseId: string, resultId: string, studentId: string) => Promise<_playcademy_types.TimebackGradeLevelTestReviewResponse>;
+            }) => Promise<TimebackStudentActivityResponse>;
+            getGradeLevelTestResults: (gameId: string, courseId: string, studentId: string) => Promise<TimebackGradeLevelTestResultsResponse>;
+            getGradeLevelTestReview: (gameId: string, courseId: string, resultId: string, studentId: string) => Promise<TimebackGradeLevelTestReviewResponse>;
             getActivityDetail: (timebackId: string, courseId: string, activityId: string, options: {
                 gameId: string;
                 runId?: string;
-            }) => Promise<_playcademy_types.TimebackActivityDetailResponse>;
+            }) => Promise<TimebackActivityDetailResponse>;
             getMetricDiscrepancies: (gameId: string, courseId: string, options?: {
-                window?: _playcademy_types.TimebackDiscrepancyQueueWindow;
+                window?: TimebackDiscrepancyQueueWindow;
                 startDate?: string;
                 endDate?: string;
                 studentId?: string;
-                discrepancyMetricScopes?: _playcademy_types.GameMetricComparisonMetric[];
+                discrepancyMetricScopes?: GameMetricComparisonMetric[];
                 includeVerified?: boolean;
                 eventOffset?: number;
-            }) => Promise<_playcademy_types.TimebackMetricDiscrepancyQueueResponse>;
-            verifyMetricDiscrepancy: (gameId: string, courseId: string, request: _playcademy_types.VerifyTimebackMetricDiscrepancyRequest) => Promise<_playcademy_types.VerifyTimebackMetricDiscrepancyResponse>;
-            grantXp: (request: _playcademy_types.GrantTimebackXpRequest) => Promise<_playcademy_types.TimebackAdminMutationResponse>;
-            adjustTime: (request: _playcademy_types.AdjustTimebackTimeRequest) => Promise<_playcademy_types.TimebackAdminMutationResponse>;
-            adjustMastery: (request: _playcademy_types.AdjustTimebackMasteryRequest) => Promise<_playcademy_types.TimebackAdminMutationResponse>;
-            reconcileMasteryForConfigChange: (request: _playcademy_types.ReconcileMasteryForConfigChangeRequest) => Promise<_playcademy_types.ReconcileMasteryForConfigChangeResponse>;
-            searchStudents: (gameId: string, courseId: string, query: string) => Promise<_playcademy_types.SearchStudentsResponse>;
-            enrollStudent: (request: _playcademy_types.EnrollStudentRequest) => Promise<_playcademy_types.EnrollStudentResponse>;
-            unenrollStudent: (request: _playcademy_types.UnenrollStudentRequest) => Promise<_playcademy_types.TimebackAdminMutationResponse>;
-            reactivateEnrollment: (request: _playcademy_types.ReactivateEnrollmentRequest) => Promise<_playcademy_types.TimebackAdminMutationResponse>;
+            }) => Promise<TimebackMetricDiscrepancyQueueResponse>;
+            verifyMetricDiscrepancy: (gameId: string, courseId: string, request: VerifyTimebackMetricDiscrepancyRequest) => Promise<VerifyTimebackMetricDiscrepancyResponse>;
+            grantXp: (request: GrantTimebackXpRequest) => Promise<TimebackAdminMutationResponse>;
+            adjustTime: (request: AdjustTimebackTimeRequest) => Promise<TimebackAdminMutationResponse>;
+            adjustMastery: (request: AdjustTimebackMasteryRequest) => Promise<TimebackAdminMutationResponse>;
+            reconcileMasteryForConfigChange: (request: ReconcileMasteryForConfigChangeRequest) => Promise<ReconcileMasteryForConfigChangeResponse>;
+            searchStudents: (gameId: string, courseId: string, query: string) => Promise<SearchStudentsResponse>;
+            enrollStudent: (request: EnrollStudentRequest) => Promise<EnrollStudentResponse>;
+            unenrollStudent: (request: UnenrollStudentRequest) => Promise<TimebackAdminMutationResponse>;
+            reactivateEnrollment: (request: ReactivateEnrollmentRequest) => Promise<TimebackAdminMutationResponse>;
         };
         assessments: {
-            list: (gameId: string, courseId: string) => Promise<_playcademy_types.AssessmentSummary[]>;
+            list: (gameId: string, courseId: string) => Promise<AssessmentSummary[]>;
             create: (gameId: string, courseId: string, data: {
                 assessmentKey: string;
                 title: string;
-                purpose: Exclude<_playcademy_types.AssessmentPurpose, 'diagnostic' | 'review'>;
-                standard?: _playcademy_types.AssessmentStandardRef;
-            }) => Promise<_playcademy_types.AssessmentRow>;
-            attachExisting: (gameId: string, courseId: string, manifest: _playcademy_types.AssessmentAssociationImportManifest) => Promise<_playcademy_types.AssessmentAssociationImportResponse>;
+                purpose: Exclude<AssessmentPurpose, 'diagnostic' | 'review'>;
+                standard?: AssessmentStandardRef;
+            }) => Promise<AssessmentRow>;
+            attachExisting: (gameId: string, courseId: string, manifest: AssessmentAssociationImportManifest) => Promise<AssessmentAssociationImportResponse>;
             update: (gameId: string, courseId: string, testIdentifier: string, data: {
                 title?: string;
-                purpose?: Exclude<_playcademy_types.AssessmentPurpose, 'review'>;
-                standard?: _playcademy_types.AssessmentStandardRef;
-                diagnostic?: _playcademy_types.DiagnosticAssessmentDefinitionInput | null;
-                status?: _playcademy_types.AssessmentStatus;
-            }) => Promise<_playcademy_types.AssessmentRow>;
-            syncReviewBank: (gameId: string, courseId: string) => Promise<_playcademy_types.ReviewBankSynchronizationResult>;
+                purpose?: Exclude<AssessmentPurpose, 'review'>;
+                standard?: AssessmentStandardRef;
+                diagnostic?: DiagnosticAssessmentDefinitionInput | null;
+                status?: AssessmentStatus;
+            }) => Promise<AssessmentRow>;
+            syncReviewBank: (gameId: string, courseId: string) => Promise<ReviewBankSynchronizationResult>;
             remove: (gameId: string, courseId: string, testIdentifier: string) => Promise<{
                 action: 'discarded' | 'archived';
             }>;
-            revise: (gameId: string, courseId: string, data: _playcademy_types.AssessmentRevisionRequest) => Promise<_playcademy_types.AssessmentRevisionResult>;
-            listTestLibrary: (gameId: string, courseId: string, options?: QtiLibraryQueryOptions) => Promise<_playcademy_types.QtiAssessmentTestListResponse>;
+            revise: (gameId: string, courseId: string, data: AssessmentRevisionRequest) => Promise<AssessmentRevisionResult>;
+            listTestLibrary: (gameId: string, courseId: string, options?: QtiLibraryQueryOptions) => Promise<QtiAssessmentTestListResponse>;
             copy: (gameId: string, courseId: string, data: {
                 testIdentifier: string;
                 assessmentKey: string;
-                purpose: Exclude<_playcademy_types.AssessmentPurpose, 'diagnostic' | 'review'>;
-                standard?: _playcademy_types.AssessmentStandardRef;
-            }) => Promise<_playcademy_types.AssessmentRow>;
-            listQuestions: (gameId: string, courseId: string, testIdentifier: string) => Promise<_playcademy_types.QtiTestQuestionsResponse>;
-            listQuestionLibrary: (gameId: string, courseId: string, options?: QtiLibraryQueryOptions) => Promise<_playcademy_types.QtiAssessmentItemListResponse>;
-            createQuestion: (gameId: string, courseId: string, testIdentifier: string, data: _playcademy_types.QtiQuestionCreateInput) => Promise<_playcademy_types.QtiTestQuestionRef>;
+                purpose: Exclude<AssessmentPurpose, 'diagnostic' | 'review'>;
+                standard?: AssessmentStandardRef;
+            }) => Promise<AssessmentRow>;
+            listQuestions: (gameId: string, courseId: string, testIdentifier: string) => Promise<QtiTestQuestionsResponse>;
+            listQuestionLibrary: (gameId: string, courseId: string, options?: QtiLibraryQueryOptions) => Promise<QtiAssessmentItemListResponse>;
+            createQuestion: (gameId: string, courseId: string, testIdentifier: string, data: QtiQuestionCreateInput) => Promise<QtiTestQuestionRef>;
             updateQuestion: (gameId: string, courseId: string, testIdentifier: string, itemIdentifier: string, data: Record<string, unknown>) => Promise<unknown>;
             removeQuestion: (gameId: string, courseId: string, testIdentifier: string, itemIdentifier: string) => Promise<{
                 success: boolean;
@@ -4073,7 +7183,7 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
             }>;
         };
         assessmentAssets: {
-            upload: (body: Uint8Array, sha256: string) => Promise<_playcademy_types.AssessmentAssetUploadResponse>;
+            upload: (body: Uint8Array, sha256: string) => Promise<AssessmentAssetUploadResponse>;
         };
     };
     /** Auto-initializes a PlaycademyInternalClient with context from the environment */
@@ -4136,4 +7246,4 @@ interface BeginInitHandshakeOptions {
 declare function beginInitHandshake({ iframe, origin, payload, onTimeout, onSendError }: BeginInitHandshakeOptions): () => void;
 
 export { ApiError, HANDSHAKE_MAX_DURATION_MS, HANDSHAKE_RESEND_INTERVAL_MS, INIT_WAIT_TIMEOUT_MS, MessageEvents, PlaycademyInternalClient as PlaycademyClient, PlaycademyError, PlaycademyInternalClient, beginInitHandshake, extractApiErrorInfo, isTrustedIframeMessage, messaging };
-export type { ApiErrorCode, ApiErrorInfo, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, BucketFilePage, BucketListPageOptions, ChildCheckpointRelay, ClientConfig, ClientEvents, CourseMastery, CourseXp, DemoEndOptions, DemoEndPayload, DevUploadEvent, DevUploadHooks, EmbedActivity, EmbedActivityAbandoned, EmbedActivityCompleted, EmbedActivityFailed, EmbedLaunchOptions, EmbedResumeEnvelope, EmbedResumeStore, EmbedSession, EmbedSessionTiming, EmbedTimebackRecording, ErrorResponseBody, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameCustomHostname, GameInitUser, GameRow as GameRecord, GameTokenResponse, GetHighestGradeMasteredOptions, GetMasteryOptions, GetXpOptions, HighestGradeMasteredResponse, HostedGame, InitErrorPayload, InitPayload, KVKeyEntry, KVKeyMetadata, KVSeedEntry, KVStatsResponse, KeyEventPayload, LaunchIntent, LoginResponse, MasteryResponse, MessageEventMap, ParentGameContext, ParentGameHandle, PlatformTimebackUser, PlatformTimebackUserContext, PlaycademyMode, PlaycademyServerClientConfig, PlaycademyServerClientState, ScoreSubmission, StartActivityOptions, StartActivityResult, TelemetryPayload, TimebackActivityEndRelay, TimebackActivityStartRelay, TimebackEnrollment, TimebackHeartbeatRelayRequest, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, TimebackUserHighestGradeMastered, TimebackUserMastery, TimebackUserRefreshField, TimebackUserRefreshOptions, TimebackUserXp, TokenRefreshPayload, TokenType, UpsertGameMetadataInput, UserRow as User, XpResponse };
+export type { ApiErrorCode, ApiErrorInfo, AssessmentAttemptSnapshot, AssessmentAwardRecord, AssessmentFinalizeResult, AssessmentFlow, AssessmentItemGrading, AssessmentItemOutcome, AssessmentItemSubmission, AssessmentMasteryAward, AssessmentPreparationResult, AssessmentResponseUpdate, AssessmentResponseValue, AssessmentResponses, AssessmentReviewStandard, AssessmentSaveResult, AssessmentScore, AssessmentStandardRef, AssessmentSubmitResult, AssessmentTranscript, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, AuthenticatedUser, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, BucketFilePage, BucketListPageOptions, ChildCheckpointRelay, ClientConfig, ClientEvents, ConventionalAssessmentAttemptSnapshot, ConventionalAssessmentSubmitResult, CourseMastery, CourseXp, DemoEndOptions, DemoEndPayload, DeploySource, DevUploadEvent, DevUploadHooks, DeveloperStatusEnumType, DeveloperStatusResponse, DeveloperStatusValue, DiagnosticAssessmentItemReceipt, DiagnosticAssessmentSubmitResult, DiagnosticRoutingSnapshot, DiagnosticRoutingTrackSnapshot, ELevel, EmbedActivity, EmbedActivityAbandoned, EmbedActivityCompleted, EmbedActivityFailed, EmbedLaunchOptions, EmbedResumeEnvelope, EmbedResumeStore, EmbedSession, EmbedSessionTiming, EmbedTimebackRecording, ErrorResponseBody, EventListeners, ExternalGame, FetchedGame, FinalizeAssessmentInput, Game, GameContextPayload, GameCourseMetrics, GameCustomHostname, GameInitUser, GameLeaderboardEntry, GameManifest, GameMetricComparisonKind, GameMetricComparisonMetric, GameMetricComparisonRow, GameMetricComparisonRowStatus, GameMetricsProxyResponse, GameMetricsResponse, GameMetricsUnsupportedReason, GamePlatform, GameRow as GameRecord, GameReleaseResponse, GameRunMetrics, GameRunMetricsComparison, GameRunMetricsComparisonStatus, GameRunMetricsComparisonSummary, GameTimebackIntegration, GameTokenResponse, GameType, GameUser, GetHighestGradeMasteredOptions, GetMasteryOptions, GetXpOptions, HighestGradeMasteredResponse, HostedGame, InitErrorPayload, InitPayload, KVKeyEntry, KVKeyMetadata, KVSeedEntry, KVStatsResponse, KeyEventPayload, LaunchIntent, LeaderboardEntry, LeaderboardOptions, LeaderboardTimeframe, LocalDayContext, LocalDaySource, LoginResponse, ManifestV1, ManifestV2, ManifestVersions, MasteryAssessmentSubmitResult, MasteryResponse, MessageEventMap, ParentGameContext, ParentGameHandle, PlatformRoutedDiagnosticAttemptSnapshot, PlatformRoutedDiagnosticSelectionContext, PlatformTimebackUser, PlatformTimebackUserContext, PlayableAssessment, PlayableAssessmentAttemptSnapshot, PlayableAssessmentChoice, PlayableAssessmentGraphic, PlayableAssessmentHotspot, PlayableAssessmentInteraction, PlayableAssessmentItem, PlayableChoiceInteraction, PlayableContentNode, PlayableGapMatchChoice, PlayableGapMatchInteraction, PlayableInlineChoiceInteraction, PlayableMatchChoice, PlayableMatchInteraction, PlayableOrderInteraction, PlaycademyMode, PlaycademyServerClientConfig, PlaycademyServerClientState, PopulateStudentResponse, RecordAssessmentProgressInput, Release, ReleasesResponse, ResumeAssessmentInput, SaveAssessmentInput, ScoreSubmission, SettledAssessmentAttemptSnapshot, SkillMasterySource, SkillStatus, SkillStatusLookupResult, SkillStatusRequest, SkillStatusRequestingGame, SkillStatusResponse, SkillStatusResult, SkillStatusUnsupportedReason, StandardsReviewSelectionContext, StartActivityOptions, StartActivityResult, StartAssessmentInput, StartAssessmentOptions, StartDiagnosticAssessmentInput, SubmitAssessmentInput, SubmitAssessmentItemInput, SubmitAssessmentItemResult, SubmitDiagnosticAssessmentItemInput, SubmitDiagnosticAssessmentItemResult, TelemetryPayload, TimebackActivityEndRelay, TimebackActivityStartRelay, TimebackEnrollment, TimebackHeartbeatRelayRequest, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, TimebackUserHighestGradeMastered, TimebackUserMastery, TimebackUserRefreshField, TimebackUserRefreshOptions, TimebackUserXp, TokenRefreshPayload, TokenType, UpsertGameMetadataInput, UserRow as User, UserEnrollment, UserInfo, UserOrganization, UserRank, UserRankResponse, UserRoleEnumType, UserScore, UserTimebackData, XpResponse };