@vue-skuilder/db 0.1.17 → 0.1.18

package/src/core/navigators/srs.ts

@@ -0,0 +1,195 @@
+import moment from 'moment';
+import type { ScheduledCard } from '../types/user';
+import type { CourseDBInterface } from '../interfaces/courseDB';
+import type { UserDBInterface } from '../interfaces/userDB';
+import { ContentNavigator } from './index';
+import type { WeightedCard } from './index';
+import type { ContentNavigationStrategyData } from '../types/contentNavigationStrategy';
+import type { StudySessionReviewItem, StudySessionNewItem } from '../interfaces/contentSource';
+import type { CardGenerator, GeneratorContext } from './generators/types';
+
+// ============================================================================
+// SRS NAVIGATOR
+// ============================================================================
+//
+// A generator strategy that scores review cards by urgency.
+//
+// Urgency is determined by two factors:
+// 1. Overdueness - how far past the scheduled review time
+// 2. Interval recency - shorter scheduled intervals indicate "novel content in progress"
+//
+// A card with a 3-day interval that's 2 days overdue is more urgent than a card
+// with a 6-month interval that's 2 days overdue. The shorter interval represents
+// active learning at higher resolution.
+//
+// This navigator only handles reviews - it does not generate new cards.
+// For new cards, use ELONavigator or another generator via CompositeGenerator.
+//
+// ============================================================================
+
+/**
+ * Configuration for the SRS strategy.
+ * Currently minimal - the algorithm is not parameterized.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface SRSConfig {
+  // Future: configurable urgency curves, thresholds, etc.
+}
+
+/**
+ * A navigation strategy that scores review cards by urgency.
+ *
+ * Implements CardGenerator for use in Pipeline architecture.
+ * Also extends ContentNavigator for backward compatibility with legacy code.
+ *
+ * Higher scores indicate more urgent reviews:
+ * - Cards that are more overdue (relative to their interval) score higher
+ * - Cards with shorter intervals (recent learning) score higher
+ *
+ * Only returns cards that are actually due (reviewTime has passed).
+ * Does not generate new cards - use with CompositeGenerator for mixed content.
+ */
+export default class SRSNavigator extends ContentNavigator implements CardGenerator {
+  /** Human-readable name for CardGenerator interface */
+  name: string;
+
+  constructor(
+    user: UserDBInterface,
+    course: CourseDBInterface,
+    strategyData?: ContentNavigationStrategyData
+  ) {
+    super(user, course, strategyData as ContentNavigationStrategyData);
+    this.name = strategyData?.name || 'SRS';
+  }
+
+  /**
+   * Get review cards scored by urgency.
+   *
+   * Score formula combines:
+   * - Relative overdueness: hoursOverdue / intervalHours
+   * - Interval recency: exponential decay favoring shorter intervals
+   *
+   * Cards not yet due are excluded (not scored as 0).
+   *
+   * This method supports both the legacy signature (limit only) and the
+   * CardGenerator interface signature (limit, context).
+   *
+   * @param limit - Maximum number of cards to return
+   * @param _context - Optional GeneratorContext (currently unused, but required for interface)
+   */
+  async getWeightedCards(limit: number, _context?: GeneratorContext): Promise<WeightedCard[]> {
+    if (!this.user || !this.course) {
+      throw new Error('SRSNavigator requires user and course to be set');
+    }
+
+    const reviews = await this.user.getPendingReviews(this.course.getCourseID());
+    const now = moment.utc();
+
+    // Filter to only cards that are actually due
+    const dueReviews = reviews.filter((r) => now.isAfter(moment.utc(r.reviewTime)));
+
+    const scored = dueReviews.map((review) => {
+      const { score, reason } = this.computeUrgencyScore(review, now);
+
+      return {
+        cardId: review.cardId,
+        courseId: review.courseId,
+        score,
+        provenance: [
+          {
+            strategy: 'srs',
+            strategyName: this.strategyName || this.name,
+            strategyId: this.strategyId || 'NAVIGATION_STRATEGY-SRS-default',
+            action: 'generated' as const,
+            score,
+            reason,
+          },
+        ],
+      };
+    });
+
+    // Sort by score descending and limit
+    return scored.sort((a, b) => b.score - a.score).slice(0, limit);
+  }
+
+  /**
+   * Compute urgency score for a review card.
+   *
+   * Two factors:
+   * 1. Relative overdueness = hoursOverdue / intervalHours
+   *    - 2 days overdue on 3-day interval = 0.67 (urgent)
+   *    - 2 days overdue on 180-day interval = 0.01 (not urgent)
+   *
+   * 2. Interval recency factor = 0.3 + 0.7 * exp(-intervalHours / 720)
+   *    - 24h interval → ~1.0 (very recent learning)
+   *    - 30 days (720h) → ~0.56
+   *    - 180 days → ~0.30
+   *
+   * Combined: base 0.5 + weighted average of factors * 0.45
+   * Result range: approximately 0.5 to 0.95
+   */
+  private computeUrgencyScore(
+    review: ScheduledCard,
+    now: moment.Moment
+  ): { score: number; reason: string } {
+    const scheduledAt = moment.utc(review.scheduledAt);
+    const due = moment.utc(review.reviewTime);
+
+    // Interval = time between scheduling and due date (minimum 1 hour to avoid division issues)
+    const intervalHours = Math.max(1, due.diff(scheduledAt, 'hours'));
+    const hoursOverdue = now.diff(due, 'hours');
+
+    // Relative overdueness: how late relative to the interval
+    const relativeOverdue = hoursOverdue / intervalHours;
+
+    // Interval recency factor: shorter intervals = more urgent
+    // Exponential decay with 720h (30 days) as the characteristic time
+    const recencyFactor = 0.3 + 0.7 * Math.exp(-intervalHours / 720);
+
+    // Combined urgency: weighted average of relative overdue and recency
+    // Clamp relative overdue contribution to [0, 1] to avoid runaway scores
+    const overdueContribution = Math.min(1.0, Math.max(0, relativeOverdue));
+    const urgency = overdueContribution * 0.5 + recencyFactor * 0.5;
+
+    // Final score: base 0.5 + urgency contribution, capped at 0.95
+    const score = Math.min(0.95, 0.5 + urgency * 0.45);
+
+    const reason =
+      `${Math.round(hoursOverdue)}h overdue (interval: ${Math.round(intervalHours)}h, ` +
+      `relative: ${relativeOverdue.toFixed(2)}), recency: ${recencyFactor.toFixed(2)}, review`;
+
+    return { score, reason };
+  }
+
+  /**
+   * Get pending reviews in legacy format.
+   *
+   * Returns all pending reviews for the course, enriched with session item fields.
+   */
+  async getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]> {
+    if (!this.user || !this.course) {
+      throw new Error('SRSNavigator requires user and course to be set');
+    }
+
+    const reviews = await this.user.getPendingReviews(this.course.getCourseID());
+
+    return reviews.map((r) => ({
+      ...r,
+      contentSourceType: 'course' as const,
+      contentSourceID: this.course!.getCourseID(),
+      cardID: r.cardId,
+      courseID: r.courseId,
+      qualifiedID: `${r.courseId}-${r.cardId}`,
+      reviewID: r._id,
+      status: 'review' as const,
+    }));
+  }
+
+  /**
+   * SRS does not generate new cards.
+   * Use ELONavigator or another generator for new cards.
+   */
+  async getNewCards(_n?: number): Promise<StudySessionNewItem[]> {
+    return [];
+  }
+}

