coursecode 0.1.0

package/framework/js/state/lms-error-utils.js

@@ -0,0 +1,58 @@
+/**
+ * @file lms-error-utils.js
+ * @description Shared LMS error classification helpers for diagnostics.
+ */
+
+/**
+ * Classifies LMS operation errors into stable buckets for telemetry/UI handling.
+ * @param {unknown} error
+ * @returns {'timeout'|'network'|'scorm-api'|'validation'|'session'|'unknown'}
+ */
+export function classifyLmsError(error) {
+    const message = String(error?.message || error || '').toLowerCase();
+
+    if (message.includes('timed out') || message.includes('timeout')) {
+        return 'timeout';
+    }
+
+    if (
+        message.includes('network') ||
+        message.includes('fetch') ||
+        message.includes('failed to fetch') ||
+        message.includes('socket') ||
+        message.includes('connection')
+    ) {
+        return 'network';
+    }
+
+    if (
+        message.includes('scorm') ||
+        message.includes('lmssetvalue') ||
+        message.includes('lmsgetvalue') ||
+        message.includes('commit') ||
+        message.includes('terminate')
+    ) {
+        return 'scorm-api';
+    }
+
+    if (
+        message.includes('invalid') ||
+        message.includes('must be') ||
+        message.includes('required') ||
+        message.includes('out of range')
+    ) {
+        return 'validation';
+    }
+
+    if (
+        message.includes('session') ||
+        message.includes('already terminated') ||
+        message.includes('not initialized') ||
+        message.includes('expired')
+    ) {
+        return 'session';
+    }
+
+    return 'unknown';
+}
+

package/framework/js/state/state-commits.js

@@ -0,0 +1,200 @@
+/**
+ * @file state-commits.js
+ * @description Auto-batched commit scheduling and LMS persistence.
+ * @internal Only used by state-manager.js
+ */
+
+import { eventBus } from '../core/event-bus.js';
+import { logger } from '../utilities/logger.js';
+import { classifyLmsError } from './lms-error-utils.js';
+
+// Auto-batch debounce delay in milliseconds
+const AUTO_BATCH_DELAY_MS = 500;
+
+export class CommitScheduler {
+    /**
+     * @param {import('./lms-connection.js').default} lmsConnection
+     * @param {import('./state-domains.js').DomainStore} domainStore
+     * @param {import('./transaction-log.js').TransactionLog} txLog
+     */
+    constructor(lmsConnection, domainStore, txLog) {
+        this._lms = lmsConnection;
+        this._domains = domainStore;
+        this._txLog = txLog;
+
+        this._autoBatchTimer = null;
+        this._autoBatchDirty = false;
+        this._autoBatchSuspendDirty = false;
+        this._inFlightCommit = null;
+    }
+
+    /**
+     * Schedules an auto-batched commit after a debounce delay.
+     * @param {boolean} needsSuspendSync - Whether this write requires suspend_data sync
+     */
+    scheduleCommit(needsSuspendSync) {
+        this._autoBatchDirty = true;
+        if (needsSuspendSync) {
+            this._autoBatchSuspendDirty = true;
+        }
+
+        if (this._autoBatchTimer) {
+            clearTimeout(this._autoBatchTimer);
+        }
+
+        this._autoBatchTimer = setTimeout(() => {
+            this._executeCommit();
+        }, AUTO_BATCH_DELAY_MS);
+
+        logger.debug(`[StateManager] Auto-batch scheduled (${AUTO_BATCH_DELAY_MS}ms debounce)`);
+    }
+
+    /**
+     * Immediately flushes any pending auto-batched writes.
+     */
+    async flush() {
+        if (this._autoBatchTimer) {
+            clearTimeout(this._autoBatchTimer);
+            this._autoBatchTimer = null;
+        }
+
+        if (this._autoBatchDirty) {
+            logger.debug('[StateManager] Force-flushing pending writes (critical action)');
+            await this._executeCommit();
+            return;
+        }
+
+        // If a commit is currently in-flight, wait for it before continuing.
+        if (this._inFlightCommit) {
+            await this._inFlightCommit;
+        }
+    }
+
+    /**
+     * Commits state to LMS immediately. Used for critical paths (terminate, clearAllData).
+     */
+    async commitToLMS() {
+        // Critical commits should not race with auto-batch commits.
+        if (this._inFlightCommit) {
+            await this._inFlightCommit;
+        }
+
+        if (this._autoBatchTimer) {
+            clearTimeout(this._autoBatchTimer);
+            this._autoBatchTimer = null;
+        }
+
+        // A critical commit writes full state immediately, so clear pending flags.
+        this._autoBatchDirty = false;
+        this._autoBatchSuspendDirty = false;
+
+        eventBus.emit('state:commitStart');
+
+        try {
+            const stateSnapshot = {
+                domains: Object.keys(this._domains.state),
+                domainSizes: Object.fromEntries(
+                    Object.entries(this._domains.state).map(([key, value]) => [
+                        key,
+                        JSON.stringify(value).length
+                    ])
+                ),
+                totalSize: JSON.stringify(this._domains.state).length,
+                totalSizeKB: (JSON.stringify(this._domains.state).length / 1024).toFixed(2)
+            };
+
+            logger.debug('[StateManager] Committing state:', stateSnapshot);
+
+            this._lms.setSuspendData(this._domains.state);
+            this._inFlightCommit = this._lms.commit();
+            await this._inFlightCommit;
+            logger.debug('[StateManager] State committed to LMS');
+            eventBus.emit('state:commitSuccess');
+            eventBus.emit('state:committed');
+            return true;
+        } catch (error) {
+            const classification = classifyLmsError(error);
+            const stateSnapshot = {
+                domains: Object.keys(this._domains.state),
+                domainSizes: {},
+                problematicDomains: [],
+                recentTransactions: this._txLog.getRecent(5)
+            };
+
+            for (const [key, value] of Object.entries(this._domains.state)) {
+                try {
+                    const serialized = JSON.stringify(value);
+                    stateSnapshot.domainSizes[key] = serialized.length;
+                    if (serialized.length > 10000) {
+                        stateSnapshot.problematicDomains.push({
+                            domain: key,
+                            size: serialized.length,
+                            sizeKB: (serialized.length / 1024).toFixed(2)
+                        });
+                    }
+                } catch (e) {
+                    stateSnapshot.domainSizes[key] = 'SERIALIZATION_FAILED';
+                    stateSnapshot.problematicDomains.push({ domain: key, error: e.message });
+                }
+            }
+
+            logger.error('[StateManager] Commit failed with detailed diagnostics:', { domain: 'state', operation: 'commit', stack: error.stack, stateSnapshot });
+            eventBus.emit('state:commitFailed', { error: error.message, classification, stateSnapshot });
+            throw error;
+        } finally {
+            this._inFlightCommit = null;
+        }
+    }
+
+    // --- Private ---
+
+    async _executeCommit() {
+        this._autoBatchTimer = null;
+
+        if (!this._autoBatchDirty) return;
+
+        // Avoid overlapping commits; wait and re-evaluate dirty state.
+        if (this._inFlightCommit) {
+            await this._inFlightCommit;
+            if (!this._autoBatchDirty) return;
+        }
+
+        eventBus.emit('state:commitStart');
+
+        // Snapshot then clear dirty flags up-front so writes during await are preserved.
+        const needsSuspendSync = this._autoBatchSuspendDirty;
+        this._autoBatchDirty = false;
+        this._autoBatchSuspendDirty = false;
+
+        try {
+            if (needsSuspendSync) {
+                this._lms.setSuspendData(this._domains.state);
+            }
+
+            this._inFlightCommit = this._lms.commit();
+            await this._inFlightCommit;
+
+            logger.debug('[StateManager] Auto-batch committed');
+            eventBus.emit('state:commitSuccess');
+            eventBus.emit('state:committed');
+        } catch (error) {
+            const classification = classifyLmsError(error);
+            // Preserve failed write intent for a retry.
+            this._autoBatchDirty = true;
+            if (needsSuspendSync) {
+                this._autoBatchSuspendDirty = true;
+            }
+            logger.error('[StateManager] Auto-batch commit failed:', { domain: 'state', operation: 'autoBatchCommit', stack: error.stack });
+            eventBus.emit('state:commitFailed', { error: error.message, classification });
+        } finally {
+            this._inFlightCommit = null;
+
+            // If writes happened during commit, schedule follow-up commit.
+            if (this._autoBatchDirty && !this._autoBatchTimer) {
+                this._autoBatchTimer = setTimeout(() => {
+                    this._executeCommit();
+                }, AUTO_BATCH_DELAY_MS);
+            }
+        }
+    }
+}

