@vue-skuilder/db 0.1.18 → 0.1.21

package/src/study/SessionController.ts

@@ -14,12 +14,8 @@ import {
 
 import { CardRecord, CardHistory, CourseRegistrationDoc } from '@db/core';
 import { Loggable } from '@db/util';
-import { ScheduledCard } from '@db/core/types/user';
-import { WeightedCard, getCardOrigin } from '@db/core/navigators';
-
-function randomInt(min: number, max: number): number {
-  return Math.floor(Math.random() * (max - min + 1)) + min;
-}
+import { getCardOrigin } from '@db/core/navigators';
+import { SourceMixer, QuotaRoundRobinMixer, SourceBatch } from './SourceMixer';
 
 export interface StudySessionRecord {
   card: {
@@ -32,6 +28,7 @@ export interface StudySessionRecord {
 }
 
 import { DataLayerProvider } from '@db/core';
+import { logger } from '@db/util/logger';
 
 export type SessionAction =
   | 'dismiss-success'
@@ -63,6 +60,7 @@ export class SessionController<TView = unknown> extends Loggable {
   private srsService: SrsService;
   private eloService: EloService;
   private hydrationService: CardHydrationService<TView>;
+  private mixer: SourceMixer;
 
   private sources: StudyContentSource[];
   // dataLayer and getViewComponent now injected into CardHydrationService
@@ -95,25 +93,29 @@ export class SessionController<TView = unknown> extends Loggable {
   private _intervalHandle: NodeJS.Timeout;
 
   /**
-   *
+   * @param sources - Array of content sources to mix for the session
+   * @param time - Session duration in seconds
+   * @param dataLayer - Data layer provider
+   * @param getViewComponent - Function to resolve view components
+   * @param mixer - Optional source mixer strategy (defaults to QuotaRoundRobinMixer)
    */
   constructor(
     sources: StudyContentSource[],
     time: number,
     dataLayer: DataLayerProvider,
-    getViewComponent: (viewId: string) => TView
+    getViewComponent: (viewId: string) => TView,
+    mixer?: SourceMixer
   ) {
     super();
 
+    this.mixer = mixer || new QuotaRoundRobinMixer();
     this.srsService = new SrsService(dataLayer.getUserDB());
     this.eloService = new EloService(dataLayer, dataLayer.getUserDB());
 
     this.hydrationService = new CardHydrationService<TView>(
       getViewComponent,
       (courseId: string) => dataLayer.getCourseDB(courseId),
-      () => this._selectNextItemToHydrate(),
-      (item: StudySessionItem) => this.removeItemFromQueue(item),
-      () => this.hasAvailableCards()
+      () => this._getItemsToHydrate()
     );
 
     this.services = {
@@ -181,20 +183,14 @@ export class SessionController<TView = unknown> extends Loggable {
   }
 
   public async prepareSession() {
-    try {
-      // Use new getWeightedCards API if available, fall back to legacy methods
-      const hasWeightedCards = this.sources.some((s) => typeof s.getWeightedCards === 'function');
-
-      if (hasWeightedCards) {
-        await this.getWeightedContent();
-      } else {
-        // Legacy path: separate calls for reviews and new cards
-        await Promise.all([this.getScheduledReviews(), this.getNewCards()]);
-      }
-    } catch (e) {
-      this.error('Error preparing study session:', e);
+    // All content sources must implement getWeightedCards()
+    if (this.sources.some((s) => typeof s.getWeightedCards !== 'function')) {
+      throw new Error(
+        '[SessionController] All content sources must implement getWeightedCards().'
+      );
     }
 
+    await this.getWeightedContent();
     await this.hydrationService.ensureHydratedCards();
 
     this._intervalHandle = setInterval(() => {
@@ -240,20 +236,12 @@ export class SessionController<TView = unknown> extends Loggable {
       return items;
     };
 
-    const extractHydratedItems = () => {
-      // We can't easily iterate the hydrated queue without dequeuing,
-      // so we'll just report the count via hydratedCache.count below
-
-      const items: any[] = [];
-      return items;
-    };
-
     return {
       api: {
         mode: supportsWeightedCards ? 'weighted' : 'legacy',
         description: supportsWeightedCards
           ? 'Using getWeightedCards() API with scored candidates'
-          : 'Using legacy getNewCards()/getPendingReviews() API',
+          : 'ERROR: getWeightedCards() not a function.',
       },
       reviewQueue: {
         length: this.reviewQ.length,
@@ -272,194 +260,119 @@ export class SessionController<TView = unknown> extends Loggable {
       },
       hydratedCache: {
         count: this.hydrationService.hydratedCount,
-        failedCacheSize: this.hydrationService.failedCacheSize,
-        items: extractHydratedItems(),
+        cardIds: this.hydrationService.getHydratedCardIds(),
       },
     };
   }
 
   /**
-   * Fetch content using the new getWeightedCards API.
-   *
-   * This method uses getWeightedCards() to get scored candidates, then uses the
-   * scores to determine ordering. For reviews, we still need the full ScheduledCard
-   * data from getPendingReviews(), so we fetch both and use scores for ordering.
+   * Fetch content using the getWeightedCards API and mix across sources.
    *
-   * The hybrid approach:
-   * 1. Fetch weighted cards to get scoring/ordering information
-   * 2. Fetch full review data via legacy getPendingReviews()
-   * 3. Order reviews by their weighted scores
-   * 4. Add new cards ordered by their weighted scores
+   * This method:
+   * 1. Fetches weighted cards from each source
+   * 2. Fetches full review data (we need ScheduledCard fields for queue)
+   * 3. Uses SourceMixer to balance content across sources
+   * 4. Populates review and new card queues with mixed results
    */
   private async getWeightedContent() {
     const limit = 20; // Initial batch size per source
 
-    // Collect weighted cards for scoring, and full review data for queue population
-    const allWeighted: WeightedCard[] = [];
-    const allReviews: (StudySessionReviewItem & ScheduledCard)[] = [];
-    const allNewCards: StudySessionNewItem[] = [];
+    // Collect batches from each source
+    const batches: SourceBatch[] = [];
 
-    for (const source of this.sources) {
+    for (let i = 0; i < this.sources.length; i++) {
+      const source = this.sources[i];
       try {
-        // Always fetch full review data (we need ScheduledCard fields)
-        const reviews = await source.getPendingReviews().catch((error) => {
-          this.error(`Failed to get reviews for source:`, error);
-          return [];
-        });
-        allReviews.push(...reviews);
+        // Fetch weighted cards for mixing
+        const weighted = await source.getWeightedCards!(limit);
 
-        // Fetch weighted cards for scoring if available
-        if (typeof source.getWeightedCards === 'function') {
-          const weighted = await source.getWeightedCards(limit);
-          allWeighted.push(...weighted);
-        } else {
-          // Fallback: fetch new cards directly and assign score=1.0
-          const newCards = await source.getNewCards(limit);
-          allNewCards.push(...newCards);
-
-          // Create pseudo-weighted entries for ordering
-          allWeighted.push(
-            ...newCards.map((c) => ({
-              cardId: c.cardID,
-              courseId: c.courseID,
-              score: 1.0,
-              provenance: [
-                {
-                  strategy: 'legacy',
-                  strategyName: 'Legacy Fallback',
-                  strategyId: 'legacy-fallback',
-                  action: 'generated' as const,
-                  score: 1.0,
-                  reason: 'Fallback to legacy getNewCards(), new card',
-                },
-              ],
-            })),
-            ...reviews.map((r) => ({
-              cardId: r.cardID,
-              courseId: r.courseID,
-              score: 1.0,
-              provenance: [
-                {
-                  strategy: 'legacy',
-                  strategyName: 'Legacy Fallback',
-                  strategyId: 'legacy-fallback',
-                  action: 'generated' as const,
-                  score: 1.0,
-                  reason: 'Fallback to legacy getPendingReviews(), review',
-                },
-              ],
-            }))
-          );
-        }
+        batches.push({
+          sourceIndex: i,
+          weighted,
+        });
       } catch (error) {
-        this.error(`Failed to get content from source:`, error);
+        this.error(`Failed to get content from source ${i}:`, error);
+        // Re-throw if this is the only source - we can't proceed without any content
+        if (this.sources.length === 1) {
+          throw new Error(`Cannot start session: failed to load content from source ${i}`);
+        }
       }
     }
 
-    // Build a score lookup map from weighted cards
-    const scoreMap = new Map<string, number>();
-    for (const w of allWeighted) {
-      const key = `${w.courseId}::${w.cardId}`;
-      scoreMap.set(key, w.score);
+    // Verify we got content from at least one source
+    if (batches.length === 0) {
+      throw new Error(
+        `Cannot start session: failed to load content from all ${this.sources.length} source(s). ` +
+          `Check logs for details.`
+      );
     }
 
-    // Sort reviews by score (from weighted cards) descending
-    const scoredReviews = allReviews.map((r) => ({
-      review: r,
-      score: scoreMap.get(`${r.courseID}::${r.cardID}`) ?? 1.0,
-    }));
-    scoredReviews.sort((a, b) => b.score - a.score);
-
-    // Add reviews to queue in score order
-    let report = 'Weighted content session created with:\n';
-    for (const { review, score } of scoredReviews) {
-      this.reviewQ.add(review, review.cardID);
-      report += `Review: ${review.courseID}::${review.cardID} (score: ${score.toFixed(2)})\n`;
-    }
+    // Mix weighted cards across sources using configured strategy
+    const mixedWeighted = this.mixer.mix(batches, limit * this.sources.length);
+
+    // Split mixed results by card origin
+    const reviewWeighted = mixedWeighted.filter((w) => getCardOrigin(w) === 'review');
+    const newWeighted = mixedWeighted.filter((w) => getCardOrigin(w) === 'new');
 
-    // Get new cards from weighted list (filter out reviews)
-    const newCardWeighted = allWeighted
-      .filter((w) => getCardOrigin(w) === 'new')
-      .sort((a, b) => b.score - a.score);
+    logger.debug(`[reviews] got ${reviewWeighted.length} reviews from mixer`);
 
-    // Add new cards to queue in score order
-    for (const card of newCardWeighted) {
+    // Populate review queue from mixed results (already sorted by mixer)
+    let report = 'Mixed content session created with:\n';
+    for (const w of reviewWeighted) {
+      const reviewItem: StudySessionReviewItem = {
+        cardID: w.cardId,
+        courseID: w.courseId,
+        contentSourceType: 'course',
+        contentSourceID: w.courseId,
+        reviewID: w.reviewID!,
+        status: 'review',
+      };
+      this.reviewQ.add(reviewItem, reviewItem.cardID);
+      report += `Review: ${w.courseId}::${w.cardId} (score: ${w.score.toFixed(2)})\n`;
+    }
+
+    // Populate new card queue from mixed results (already sorted by mixer)
+    for (const w of newWeighted) {
       const newItem: StudySessionNewItem = {
-        cardID: card.cardId,
-        courseID: card.courseId,
+        cardID: w.cardId,
+        courseID: w.courseId,
         contentSourceType: 'course',
-        contentSourceID: card.courseId,
+        contentSourceID: w.courseId,
         status: 'new',
       };
-      this.newQ.add(newItem, card.cardId);
-      report += `New: ${card.courseId}::${card.cardId} (score: ${card.score.toFixed(2)})\n`;
+      this.newQ.add(newItem, newItem.cardID);
+      report += `New: ${w.courseId}::${w.cardId} (score: ${w.score.toFixed(2)})\n`;
     }
 
     this.log(report);
   }
 
   /**
-   * @deprecated Use getWeightedContent() instead. This method is kept for backward
-   * compatibility with sources that don't support getWeightedCards().
+   * Returns items that should be pre-hydrated.
+   * Deterministic: top N items from each queue to ensure coverage.
+   * Failed queue items will typically already be hydrated (from initial render).
    */
-  private async getScheduledReviews() {
-    const reviews = await Promise.all(
-      this.sources.map((c) =>
-        c.getPendingReviews().catch((error) => {
-          this.error(`Failed to get reviews for source ${c}:`, error);
-          return [];
-        })
-      )
-    );
-
-    const dueCards: (StudySessionReviewItem & ScheduledCard)[] = [];
+  private _getItemsToHydrate(): StudySessionItem[] {
+    const items: StudySessionItem[] = [];
+    const ITEMS_PER_QUEUE = 2;
 
-    while (reviews.length != 0 && reviews.some((r) => r.length > 0)) {
-      // pick a random review source
-      const index = randomInt(0, reviews.length - 1);
-      const source = reviews[index];
-
-      if (source.length === 0) {
-        reviews.splice(index, 1);
-        continue;
-      } else {
-        dueCards.push(source.shift()!);
-      }
+    for (let i = 0; i < Math.min(ITEMS_PER_QUEUE, this.reviewQ.length); i++) {
+      items.push(this.reviewQ.peek(i));
+    }
+    for (let i = 0; i < Math.min(ITEMS_PER_QUEUE, this.newQ.length); i++) {
+      items.push(this.newQ.peek(i));
+    }
+    for (let i = 0; i < Math.min(ITEMS_PER_QUEUE, this.failedQ.length); i++) {
+      items.push(this.failedQ.peek(i));
     }
 
-    let report = 'Review session created with:\n';
-    this.reviewQ.addAll(dueCards, (c) => c.cardID);
-    report += dueCards.map((card) => `Card ${card.courseID}::${card.cardID} `).join('\n');
-    this.log(report);
+    return items;
   }
 
   /**
-   * @deprecated Use getWeightedContent() instead. This method is kept for backward
-   * compatibility with sources that don't support getWeightedCards().
+   * Selects the next item to present to the user.
+   * Nondeterministic: uses probability to balance between queues based on session state.
    */
-  private async getNewCards(n: number = 10) {
-    const perCourse = Math.ceil(n / this.sources.length);
-    const newContent = await Promise.all(this.sources.map((c) => c.getNewCards(perCourse)));
-
-    // [ ] is this a noop?
-    newContent.forEach((newContentFromSource) => {
-      newContentFromSource.filter((c) => {
-        return this._sessionRecord.find((record) => record.card.card_id === c.cardID) === undefined;
-      });
-    });
-
-    while (n > 0 && newContent.some((nc) => nc.length > 0)) {
-      for (let i = 0; i < newContent.length; i++) {
-        if (newContent[i].length > 0) {
-          const item = newContent[i].splice(0, 1)[0];
-          this.log(`Adding new card: ${item.courseID}::${item.cardID}`);
-          this.newQ.add(item, item.cardID);
-          n--;
-        }
-      }
-    }
-  }
-
   private _selectNextItemToHydrate(): StudySessionItem | null {
     const choice = Math.random();
     let newBound: number = 0.1;
@@ -543,22 +456,28 @@ export class SessionController<TView = unknown> extends Loggable {
       return null;
     }
 
-    let card = this.hydrationService.dequeueHydratedCard();
+    // Get what SessionController thinks should be next
+    const nextItem = this._selectNextItemToHydrate();
+    if (!nextItem) {
+      this._currentCard = null;
+      return null;
+    }
+
+    // Look up in hydration cache
+    let card = this.hydrationService.getHydratedCard(nextItem.cardID);
 
-    // If no hydrated card but source cards available, wait for hydration
-    if (!card && this.hasAvailableCards()) {
-      card = await this.hydrationService.waitForHydratedCard();
+    // 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);
+
     // Trigger background hydration to maintain cache (async, non-blocking)
     await this.hydrationService.ensureHydratedCards();
 
-    if (card) {
-      this._currentCard = card;
-    } else {
-      this._currentCard = null;
-    }
-
+    this._currentCard = card;
     return card;
   }
 
@@ -617,9 +536,11 @@ export class SessionController<TView = unknown> extends Loggable {
       // }
 
       if (action === 'dismiss-success') {
+        // Remove from hydration cache to free memory
+        this.hydrationService.removeCard(this._currentCard.item.cardID);
         // schedule a review - currently done in Study.vue
       } else if (action === 'marked-failed') {
-        this.hydrationService.cacheFailedCard(this._currentCard);
+        // Card stays in hydration cache for re-use (no removeCard call)
 
         let failedItem: StudySessionFailedItem;
 
@@ -644,26 +565,25 @@ export class SessionController<TView = unknown> extends Loggable {
 
         this.failedQ.add(failedItem, failedItem.cardID);
       } else if (action === 'dismiss-error') {
-        // some error logging?
+        // Remove from cache on error as well
+        this.hydrationService.removeCard(this._currentCard.item.cardID);
       } else if (action === 'dismiss-failed') {
-        // handled by Study.vue
+        // Remove from cache - card has been fully processed after failure cleanup
+        this.hydrationService.removeCard(this._currentCard.item.cardID);
       }
     }
   }
 
-  private hasAvailableCards(): boolean {
-    return this.reviewQ.length > 0 || this.newQ.length > 0 || this.failedQ.length > 0;
-  }
-
   /**
-   * Helper method for CardHydrationService to remove items from appropriate queue.
+   * Remove an item from its source queue after consumption by nextCard().
    */
   private removeItemFromQueue(item: StudySessionItem): void {
-    if (this.reviewQ.peek(0) === item) {
+    // Check each queue - item should be at the front of one of them
+    if (this.reviewQ.peek(0)?.cardID === item.cardID) {
       this.reviewQ.dequeue((queueItem) => queueItem.cardID);
-    } else if (this.newQ.peek(0) === item) {
+    } else if (this.newQ.peek(0)?.cardID === item.cardID) {
       this.newQ.dequeue((queueItem) => queueItem.cardID);
-    } else {
+    } else if (this.failedQ.peek(0)?.cardID === item.cardID) {
       this.failedQ.dequeue((queueItem) => queueItem.cardID);
     }
   }

package/src/study/SourceMixer.ts

@@ -0,0 +1,65 @@
+import { WeightedCard } from '@db/core/navigators';
+
+/**
+ * Represents a batch of content fetched from a single StudyContentSource.
+ */
+export interface SourceBatch {
+  sourceIndex: number;
+  weighted: WeightedCard[];
+}
+
+/**
+ * Strategy interface for mixing content from multiple sources into a unified
+ * set of weighted candidates.
+ *
+ * Different implementations can provide different balancing strategies:
+ * - QuotaRoundRobinMixer: Equal representation per source
+ * - MinMaxNormalizingMixer: Score normalization then global sort
+ * - PercentileBucketMixer: Bucketed round-robin
+ * etc.
+ */
+export interface SourceMixer {
+  /**
+   * Mix weighted cards from multiple sources into a unified, ordered list.
+   *
+   * @param batches - Content batches from each source
+   * @param limit - Target number of cards to return
+   * @returns Mixed and ordered weighted cards
+   */
+  mix(batches: SourceBatch[], limit: number): WeightedCard[];
+}
+
+/**
+ * Simple quota-based mixer: allocates equal representation to each source,
+ * taking the top-N cards by score from each.
+ *
+ * Guarantees balanced representation across sources regardless of absolute
+ * score differences. A low-scoring source gets the same quota as a high-scoring
+ * source.
+ *
+ * This is the KISS approach - simple, predictable, and fair in terms of
+ * source representation (though not necessarily optimal in terms of absolute
+ * card quality).
+ */
+export class QuotaRoundRobinMixer implements SourceMixer {
+  mix(batches: SourceBatch[], limit: number): WeightedCard[] {
+    if (batches.length === 0) {
+      return [];
+    }
+
+    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);
+
+      // Take top quotaPerSource from this source
+      const topFromSource = sortedBatch.slice(0, quotaPerSource);
+      mixed.push(...topFromSource);
+    }
+
+    // Sort the mixed result by score descending and return up to limit
+    return mixed.sort((a, b) => b.score - a.score).slice(0, limit);
+  }
+}