package/src/impl/couch/classroomDB.ts

@@ -3,6 +3,7 @@ import {
   StudySessionNewItem,
   StudySessionReviewItem,
 } from '@db/core/interfaces/contentSource';
+import { WeightedCard } from '@db/core/navigators';
 import { ClassroomConfig } from '@vue-skuilder/common';
 import { ENV } from '@db/factory';
 import { logger } from '@db/util/logger';
@@ -189,6 +190,56 @@ export class StudentClassroomDB
       }
     });
   }
+
+  /**
+   * Get cards with suitability scores for presentation.
+   *
+   * This implementation wraps the legacy getNewCards/getPendingReviews methods,
+   * assigning score=1.0 to all cards. StudentClassroomDB does not currently
+   * support pluggable navigation strategies.
+   *
+   * @param limit - Maximum number of cards to return
+   * @returns Cards sorted by score descending (all scores = 1.0)
+   */
+  public async getWeightedCards(limit: number): Promise<WeightedCard[]> {
+    const [newCards, reviews] = await Promise.all([this.getNewCards(), this.getPendingReviews()]);
+
+    const weighted: WeightedCard[] = [
+      ...newCards.map((c) => ({
+        cardId: c.cardID,
+        courseId: c.courseID,
+        score: 1.0,
+        provenance: [
+          {
+            strategy: 'classroom',
+            strategyName: 'Classroom',
+            strategyId: 'CLASSROOM',
+            action: 'generated' as const,
+            score: 1.0,
+            reason: 'Classroom legacy getNewCards(), new card',
+          },
+        ],
+      })),
+      ...reviews.map((r) => ({
+        cardId: r.cardID,
+        courseId: r.courseID,
+        score: 1.0,
+        provenance: [
+          {
+            strategy: 'classroom',
+            strategyName: 'Classroom',
+            strategyId: 'CLASSROOM',
+            action: 'generated' as const,
+            score: 1.0,
+            reason: 'Classroom legacy getPendingReviews(), review',
+          },
+        ],
+      })),
+    ];
+
+    // Sort by score descending (all 1.0 in this case) and limit
+    return weighted.slice(0, limit);
+  }
 }
 
 /**

package/src/impl/couch/courseDB.ts

@@ -34,7 +34,13 @@ import { DataLayerResult } from '@db/core/types/db';
 import { PouchError } from './types';
 import CourseLookup from './courseLookupDB';
 import { ContentNavigationStrategyData } from '@db/core/types/contentNavigationStrategy';
-import { ContentNavigator, Navigators } from '@db/core/navigators';
+import { ContentNavigator, Navigators, WeightedCard } from '@db/core/navigators';
+import { Pipeline } from '@db/core/navigators/Pipeline';
+import { PipelineAssembler } from '@db/core/navigators/PipelineAssembler';
+import CompositeGenerator from '@db/core/navigators/CompositeGenerator';
+import ELONavigator from '@db/core/navigators/elo';
+import SRSNavigator from '@db/core/navigators/srs';
+import { createEloDistanceFilter } from '@db/core/navigators/filters/eloDistance';
 
 export class CoursesDB implements CoursesDBInterface {
   _courseIDs: string[] | undefined;
@@ -225,7 +231,7 @@ export class CourseDB implements StudyContentSource, CourseDBInterface {
     if (!doc.docType || !(doc.docType === DocType.CARD)) {
       throw new Error(`failed to remove ${id} from course ${this.id}. id does not point to a card`);
     }
-    
+
     // Remove card from all associated tags before deleting the card
     try {
       const appliedTags = await this.getAppliedTags(id);
@@ -235,7 +241,7 @@ export class CourseDB implements StudyContentSource, CourseDBInterface {
           await this.removeTagFromCard(id, tagId);
         })
       );
-      
+
       // Log any individual tag cleanup failures
       results.forEach((result, index) => {
         if (result.status === 'rejected') {
@@ -247,7 +253,7 @@ export class CourseDB implements StudyContentSource, CourseDBInterface {
       logger.error(`Error removing card ${id} from tags: ${error}`);
       // Continue with card deletion even if tag cleanup fails
     }
-    
+
     return this.db.remove(doc);
   }
 
@@ -519,44 +525,97 @@ above:\n${above.rows.map((r) => `\t${r.id}-${r.key}\n`)}`;
     return Promise.resolve();
   }
 
-  async surfaceNavigationStrategy(): Promise<ContentNavigationStrategyData> {
+  /**
+   * Creates an instantiated navigator for this course.
+   *
+   * Handles multiple generators by wrapping them in CompositeGenerator.
+   * This is the preferred method for getting a ready-to-use navigator.
+   *
+   * @param user - User database interface
+   * @returns Instantiated ContentNavigator ready for use
+   */
+  async createNavigator(user: UserDBInterface): Promise<ContentNavigator> {
     try {
-      const config = await this.getCourseConfig();
-      // @ts-expect-error tmp: defaultNavigationStrategyId property does not yet exist
-      if (config.defaultNavigationStrategyId) {
-        try {
-          // @ts-expect-error tmp: defaultNavigationStrategyId property does not yet exist
-          const strategy = await this.getNavigationStrategy(config.defaultNavigationStrategyId);
-          if (strategy) {
-            logger.debug(`Surfacing strategy ${strategy.name} from course config`);
-            return strategy;
-          }
-        } catch (e) {
-          logger.warn(
-            // @ts-expect-error tmp: defaultNavigationStrategyId property does not yet exist
-            `Failed to load strategy '${config.defaultNavigationStrategyId}' specified in course config. Falling back to ELO.`,
-            e
-          );
-        }
+      const allStrategies = await this.getAllNavigationStrategies();
+
+      if (allStrategies.length === 0) {
+        // No strategies configured: use default Pipeline(Composite(ELO, SRS), [eloDistanceFilter])
+        logger.debug(
+          '[courseDB] No strategy documents found, using default Pipeline(Composite(ELO, SRS), [eloDistanceFilter])'
+        );
+        return this.createDefaultPipeline(user);
       }
-    } catch (e) {
-      logger.warn(
-        'Could not retrieve course config to determine navigation strategy. Falling back to ELO.',
-        e
+
+      // Use PipelineAssembler to build a Pipeline from strategy documents
+      const assembler = new PipelineAssembler();
+      const { pipeline, generatorStrategies, filterStrategies, warnings } =
+        await assembler.assemble({
+          strategies: allStrategies,
+          user,
+          course: this,
+        });
+
+      // Log any warnings from assembly
+      for (const warning of warnings) {
+        logger.warn(`[PipelineAssembler] ${warning}`);
+      }
+
+      if (!pipeline) {
+        // Assembly failed - fall back to default
+        logger.debug('[courseDB] Pipeline assembly failed, using default pipeline');
+        return this.createDefaultPipeline(user);
+      }
+
+      logger.debug(
+        `[courseDB] Using assembled pipeline with ${generatorStrategies.length} generator(s) and ${filterStrategies.length} filter(s)`
       );
+      return pipeline;
+    } catch (e) {
+      logger.error(`[courseDB] Error creating navigator: ${e}`);
+      throw e;
     }
+  }
 
-    logger.warn(`Returning hard-coded default ELO navigator`);
-    const ret: ContentNavigationStrategyData = {
-      _id: 'NAVIGATION_STRATEGY-ELO',
+  private makeDefaultEloStrategy(): ContentNavigationStrategyData {
+    return {
+      _id: 'NAVIGATION_STRATEGY-ELO-default',
       docType: DocType.NAVIGATION_STRATEGY,
-      name: 'ELO',
-      description: 'ELO-based navigation strategy',
+      name: 'ELO (default)',
+      description: 'Default ELO-based navigation strategy for new cards',
       implementingClass: Navigators.ELO,
       course: this.id,
-      serializedData: '', // serde is a noop for ELO navigator.
+      serializedData: '',
     };
-    return Promise.resolve(ret);
+  }
+
+  private makeDefaultSrsStrategy(): ContentNavigationStrategyData {
+    return {
+      _id: 'NAVIGATION_STRATEGY-SRS-default',
+      docType: DocType.NAVIGATION_STRATEGY,
+      name: 'SRS (default)',
+      description: 'Default SRS-based navigation strategy for reviews',
+      implementingClass: Navigators.SRS,
+      course: this.id,
+      serializedData: '',
+    };
+  }
+
+  /**
+   * Creates the default navigation pipeline for courses with no configured strategies.
+   *
+   * Default: Pipeline(Composite(ELO, SRS), [eloDistanceFilter])
+   * - ELO generator: scores new cards by skill proximity
+   * - SRS generator: scores reviews by overdueness and interval recency
+   * - ELO distance filter: penalizes cards far from user's current level
+   */
+  private createDefaultPipeline(user: UserDBInterface): Pipeline {
+    const eloNavigator = new ELONavigator(user, this, this.makeDefaultEloStrategy());
+    const srsNavigator = new SRSNavigator(user, this, this.makeDefaultSrsStrategy());
+
+    const compositeGenerator = new CompositeGenerator([eloNavigator, srsNavigator]);
+    const eloDistanceFilter = createEloDistanceFilter();
+
+    return new Pipeline(compositeGenerator, [eloDistanceFilter], user, this);
   }
 
   ////////////////////////////////////
@@ -571,11 +630,10 @@ above:\n${above.rows.map((r) => `\t${r.id}-${r.key}\n`)}`;
     const u = await this._getCurrentUser();
 
     try {
-      const strategy = await this.surfaceNavigationStrategy();
-      const navigator = await ContentNavigator.create(u, this, strategy);
+      const navigator = await this.createNavigator(u);
       return navigator.getNewCards(limit);
     } catch (e) {
-      logger.error(`[courseDB] Error surfacing a NavigationStrategy: ${e}`);
+      logger.error(`[courseDB] Error in getNewCards: ${e}`);
       throw e;
     }
   }
@@ -584,11 +642,31 @@ above:\n${above.rows.map((r) => `\t${r.id}-${r.key}\n`)}`;
     const u = await this._getCurrentUser();
 
     try {
-      const strategy = await this.surfaceNavigationStrategy();
-      const navigator = await ContentNavigator.create(u, this, strategy);
+      const navigator = await this.createNavigator(u);
       return navigator.getPendingReviews();
     } catch (e) {
-      logger.error(`[courseDB] Error surfacing a NavigationStrategy: ${e}`);
+      logger.error(`[courseDB] Error in getPendingReviews: ${e}`);
+      throw e;
+    }
+  }
+
+  /**
+   * Get cards with suitability scores for presentation.
+   *
+   * This is the PRIMARY API for content sources going forward. Delegates to the
+   * course's configured NavigationStrategy to get scored candidates.
+   *
+   * @param limit - Maximum number of cards to return
+   * @returns Cards sorted by score descending
+   */
+  public async getWeightedCards(limit: number): Promise<WeightedCard[]> {
+    const u = await this._getCurrentUser();
+
+    try {
+      const navigator = await this.createNavigator(u);
+      return navigator.getWeightedCards(limit);
+    } catch (e) {
+      logger.error(`[courseDB] Error getting weighted cards: ${e}`);
       throw e;
     }
   }

package/src/impl/static/courseDB.ts

@@ -391,10 +391,6 @@ export class StaticCourseDB implements CourseDBInterface {
     throw new Error('Cannot update navigation strategies in static mode');
   }
 
-  async surfaceNavigationStrategy(): Promise<ContentNavigationStrategyData> {
-    return this.getNavigationStrategy('ELO');
-  }
-
   // Study Content Source implementation
   async getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]> {
     // In static mode, reviews would be stored locally

package/src/study/SessionController.ts

@@ -15,6 +15,7 @@ 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;
@@ -181,7 +182,15 @@ export class SessionController<TView = unknown> extends Loggable {
 
   public async prepareSession() {
     try {
-      await Promise.all([this.getScheduledReviews(), this.getNewCards()]);
+      // 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);
     }
@@ -213,6 +222,11 @@ export class SessionController<TView = unknown> extends Loggable {
    * Used by SessionControllerDebug component for runtime inspection.
    */
   public getDebugInfo() {
+    // Check if sources support weighted cards
+    const supportsWeightedCards = this.sources.some(
+      (s) => typeof s.getWeightedCards === 'function'
+    );
+
     const extractQueueItems = (queue: ItemQueue<any>, limit: number = 10) => {
       const items = [];
       for (let i = 0; i < Math.min(queue.length, limit); i++) {
@@ -235,6 +249,12 @@ export class SessionController<TView = unknown> extends Loggable {
     };
 
     return {
+      api: {
+        mode: supportsWeightedCards ? 'weighted' : 'legacy',
+        description: supportsWeightedCards
+          ? 'Using getWeightedCards() API with scored candidates'
+          : 'Using legacy getNewCards()/getPendingReviews() API',
+      },
       reviewQueue: {
         length: this.reviewQ.length,
         dequeueCount: this.reviewQ.dequeueCount,
@@ -258,6 +278,130 @@ export class SessionController<TView = unknown> extends Loggable {
     };
   }
 
+  /**
+   * 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.
+   *
+   * 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
+   */
+  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[] = [];
+
+    for (const source of this.sources) {
+      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 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',
+                },
+              ],
+            }))
+          );
+        }
+      } catch (error) {
+        this.error(`Failed to get content from source:`, error);
+      }
+    }
+
+    // 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);
+    }
+
+    // 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`;
+    }
+
+    // Get new cards from weighted list (filter out reviews)
+    const newCardWeighted = allWeighted
+      .filter((w) => getCardOrigin(w) === 'new')
+      .sort((a, b) => b.score - a.score);
+
+    // Add new cards to queue in score order
+    for (const card of newCardWeighted) {
+      const newItem: StudySessionNewItem = {
+        cardID: card.cardId,
+        courseID: card.courseId,
+        contentSourceType: 'course',
+        contentSourceID: card.courseId,
+        status: 'new',
+      };
+      this.newQ.add(newItem, card.cardId);
+      report += `New: ${card.courseId}::${card.cardId} (score: ${card.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().
+   */
   private async getScheduledReviews() {
     const reviews = await Promise.all(
       this.sources.map((c) =>
@@ -289,6 +433,10 @@ export class SessionController<TView = unknown> extends Loggable {
     this.log(report);
   }
 
+  /**
+   * @deprecated Use getWeightedContent() instead. This method is kept for backward
+   * compatibility with sources that don't support getWeightedCards().
+   */
   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)));