coursecode 0.1.0

package/framework/js/state/state-validation.js

@@ -0,0 +1,311 @@
+/**
+ * @file state-validation.js
+ * @description State hydration, validation, and migration logic.
+ * Validates stored LMS state against current course structure.
+ * @internal Only used by state-manager.js
+ */
+
+import { eventBus } from '../core/event-bus.js';
+import { logger } from '../utilities/logger.js';
+
+// =================================================================
+// State Schema Version
+// =================================================================
+// Increment this when the state structure changes in incompatible ways.
+const STATE_SCHEMA_VERSION = 1;
+
+// Migration functions keyed by TARGET version number.
+// Each migration transforms state from (version - 1) to (version).
+const STATE_MIGRATIONS = {
+    // No migrations yet - add here when STATE_SCHEMA_VERSION is incremented
+};
+
+/**
+ * Handles state validation mismatches.
+ * - In dev mode: Throws an error with detailed diagnostics
+ * - In prod mode: Logs warning and returns the default value for graceful recovery
+ */
+function handleStateMismatch(domain, message, context, defaultValue) {
+    const fullMessage = `[StateManager] State mismatch in "${domain}": ${message}`;
+
+    if (import.meta.env.DEV) {
+        logger.fatal(fullMessage, {
+            domain: 'state',
+            operation: 'validation',
+            ...context,
+            hint: 'This error occurs when stored LMS data is incompatible with the current course structure. ' +
+                'Clear your LMS data or use a fresh learner account to test the updated course.'
+        });
+    } else {
+        logger.warn(`${fullMessage}. Reverting to defaults.`, context);
+        eventBus.emit('state:recovered', {
+            domain,
+            message,
+            context,
+            action: 'reverted_to_defaults'
+        });
+        return defaultValue;
+    }
+}
+
+export class StateValidator {
+    constructor() {
+        this._validationConfig = null;
+    }
+
+    get schemaVersion() {
+        return STATE_SCHEMA_VERSION;
+    }
+
+    /**
+     * Sets the course configuration used for state validation.
+     * Must be called BEFORE hydration to enable validation.
+     */
+    setCourseValidationConfig(config) {
+        if (!config || typeof config !== 'object') {
+            throw new Error('StateManager: validation config must be an object');
+        }
+        if (!config.structure || !Array.isArray(config.structure)) {
+            throw new Error('StateManager: validation config must include a structure array');
+        }
+
+        const slideIds = new Set();
+        const interactionIdsBySlide = new Map();
+
+        const processItem = (item) => {
+            if (item.id) {
+                slideIds.add(item.id);
+            }
+            if (item.children && Array.isArray(item.children)) {
+                item.children.forEach(processItem);
+            }
+        };
+        config.structure.forEach(processItem);
+
+        const objectiveIds = new Set();
+        if (config.objectives && Array.isArray(config.objectives)) {
+            config.objectives.forEach(obj => {
+                if (obj.id) objectiveIds.add(obj.id);
+            });
+        }
+
+        this._validationConfig = {
+            slideIds,
+            objectiveIds,
+            interactionIdsBySlide,
+            courseVersion: config.version || null,
+            schemaVersion: STATE_SCHEMA_VERSION
+        };
+
+        logger.debug(`[StateManager] Validation config set: ${slideIds.size} slides, ${objectiveIds.size} objectives`);
+    }
+
+    /**
+     * Creates a fresh state object with schema version.
+     */
+    createFreshState() {
+        return {
+            _meta: {
+                schemaVersion: STATE_SCHEMA_VERSION,
+                createdAt: new Date().toISOString()
+            }
+        };
+    }
+
+    /**
+     * Hydrates state from the LMS using semantic driver reads.
+     * @param {Object} lmsConnection - The LMS connection instance
+     * @returns {Object} The hydrated state
+     */
+    hydrateStateFromLMS(lmsConnection) {
+        let entryMode;
+        try {
+            entryMode = lmsConnection.getEntryMode();
+            logger.debug(`[StateManager] Entry mode: "${entryMode}"`);
+        } catch (error) {
+            throw new Error(`StateManager: Cannot read entry mode. LMS connection may not be initialized. Error: ${error.message}`);
+        }
+
+        if (entryMode === 'ab-initio') {
+            logger.debug('[StateManager] Fresh session (ab-initio), starting with empty state');
+            return this.createFreshState();
+        }
+
+        const suspendData = lmsConnection.getSuspendData();
+        if (suspendData) {
+            const state = this.validateAndMigrateState(suspendData);
+            logger.debug('[StateManager] Hydrated state from suspend_data');
+            logger.debug(`[StateManager] Restored ${Object.keys(state).length} domain(s) from previous session`);
+            return state;
+        }
+
+        if (entryMode === 'resume') {
+            logger.warn('[StateManager] Entry mode is "resume" but no suspend_data found. This may indicate a previous session that was not properly saved.');
+        } else {
+            logger.debug('[StateManager] No suspend_data found, starting with fresh state');
+        }
+        return this.createFreshState();
+    }
+
+    /**
+     * Validates loaded state against current course configuration and migrates if needed.
+     */
+    validateAndMigrateState(loadedState) {
+        if (!this._validationConfig) {
+            logger.debug('[StateManager] No validation config set, skipping state validation');
+            if (!loadedState._meta) {
+                loadedState._meta = {
+                    schemaVersion: STATE_SCHEMA_VERSION,
+                    createdAt: new Date().toISOString()
+                };
+            }
+            return loadedState;
+        }
+
+        const { slideIds, objectiveIds: _objectiveIds } = this._validationConfig;
+        const storedSchemaVersion = loadedState._meta?.schemaVersion || 0;
+
+        logger.debug(`[StateManager] Validating state: stored schema v${storedSchemaVersion}, current v${STATE_SCHEMA_VERSION}`);
+
+        if (storedSchemaVersion > STATE_SCHEMA_VERSION) {
+            return handleStateMismatch(
+                '_meta',
+                `Stored state has newer schema version (${storedSchemaVersion}) than current (${STATE_SCHEMA_VERSION}). ` +
+                'This may indicate the course was downgraded.',
+                { storedSchemaVersion, currentSchemaVersion: STATE_SCHEMA_VERSION },
+                this.createFreshState()
+            );
+        }
+
+        if (storedSchemaVersion < STATE_SCHEMA_VERSION) {
+            logger.info(`[StateManager] Upgrading state from schema v${storedSchemaVersion} to v${STATE_SCHEMA_VERSION}`);
+            loadedState = this._runMigrations(loadedState, storedSchemaVersion, STATE_SCHEMA_VERSION);
+        }
+
+        const validatedState = { ...loadedState };
+
+        validatedState._meta = {
+            ...loadedState._meta,
+            schemaVersion: STATE_SCHEMA_VERSION,
+            lastValidatedAt: new Date().toISOString()
+        };
+
+        if (loadedState.navigation) {
+            validatedState.navigation = this._validateNavigationState(loadedState.navigation, slideIds);
+        }
+        if (loadedState.engagement) {
+            validatedState.engagement = this._validateEngagementState(loadedState.engagement, slideIds);
+        }
+        if (loadedState.interactionResponses) {
+            validatedState.interactionResponses = this._validateInteractionResponsesState(loadedState.interactionResponses);
+        }
+
+        for (const key of Object.keys(loadedState)) {
+            if (key.startsWith('assessment_')) {
+                const assessmentId = key.replace('assessment_', '');
+                validatedState[key] = this._validateAssessmentState(loadedState[key], assessmentId);
+            }
+        }
+
+        return validatedState;
+    }
+
+    _runMigrations(state, fromVersion, toVersion) {
+        let migratedState = { ...state };
+
+        for (let version = fromVersion + 1; version <= toVersion; version++) {
+            const migration = STATE_MIGRATIONS[version];
+            if (migration) {
+                logger.info(`[StateManager] Running migration to schema v${version}`);
+                try {
+                    migratedState = migration(migratedState);
+                } catch (error) {
+                    const errorMessage = `State migration to v${version} failed: ${error.message}`;
+                    logger.error(`[StateManager] ${errorMessage}`, error);
+
+                    if (import.meta.env.DEV) {
+                        throw new Error(errorMessage);
+                    }
+                    eventBus.emit('state:recovered', {
+                        domain: '_meta',
+                        message: errorMessage,
+                        context: { fromVersion, toVersion, failedAtVersion: version },
+                        action: 'migration_skipped'
+                    });
+                }
+            } else {
+                logger.debug(`[StateManager] No migration defined for v${version}, skipping`);
+            }
+        }
+
+        return migratedState;
+    }
+
+    _validateNavigationState(navState, slideIds) {
+        if (!navState || typeof navState !== 'object') return navState;
+
+        const validated = { ...navState };
+
+        if (Array.isArray(navState.visitedSlides)) {
+            const invalidSlides = navState.visitedSlides.filter(id => !slideIds.has(id));
+            if (invalidSlides.length > 0) {
+                if (import.meta.env.DEV) {
+                    logger.warn(
+                        `[StateManager] Navigation state contains ${invalidSlides.length} invalid slide ID(s): ${invalidSlides.join(', ')}. ` +
+                        'These slides no longer exist in the course structure and will be removed.'
+                    );
+                }
+                validated.visitedSlides = navState.visitedSlides.filter(id => slideIds.has(id));
+            }
+        }
+
+        return validated;
+    }
+
+    _validateEngagementState(engagementState, slideIds) {
+        if (!engagementState || typeof engagementState !== 'object') return engagementState;
+
+        const validated = {};
+        const invalidSlides = [];
+
+        for (const [slideId, slideState] of Object.entries(engagementState)) {
+            if (slideIds.has(slideId)) {
+                validated[slideId] = slideState;
+            } else {
+                invalidSlides.push(slideId);
+            }
+        }
+
+        if (invalidSlides.length > 0 && import.meta.env.DEV) {
+            logger.warn(
+                `[StateManager] Engagement state contains ${invalidSlides.length} invalid slide ID(s): ${invalidSlides.join(', ')}. ` +
+                'These slides no longer exist and their engagement data will be discarded.'
+            );
+        }
+
+        return validated;
+    }
+
+    _validateInteractionResponsesState(responsesState) {
+        if (!responsesState || typeof responsesState !== 'object') return responsesState;
+
+        const validated = {};
+        for (const [id, state] of Object.entries(responsesState)) {
+            if (state && typeof state === 'object') {
+                validated[id] = state;
+            }
+        }
+        return validated;
+    }
+
+    _validateAssessmentState(assessmentState, assessmentId) {
+        if (!assessmentState || typeof assessmentState !== 'object') return assessmentState;
+
+        const validated = { ...assessmentState };
+        if (validated.session?.responses && typeof validated.session.responses !== 'object') {
+            logger.warn(`[StateManager] Assessment "${assessmentId}" has invalid response format. Clearing responses.`);
+            validated.session.responses = {};
+        }
+        return validated;
+    }
+}

