@vue-skuilder/db 0.1.20 → 0.1.21

package/src/core/navigators/{relativePriority.ts → filters/relativePriority.ts}

@@ -1,11 +1,9 @@
-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 '..';
-import type { CardFilter, FilterContext } from './filters/types';
+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 { CardFilter, FilterContext } from './types';
 
 /**
  * Configuration for the RelativePriority strategy.
@@ -85,7 +83,6 @@ const DEFAULT_COMBINE_MODE: 'max' | 'average' | 'min' = 'max';
  */
 export default class RelativePriorityNavigator extends ContentNavigator implements CardFilter {
   private config: RelativePriorityConfig;
-  private _strategyData: ContentNavigationStrategyData;
 
   /** Human-readable name for CardFilter interface */
   name: string;
@@ -93,12 +90,11 @@ export default class RelativePriorityNavigator extends ContentNavigator implemen
   constructor(
     user: UserDBInterface,
     course: CourseDBInterface,
-    _strategyData: ContentNavigationStrategyData
+    strategyData: ContentNavigationStrategyData
   ) {
-    super(user, course, _strategyData);
-    this._strategyData = _strategyData;
-    this.config = this.parseConfig(_strategyData.serializedData);
-    this.name = _strategyData.name || 'Relative Priority';
+    super(user, course, strategyData);
+    this.config = this.parseConfig(strategyData.serializedData);
+    this.name = strategyData.name || 'Relative Priority';
   }
 
   private parseConfig(serializedData: string): RelativePriorityConfig {
@@ -242,14 +238,4 @@ export default class RelativePriorityNavigator extends ContentNavigator implemen
         'Use Pipeline with a generator and this filter via transform().'
     );
   }
-
-  // Legacy methods - stub implementations since filters don't generate cards
-
-  async getNewCards(_n?: number): Promise<StudySessionNewItem[]> {
-    return [];
-  }
-
-  async getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]> {
-    return [];
-  }
 }

package/src/core/navigators/filters/userTagPreference.ts

@@ -1,10 +1,8 @@
-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 '../..';
 import type { CardFilter, FilterContext } from './types';
 
 // ============================================================================
@@ -97,9 +95,7 @@ export default class UserTagPreferenceFilter extends ContentNavigator implements
    * Returns the maximum multiplier among all matching tags, or 1.0 if no matches.
    */
   private computeMultiplier(cardTags: string[], boostMap: Record<string, number>): number {
-    const multipliers = cardTags
-      .map((tag) => boostMap[tag])
-      .filter((val) => val !== undefined);
+    const multipliers = cardTags.map((tag) => boostMap[tag]).filter((val) => val !== undefined);
 
     if (multipliers.length === 0) {
       return 1.0;
@@ -150,7 +146,6 @@ export default class UserTagPreferenceFilter extends ContentNavigator implements
   async transform(cards: WeightedCard[], _context: FilterContext): Promise<WeightedCard[]> {
     // Read user preferences from strategy state
     const prefs = await this.getStrategyState<UserTagPreferenceState>();
-    
 
     // No preferences configured → pass through unchanged
     if (!prefs || Object.keys(prefs.boost).length === 0) {
@@ -219,14 +214,4 @@ export default class UserTagPreferenceFilter extends ContentNavigator implements
         'Use Pipeline with a generator and this filter via transform().'
     );
   }
-
-  // Legacy methods - stub implementations since filters don't generate cards
-
-  async getNewCards(_n?: number): Promise<StudySessionNewItem[]> {
-    return [];
-  }
-
-  async getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]> {
-    return [];
-  }
 }

package/src/core/navigators/{CompositeGenerator.ts → generators/CompositeGenerator.ts}

@@ -1,12 +1,10 @@
-import { ContentNavigator } from './index';
-import type { WeightedCard } from './index';
-import type { ContentNavigationStrategyData } from '../types/contentNavigationStrategy';
-import type { CourseDBInterface } from '../interfaces/courseDB';
-import type { UserDBInterface } from '../interfaces/userDB';
-import type { StudySessionNewItem, StudySessionReviewItem } from '../interfaces/contentSource';
-import type { ScheduledCard } from '../types/user';
-import type { CardGenerator, GeneratorContext } from './generators/types';
-import { logger } from '../../util/logger';
+import { ContentNavigator } from '../index';
+import type { WeightedCard } from '../index';
+import type { ContentNavigationStrategyData } from '../../types/contentNavigationStrategy';
+import type { CourseDBInterface } from '../../interfaces/courseDB';
+import type { UserDBInterface } from '../../interfaces/userDB';
+import type { CardGenerator, GeneratorContext } from './types';
+import { logger } from '../../../util/logger';
 
 // ============================================================================
 // COMPOSITE GENERATOR
