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

package/dist/server/edge.d.ts

@@ -1,10 +1,1202 @@
-import { SchemaInfo } from '@playcademy/cloudflare';
-import { GamePermission } from '@playcademy/constants';
-import { TimebackCourseConfig, CourseConfig, OrganizationConfig, ComponentConfig, ResourceConfig, ComponentResourceConfig } from '@playcademy/types/timeback';
-export { ActivityData, ComponentConfig, ComponentResourceConfig, EndActivityPayload, OrganizationConfig, ResourceConfig, TimebackGrade, TimebackSubject } from '@playcademy/types/timeback';
-import { UserInfo } from '@playcademy/types/user';
-export { UserInfo } from '@playcademy/types/user';
-import * as _playcademy_types from '@playcademy/types';
+/**
+ * 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
+}
+
+/**
+ * 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;
+
+/**
+ * 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];
+/**
+ * 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;
+}
+
+/**
+ * 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 activity completion
+ */
+interface ScoreData {
+    /** Number of questions answered correctly */
+    correctQuestions: number;
+    /** Total number of questions */
+    totalQuestions: number;
+}
+/**
+ * Timing data for activity completion
+ */
+interface TimingData {
+    /** Duration of the activity in seconds */
+    durationSeconds: number;
+}
+/**
+ * Complete payload for ending an activity
+ */
+interface EndActivityPayload {
+    /** Activity metadata */
+    activityData: ActivityData;
+    /** Score information */
+    scoreData: ScoreData;
+    /** Timing information */
+    timingData: TimingData;
+    /** XP earned for this activity */
+    xpEarned: number;
+    /** Number of learning units mastered */
+    masteredUnits?: number;
+    /** Optional arbitrary extensions to include in the Caliper event */
+    extensions?: TimebackActivityExtensions;
+    /**
+     * Stable identifier (UUID) for this activity run, enabling the platform's
+     * duplicate-completion guard: at most one completion is recorded per
+     * activity per run, and a resubmission returns `blockedByDedupeGuard`
+     * with the originally recorded award instead of double-counting XP.
+     * Without it, retried submissions may award XP twice. Use a fresh UUID
+     * per logical run — a genuine retake needs a new `runId`.
+     */
+    runId?: string;
+}
+
+/**
+ * TimeBack API Request/Response Types
+ *
+ * Types for TimeBack API endpoints including XP tracking,
+ * setup, verification, and activity completion.
+ *
+ * @module types/timeback/api
+ */
+
+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;
+}
+/**
+ * Mastery data for a single course.
+ */
+interface StudentCourseMastery {
+    grade: number;
+    subject: string;
+    title: string;
+    /** True mastered units from analytics. May exceed masterableUnits for historical data. */
+    masteredUnits: number;
+    /** Configured mastery ceiling for the course. */
+    masterableUnits: number;
+    /** Clamped course completion percentage from 0..100. */
+    pctComplete: number;
+    isComplete: boolean;
+}
+/**
+ * Response from student mastery query.
+ */
+interface StudentMasteryResponse {
+    /** True mastered units across all queried courses */
+    totalMasteredUnits: number;
+    /** Configured mastery ceiling across all queried courses */
+    totalMasterableUnits: number;
+    /** Per-course mastery breakdown (if requested) */
+    courses?: StudentCourseMastery[];
+}
+/**
+ * XP data for a single course.
+ */
+interface StudentCourseXp {
+    grade: number;
+    subject: string;
+    title: string;
+    totalXp: number;
+    todayXp?: number;
+}
+/**
+ * Response from student XP query.
+ */
+interface StudentXpResponse {
+    /** Total XP across all queried courses */
+    totalXp: number;
+    /** Today's XP (if requested) */
+    todayXp?: number;
+    /** Per-course XP breakdown (if requested) */
+    courses?: StudentCourseXp[];
+}
+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;
+    };
+}
+
+declare const DIAGNOSTIC_TRACK_OUTCOMES: readonly ['provisional', 'unresolved', 'route-to-instruction', 'not-assessed'];
+type DiagnosticTrackOutcome = (typeof DIAGNOSTIC_TRACK_OUTCOMES)[number];
+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];
+
+/** 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>>;
+/**
+ * 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 GetLatestAssessmentOptionsBase {
+    subject?: TimebackSubject;
+    grade?: TimebackGrade;
+}
+/** Filters for finding the authenticated student's latest completed assessment. */
+type GetLatestAssessmentOptions = (GetLatestAssessmentOptionsBase & {
+    purpose: Exclude<AssessmentPurpose, 'mastery'>;
+    standard?: never;
+}) | (GetLatestAssessmentOptionsBase & {
+    purpose: 'mastery';
+    standard: AssessmentStandardRef;
+});
+/** Compact result returned by the latest-completed-assessment lookup. */
+interface LatestAssessmentResult {
+    attemptId: string;
+    purpose: AssessmentPurpose;
+    activityId: string;
+    subject: TimebackSubject;
+    grade: TimebackGrade;
+    testIdentifier: string;
+    /** Canonical request identity for mastery results; null for other purposes. */
+    standard: AssessmentStandardRef | null;
+    completedAt: string;
+    /** Persisted aggregate score normalized to the inclusive 0..1 range. */
+    score: Pick<AssessmentScore, 'normalized'>;
+}
+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;
+}
+/** Final unpersisted window from the SDK's shared activity-session clock. */
+interface AssessmentSessionTiming {
+    /** Stable identity for the whole assessment attempt. */
+    runId: string;
+    /** Identity for this individual sitting of a resumable attempt. */
+    resumeId: string;
+    activeSeconds: number;
+    inactiveSeconds?: number;
+}
+/** Internal game-backend wire input after the browser SDK closes its clock. */
+interface SubmitAssessmentRequest extends SubmitAssessmentInput {
+    session?: AssessmentSessionTiming;
+}
 
 /**
  * @fileoverview Server SDK Type Definitions
@@ -298,6 +1490,87 @@ interface WorkerDeploymentBundle {
     compatibilityFlags?: string[];
 }
 
+/**
+ * User Types
+ *
+ * Enums, DTOs and API response types. Database row types are in @playcademy/data/types.
+ *
+ * @module types/user
+ */
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
+/** 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;
+};
+
 /**
  * Server-side Playcademy client for recording student activity to TimeBack.
  *
@@ -370,41 +1643,41 @@ declare class PlaycademyClient {
     /** TimeBack integration methods (endActivity) */
     timeback: {
         assessments: {
-            prepare: (studentId: string, input: _playcademy_types.StartAssessmentInput) => Promise<_playcademy_types.AssessmentPreparationResult>;
-            start: (studentId: string, input: _playcademy_types.StartAssessmentInput, options?: _playcademy_types.StartAssessmentOptions) => Promise<_playcademy_types.AssessmentAttemptSnapshot>;
-            latest: (studentId: string, options: _playcademy_types.GetLatestAssessmentOptions) => Promise<_playcademy_types.LatestAssessmentResult | null>;
-            get: (studentId: string, attemptId: string) => Promise<_playcademy_types.AssessmentAttemptSnapshot>;
-            save: (studentId: string, attemptId: string, input: _playcademy_types.SaveAssessmentInput) => Promise<_playcademy_types.AssessmentSaveResult>;
-            resume: (studentId: string, attemptId: string, input?: _playcademy_types.ResumeAssessmentInput) => Promise<_playcademy_types.AssessmentAttemptSnapshot>;
-            recordProgress: (studentId: string, attemptId: string, input: _playcademy_types.RecordAssessmentProgressInput) => Promise<{
+            prepare: (studentId: string, input: StartAssessmentInput) => Promise<AssessmentPreparationResult>;
+            start: (studentId: string, input: StartAssessmentInput, options?: StartAssessmentOptions) => Promise<AssessmentAttemptSnapshot>;
+            latest: (studentId: string, options: GetLatestAssessmentOptions) => Promise<LatestAssessmentResult | null>;
+            get: (studentId: string, attemptId: string) => Promise<AssessmentAttemptSnapshot>;
+            save: (studentId: string, attemptId: string, input: SaveAssessmentInput) => Promise<AssessmentSaveResult>;
+            resume: (studentId: string, attemptId: string, input?: ResumeAssessmentInput) => Promise<AssessmentAttemptSnapshot>;
+            recordProgress: (studentId: string, attemptId: string, input: RecordAssessmentProgressInput) => Promise<{
                 attemptId: string;
             }>;
-            submitItem: (studentId: string, attemptId: string, input: _playcademy_types.SubmitAssessmentItemInput) => Promise<_playcademy_types.SubmitAssessmentItemResult>;
-            submit: (studentId: string, attemptId: string, input: _playcademy_types.SubmitAssessmentRequest, context: {
+            submitItem: (studentId: string, attemptId: string, input: SubmitAssessmentItemInput) => Promise<SubmitAssessmentItemResult>;
+            submit: (studentId: string, attemptId: string, input: SubmitAssessmentRequest, context: {
                 sensorUrl: string;
-            }) => Promise<_playcademy_types.AssessmentSubmitResult>;
-            finalize: (studentId: string, attemptId: string, input: _playcademy_types.FinalizeAssessmentInput, context: {
+            }) => Promise<AssessmentSubmitResult>;
+            finalize: (studentId: string, attemptId: string, input: FinalizeAssessmentInput, context: {
                 sensorUrl: string;
-            }) => Promise<_playcademy_types.AssessmentFinalizeResult>;
+            }) => Promise<AssessmentFinalizeResult>;
         };
-        endActivity: (studentId: string, payload: _playcademy_types.EndActivityPayload) => Promise<_playcademy_types.EndActivityResponse>;
+        endActivity: (studentId: string, payload: EndActivityPayload) => Promise<EndActivityResponse>;
         getStudentXp: (studentId: string, options?: {
             grade?: number;
             subject?: string;
             include?: ('perCourse' | 'today')[];
-        }) => Promise<_playcademy_types.StudentXpResponse>;
+        }) => Promise<StudentXpResponse>;
         getStudentMastery: (studentId: string, options?: {
             grade?: number;
             subject?: string;
             include?: 'perCourse'[];
-        }) => Promise<_playcademy_types.StudentMasteryResponse>;
+        }) => Promise<StudentMasteryResponse>;
         getStudentHighestGradeMastered: (studentId: string, options: {
             subject: string;
-        }) => Promise<_playcademy_types.StudentHighestGradeMasteredResponse>;
+        }) => Promise<StudentHighestGradeMasteredResponse>;
     };
     /** Cross-game skill status (getStatus) */
     skills: {
-        getStatus: (request: _playcademy_types.SkillStatusRequest) => Promise<_playcademy_types.SkillStatusLookupResult>;
+        getStatus: (request: SkillStatusRequest) => Promise<SkillStatusLookupResult>;
     };
 }
 
@@ -470,4 +1743,4 @@ declare function verifyGameToken(gameToken: string, options?: {
 }): Promise<VerifyGameTokenResponse>;
 
 export { PlaycademyClient, verifyGameToken };
-export type { IntegrationsConfig, PlaycademyConfig, PlaycademyServerClientConfig, PlaycademyServerClientState, QueueConfig, RequestContext, TimebackBaseConfig, TimebackCourseConfigWithOverrides, TimebackIntegrationConfig, WorkerDeploymentBundle, WorkerResourceBindings };
+export type { ActivityData, ComponentConfig, ComponentResourceConfig, EndActivityPayload, IntegrationsConfig, OrganizationConfig, PlaycademyConfig, PlaycademyServerClientConfig, PlaycademyServerClientState, QueueConfig, RequestContext, ResourceConfig, TimebackBaseConfig, TimebackCourseConfigWithOverrides, TimebackGrade, TimebackIntegrationConfig, TimebackSubject, UserInfo, WorkerDeploymentBundle, WorkerResourceBindings };