@vue-skuilder/db 0.1.24 → 0.1.25

package/src/study/SessionController.ts

@@ -17,6 +17,8 @@ import { recordUserOutcome } from '@db/core/orchestration/recording';
 import { Loggable } from '@db/util';
 import { getCardOrigin } from '@db/core/navigators';
 import { SourceMixer, QuotaRoundRobinMixer, SourceBatch } from './SourceMixer';
+import { captureMixerRun } from './MixerDebugger';
+import { startSessionTracking, recordCardPresentation, snapshotQueues, endSessionTracking } from './SessionDebugger';
 
 export interface StudySessionRecord {
   card: {
@@ -62,6 +64,8 @@ export class SessionController<TView = unknown> extends Loggable {
   private eloService: EloService;
   private hydrationService: CardHydrationService<TView>;
   private mixer: SourceMixer;
+  private dataLayer: DataLayerProvider;
+  private courseNameCache: Map<string, string> = new Map();
 
   private sources: StudyContentSource[];
   // dataLayer and getViewComponent now injected into CardHydrationService
@@ -85,7 +89,11 @@ export class SessionController<TView = unknown> extends Loggable {
     return this._secondsRemaining;
   }
   public get report(): string {
-    return `${this.reviewQ.dequeueCount} reviews, ${this.newQ.dequeueCount} new cards`;
+    const reviewCount = this.reviewQ.dequeueCount;
+    const newCount = this.newQ.dequeueCount;
+    const reviewWord = reviewCount === 1 ? 'review' : 'reviews';
+    const newCardWord = newCount === 1 ? 'new card' : 'new cards';
+    return `${reviewCount} ${reviewWord}, ${newCount} ${newCardWord}`;
   }
   public get detailedReport(): string {
     return this.newQ.toString + '\n' + this.reviewQ.toString + '\n' + this.failedQ.toString;
@@ -109,6 +117,7 @@ export class SessionController<TView = unknown> extends Loggable {
   ) {
     super();
 
+    this.dataLayer = dataLayer;
     this.mixer = mixer || new QuotaRoundRobinMixer();
     this.srsService = new SrsService(dataLayer.getUserDB());
     this.eloService = new EloService(dataLayer, dataLayer.getUserDB());
@@ -194,6 +203,9 @@ export class SessionController<TView = unknown> extends Loggable {
     await this.getWeightedContent();
     await this.hydrationService.ensureHydratedCards();
 
+    // Start session tracking for debugging
+    startSessionTracking(this.reviewQ.length, this.newQ.length, this.failedQ.length);
+
     this._intervalHandle = setInterval(() => {
       this.tick();
     }, 1000);
@@ -311,6 +323,35 @@ export class SessionController<TView = unknown> extends Loggable {
     // Mix weighted cards across sources using configured strategy
     const mixedWeighted = this.mixer.mix(batches, limit * this.sources.length);
 
+    // Capture mixer run for debugging - fetch course names
+    const sourceIds = batches.map((b) => {
+      const firstCard = b.weighted[0];
+      return firstCard?.courseId || `source-${b.sourceIndex}`;
+    });
+    // Populate course name cache (one-time fetch, reused by SessionDebugger)
+    await Promise.all(
+      sourceIds.map(async (id) => {
+        try {
+          const config = await this.dataLayer.getCoursesDB().getCourseConfig(id);
+          this.courseNameCache.set(id, config.name);
+        } catch {
+          // leave unmapped
+        }
+      })
+    );
+    const sourceNames = sourceIds.map((id) => this.courseNameCache.get(id));
+    const quotaPerSource =
+      this.mixer instanceof QuotaRoundRobinMixer ? Math.ceil((limit * this.sources.length) / batches.length) : undefined;
+    captureMixerRun(
+      this.mixer.constructor.name,
+      batches,
+      sourceIds,
+      sourceNames,
+      limit * this.sources.length,
+      quotaPerSource,
+      mixedWeighted
+    );
+
     // Split mixed results by card origin
     const reviewWeighted = mixedWeighted.filter((w) => getCardOrigin(w) === 'review');
     const newWeighted = mixedWeighted.filter((w) => getCardOrigin(w) === 'new');
@@ -454,32 +495,67 @@ export class SessionController<TView = unknown> extends Loggable {
 
     if (this._secondsRemaining <= 0 && this.failedQ.length === 0) {
       this._currentCard = null;
+      endSessionTracking();
       return null;
     }
 
-    // Get what SessionController thinks should be next
-    const nextItem = this._selectNextItemToHydrate();
-    if (!nextItem) {
-      this._currentCard = null;
-      return null;
-    }
+    // Try multiple cards in case some fail hydration (e.g., deleted from DB)
+    const MAX_SKIP = 20;
+    for (let attempt = 0; attempt < MAX_SKIP; attempt++) {
+      const nextItem = this._selectNextItemToHydrate();
+      if (!nextItem) {
+        this._currentCard = null;
+        endSessionTracking();
+        return null;
+      }
 
-    // Look up in hydration cache
-    let card = this.hydrationService.getHydratedCard(nextItem.cardID);
+      // Look up in hydration cache
+      let card = this.hydrationService.getHydratedCard(nextItem.cardID);
 
-    // If not ready, wait for it
-    if (!card) {
-      card = await this.hydrationService.waitForCard(nextItem.cardID);
-    }
+      // If not ready, wait for it
+      if (!card) {
+        card = await this.hydrationService.waitForCard(nextItem.cardID);
+      }
 
-    // Remove from source queue now that we're consuming it
-    this.removeItemFromQueue(nextItem);
+      // Remove from source queue now that we're consuming it
+      this.removeItemFromQueue(nextItem);
 
-    // Trigger background hydration to maintain cache (async, non-blocking)
-    await this.hydrationService.ensureHydratedCards();
+      if (card) {
+        // Trigger background hydration to maintain cache (async, non-blocking)
+        await this.hydrationService.ensureHydratedCards();
+        this._currentCard = card;
+
+        // Record presentation for debugging
+        const origin = nextItem.status === 'review' || nextItem.status === 'failed-review' ? 'review' :
+                       nextItem.status === 'new' || nextItem.status === 'failed-new' ? 'new' : 'failed';
+        const queueSource = nextItem.status.startsWith('failed') ? 'failedQ' :
+                           (nextItem.status === 'review' ? 'reviewQ' : 'newQ');
+
+        recordCardPresentation(
+          nextItem.cardID,
+          nextItem.courseID,
+          this.courseNameCache.get(nextItem.courseID),
+          origin,
+          queueSource as 'reviewQ' | 'newQ' | 'failedQ'
+        );
+
+        // Snapshot queue state
+        snapshotQueues(this.reviewQ.length, this.newQ.length, this.failedQ.length);
+
+        return card;
+      }
+
+      // Card failed hydration (deleted from DB?) — skip and clean up
+      this.log(`Skipping card ${nextItem.cardID}: hydration failed, trying next`);
+      if (isReview(nextItem)) {
+        this.srsService.removeReview(nextItem.reviewID);
+      }
+    }
 
-    this._currentCard = card;
-    return card;
+    this.log(`Exhausted ${MAX_SKIP} skip attempts finding a hydratable card`);
+    this._currentCard = null;
+    endSessionTracking();
+    return null;
   }
 
   /**

package/src/study/SessionDebugger.ts

@@ -0,0 +1,442 @@
+import { logger } from '../util/logger';
+
+// ============================================================================
+// SESSION DEBUGGER
+// ============================================================================
+//
+// Console-accessible debug API for inspecting session runtime behavior.
+//
+// Exposed as `window.skuilder.session` for interactive exploration.
+//
+// Usage:
+//   window.skuilder.session.showQueue()
+//   window.skuilder.session.showHistory()
+//   window.skuilder.session.showInterleaving()
+//   window.skuilder.session.export()
+//
+// ============================================================================
+
+/**
+ * Snapshot of queue state at a given moment.
+ */
+export interface QueueSnapshot {
+  timestamp: Date;
+  reviewQLength: number;
+  newQLength: number;
+  failedQLength: number;
+  reviewQNext3?: string[]; // cardIds of next 3 in reviewQ
+  newQNext3?: string[]; // cardIds of next 3 in newQ
+}
+
+/**
+ * Record of a single card presentation.
+ */
+export interface CardPresentation {
+  timestamp: Date;
+  sequenceNumber: number; // 1-indexed position in session
+  cardId: string;
+  courseId: string;
+  courseName?: string;
+  origin: 'review' | 'new' | 'failed';
+  queueSource: 'reviewQ' | 'newQ' | 'failedQ';
+  score?: number; // If available from weighted cards
+}
+
+/**
+ * Complete session execution record.
+ */
+export interface SessionRunReport {
+  sessionId: string;
+  startTime: Date;
+  endTime?: Date;
+
+  // Initial state
+  initialQueues: QueueSnapshot;
+
+  // Card presentations in order
+  presentations: CardPresentation[];
+
+  // Queue snapshots at various points
+  queueSnapshots: QueueSnapshot[];
+}
+
+/**
+ * Active session state.
+ */
+let activeSession: SessionRunReport | null = null;
+const sessionHistory: SessionRunReport[] = [];
+const MAX_HISTORY = 5;
+
+/**
+ * Start tracking a new session.
+ */
+export function startSessionTracking(
+  reviewQLength: number,
+  newQLength: number,
+  failedQLength: number
+): void {
+  const sessionId = `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+  activeSession = {
+    sessionId,
+    startTime: new Date(),
+    initialQueues: {
+      timestamp: new Date(),
+      reviewQLength,
+      newQLength,
+      failedQLength,
+    },
+    presentations: [],
+    queueSnapshots: [],
+  };
+
+  logger.debug(`[SessionDebugger] Started tracking session: ${sessionId}`);
+}
+
+/**
+ * Record a card presentation.
+ */
+export function recordCardPresentation(
+  cardId: string,
+  courseId: string,
+  courseName: string | undefined,
+  origin: 'review' | 'new' | 'failed',
+  queueSource: 'reviewQ' | 'newQ' | 'failedQ',
+  score?: number
+): void {
+  if (!activeSession) {
+    logger.warn('[SessionDebugger] No active session to record presentation');
+    return;
+  }
+
+  activeSession.presentations.push({
+    timestamp: new Date(),
+    sequenceNumber: activeSession.presentations.length + 1,
+    cardId,
+    courseId,
+    courseName,
+    origin,
+    queueSource,
+    score,
+  });
+}
+
+/**
+ * Take a snapshot of current queue state.
+ */
+export function snapshotQueues(
+  reviewQLength: number,
+  newQLength: number,
+  failedQLength: number,
+  reviewQNext3?: string[],
+  newQNext3?: string[]
+): void {
+  if (!activeSession) {
+    return;
+  }
+
+  activeSession.queueSnapshots.push({
+    timestamp: new Date(),
+    reviewQLength,
+    newQLength,
+    failedQLength,
+    reviewQNext3,
+    newQNext3,
+  });
+}
+
+/**
+ * End the current session tracking.
+ */
+export function endSessionTracking(): void {
+  if (!activeSession) {
+    return;
+  }
+
+  activeSession.endTime = new Date();
+
+  // Add to history
+  sessionHistory.unshift(activeSession);
+  if (sessionHistory.length > MAX_HISTORY) {
+    sessionHistory.pop();
+  }
+
+  logger.debug(`[SessionDebugger] Ended session: ${activeSession.sessionId}`);
+  activeSession = null;
+}
+
+// ============================================================================
+// CONSOLE API
+// ============================================================================
+
+/**
+ * Show current queue state (if session active).
+ */
+function showCurrentQueue(): void {
+  if (!activeSession) {
+    logger.info('[Session Debug] No active session.');
+    return;
+  }
+
+  const latest = activeSession.queueSnapshots[activeSession.queueSnapshots.length - 1] || activeSession.initialQueues;
+
+  // eslint-disable-next-line no-console
+  console.group('📊 Current Queue State');
+  logger.info(`Review Queue: ${latest.reviewQLength} cards`);
+  if (latest.reviewQNext3 && latest.reviewQNext3.length > 0) {
+    logger.info(`  Next: ${latest.reviewQNext3.join(', ')}`);
+  }
+  logger.info(`New Queue: ${latest.newQLength} cards`);
+  if (latest.newQNext3 && latest.newQNext3.length > 0) {
+    logger.info(`  Next: ${latest.newQNext3.join(', ')}`);
+  }
+  logger.info(`Failed Queue: ${latest.failedQLength} cards`);
+  // eslint-disable-next-line no-console
+  console.groupEnd();
+}
+
+/**
+ * Show presentation history for current or last session.
+ */
+function showPresentationHistory(sessionIndex: number = 0): void {
+  const session = sessionIndex === 0 && activeSession ? activeSession : sessionHistory[sessionIndex];
+
+  if (!session) {
+    logger.info(`[Session Debug] No session found at index ${sessionIndex}`);
+    return;
+  }
+
+  // eslint-disable-next-line no-console
+  console.group(`📜 Session History: ${session.sessionId}`);
+  logger.info(`Started: ${session.startTime.toLocaleTimeString()}`);
+  if (session.endTime) {
+    logger.info(`Ended: ${session.endTime.toLocaleTimeString()}`);
+  }
+  logger.info(`Cards presented: ${session.presentations.length}`);
+
+  if (session.presentations.length > 0) {
+    // eslint-disable-next-line no-console
+    console.table(
+      session.presentations.map((p) => ({
+        '#': p.sequenceNumber,
+        course: p.courseName || p.courseId.slice(0, 8),
+        origin: p.origin,
+        queue: p.queueSource,
+        score: p.score?.toFixed(3) || '-',
+        time: p.timestamp.toLocaleTimeString(),
+      }))
+    );
+  }
+
+  // eslint-disable-next-line no-console
+  console.groupEnd();
+}
+
+/**
+ * Analyze course interleaving pattern.
+ */
+function showInterleaving(sessionIndex: number = 0): void {
+  const session = sessionIndex === 0 && activeSession ? activeSession : sessionHistory[sessionIndex];
+
+  if (!session) {
+    logger.info(`[Session Debug] No session found at index ${sessionIndex}`);
+    return;
+  }
+
+  // eslint-disable-next-line no-console
+  console.group('🔀 Interleaving Analysis');
+
+  // Course distribution
+  const courseCounts = new Map<string, number>();
+  const courseOrigins = new Map<string, { review: number; new: number; failed: number }>();
+
+  session.presentations.forEach((p) => {
+    const name = p.courseName || p.courseId;
+    courseCounts.set(name, (courseCounts.get(name) || 0) + 1);
+
+    if (!courseOrigins.has(name)) {
+      courseOrigins.set(name, { review: 0, new: 0, failed: 0 });
+    }
+    const origins = courseOrigins.get(name)!;
+    origins[p.origin]++;
+  });
+
+  logger.info('Course distribution:');
+  // eslint-disable-next-line no-console
+  console.table(
+    Array.from(courseCounts.entries()).map(([course, count]) => {
+      const origins = courseOrigins.get(course)!;
+      return {
+        course,
+        total: count,
+        reviews: origins.review,
+        new: origins.new,
+        failed: origins.failed,
+        percentage: ((count / session.presentations.length) * 100).toFixed(1) + '%',
+      };
+    })
+  );
+
+  // Show interleaving pattern (first 20 cards)
+  if (session.presentations.length > 0) {
+    logger.info('\nPresentation sequence (first 20):');
+    const sequence = session.presentations
+      .slice(0, 20)
+      .map((p, idx) => `${idx + 1}. ${p.courseName || p.courseId.slice(0, 8)} (${p.origin})`)
+      .join('\n');
+    logger.info(sequence);
+  }
+
+  // Detect clustering (same course in a row)
+  let maxCluster = 0;
+  let currentCluster = 1;
+  let currentCourse = session.presentations[0]?.courseId;
+
+  for (let i = 1; i < session.presentations.length; i++) {
+    if (session.presentations[i].courseId === currentCourse) {
+      currentCluster++;
+      maxCluster = Math.max(maxCluster, currentCluster);
+    } else {
+      currentCourse = session.presentations[i].courseId;
+      currentCluster = 1;
+    }
+  }
+
+  if (maxCluster > 3) {
+    logger.info(`\n⚠️ Detected clustering: max ${maxCluster} cards from same course in a row`);
+    logger.info('This suggests cards are sorted by score rather than round-robin by course.');
+  }
+
+  // eslint-disable-next-line no-console
+  console.groupEnd();
+}
+
+/**
+ * Console API object exposed on window.skuilder.session
+ */
+export const sessionDebugAPI = {
+  /**
+   * Get raw session history for programmatic access.
+   */
+  get sessions(): SessionRunReport[] {
+    return [...sessionHistory];
+  },
+
+  /**
+   * Get active session if any.
+   */
+  get active(): SessionRunReport | null {
+    return activeSession;
+  },
+
+  /**
+   * Show current queue state.
+   */
+  showQueue(): void {
+    showCurrentQueue();
+  },
+
+  /**
+   * Show presentation history for current or past session.
+   */
+  showHistory(sessionIndex: number = 0): void {
+    showPresentationHistory(sessionIndex);
+  },
+
+  /**
+   * Analyze course interleaving pattern.
+   */
+  showInterleaving(sessionIndex: number = 0): void {
+    showInterleaving(sessionIndex);
+  },
+
+  /**
+   * List all tracked sessions.
+   */
+  listSessions(): void {
+    if (activeSession) {
+      logger.info(`Active session: ${activeSession.sessionId} (${activeSession.presentations.length} cards presented)`);
+    }
+
+    if (sessionHistory.length === 0) {
+      logger.info('[Session Debug] No completed sessions in history.');
+      return;
+    }
+
+    // eslint-disable-next-line no-console
+    console.table(
+      sessionHistory.map((s, idx) => ({
+        index: idx,
+        id: s.sessionId.slice(-8),
+        started: s.startTime.toLocaleTimeString(),
+        ended: s.endTime?.toLocaleTimeString() || 'incomplete',
+        cards: s.presentations.length,
+      }))
+    );
+  },
+
+  /**
+   * Export session history as JSON for bug reports.
+   */
+  export(): string {
+    const data = {
+      active: activeSession,
+      history: sessionHistory,
+    };
+    const json = JSON.stringify(data, null, 2);
+    logger.info('[Session Debug] Session data exported. Copy the returned string or use:');
+    logger.info('  copy(window.skuilder.session.export())');
+    return json;
+  },
+
+  /**
+   * Clear session history.
+   */
+  clear(): void {
+    sessionHistory.length = 0;
+    logger.info('[Session Debug] Session history cleared.');
+  },
+
+  /**
+   * Show help.
+   */
+  help(): void {
+    logger.info(`
+🎯 Session Debug API
+
+Commands:
+  .showQueue()              Show current queue state (active session only)
+  .showHistory(index?)      Show presentation history (0=current/last, 1=previous, etc)
+  .showInterleaving(index?) Analyze course interleaving pattern
+  .listSessions()           List all tracked sessions
+  .export()                 Export session data as JSON for bug reports
+  .clear()                  Clear session history
+  .sessions                 Access raw session history array
+  .active                   Access active session (if any)
+  .help()                   Show this help message
+
+Example:
+  window.skuilder.session.showHistory()
+  window.skuilder.session.showInterleaving()
+  window.skuilder.session.showQueue()
+`);
+  },
+};
+
+// ============================================================================
+// WINDOW MOUNT
+// ============================================================================
+
+/**
+ * Mount the debug API on window.skuilder.session
+ */
+export function mountSessionDebugger(): void {
+  if (typeof window === 'undefined') return;
+
+  const win = window as any;
+  win.skuilder = win.skuilder || {};
+  win.skuilder.session = sessionDebugAPI;
+}
+
+// Auto-mount when module is loaded
+mountSessionDebugger();

package/src/study/SourceMixer.ts

@@ -30,16 +30,16 @@ export interface SourceMixer {
 }
 
 /**
- * Simple quota-based mixer: allocates equal representation to each source,
- * taking the top-N cards by score from each.
+ * Quota-based mixer with interleaved output.
  *
- * Guarantees balanced representation across sources regardless of absolute
- * score differences. A low-scoring source gets the same quota as a high-scoring
- * source.
+ * Allocates equal representation to each source (top-N by score), then
+ * interleaves the results by dealing from a randomly-shuffled source order.
+ * Within each source, cards are dealt in score-descending order.
  *
- * This is the KISS approach - simple, predictable, and fair in terms of
- * source representation (though not necessarily optimal in terms of absolute
- * card quality).
+ * This ensures that cards from different courses are spread throughout the
+ * queue rather than clustered by score bands, which matters because
+ * SessionController consumes queues front-to-back and sessions often end
+ * before reaching the tail.
  */
 export class QuotaRoundRobinMixer implements SourceMixer {
   mix(batches: SourceBatch[], limit: number): WeightedCard[] {
@@ -48,18 +48,37 @@ export class QuotaRoundRobinMixer implements SourceMixer {
     }
 
     const quotaPerSource = Math.ceil(limit / batches.length);
-    const mixed: WeightedCard[] = [];
 
-    for (const batch of batches) {
-      // Sort this source's cards by score descending
-      const sortedBatch = [...batch.weighted].sort((a, b) => b.score - a.score);
+    // Build per-source stacks sorted by score descending, capped at quota
+    const sourceStacks: WeightedCard[][] = batches.map((batch) => {
+      return [...batch.weighted].sort((a, b) => b.score - a.score).slice(0, quotaPerSource);
+    });
 
-      // Take top quotaPerSource from this source
-      const topFromSource = sortedBatch.slice(0, quotaPerSource);
-      mixed.push(...topFromSource);
+    // Shuffle the source ordering so no course is systematically first
+    for (let i = sourceStacks.length - 1; i > 0; i--) {
+      const j = Math.floor(Math.random() * (i + 1));
+      [sourceStacks[i], sourceStacks[j]] = [sourceStacks[j], sourceStacks[i]];
     }
 
-    // Sort the mixed result by score descending and return up to limit
-    return mixed.sort((a, b) => b.score - a.score).slice(0, limit);
+    // Interleave: deal one card from each source in rotation
+    const result: WeightedCard[] = [];
+    let exhausted = 0;
+    const cursors = new Array(sourceStacks.length).fill(0);
+
+    while (result.length < limit && exhausted < sourceStacks.length) {
+      exhausted = 0;
+      for (let s = 0; s < sourceStacks.length; s++) {
+        if (result.length >= limit) break;
+
+        if (cursors[s] < sourceStacks[s].length) {
+          result.push(sourceStacks[s][cursors[s]]);
+          cursors[s]++;
+        } else {
+          exhausted++;
+        }
+      }
+    }
+
+    return result;
   }
 }