@@ -100,9 +98,16 @@ export default class CompositeGenerator extends ContentNavigator implements Card
    * CardGenerator interface signature (limit, context).
    *
    * @param limit - Maximum number of cards to return
-   * @param context - Optional GeneratorContext passed to child generators
+   * @param context - GeneratorContext passed to child generators (required when called via Pipeline)
    */
   async getWeightedCards(limit: number, context?: GeneratorContext): Promise<WeightedCard[]> {
+    if (!context) {
+      throw new Error(
+        'CompositeGenerator.getWeightedCards requires a GeneratorContext. ' +
+          'It should be called via Pipeline, not directly.'
+      );
+    }
+
     // Fetch from all generators in parallel
     const results = await Promise.all(
       this.generators.map((g) => g.getWeightedCards(limit, context))
@@ -211,58 +216,4 @@ export default class CompositeGenerator extends ContentNavigator implements Card
         return scores[0];
     }
   }
-
-  /**
-   * Get new cards from all generators, merged and deduplicated.
-   */
-  async getNewCards(n?: number): Promise<StudySessionNewItem[]> {
-    // For legacy method, need to filter to generators that have getNewCards
-    const legacyGenerators = this.generators.filter(
-      (g): g is CardGenerator & ContentNavigator => g instanceof ContentNavigator
-    );
-
-    const results = await Promise.all(legacyGenerators.map((g) => g.getNewCards(n)));
-
-    // Deduplicate by cardID
-    const seen = new Set<string>();
-    const merged: StudySessionNewItem[] = [];
-
-    for (const cards of results) {
-      for (const card of cards) {
-        if (!seen.has(card.cardID)) {
-          seen.add(card.cardID);
-          merged.push(card);
-        }
-      }
-    }
-
-    return n ? merged.slice(0, n) : merged;
-  }
-
-  /**
-   * Get pending reviews from all generators, merged and deduplicated.
-   */
-  async getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]> {
-    // For legacy method, need to filter to generators that have getPendingReviews
-    const legacyGenerators = this.generators.filter(
-      (g): g is CardGenerator & ContentNavigator => g instanceof ContentNavigator
-    );
-
-    const results = await Promise.all(legacyGenerators.map((g) => g.getPendingReviews()));
-
-    // Deduplicate by cardID
-    const seen = new Set<string>();
-    const merged: (StudySessionReviewItem & ScheduledCard)[] = [];
-
-    for (const reviews of results) {
-      for (const review of reviews) {
-        if (!seen.has(review.cardID)) {
-          seen.add(review.cardID);
-          merged.push(review);
-        }
-      }
-    }
-
-    return merged;
-  }
 }

package/src/core/navigators/{elo.ts → generators/elo.ts}

@@ -1,12 +1,10 @@
-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 { CourseElo } from '@vue-skuilder/common';
+import type { CourseDBInterface } from '../../interfaces/courseDB';
+import type { UserDBInterface } from '../../interfaces/userDB';
+import { ContentNavigator } from '../index';
+import type { WeightedCard } from '../index';
 import { toCourseElo } from '@vue-skuilder/common';
-import type { StudySessionReviewItem, StudySessionNewItem, QualifiedCardID } from '..';
-import type { CardGenerator, GeneratorContext } from './generators/types';
+import type { QualifiedCardID } from '../..';
+import type { CardGenerator, GeneratorContext } from './types';
 
 // ============================================================================
 // ELO NAVIGATOR
@@ -51,59 +49,6 @@ export default class ELONavigator extends ContentNavigator implements CardGenera
     this.name = strategyData?.name || 'ELO';
   }
 