package/framework/js/state/state-domains.js

@@ -0,0 +1,86 @@
+/**
+ * @file state-domains.js
+ * @description Domain state CRUD operations with append-only semantics.
+ * @internal Only used by state-manager.js
+ */
+
+import { deepClone } from '../utilities/utilities.js';
+import { eventBus } from '../core/event-bus.js';
+import { logger } from '../utilities/logger.js';
+
+// Domains that use append-only semantics (each setDomainState call adds a new record)
+const APPEND_ONLY_DOMAINS = new Set([
+    'interactions'
+]);
+
+export class DomainStore {
+    /**
+     * @param {import('./transaction-log.js').TransactionLog} txLog
+     */
+    constructor(txLog) {
+        this.state = {};
+        this._txLog = txLog;
+    }
+
+    /**
+     * Retrieves a deep-cloned copy of the entire state.
+     */
+    getState() {
+        return deepClone(this.state);
+    }
+
+    /**
+     * Retrieves a deep-cloned copy of a specific domain.
+     * @param {string} domain - The top-level key for the state domain
+     */
+    getDomainState(domain) {
+        if (typeof domain !== 'string' || domain.trim() === '') {
+            throw new Error('StateManager: domain must be a non-empty string');
+        }
+        return this.state[domain] ? deepClone(this.state[domain]) : undefined;
+    }
+
+    /**
+     * Sets the state for a specific domain.
+     * Append-only domains append a new record; normal domains replace.
+     *
+     * @param {string} domain
+     * @param {any} value
+     * @param {object} [meta={}]
+     * @returns {object|undefined} For append-only domains, the appended record with index
+     */
+    setDomainState(domain, value, meta = {}) {
+        if (typeof domain !== 'string' || domain.trim() === '') {
+            throw new Error('StateManager: domain must be a non-empty string');
+        }
+
+        let result;
+        if (APPEND_ONLY_DOMAINS.has(domain)) {
+            if (!Array.isArray(this.state[domain])) {
+                this.state[domain] = [];
+            }
+            const index = this.state[domain].length;
+            result = { ...value, _index: index };
+            this.state[domain].push(result);
+            logger.debug(`[StateManager] Appended to ${domain} at index ${index}`);
+        } else {
+            this.state[domain] = value;
+            logger.debug(`[StateManager] State updated for domain: ${domain}`);
+        }
+
+        this._txLog.record(domain, APPEND_ONLY_DOMAINS.has(domain) ? 'append' : 'set', {
+            size: JSON.stringify(value).length
+        });
+
+        eventBus.emit('state:changed', { domain, value: result || value, meta });
+
+        return result;
+    }
+
+    /**
+     * Clears all state.
+     */
+    clearState() {
+        this.state = {};
+    }
+}