@vue-skuilder/db 0.1.17 → 0.1.20

package/src/core/navigators/hierarchyDefinition.ts

@@ -0,0 +1,266 @@
+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 { toCourseElo } from '@vue-skuilder/common';
+
+/**
+ * A single prerequisite requirement for a tag.
+ * Each prerequisite refers to one tag with its own mastery threshold.
+ */
+interface TagPrerequisite {
+  /** The tag that must be mastered */
+  tag: string;
+  /** Thresholds for considering this prerequisite tag "mastered" */
+  masteryThreshold?: {
+    /** Minimum ELO score for mastery. If not set, uses avgElo comparison */
+    minElo?: number;
+    /** Minimum interaction count (default: 3) */
+    minCount?: number;
+  };
+}
+
+/**
+ * Configuration for the HierarchyDefinition strategy
+ */
+export interface HierarchyConfig {
+  /** Map of tag ID to its list of prerequisites (each with individual thresholds) */
+  prerequisites: {
+    [tagId: string]: TagPrerequisite[];
+  };
+}
+
+const DEFAULT_MIN_COUNT = 3;
+
+/**
+ * A filter strategy that gates cards based on prerequisite mastery.
+ *
+ * Cards are locked until the user masters all prerequisite tags.
+ * Locked cards receive score: 0 (hard filter).
+ *
+ * Mastery is determined by:
+ * - User's ELO for the tag exceeds threshold (or avgElo if not specified)
+ * - User has minimum interaction count with the tag
+ *
+ * Tags with no prerequisites are always unlocked.
+ *
+ * Implements CardFilter for use in Pipeline architecture.
+ * Also extends ContentNavigator for backward compatibility.
+ */
+export default class HierarchyDefinitionNavigator extends ContentNavigator implements CardFilter {
+  private config: HierarchyConfig;
+  private _strategyData: ContentNavigationStrategyData;
+
+  /** Human-readable name for CardFilter interface */
+  name: string;
+
+  constructor(
+    user: UserDBInterface,
+    course: CourseDBInterface,
+    _strategyData: ContentNavigationStrategyData
+  ) {
+    super(user, course, _strategyData);
+    this._strategyData = _strategyData;
+    this.config = this.parseConfig(_strategyData.serializedData);
+    this.name = _strategyData.name || 'Hierarchy Definition';
+  }
+
+  private parseConfig(serializedData: string): HierarchyConfig {
+    try {
+      const parsed = JSON.parse(serializedData);
+      return {
+        prerequisites: parsed.prerequisites || {},
+      };
+    } catch {
+      // Return safe defaults if parsing fails
+      return {
+        prerequisites: {},
+      };
+    }
+  }
+
+  /**
+   * Check if a specific prerequisite is satisfied
+   */
+  private isPrerequisiteMet(
+    prereq: TagPrerequisite,
+    userTagElo: { score: number; count: number } | undefined,
+    userGlobalElo: number
+  ): boolean {
+    if (!userTagElo) return false;
+
+    const minCount = prereq.masteryThreshold?.minCount ?? DEFAULT_MIN_COUNT;
+    if (userTagElo.count < minCount) return false;
+
+    if (prereq.masteryThreshold?.minElo !== undefined) {
+      return userTagElo.score >= prereq.masteryThreshold.minElo;
+    } else {
+      // Default: user ELO for tag > global user ELO (proxy for "above average")
+      return userTagElo.score >= userGlobalElo;
+    }
+  }
+
+  /**
+   * Get the set of tags the user has mastered.
+   * A tag is "mastered" if it appears as a prerequisite somewhere and meets its threshold.
+   */
+  private async getMasteredTags(context: FilterContext): Promise<Set<string>> {
+    const mastered = new Set<string>();
+
+    try {
+      const courseReg = await context.user.getCourseRegDoc(context.course.getCourseID());
+      const userElo = toCourseElo(courseReg.elo);
+
+      // Collect all unique prerequisite tags and check mastery for each
+      for (const prereqs of Object.values(this.config.prerequisites)) {
+        for (const prereq of prereqs) {
+          const tagElo = userElo.tags[prereq.tag];
+          if (this.isPrerequisiteMet(prereq, tagElo, userElo.global.score)) {
+            mastered.add(prereq.tag);
+          }
+        }
+      }
+    } catch {
+      // If we can't get user data, return empty set (no tags mastered)
+    }
+
+    return mastered;
+  }
+
+  /**
+   * Get the set of tags that are unlocked (prerequisites met)
+   */
+  private getUnlockedTags(masteredTags: Set<string>): Set<string> {
+    const unlocked = new Set<string>();
+
+    for (const [tagId, prereqs] of Object.entries(this.config.prerequisites)) {
+      const allPrereqsMet = prereqs.every((prereq) => masteredTags.has(prereq.tag));
+      if (allPrereqsMet) {
+        unlocked.add(tagId);
+      }
+    }
+
+    return unlocked;
+  }
+
+  /**
+   * Check if a tag has prerequisites defined in config
+   */
+  private hasPrerequisites(tagId: string): boolean {
+    return tagId in this.config.prerequisites;
+  }
+
+  /**
+   * Check if a card is unlocked and generate reason.
+   */
+  private async checkCardUnlock(
+    card: WeightedCard,
+    course: CourseDBInterface,
+    unlockedTags: Set<string>,
+    masteredTags: Set<string>
+  ): Promise<{ isUnlocked: boolean; reason: string }> {
+    try {
+      // Pipeline hydrates tags before filters run
+      const cardTags = card.tags ?? [];
+
+      // Check each tag's prerequisite status
+      const lockedTags = cardTags.filter(
+        (tag) => this.hasPrerequisites(tag) && !unlockedTags.has(tag)
+      );
+
+      if (lockedTags.length === 0) {
+        const tagList = cardTags.length > 0 ? cardTags.join(', ') : 'none';
+        return {
+          isUnlocked: true,
+          reason: `Prerequisites met, tags: ${tagList}`,
+        };
+      }
+
+      // Find missing prerequisites for locked tags
+      const missingPrereqs = lockedTags.flatMap((tag) => {
+        const prereqs = this.config.prerequisites[tag] || [];
+        return prereqs.filter((p) => !masteredTags.has(p.tag)).map((p) => p.tag);
+      });
+
+      return {
+        isUnlocked: false,
+        reason: `Blocked: missing prerequisites ${missingPrereqs.join(', ')} for tags ${lockedTags.join(', ')}`,
+      };
+    } catch {
+      // If we can't get tags, assume unlocked (fail open)
+      return {
+        isUnlocked: true,
+        reason: 'Prerequisites check skipped (tag lookup failed)',
+      };
+    }
+  }
+
+  /**
+   * CardFilter.transform implementation.
+   *
+   * Apply prerequisite gating to cards. Cards with locked tags receive score: 0.
+   */
+  async transform(cards: WeightedCard[], context: FilterContext): Promise<WeightedCard[]> {
+    // Get mastery state
+    const masteredTags = await this.getMasteredTags(context);
+    const unlockedTags = this.getUnlockedTags(masteredTags);
+
+    // Apply prerequisite gating as score multiplier
+    const gated: WeightedCard[] = [];
+
+    for (const card of cards) {
+      const { isUnlocked, reason } = await this.checkCardUnlock(
+        card,
+        context.course,
+        unlockedTags,
+        masteredTags
+      );
+      const finalScore = isUnlocked ? card.score : 0;
+      const action = isUnlocked ? 'passed' : 'penalized';
+
+      gated.push({
+        ...card,
+        score: finalScore,
+        provenance: [
+          ...card.provenance,
+          {
+            strategy: 'hierarchyDefinition',
+            strategyName: this.strategyName || this.name,
+            strategyId: this.strategyId || 'NAVIGATION_STRATEGY-hierarchy',
+            action,
+            score: finalScore,
+            reason,
+          },
+        ],
+      });
+    }
+
+    return gated;
+  }
+
+  /**
+   * Legacy getWeightedCards - now throws as filters should not be used as generators.
+   *
+   * Use transform() via Pipeline instead.
+   */
+  async getWeightedCards(_limit: number): Promise<WeightedCard[]> {
+    throw new Error(
+      'HierarchyDefinitionNavigator is a filter and should not be used as a generator. ' +
+        '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/index.ts

@@ -5,23 +5,341 @@ import {
   StudySessionReviewItem,
   StudySessionNewItem,
 } from '..';
+
+// Re-export filter types
+export type { CardFilter, FilterContext, CardFilterFactory } from './filters/types';
+
+// Re-export generator types
+export type { CardGenerator, GeneratorContext, CardGeneratorFactory } from './generators/types';
+
 import { ContentNavigationStrategyData } from '../types/contentNavigationStrategy';
 import { ScheduledCard } from '../types/user';
 import { logger } from '../../util/logger';
 
+// ============================================================================
+// NAVIGATION STRATEGY API
+// ============================================================================
+//
+// This module defines the ContentNavigator base class and the WeightedCard type,
+// which form the foundation of the pluggable navigation strategy system.
+//
+// KEY CONCEPTS:
+//
+// 1. WeightedCard - A card with a suitability score (0-1) and provenance trail.
+//    The provenance tracks how each strategy in the pipeline contributed to
+//    the card's final score, ensuring transparency and debuggability.
+//
+// 2. ContentNavigator - Abstract base class for backward compatibility.
+//    New code should use CardGenerator or CardFilter interfaces directly.
+//
+// 3. CardGenerator vs CardFilter:
+//    - Generators (ELO, SRS, HardcodedOrder) produce candidate cards with scores
+//    - Filters (Hierarchy, Interference, Priority, EloDistance) transform scores
+//
+// 4. Pipeline architecture:
+//    Pipeline(generator, [filter1, filter2, ...]) executes:
+//      cards = generator.getWeightedCards()
+//      cards = filter1.transform(cards, context)
+//      cards = filter2.transform(cards, context)
+//      return sorted(cards)
+//
+// 5. Provenance tracking - Each strategy adds an entry explaining its contribution.
+//    This makes the system transparent and debuggable.
+//
+// ============================================================================
+
+/**
+ * Tracks a single strategy's contribution to a card's final score.
+ *
+ * Each strategy in the pipeline adds a StrategyContribution entry to the
+ * card's provenance array, creating an audit trail of scoring decisions.
+ */
+export interface StrategyContribution {
+  /**
+   * Strategy type (implementing class name).
+   * Examples: 'elo', 'hierarchyDefinition', 'interferenceMitigator'
+   */
+  strategy: string;
+
+  /**
+   * Human-readable name identifying this specific strategy instance.
+   * Extracted from ContentNavigationStrategyData.name.
+   * Courses may have multiple instances of the same strategy type with
+   * different configurations.
+   *
+   * Examples:
+   * - "ELO (default)"
+   * - "Interference: b/d/p confusion"
+   * - "Interference: phonetic confusables"
+   * - "Priority: Common letters first"
+   */
+  strategyName: string;
+
+  /**
+   * Unique database document ID for this strategy instance.
+   * Extracted from ContentNavigationStrategyData._id.
+   * Use this to fetch the full strategy configuration document.
+   *
+   * Examples:
+   * - "NAVIGATION_STRATEGY-ELO-default"
+   * - "NAVIGATION_STRATEGY-interference-bdp"
+   * - "NAVIGATION_STRATEGY-priority-common-letters"
+   */
+  strategyId: string;
+
+  /**
+   * What the strategy did:
+   * - 'generated': Strategy produced this card (generators only)
+   * - 'passed': Strategy evaluated but didn't change score (transparent pass-through)
+   * - 'boosted': Strategy increased the score
+   * - 'penalized': Strategy decreased the score
+   */
+  action: 'generated' | 'passed' | 'boosted' | 'penalized';
+
+  /** Score after this strategy's processing */
+  score: number;
+
+  /**
+   * Human-readable explanation of the strategy's decision.
+   *
+   * Examples:
+   * - "ELO distance 75, new card"
+   * - "Prerequisites met: letter-sounds"
+   * - "Interferes with immature tag 'd' (decay 0.8)"
+   * - "High-priority tag 's' (0.95) → boost 1.15x"
+   *
+   * Required for transparency - silent adjusters are anti-patterns.
+   */
+  reason: string;
+}
+
+/**
+ * A card with a suitability score and provenance trail.
+ *
+ * Scores range from 0-1:
+ * - 1.0 = fully suitable
+ * - 0.0 = hard filter (e.g., prerequisite not met)
+ * - 0.5 = neutral
+ * - Intermediate values = soft preference
+ *
+ * Provenance tracks the scoring pipeline:
+ * - First entry: Generator that produced the card
+ * - Subsequent entries: Filters that transformed the score
+ * - Each entry includes action and human-readable reason
+ */
+export interface WeightedCard {
+  cardId: string;
+  courseId: string;
+  /** Suitability score from 0-1 */
+  score: number;
+  /**
+   * Audit trail of strategy contributions.
+   * First entry is from the generator, subsequent entries from filters.
+   */
+  provenance: StrategyContribution[];
+  /**
+   * Pre-fetched tags. Populated by Pipeline before filters run.
+   * Filters should use this instead of querying getAppliedTags() individually.
+   */
+  tags?: string[];
+}
+
+/**
+ * Extract card origin from provenance trail.
+ *
+ * The first provenance entry (from the generator) indicates whether
+ * this is a new card, review, or failed card. We parse the reason
+ * string to extract this information.
+ *
+ * @param card - Card with provenance trail
+ * @returns Card origin ('new', 'review', or 'failed')
+ */
+export function getCardOrigin(card: WeightedCard): 'new' | 'review' | 'failed' {
+  if (card.provenance.length === 0) {
+    throw new Error('Card has no provenance - cannot determine origin');
+  }
+
+  const firstEntry = card.provenance[0];
+  const reason = firstEntry.reason.toLowerCase();
+
+  if (reason.includes('failed')) {
+    return 'failed';
+  }
+  if (reason.includes('review')) {
+    return 'review';
+  }
+  return 'new';
+}
+
 export enum Navigators {
   ELO = 'elo',
+  SRS = 'srs',
   HARDCODED = 'hardcodedOrder',
+  HIERARCHY = 'hierarchyDefinition',
+  INTERFERENCE = 'interferenceMitigator',
+  RELATIVE_PRIORITY = 'relativePriority',
+  USER_TAG_PREFERENCE = 'userTagPreference',
+}
+
+// ============================================================================
+// NAVIGATOR ROLE CLASSIFICATION
+// ============================================================================
+//
+// Navigators are classified as either generators or filters:
+// - Generators: Produce candidate cards (ELO, SRS, HardcodedOrder)
+// - Filters: Transform/score candidates (Hierarchy, Interference, RelativePriority)
+//
+// This classification is used by PipelineAssembler to build pipelines:
+// 1. Instantiate generators (possibly into a CompositeGenerator)
+// 2. Instantiate filters
+// 3. Create Pipeline(generator, filters)
+//
+// ============================================================================
+
+/**
+ * Role classification for navigation strategies.
+ *
+ * - GENERATOR: Produces candidate cards with initial scores
+ * - FILTER: Transforms cards with score multipliers
+ */
+export enum NavigatorRole {
+  GENERATOR = 'generator',
+  FILTER = 'filter',
+}
+
+/**
+ * Registry mapping navigator implementations to their roles.
+ */
+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,
+  [Navigators.USER_TAG_PREFERENCE]: NavigatorRole.FILTER,
+};
+
+/**
+ * Check if a navigator implementation is a generator.
+ *
+ * @param impl - Navigator implementation name (e.g., 'elo', 'hierarchyDefinition')
+ * @returns true if the navigator is a generator, false otherwise
+ */
+export function isGenerator(impl: string): boolean {
+  return NavigatorRoles[impl as Navigators] === NavigatorRole.GENERATOR;
 }
 
 /**
- * A content-navigator provides runtime steering of study sessions.
+ * Check if a navigator implementation is a filter.
+ *
+ * @param impl - Navigator implementation name (e.g., 'elo', 'hierarchyDefinition')
+ * @returns true if the navigator is a filter, false otherwise
+ */
+export function isFilter(impl: string): boolean {
+  return NavigatorRoles[impl as Navigators] === NavigatorRole.FILTER;
+}
+
+/**
+ * Abstract base class for navigation strategies.
+ *
+ * This class exists primarily for backward compatibility with legacy code.
+ * New code should use CardGenerator or CardFilter interfaces directly.
+ *
+ * The class implements StudyContentSource for compatibility with SessionController.
+ * Once SessionController migrates to use getWeightedCards() exclusively,
+ * the legacy methods can be removed.
  */
 export abstract class ContentNavigator implements StudyContentSource {
+  /** User interface for this navigation session */
+  protected user?: UserDBInterface;
+
+  /** Course interface for this navigation session */
+  protected course?: CourseDBInterface;
+
+  /** Human-readable name for this strategy instance (from ContentNavigationStrategyData.name) */
+  protected strategyName?: string;
+
+  /** Unique document ID for this strategy instance (from ContentNavigationStrategyData._id) */
+  protected strategyId?: string;
+
+  /**
+   * 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.
+   */
+  constructor(
+    user?: UserDBInterface,
+    course?: CourseDBInterface,
+    strategyData?: ContentNavigationStrategyData
+  ) {
+    if (user && course && strategyData) {
+      this.user = user;
+      this.course = course;
+      this.strategyName = strategyData.name;
+      this.strategyId = strategyData._id;
+    }
+  }
+
+  // ============================================================================
+  // STRATEGY STATE HELPERS
+  // ============================================================================
+  //
+  // These methods allow strategies to persist their own state (user preferences,
+  // learned patterns, temporal tracking) in the user database.
+  //
+  // ============================================================================
+
+  /**
+   * Unique key identifying this strategy for state storage.
+   *
+   * Defaults to the constructor name (e.g., "UserTagPreferenceFilter").
+   * Override in subclasses if multiple instances of the same strategy type
+   * need separate state storage.
+   */
+  protected get strategyKey(): string {
+    return this.constructor.name;
+  }
+
+  /**
+   * Get this strategy's persisted state for the current course.
+   *
+   * @returns The strategy's data payload, or null if no state exists
+   * @throws Error if user or course is not initialized
+   */
+  protected async getStrategyState<T>(): Promise<T | null> {
+    if (!this.user || !this.course) {
+      throw new Error(
+        `Cannot get strategy state: navigator not properly initialized. ` +
+          `Ensure user and course are provided to constructor.`
+      );
+    }
+    return this.user.getStrategyState<T>(this.course.getCourseID(), this.strategyKey);
+  }
+
+  /**
+   * Persist this strategy's state for the current course.
+   *
+   * @param data - The strategy's data payload to store
+   * @throws Error if user or course is not initialized
+   */
+  protected async putStrategyState<T>(data: T): Promise<void> {
+    if (!this.user || !this.course) {
+      throw new Error(
+        `Cannot put strategy state: navigator not properly initialized. ` +
+          `Ensure user and course are provided to constructor.`
+      );
+    }
+    return this.user.putStrategyState<T>(this.course.getCourseID(), this.strategyKey, data);
+  }
+
   /**
+   * Factory method to create navigator instances dynamically.
    *
-   * @param user
-   * @param strategyData
+   * @param user - User interface
+   * @param course - Course interface
+   * @param strategyData - Strategy configuration document
    * @returns the runtime object used to steer a study session.
    */
   static async create(
@@ -53,6 +371,89 @@ 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.
+   *
+   * **This is the PRIMARY API for navigation strategies.**
+   *
+   * Returns cards ranked by suitability score (0-1). Higher scores indicate
+   * better candidates for presentation. Each card includes a provenance trail
+   * documenting how strategies contributed to the final score.
+   *
+   * ## 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.
+   *
+   * @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);
+  }
 }