-  async getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]> {
-    type ratedReview = ScheduledCard & CourseElo;
-
-    const reviews = await this.user.getPendingReviews(this.course.getCourseID()); // todo: this adds a db round trip - should be server side
-    const elo = await this.course.getCardEloData(reviews.map((r) => r.cardId));
-
-    const ratedReviews = reviews.map((r, i) => {
-      const ratedR: ratedReview = {
-        ...r,
-        ...elo[i],
-      };
-      return ratedR;
-    });
-
-    ratedReviews.sort((a, b) => {
-      return a.global.score - b.global.score;
-    });
-
-    return ratedReviews.map((r) => {
-      return {
-        ...r,
-        contentSourceType: 'course',
-        contentSourceID: this.course.getCourseID(),
-        cardID: r.cardId,
-        courseID: r.courseId,
-        qualifiedID: `${r.courseId}-${r.cardId}`,
-        reviewID: r._id,
-        status: 'review',
-      };
-    });
-  }
-
-  async getNewCards(limit: number = 99): Promise<StudySessionNewItem[]> {
-    const activeCards = await this.user.getActiveCards();
-    return (
-      await this.course.getCardsCenteredAtELO(
-        { limit: limit, elo: 'user' },
-        (c: QualifiedCardID) => {
-          if (activeCards.some((ac) => c.cardID === ac.cardID)) {
-            return false;
-          } else {
-            return true;
-          }
-        }
-      )
-    ).map((c) => {
-      return {
-        ...c,
-        status: 'new',
-      };
-    });
-  }
-
   /**
    * Get new cards with suitability scores based on ELO distance.
    *
@@ -130,8 +75,13 @@ export default class ELONavigator extends ContentNavigator implements CardGenera
       userGlobalElo = userElo.global.score;
     }
 
-    // Get new cards (existing logic)
-    const newCards = await this.getNewCards(limit);
+    const activeCards = await this.user.getActiveCards();
+    const newCards = (
+      await this.course.getCardsCenteredAtELO(
+        { limit, elo: 'user' },
+        (c: QualifiedCardID) => !activeCards.some((ac) => c.cardID === ac.cardID)
+      )
+    ).map((c) => ({ ...c, status: 'new' as const }));
 
     // Get ELO data for all cards in one batch
     const cardIds = newCards.map((c) => c.cardID);

package/src/core/navigators/{srs.ts → generators/srs.ts}

@@ -1,12 +1,12 @@
 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';
+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 { CardGenerator, GeneratorContext } from './types';
+import { logger } from '@db/util/logger';
 
 // ============================================================================
 // SRS NAVIGATOR
@@ -95,6 +95,7 @@ export default class SRSNavigator extends ContentNavigator implements CardGenera
         cardId: review.cardId,
         courseId: review.courseId,
         score,
+        reviewID: review._id,
         provenance: [
           {
             strategy: 'srs',
@@ -108,6 +109,8 @@ export default class SRSNavigator extends ContentNavigator implements CardGenera
       };
     });
 
+    logger.debug(`[srsNav] got ${scored.length} weighted cards`);
+
     // Sort by score descending and limit
     return scored.sort((a, b) => b.score - a.score).slice(0, limit);
   }
@@ -160,36 +163,4 @@ export default class SRSNavigator extends ContentNavigator implements CardGenera
 
     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/core/navigators/generators/types.ts

@@ -9,7 +9,7 @@ import type { UserDBInterface } from '../../interfaces/userDB';
 // Generators produce candidate cards with initial scores.
 // They are the "source" stage of a navigation pipeline.
 //
-// Examples: ELO (skill proximity), SRS (review scheduling), HardcodedOrder
+// Examples: ELO (skill proximity), SRS (review scheduling)
 //
 // Generators differ from filters:
 // - Generators: produce candidates from DB queries, assign initial scores

package/src/core/navigators/index.ts

@@ -1,10 +1,4 @@
-import {
-  StudyContentSource,
-  UserDBInterface,
-  CourseDBInterface,
-  StudySessionReviewItem,
-  StudySessionNewItem,
-} from '..';
+import { StudyContentSource, UserDBInterface, CourseDBInterface } from '..';
 
 // Re-export filter types
 export type { CardFilter, FilterContext, CardFilterFactory } from './filters/types';
@@ -13,7 +7,6 @@ export type { CardFilter, FilterContext, CardFilterFactory } from './filters/typ
 export type { CardGenerator, GeneratorContext, CardGeneratorFactory } from './generators/types';
 
 import { ContentNavigationStrategyData } from '../types/contentNavigationStrategy';
-import { ScheduledCard } from '../types/user';
 import { logger } from '../../util/logger';
 
 // ============================================================================
@@ -33,7 +26,7 @@ import { logger } from '../../util/logger';
 //    New code should use CardGenerator or CardFilter interfaces directly.
 //
 // 3. CardGenerator vs CardFilter:
-//    - Generators (ELO, SRS, HardcodedOrder) produce candidate cards with scores
+//    - Generators (ELO, SRS) produce candidate cards with scores
 //    - Filters (Hierarchy, Interference, Priority, EloDistance) transform scores
 //
 // 4. Pipeline architecture:
@@ -142,6 +135,12 @@ export interface WeightedCard {
    * Filters should use this instead of querying getAppliedTags() individually.
    */
   tags?: string[];
