@vue-skuilder/db 0.1.18 → 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 {
@@ -190,28 +186,16 @@ export default class RelativePriorityNavigator extends ContentNavigator implemen
     }
   }
 
-  /**
-   * Get tags for a single card.
-   */
-  private async getCardTags(cardId: string, course: CourseDBInterface): Promise<string[]> {
-    try {
-      const tagResponse = await course.getAppliedTags(cardId);
-      return tagResponse.rows.map((r) => r.doc?.name).filter((x): x is string => !!x);
-    } catch {
-      return [];
-    }
-  }
-
   /**
    * CardFilter.transform implementation.
    *
    * Apply priority-adjusted scoring. Cards with high-priority tags get boosted,
    * cards with low-priority tags get reduced scores.
    */
-  async transform(cards: WeightedCard[], context: FilterContext): Promise<WeightedCard[]> {
+  async transform(cards: WeightedCard[], _context: FilterContext): Promise<WeightedCard[]> {
     const adjusted: WeightedCard[] = await Promise.all(
       cards.map(async (card) => {
-        const cardTags = await this.getCardTags(card.cardId, context.course);
+        const cardTags = card.tags ?? [];
         const priority = this.computeCardPriority(cardTags);
         const boostFactor = this.computeBoostFactor(priority);
         const finalScore = Math.max(0, Math.min(1, card.score * boostFactor));
@@ -254,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/userGoalStub.ts

@@ -0,0 +1,136 @@
+// ============================================================================
+// USER GOAL NAVIGATOR — STUB
+// ============================================================================
+//
+// STATUS: NOT IMPLEMENTED — This file documents architectural intent only.
+//
+// ============================================================================
+//
+// ## Purpose
+//
+// Goals define WHAT the user wants to learn, as opposed to preferences which
+// define HOW they want to learn. Goals affect:
+//
+// 1. **Content scoping**: Which tags/content are relevant to this user
+// 2. **Progress tracking**: ELO is measured against goal-relevant content
+// 3. **Completion criteria**: User is "done" when goal mastery is achieved
+// 4. **Curriculum composition**: Goals enable cross-curriculum dependencies
+//
+// ## Goals vs Preferences
+//
+// | Aspect        | Goal                          | Preference                    |
+// |---------------|-------------------------------|-------------------------------|
+// | Defines       | Destination (what to learn)   | Path (how to learn)           |
+// | Example       | "Master ear-training"         | "Skip text-heavy cards"       |
+// | Affects ELO   | Yes — scopes what's tracked   | No — just filters cards       |
+// | Completion    | Yes — defines "done"          | No — persists indefinitely    |
+// | Filter impl   | UserGoalNavigator             | UserTagPreferenceFilter       |
+//
+// ## Curriculum Composition
+//
+// Goals enable software-style composition for curricula. A physics course
+// can teach classical mechanics without owning the calculus prerequisites.
+//
+// Instead, it declares a dependency:
+//
+// ```typescript
+// interface CurriculumDependency {
+//   // NPM-style package resolution
+//   curriculumId: string;        // e.g., "@skuilder/calculus"
+//   version: string;             // e.g., "^2.0.0" (semver)
+//
+//   // Goal within that curriculum
+//   goal: string;                // e.g., "differential-calculus"
+//
+//   // How this maps to local prerequisites
+//   satisfiesLocalTags: string[]; // e.g., ["calculus-prereq"]
+// }
+// ```
+//
+// When a physics card requires "calculus-prereq", the system:
+// 1. Checks if user has achieved the "differential-calculus" goal in @skuilder/calculus
+// 2. If not, defers to that curriculum to teach the prerequisite
+// 3. Returns to physics once the goal is satisfied
+//
+// This allows:
+// - Specialized curricula (calculus experts author calculus content)
+// - Reusable prerequisites across multiple courses
+// - User can bring their own "calculus credential" from prior learning
+//
+// ## User Goal State (Proposed)
+//
+// ```typescript
+// interface UserGoalState {
+//   // Primary goals — what the user wants to achieve
+//   targetTags: string[];
+//
+//   // Excluded goals — content the user explicitly doesn't care about
+//   excludedTags: string[];
+//
+//   // Cross-curriculum goals (for composition)
+//   externalGoals?: {
+//     curriculumId: string;
+//     goal: string;
+//     status: 'not-started' | 'in-progress' | 'achieved';
+//   }[];
+//
+//   // When this goal configuration was set
+//   updatedAt: string;
+// }
+// ```
+//
+// ## Implementation Considerations
+//
+// 1. **ELO Scoping**: When goals are set, user ELO tracking should focus on
+//    goal-relevant tags. This may require changes to ELO update logic.
+//
+// 2. **Progress Reporting**: UI should show progress toward goals, not just
+//    overall course completion.
+//
+// 3. **Goal Achievement**: Need to define when a goal is "achieved" —
+//    probably ELO threshold + mastery percentage on goal-tagged content.
+//
+// 4. **Curriculum Registry**: For cross-curriculum composition, need a
+//    registry/resolver for curriculum packages (similar to npm registry).
+//
+// 5. **Interaction with HierarchyDefinition**: Goals should work with
+//    prerequisite chains — user can't skip prerequisites just because
+//    they're not part of their goal.
+//
+// ## Related Files
+//
+// - `filters/userTagPreference.ts` — Preferences (path constraints)
+// - `hierarchyDefinition.ts` — Prerequisites (enforced regardless of goals)
+// - `../types/strategyState.ts` — Storage mechanism for user state
+//
+// ## Next Steps
+//
+// 1. Design goal state schema in detail
+// 2. Define goal achievement criteria
+// 3. Implement goal-scoped ELO tracking
+// 4. Build UI for goal configuration
+// 5. Design curriculum dependency resolution
+//
+// ============================================================================
+
+// Placeholder export to make this a valid module
+export const USER_GOAL_NAVIGATOR_STUB = true;
+
+/**
+ * @stub UserGoalNavigator
+ *
+ * A navigator that scopes learning to user-defined goals.
+ * See module-level documentation for architectural intent.
+ *
+ * NOT IMPLEMENTED — This is a design placeholder.
+ */
+export interface UserGoalState {
+  /** Tags the user wants to master (defines "success") */
+  targetTags: string[];
+
+  /** Tags the user explicitly doesn't care about */
+  excludedTags: string[];
+
+  /** ISO timestamp of last update */
+  updatedAt: string;
+}

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

@@ -0,0 +1,217 @@
+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';
+
+// ============================================================================
+// USER TAG PREFERENCE FILTER
+// ============================================================================
+//
+// Allows users to personalize their learning experience by specifying:
+// - Tags to boost/penalize (score multiplied by boost factor)
+//
+// User preferences are stored in STRATEGY_STATE documents in the user's
+// database, enabling persistence across sessions and sync across devices.
+//
+// Use cases:
+// - Goal-based learning: "I want to learn piano by ear, skip sight-reading"
+// - Selective focus: "I only want to practice chess endgames"
+// - Accessibility: "Skip text-heavy cards, prefer visual content"
+// - Difficulty customization: "Skip beginner content I already know"
+//
+// ============================================================================
+
+/**
+ * User's tag preference state, stored in STRATEGY_STATE document.
+ *
+ * This interface defines what gets persisted to the user's database.
+ * UI components write to this structure, and the filter reads from it.
+ *
+ * ## Preferences vs Goals
+ *
+ * Preferences are **path constraints** — they affect HOW the user learns,
+ * not WHAT they're trying to learn. Examples:
+ * - "Skip text-heavy cards" (accessibility)
+ * - "Prefer visual content"
+ *
+ * For **goal-based** filtering (defining WHAT to learn), see the separate
+ * UserGoalNavigator (stub). Goals affect progress tracking and completion
+ * criteria; preferences only affect card selection.
+ *
+ * ## Slider Semantics
+ *
+ * Each tag maps to a multiplier value in the `boost` record:
+ * - `0` = banish/exclude (card score = 0)
+ * - `0.5` = penalize by 50%
+ * - `1.0` = neutral/no effect (default when tag added)
+ * - `2.0` = 2x preference boost
+ * - Higher values = stronger preference
+ *
+ * If multiple tags on a card have preferences, the maximum multiplier wins.
+ */
+export interface UserTagPreferenceState {
+  /**
+   * Tag-specific multipliers.
+   * Maps tag name to score multiplier (0 = exclude, 1 = neutral, >1 = boost).
+   */
+  boost: Record<string, number>;
+
+  /**
+   * ISO timestamp of last update.
+   * Use `moment.utc(updatedAt)` to parse into a Moment object.
+   */
+  updatedAt: string;
+}
+
+/**
+ * A filter that applies user-configured tag preferences.
+ *
+ * Reads preferences from STRATEGY_STATE document in user's database.
+ * If no preferences exist, passes through unchanged (no-op).
+ *
+ * Implements CardFilter for use in Pipeline architecture.
+ * Also extends ContentNavigator for compatibility with dynamic loading.
+ */
+export default class UserTagPreferenceFilter extends ContentNavigator implements CardFilter {
+  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.name = strategyData.name || 'User Tag Preferences';
+  }
+
+  /**
+   * Compute multiplier for a card based on its tags and user preferences.
+   * 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);
+
+    if (multipliers.length === 0) {
+      return 1.0;
+    }
+
+    // Use max multiplier among matching tags
+    return Math.max(...multipliers);
+  }
+
+  /**
+   * Build human-readable reason for the filter's decision.
+   */
+  private buildReason(
+    cardTags: string[],
+    boostMap: Record<string, number>,
+    multiplier: number
+  ): string {
+    // Find which tag(s) contributed to the multiplier
+    const matchingTags = cardTags.filter((tag) => boostMap[tag] === multiplier);
+
+    if (multiplier === 0) {
+      return `Excluded by user preference: ${matchingTags.join(', ')} (${multiplier}x)`;
+    }
+
+    if (multiplier < 1.0) {
+      return `Penalized by user preference: ${matchingTags.join(', ')} (${multiplier.toFixed(2)}x)`;
+    }
+
+    if (multiplier > 1.0) {
+      return `Boosted by user preference: ${matchingTags.join(', ')} (${multiplier.toFixed(2)}x)`;
+    }
+
+    return 'No matching user preferences';
+  }
+
+  /**
+   * CardFilter.transform implementation.
+   *
+   * Apply user tag preferences:
+   * 1. Read preferences from strategy state
+   * 2. If no preferences, pass through unchanged
+   * 3. For each card:
+   *    - Look up tag in boost record
+   *    - If tag found: apply multiplier (0 = exclude, 1 = neutral, >1 = boost)
+   *    - If multiple tags match: use max multiplier
+   *    - Append provenance with clear reason
+   */
+  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) {
+      return cards.map((card) => ({
+        ...card,
+        provenance: [
+          ...card.provenance,
+          {
+            strategy: 'userTagPreference',
+            strategyName: this.strategyName || this.name,
+            strategyId: this.strategyId || this._strategyData._id,
+            action: 'passed' as const,
+            score: card.score,
+            reason: 'No user tag preferences configured',
+          },
+        ],
+      }));
+    }
+
+    // Process each card
+    const adjusted: WeightedCard[] = await Promise.all(
+      cards.map(async (card) => {
+        const cardTags = card.tags ?? [];
+
+        // Compute multiplier based on card tags and user preferences
+        const multiplier = this.computeMultiplier(cardTags, prefs.boost);
+        const finalScore = Math.min(1, card.score * multiplier);
+
+        // Determine action for provenance
+        let action: 'passed' | 'boosted' | 'penalized';
+        if (multiplier === 0 || multiplier < 1.0) {
+          action = 'penalized';
+        } else if (multiplier > 1.0) {
+          action = 'boosted';
+        } else {
+          action = 'passed';
+        }
+
+        return {
+          ...card,
+          score: finalScore,
+          provenance: [
+            ...card.provenance,
+            {
+              strategy: 'userTagPreference',
+              strategyName: this.strategyName || this.name,
+              strategyId: this.strategyId || this._strategyData._id,
+              action,
+              score: finalScore,
+              reason: this.buildReason(cardTags, prefs.boost, multiplier),
+            },
+          ],
+        };
+      })
+    );
+
+    return adjusted;
+  }
+
+  /**
+   * Legacy getWeightedCards - throws as filters should not be used as generators.
+   */
+  async getWeightedCards(_limit: number): Promise<WeightedCard[]> {
+    throw new Error(
+      'UserTagPreferenceFilter is a filter and should not be used as a generator. ' +
+        'Use Pipeline with a generator and this filter via transform().'
+    );
+  }
+}

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);