package/framework/js/state/transaction-log.js

@@ -0,0 +1,41 @@
+/**
+ * @file transaction-log.js
+ * @description Ring buffer for recording state transactions. Used for debugging.
+ * @internal Only used by state-manager.js
+ */
+
+const DEFAULT_SIZE = 50;
+
+export class TransactionLog {
+    constructor(size = DEFAULT_SIZE) {
+        this._buffer = new Array(size);
+        this._size = size;
+        this._head = 0;
+        this._count = 0;
+    }
+
+    record(domain, action, meta = {}) {
+        this._buffer[this._head] = {
+            domain,
+            action,
+            timestamp: Date.now(),
+            ...meta
+        };
+        this._head = (this._head + 1) % this._size;
+        if (this._count < this._size) this._count++;
+    }
+
+    getRecent(n = 10) {
+        const count = Math.min(n, this._count);
+        const entries = [];
+        for (let i = 0; i < count; i++) {
+            const idx = (this._head - 1 - i + this._size) % this._size;
+            entries.push(this._buffer[idx]);
+        }
+        return entries;
+    }
+
+    toArray() {
+        return this.getRecent(this._count);
+    }
+}

package/framework/js/state/xapi-statement-service.js

@@ -0,0 +1,325 @@
+/**
+ * @file xapi-statement-service.js
+ * @description Format-agnostic event listener that bridges manager events to driver xAPI methods.
+ * 
+ * This service subscribes to objective, interaction, and assessment events and routes them
+ * to the active driver's xAPI statement methods (if available). SCORM drivers don't implement
+ * these methods, so this is a no-op for SCORM formats.
+ * 
+ * This enables rich xAPI learning records for cmi5 without modifying SCORM behavior.
+ */
+
+import { eventBus } from '../core/event-bus.js';
+import { logger } from '../utilities/logger.js';
+
+/**
+ * xAPI Statement Service
+ * Bridges manager events to driver xAPI methods for cmi5 learning records.
+ */
+class XapiStatementService {
+    constructor() {
+        this._driver = null;
+        this._isInitialized = false;
+        this._subscriptions = [];
+
+        // Slide time tracking
+        this._currentSlideId = null;
+        this._currentSlideTitle = null;
+        this._slideEntryTime = null;
+    }
+
+    /**
+     * Initializes the service with the active driver.
+     * Only subscribed events if the driver supports xAPI methods.
+     * @param {Object} driver - The active LMS driver instance
+     */
+    initialize(driver) {
+        if (this._isInitialized) {
+            logger.warn('[XapiStatementService] Already initialized');
+            return;
+        }
+
+        this._driver = driver;
+
+        // Only subscribe if driver has xAPI methods (cmi5 only)
+        if (!this._hasXapiSupport()) {
+            logger.debug('[XapiStatementService] Driver does not support xAPI statements, service inactive');
+            this._isInitialized = true;
+            return;
+        }
+
+        logger.info('[XapiStatementService] Initializing xAPI statement bridge');
+        this._subscribeToEvents();
+        this._isInitialized = true;
+    }
+
+    /**
+     * Checks if the driver supports xAPI statement methods.
+     * @private
+     */
+    _hasXapiSupport() {
+        return (
+            this._driver &&
+            typeof this._driver.sendObjectiveStatement === 'function' &&
+            typeof this._driver.sendInteractionStatement === 'function' &&
+            typeof this._driver.sendAssessmentStatement === 'function' &&
+            typeof this._driver.sendSlideStatement === 'function'
+        );
+    }
+
+    /**
+     * Subscribes to manager events and routes to xAPI methods.
+     * @private
+     */
+    _subscribeToEvents() {
+        // Objective events
+        this._subscriptions.push(
+            eventBus.on('objective:updated', this._handleObjectiveUpdated.bind(this))
+        );
+        this._subscriptions.push(
+            eventBus.on('objective:score:updated', this._handleObjectiveScoreUpdated.bind(this))
+        );
+
+        // Interaction events
+        this._subscriptions.push(
+            eventBus.on('interaction:recorded', this._handleInteractionRecorded.bind(this))
+        );
+
+        // Assessment events
+        this._subscriptions.push(
+            eventBus.on('assessment:submitted', this._handleAssessmentSubmitted.bind(this))
+        );
+
+        // Navigation events for slide tracking
+        this._subscriptions.push(
+            eventBus.on('navigation:changed', this._handleNavigationChanged.bind(this))
+        );
+
+        // Session termination - send pending slide statement before LRS connection closes
+        this._subscriptions.push(
+            eventBus.on('session:beforeTerminate', this._handleBeforeTerminate.bind(this))
+        );
+
+        logger.debug('[XapiStatementService] Subscribed to manager events');
+    }
+
+    /**
+     * Handles objective update events.
+     * @private
+     */
+    async _handleObjectiveUpdated(objective) {
+        if (!objective?.id) return;
+
+        // Determine verb based on status changes
+        let verb = 'progressed';
+        if (objective.completion_status === 'completed') {
+            verb = 'completed';
+        }
+        if (objective.success_status === 'passed') {
+            verb = 'passed';
+        } else if (objective.success_status === 'failed') {
+            verb = 'failed';
+        }
+
+        try {
+            await this._driver.sendObjectiveStatement({
+                id: objective.id,
+                verb: verb,
+                name: objective.description || objective.id,
+                score: objective.score !== undefined ? objective.score / 100 : undefined
+            });
+        } catch (error) {
+            logger.error('[XapiStatementService] Failed to send objective statement:', error);
+            // Don't throw - xAPI statements are non-blocking
+        }
+    }
+
+    /**
+     * Handles objective score update events.
+     * @private
+     */
+    async _handleObjectiveScoreUpdated({ id, objectiveId, score }) {
+        const resolvedId = id || objectiveId;
+        if (!resolvedId) return;
+
+        try {
+            await this._driver.sendObjectiveStatement({
+                id: resolvedId,
+                verb: 'progressed',
+                score: typeof score === 'number' && !isNaN(score) ? score / 100 : undefined
+            });
+        } catch (error) {
+            logger.error('[XapiStatementService] Failed to send objective score statement:', error);
+        }
+    }
+
+    /**
+     * Handles interaction recorded events.
+     * @private
+     */
+    async _handleInteractionRecorded(interaction) {
+        if (!interaction?.id) return;
+
+        try {
+            await this._driver.sendInteractionStatement({
+                id: interaction.id,
+                type: interaction.type || 'other',
+                response: interaction.learner_response || '',
+                correct: interaction.result === 'correct',
+                description: interaction.description || undefined,
+                duration: interaction.latency || undefined,
+                objectiveId: interaction.objectives?.[0] || undefined
+            });
+        } catch (error) {
+            logger.error('[XapiStatementService] Failed to send interaction statement:', error);
+        }
+    }
+
+    /**
+     * Handles assessment submitted events.
+     * @private
+     */
+    async _handleAssessmentSubmitted({ assessmentId, results }) {
+        if (!assessmentId || !results) return;
+
+        // Calculate ISO 8601 duration from timeSpent (MM:SS format)
+        let duration;
+        if (results.timeSpent) {
+            const parts = results.timeSpent.split(':');
+            if (parts.length === 3) {
+                const hours = parseInt(parts[0], 10);
+                const minutes = parseInt(parts[1], 10);
+                const seconds = parseInt(parts[2], 10);
+                if (!isNaN(hours) && !isNaN(minutes) && !isNaN(seconds)) {
+                    duration = `PT${hours}H${minutes}M${seconds}S`;
+                }
+            } else if (parts.length === 2) {
+                const minutes = parseInt(parts[0], 10);
+                const seconds = parseInt(parts[1], 10);
+                if (!isNaN(minutes) && !isNaN(seconds)) {
+                    duration = `PT${minutes}M${seconds}S`;
+                }
+            }
+        }
+
+        try {
+            const score = typeof results.scorePercentage === 'number' ? results.scorePercentage / 100 : undefined;
+            await this._driver.sendAssessmentStatement({
+                id: assessmentId,
+                score, // Convert to 0-1 scaled; undefined if not provided
+                passed: results.passed,
+                questionCount: results.totalQuestions,
+                correctCount: results.correctCount,
+                attemptNumber: results.attemptNumber,
+                duration: duration
+            });
+        } catch (error) {
+            logger.error('[XapiStatementService] Failed to send assessment statement:', error);
+        }
+    }
+
+    /**
+     * Handles navigation change events for slide tracking.
+     * Sends 'experienced' statement for the previous slide with duration.
+     * @private
+     */
+    async _handleNavigationChanged({ fromSlideId, toSlideId, slideTitle }) {
+        // Send statement for previous slide (if any)
+        if (fromSlideId && this._slideEntryTime) {
+            const duration = this._calculateDuration(this._slideEntryTime);
+
+            try {
+                await this._driver.sendSlideStatement({
+                    id: fromSlideId,
+                    title: this._currentSlideTitle || undefined,
+                    verb: 'experienced',
+                    duration: duration
+                });
+            } catch (error) {
+                logger.error('[XapiStatementService] Failed to send slide statement:', error);
+            }
+        }
+
+        // Track entry time and title for new slide
+        this._currentSlideId = toSlideId;
+        this._currentSlideTitle = slideTitle || null;
+        this._slideEntryTime = Date.now();
+    }
+
+    /**
+     * Calculates ISO 8601 duration from a start timestamp.
+     * @private
+     */
+    _calculateDuration(startTime) {
+        const elapsedMs = Date.now() - startTime;
+        const totalSeconds = Math.floor(elapsedMs / 1000);
+        const hours = Math.floor(totalSeconds / 3600);
+        const minutes = Math.floor((totalSeconds % 3600) / 60);
+        const seconds = totalSeconds % 60;
+
+        if (hours > 0) {
+            return `PT${hours}H${minutes}M${seconds}S`;
+        } else if (minutes > 0) {
+            return `PT${minutes}M${seconds}S`;
+        } else {
+            return `PT${seconds}S`;
+        }
+    }
+
+    /**
+     * Handles session termination by sending the final slide statement.
+     * @private
+     */
+    async _handleBeforeTerminate() {
+        await this._sendPendingSlideStatement();
+    }
+
+    /**
+     * Sends an 'experienced' statement for the current slide if one is pending.
+     * This captures time spent on the final slide before session ends.
+     * @private
+     */
+    async _sendPendingSlideStatement() {
+        if (!this._currentSlideId || !this._slideEntryTime || !this._driver) {
+            return;
+        }
+
+        const duration = this._calculateDuration(this._slideEntryTime);
+
+        try {
+            await this._driver.sendSlideStatement({
+                id: this._currentSlideId,
+                title: this._currentSlideTitle || undefined,
+                verb: 'experienced',
+                duration: duration
+            });
+            logger.debug(`[XapiStatementService] Sent final slide statement: ${this._currentSlideId}`);
+        } catch (error) {
+            logger.error('[XapiStatementService] Failed to send final slide statement:', error);
+        }
+
+        // Clear tracking to prevent duplicate sends
+        this._currentSlideId = null;
+        this._currentSlideTitle = null;
+        this._slideEntryTime = null;
+    }
+
+    /**
+     * Cleans up event subscriptions.
+     */
+    destroy() {
+        this._subscriptions.forEach(unsub => {
+            if (typeof unsub === 'function') unsub();
+        });
+        this._subscriptions = [];
+        this._driver = null;
+        this._isInitialized = false;
+        this._currentSlideId = null;
+        this._currentSlideTitle = null;
+        this._slideEntryTime = null;
+    }
+}
+
+// Singleton instance
+const xapiStatementService = new XapiStatementService();
+export default xapiStatementService;