+  /**
+   * Review document ID (_id from ScheduledCard).
+   * Present when this card originated from SRS review scheduling.
+   * Used by SessionController to track review outcomes and maintain review state.
+   */
+  reviewID?: string;
 }
 
 /**
@@ -174,7 +173,6 @@ export function getCardOrigin(card: WeightedCard): 'new' | 'review' | 'failed' {
 export enum Navigators {
   ELO = 'elo',
   SRS = 'srs',
-  HARDCODED = 'hardcodedOrder',
   HIERARCHY = 'hierarchyDefinition',
   INTERFERENCE = 'interferenceMitigator',
   RELATIVE_PRIORITY = 'relativePriority',
@@ -186,7 +184,7 @@ export enum Navigators {
 // ============================================================================
 //
 // Navigators are classified as either generators or filters:
-// - Generators: Produce candidate cards (ELO, SRS, HardcodedOrder)
+// - Generators: Produce candidate cards (ELO, SRS)
 // - Filters: Transform/score candidates (Hierarchy, Interference, RelativePriority)
 //
 // This classification is used by PipelineAssembler to build pipelines:
@@ -213,7 +211,6 @@ export enum NavigatorRole {
 export const NavigatorRoles: Record<Navigators, NavigatorRole> = {
   [Navigators.ELO]: NavigatorRole.GENERATOR,
   [Navigators.SRS]: NavigatorRole.GENERATOR,
-  [Navigators.HARDCODED]: NavigatorRole.GENERATOR,
   [Navigators.HIERARCHY]: NavigatorRole.FILTER,
   [Navigators.INTERFERENCE]: NavigatorRole.FILTER,
   [Navigators.RELATIVE_PRIORITY]: NavigatorRole.FILTER,
@@ -252,10 +249,10 @@ export function isFilter(impl: string): boolean {
  */
 export abstract class ContentNavigator implements StudyContentSource {
   /** User interface for this navigation session */
-  protected user?: UserDBInterface;
+  protected user: UserDBInterface;
 
   /** Course interface for this navigation session */
-  protected course?: CourseDBInterface;
+  protected course: CourseDBInterface;
 
   /** Human-readable name for this strategy instance (from ContentNavigationStrategyData.name) */
   protected strategyName?: string;
@@ -267,16 +264,17 @@ export abstract class ContentNavigator implements StudyContentSource {
    * Constructor for standard navigators.
    * Call this from subclass constructors to initialize common fields.
    *
-   * Note: CompositeGenerator doesn't use this pattern and should call super() without args.
+   * Note: CompositeGenerator and Pipeline call super() without args, then set
+   * user/course fields directly if needed.
    */
   constructor(
     user?: UserDBInterface,
     course?: CourseDBInterface,
     strategyData?: ContentNavigationStrategyData
   ) {
-    if (user && course && strategyData) {
-      this.user = user;
-      this.course = course;
+    this.user = user!;
+    this.course = course!;
+    if (strategyData) {
       this.strategyName = strategyData.name;
       this.strategyId = strategyData._id;
     }
@@ -352,15 +350,19 @@ export abstract class ContentNavigator implements StudyContentSource {
 
     // Try different extension variations
     const variations = ['.ts', '.js', ''];
+    const dirs = ['filters', 'generators'];
 
     for (const ext of variations) {
-      try {
-        const module = await import(`./${implementingClass}${ext}`);
-        NavigatorImpl = module.default;
-        break; // Break the loop if loading succeeds
-      } catch (e) {
-        // Continue to next variation if this one fails
-        logger.debug(`Failed to load with extension ${ext}:`, e);
+      for (const dir of dirs) {
+        const loadFrom = `./${dir}/${implementingClass}${ext}`;
+        try {
+          const module = await import(loadFrom);
+          NavigatorImpl = module.default;
+          break; // Break the loop if loading succeeds
+        } catch (e) {
+          // Continue to next variation if this one fails
+          logger.debug(`Failed to load extension from ${loadFrom}:`, e);
+        }
       }
     }
 
@@ -371,24 +373,6 @@ export abstract class ContentNavigator implements StudyContentSource {
     return new NavigatorImpl(user, course, strategyData);
   }
 
-  /**
-   * Get cards scheduled for review.
-   *
-   * @deprecated This method is part of the legacy StudyContentSource interface.
-   * New strategies should focus on implementing CardGenerator.getWeightedCards() instead.
-   */
-  abstract getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]>;
-
-  /**
-   * Get new cards for introduction.
-   *
-   * @deprecated This method is part of the legacy StudyContentSource interface.
-   * New strategies should focus on implementing CardGenerator.getWeightedCards() instead.
-   *
-   * @param n - Maximum number of new cards to return
-   */
-  abstract getNewCards(n?: number): Promise<StudySessionNewItem[]>;
-
   /**
    * Get cards with suitability scores and provenance trails.
    *
@@ -398,62 +382,23 @@ export abstract class ContentNavigator implements StudyContentSource {
    * better candidates for presentation. Each card includes a provenance trail
    * documenting how strategies contributed to the final score.
    *
+   * ## Implementation Required
+   * All navigation strategies MUST override this method. The base class does
+   * not provide a default implementation.
+   *
    * ## For Generators
    * Override this method to generate candidates and compute scores based on
    * your strategy's logic (e.g., ELO proximity, review urgency). Create the
    * initial provenance entry with action='generated'.
    *
-   * ## Default Implementation
-   * The base class provides a backward-compatible default that:
-   * 1. Calls legacy getNewCards() and getPendingReviews()
-   * 2. Assigns score=1.0 to all cards
-   * 3. Creates minimal provenance from legacy methods
-   * 4. Returns combined results up to limit
-   *
-   * This allows existing strategies to work without modification while
-   * new strategies can override with proper scoring and provenance.
+   * ## For Filters
+   * Filters should implement the CardFilter interface instead and be composed
+   * via Pipeline. Filters do not directly implement getWeightedCards().
    *
    * @param limit - Maximum cards to return
    * @returns Cards sorted by score descending, with provenance trails
    */
-  async getWeightedCards(limit: number): Promise<WeightedCard[]> {
-    // Default implementation: delegate to legacy methods, assign score=1.0
-    const newCards = await this.getNewCards(limit);
-    const reviews = await this.getPendingReviews();
-
-    const weighted: WeightedCard[] = [
-      ...newCards.map((c) => ({
-        cardId: c.cardID,
-        courseId: c.courseID,
-        score: 1.0,
-        provenance: [
-          {
-            strategy: 'legacy',
-            strategyName: this.strategyName || 'Legacy API',
-            strategyId: this.strategyId || 'legacy-fallback',
-            action: 'generated' as const,
-            score: 1.0,
-            reason: 'Generated via legacy getNewCards(), new card',
-          },
-        ],
-      })),
-      ...reviews.map((r) => ({
-        cardId: r.cardID,
-        courseId: r.courseID,
-        score: 1.0,
-        provenance: [
-          {
-            strategy: 'legacy',
-            strategyName: this.strategyName || 'Legacy API',
-            strategyId: this.strategyId || 'legacy-fallback',
-            action: 'generated' as const,
-            score: 1.0,
-            reason: 'Generated via legacy getPendingReviews(), review',
-          },
-        ],
-      })),
-    ];
-
-    return weighted.slice(0, limit);
+  async getWeightedCards(_limit: number): Promise<WeightedCard[]> {
+    throw new Error(`${this.constructor.name} must implement getWeightedCards(). `);
   }
 }