@vue-skuilder/db 0.1.16 → 0.1.18

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@vue-skuilder/db",
+  "type": "module",
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "Database layer for vue-skuilder",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -39,13 +40,15 @@
     "build": "tsup",
     "build:debug": "tsup --sourcemap inline",
     "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "lint": "npx eslint .",
     "lint:fix": "npx eslint . --fix",
     "lint:check": "npx eslint . --max-warnings 0"
   },
   "dependencies": {
     "@nilock2/pouchdb-authentication": "^1.0.2",
-    "@vue-skuilder/common": "0.1.16",
+    "@vue-skuilder/common": "0.1.18",
     "cross-fetch": "^4.1.0",
     "moment": "^2.29.4",
     "pouchdb": "^9.0.0",
@@ -55,7 +58,9 @@
   "devDependencies": {
     "@types/uuid": "^10.0.0",
     "tsup": "^8.0.2",
-    "typescript": "~5.7.2"
+    "typescript": "~5.9.3",
+    "vite": "^7.0.0",
+    "vitest": "^4.0.14"
   },
-  "stableVersion": "0.1.16"
+  "stableVersion": "0.1.18"
 }

package/src/core/interfaces/contentSource.ts

@@ -2,6 +2,41 @@ import { getDataLayer } from '@db/factory';
 import { UserDBInterface } from '..';
 import { StudentClassroomDB } from '../../impl/couch/classroomDB';
 import { ScheduledCard } from '@db/core/types/user';
+import { WeightedCard } from '../navigators';
+import { TagFilter, hasActiveFilter } from '@vue-skuilder/common';
+import { TagFilteredContentSource } from '../../study/TagFilteredContentSource';
+
+// ============================================================================
+// API MIGRATION NOTICE
+// ============================================================================
+//
+// The StudyContentSource interface is being superseded by the ContentNavigator
+// class and its getWeightedCards() API. See:
+//   packages/db/src/core/navigators/ARCHITECTURE.md
+//
+// HISTORICAL CONTEXT:
+// - This interface was designed to abstract 'classrooms' and 'courses' as
+//   content sources for study sessions.
+// - getNewCards() and getPendingReviews() were artifacts of two hard-coded
+//   navigation strategies: ELO proximity (new) and SRS scheduling (reviews).
+// - The new/review split reflected implementation details, not fundamentals.
+//
+// THE PROBLEM:
+// - "What does 'get reviews' mean for an interference mitigator?" - it doesn't.
+// - SRS is just one strategy that could express review urgency as scores.
+// - Some strategies generate candidates, others filter/score them.
+//
+// THE SOLUTION:
+// - ContentNavigator.getWeightedCards() returns unified scored candidates.
+// - WeightedCard.source field distinguishes new/review/failed (metadata, not API).
+// - Strategies compose via delegate pattern (filter wraps generator).
+//
+// MIGRATION PATH:
+// 1. ContentNavigator implements StudyContentSource for backward compat
+// 2. SessionController will migrate to call getWeightedCards()
+// 3. Legacy methods will be deprecated, then removed
+//
+// ============================================================================
 
 export type StudySessionFailedItem = StudySessionFailedNewItem | StudySessionFailedReviewItem;
 
@@ -43,12 +78,60 @@ export interface StudySessionItem {
 export interface ContentSourceID {
   type: 'course' | 'classroom';
   id: string;
+  /**
+   * Optional tag filter for scoped study sessions.
+   * When present, creates a TagFilteredContentSource instead of a regular course source.
+   */
+  tagFilter?: TagFilter;
 }
 
 // #region docs_StudyContentSource
+/**
+ * Interface for sources that provide study content to SessionController.
+ *
+ * @deprecated This interface will be superseded by ContentNavigator.getWeightedCards().
+ * The getNewCards/getPendingReviews split was an artifact of hard-coded ELO and SRS
+ * strategies. The new API returns unified WeightedCard[] with scores.
+ *
+ * MIGRATION:
+ * - Implement ContentNavigator instead of StudyContentSource directly
+ * - Override getWeightedCards() as the primary method
+ * - Legacy methods can delegate to getWeightedCards() or be left as-is
+ *
+ * See: packages/db/src/core/navigators/ARCHITECTURE.md
+ */
 export interface StudyContentSource {
+  /**
+   * Get cards scheduled for review based on SRS algorithm.
+   *
+   * @deprecated Will be replaced by getWeightedCards() which returns scored candidates.
+   * Review urgency will be expressed as a score rather than a separate method.
+   */
   getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]>;
+
+  /**
+   * Get new cards for introduction, typically ordered by ELO proximity.
+   *
+   * @deprecated Will be replaced by getWeightedCards() which returns scored candidates.
+   * New card selection and scoring will be unified with review scoring.
+   *
+   * @param n - Maximum number of new cards to return
+   */
   getNewCards(n?: number): Promise<StudySessionNewItem[]>;
+
+  /**
+   * Get cards with suitability scores for presentation.
+   *
+   * This is the PRIMARY API for content sources going forward. Returns unified
+   * scored candidates that can be sorted and selected by SessionController.
+   *
+   * The `source` field on WeightedCard indicates origin ('new' | 'review' | 'failed')
+   * for queue routing purposes during the migration period.
+   *
+   * @param limit - Maximum number of cards to return
+   * @returns Cards sorted by score descending
+   */
+  getWeightedCards?(limit: number): Promise<WeightedCard[]>;
 }
 // #endregion docs_StudyContentSource
 
@@ -59,11 +142,12 @@ export async function getStudySource(
   if (source.type === 'classroom') {
     return await StudentClassroomDB.factory(source.id, user);
   } else {
-    // if (source.type === 'course') - removed so tsc is certain something returns
-    // return new CourseDB(source.id, async () => {
-    //   return user;
-    // });
+    // Check if this is a tag-filtered course source
+    if (hasActiveFilter(source.tagFilter)) {
+      return new TagFilteredContentSource(source.id, source.tagFilter!, user);
+    }
 
+    // Regular course source
     return getDataLayer().getCourseDB(source.id) as unknown as StudyContentSource;
   }
 }

package/src/core/interfaces/navigationStrategyManager.ts

@@ -33,11 +33,6 @@ export interface NavigationStrategyManager {
    */
   updateNavigationStrategy(id: string, data: ContentNavigationStrategyData): Promise<void>;
 
-  /**
-   * @returns A content navigation strategy suitable to the current context.
-   */
-  surfaceNavigationStrategy(): Promise<ContentNavigationStrategyData>;
-
   // [ ] addons here like:
   //     - determining Navigation Strategy from context of current user
   //     - determining weighted averages of navigation strategies

package/src/core/navigators/CompositeGenerator.ts

@@ -0,0 +1,268 @@
+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';
+
+// ============================================================================
+// COMPOSITE GENERATOR
+// ============================================================================
+//
+// Composes multiple generator strategies into a single generator.
+//
+// Use case: When a course has multiple generators (e.g., ELO + SRS), this
+// class merges their outputs into a unified candidate list.
+//
+// Aggregation strategy:
+// - Cards appearing in multiple generators get a frequency boost
+// - Score = average(scores) * (1 + 0.1 * (appearances - 1))
+// - This rewards cards that multiple generators agree on
+//
+// ============================================================================
+
+/**
+ * Aggregation modes for combining scores from multiple generators.
+ */
+export enum AggregationMode {
+  /** Use the maximum score from any generator */
+  MAX = 'max',
+  /** Average all scores */
+  AVERAGE = 'average',
+  /** Average with frequency boost: avg * (1 + 0.1 * (n-1)) */
+  FREQUENCY_BOOST = 'frequencyBoost',
+}
+
+const DEFAULT_AGGREGATION_MODE = AggregationMode.FREQUENCY_BOOST;
+const FREQUENCY_BOOST_FACTOR = 0.1;
+
+/**
+ * Composes multiple generators into a single generator.
+ *
+ * Implements CardGenerator for use in Pipeline architecture.
+ * Also extends ContentNavigator for backward compatibility.
+ *
+ * Fetches candidates from all generators, deduplicates by cardId,
+ * and aggregates scores based on the configured mode.
+ */
+export default class CompositeGenerator extends ContentNavigator implements CardGenerator {
+  /** Human-readable name for CardGenerator interface */
+  name: string = 'Composite Generator';
+
+  private generators: CardGenerator[];
+  private aggregationMode: AggregationMode;
+
+  constructor(
+    generators: CardGenerator[],
+    aggregationMode: AggregationMode = DEFAULT_AGGREGATION_MODE
+  ) {
+    super();
+    this.generators = generators;
+    this.aggregationMode = aggregationMode;
+
+    if (generators.length === 0) {
+      throw new Error('CompositeGenerator requires at least one generator');
+    }
+
+    logger.debug(
+      `[CompositeGenerator] Created with ${generators.length} generators, mode: ${aggregationMode}`
+    );
+  }
+
+  /**
+   * Creates a CompositeGenerator from strategy data.
+   *
+   * This is a convenience factory for use by PipelineAssembler.
+   */
+  static async fromStrategies(
+    user: UserDBInterface,
+    course: CourseDBInterface,
+    strategies: ContentNavigationStrategyData[],
+    aggregationMode: AggregationMode = DEFAULT_AGGREGATION_MODE
+  ): Promise<CompositeGenerator> {
+    const generators = await Promise.all(
+      strategies.map((s) => ContentNavigator.create(user, course, s))
+    );
+    // Cast is safe because we know these are generators
+    return new CompositeGenerator(generators as unknown as CardGenerator[], aggregationMode);
+  }
+
+  /**
+   * Get weighted cards from all generators, merge and deduplicate.
+   *
+   * Cards appearing in multiple generators receive a score boost.
+   * Provenance tracks which generators produced each card and how scores were aggregated.
+   *
+   * 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 passed to child generators
+   */
+  async getWeightedCards(limit: number, context?: GeneratorContext): Promise<WeightedCard[]> {
+    // Fetch from all generators in parallel
+    const results = await Promise.all(
+      this.generators.map((g) => g.getWeightedCards(limit, context))
+    );
+
+    // Group by cardId
+    const byCardId = new Map<string, WeightedCard[]>();
+    for (const cards of results) {
+      for (const card of cards) {
+        const existing = byCardId.get(card.cardId) || [];
+        existing.push(card);
+        byCardId.set(card.cardId, existing);
+      }
+    }
+
+    // Aggregate scores
+    const merged: WeightedCard[] = [];
+    for (const [, cards] of byCardId) {
+      const aggregatedScore = this.aggregateScores(cards);
+      const finalScore = Math.min(1.0, aggregatedScore); // Clamp to [0, 1]
+
+      // Merge provenance from all generators that produced this card
+      const mergedProvenance = cards.flatMap((c) => c.provenance);
+
+      // Determine action based on whether score changed
+      const initialScore = cards[0].score;
+      const action =
+        finalScore > initialScore ? 'boosted' : finalScore < initialScore ? 'penalized' : 'passed';
+
+      // Build reason explaining the aggregation
+      const reason = this.buildAggregationReason(cards, finalScore);
+
+      // Append composite provenance entry
+      merged.push({
+        ...cards[0],
+        score: finalScore,
+        provenance: [
+          ...mergedProvenance,
+          {
+            strategy: 'composite',
+            strategyName: 'Composite Generator',
+            strategyId: 'COMPOSITE_GENERATOR',
+            action,
+            score: finalScore,
+            reason,
+          },
+        ],
+      });
+    }
+
+    // Sort by score descending and limit
+    return merged.sort((a, b) => b.score - a.score).slice(0, limit);
+  }
+
+  /**
+   * Build human-readable reason for score aggregation.
+   */
+  private buildAggregationReason(cards: WeightedCard[], finalScore: number): string {
+    const count = cards.length;
+    const scores = cards.map((c) => c.score.toFixed(2)).join(', ');
+
+    if (count === 1) {
+      return `Single generator, score ${finalScore.toFixed(2)}`;
+    }
+
+    const strategies = cards.map((c) => c.provenance[0]?.strategy || 'unknown').join(', ');
+
+    switch (this.aggregationMode) {
+      case AggregationMode.MAX:
+        return `Max of ${count} generators (${strategies}): scores [${scores}] → ${finalScore.toFixed(2)}`;
+
+      case AggregationMode.AVERAGE:
+        return `Average of ${count} generators (${strategies}): scores [${scores}] → ${finalScore.toFixed(2)}`;
+
+      case AggregationMode.FREQUENCY_BOOST: {
+        const avg = cards.reduce((sum, c) => sum + c.score, 0) / count;
+        const boost = 1 + FREQUENCY_BOOST_FACTOR * (count - 1);
+        return `Frequency boost from ${count} generators (${strategies}): avg ${avg.toFixed(2)} × ${boost.toFixed(2)} → ${finalScore.toFixed(2)}`;
+      }
+
+      default:
+        return `Aggregated from ${count} generators: ${finalScore.toFixed(2)}`;
+    }
+  }
+
+  /**
+   * Aggregate scores from multiple generators for the same card.
+   */
+  private aggregateScores(cards: WeightedCard[]): number {
+    const scores = cards.map((c) => c.score);
+
+    switch (this.aggregationMode) {
+      case AggregationMode.MAX:
+        return Math.max(...scores);
+
+      case AggregationMode.AVERAGE:
+        return scores.reduce((sum, s) => sum + s, 0) / scores.length;
+
+      case AggregationMode.FREQUENCY_BOOST: {
+        const avg = scores.reduce((sum, s) => sum + s, 0) / scores.length;
+        const frequencyBoost = 1 + FREQUENCY_BOOST_FACTOR * (cards.length - 1);
+        return avg * frequencyBoost;
+      }
+
+      default:
+        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/Pipeline.ts

@@ -0,0 +1,205 @@
+import { toCourseElo } from '@vue-skuilder/common';
+import type { CourseDBInterface } from '../interfaces/courseDB';
+import type { UserDBInterface } from '../interfaces/userDB';
+import type { ScheduledCard } from '../types/user';
+import { ContentNavigator } from './index';
+import type { WeightedCard } from './index';
+import type { CardFilter, FilterContext } from './filters/types';
+import type { CardGenerator, GeneratorContext } from './generators/types';
+import type { StudySessionNewItem, StudySessionReviewItem } from '../interfaces/contentSource';
+import { logger } from '../../util/logger';
+
+// ============================================================================
+// PIPELINE
+// ============================================================================
+//
+// Executes a navigation pipeline: generator → filters → sorted results.
+//
+// Architecture:
+//   cards = generator.getWeightedCards(limit, context)
+//   cards = filter1.transform(cards, context)
+//   cards = filter2.transform(cards, context)
+//   cards = filter3.transform(cards, context)
+//   return sorted(cards).slice(0, limit)
+//
+// Benefits:
+// - Clear separation: generators produce, filters transform
+// - No nested instantiation complexity
+// - Filters don't need to know about each other
+// - Shared context built once, passed to all stages
+//
+// ============================================================================
+
+/**
+ * A navigation pipeline that runs a generator and applies filters sequentially.
+ *
+ * Implements StudyContentSource for backward compatibility with SessionController.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * const pipeline = new Pipeline(
+ *   compositeGenerator,  // or single generator
+ *   [eloDistanceFilter, interferenceFilter],
+ *   user,
+ *   course
+ * );
+ *
+ * const cards = await pipeline.getWeightedCards(20);
+ * ```
+ */
+export class Pipeline extends ContentNavigator {
+  private generator: CardGenerator;
+  private filters: CardFilter[];
+
+  /**
+   * Create a new pipeline.
+   *
+   * @param generator - The generator (or CompositeGenerator) that produces candidates
+   * @param filters - Filters to apply sequentially (order doesn't matter for multipliers)
+   * @param user - User database interface
+   * @param course - Course database interface
+   */
+  constructor(
+    generator: CardGenerator,
+    filters: CardFilter[],
+    user: UserDBInterface,
+    course: CourseDBInterface
+  ) {
+    super();
+    this.generator = generator;
+    this.filters = filters;
+    this.user = user;
+    this.course = course;
+
+    logger.debug(
+      `[Pipeline] Created with generator '${generator.name}' and ${filters.length} filters: ${filters.map((f) => f.name).join(', ')}`
+    );
+  }
+
+  /**
+   * Get weighted cards by running generator and applying filters.
+   *
+   * 1. Build shared context (user ELO, etc.)
+   * 2. Get candidates from generator (passing context)
+   * 3. Apply each filter sequentially
+   * 4. Remove zero-score cards
+   * 5. Sort by score descending
+   * 6. Return top N
+   *
+   * @param limit - Maximum number of cards to return
+   * @returns Cards sorted by score descending
+   */
+  async getWeightedCards(limit: number): Promise<WeightedCard[]> {
+    // Build shared context once
+    const context = await this.buildContext();
+
+    // Over-fetch from generator to account for filtering
+    const overFetchMultiplier = 2 + this.filters.length * 0.5;
+    const fetchLimit = Math.ceil(limit * overFetchMultiplier);
+
+    logger.debug(
+      `[Pipeline] Fetching ${fetchLimit} candidates from generator '${this.generator.name}'`
+    );
+
+    // Get candidates from generator, passing context
+    let cards = await this.generator.getWeightedCards(fetchLimit, context);
+
+    logger.debug(`[Pipeline] Generator returned ${cards.length} candidates`);
+
+    // Apply filters sequentially
+    for (const filter of this.filters) {
+      const beforeCount = cards.length;
+      cards = await filter.transform(cards, context);
+      logger.debug(`[Pipeline] Filter '${filter.name}': ${beforeCount} → ${cards.length} cards`);
+    }
+
+    // Remove zero-score cards (hard filtered)
+    cards = cards.filter((c) => c.score > 0);
+
+    // Sort by score descending
+    cards.sort((a, b) => b.score - a.score);
+
+    // Return top N
+    const result = cards.slice(0, limit);
+
+    logger.debug(
+      `[Pipeline] Returning ${result.length} cards (top scores: ${result
+        .slice(0, 3)
+        .map((c) => c.score.toFixed(2))
+        .join(', ')}...)`
+    );
+
+    return result;
+  }
+
+  /**
+   * Build shared context for generator and filters.
+   *
+   * Called once per getWeightedCards() invocation.
+   * Contains data that the generator and multiple filters might need.
+   *
+   * The context satisfies both GeneratorContext and FilterContext interfaces.
+   */
+  private async buildContext(): Promise<GeneratorContext & FilterContext> {
+    let userElo = 1000; // Default ELO
+
+    try {
+      const courseReg = await this.user!.getCourseRegDoc(this.course!.getCourseID());
+      const courseElo = toCourseElo(courseReg.elo);
+      userElo = courseElo.global.score;
+    } catch (e) {
+      logger.debug(`[Pipeline] Could not get user ELO, using default: ${e}`);
+    }
+
+    return {
+      user: this.user!,
+      course: this.course!,
+      userElo,
+    };
+  }
+
+  // ===========================================================================
+  // Legacy StudyContentSource methods
+  // ===========================================================================
+  //
+  // These delegate to the generator for backward compatibility.
+  // Eventually SessionController will use getWeightedCards() exclusively.
+  //
+
+  /**
+   * Get new cards via legacy API.
+   * Delegates to the generator if it supports the legacy interface.
+   */
+  async getNewCards(n?: number): Promise<StudySessionNewItem[]> {
+    // Check if generator has legacy method (ContentNavigator-based generators do)
+    if ('getNewCards' in this.generator && typeof this.generator.getNewCards === 'function') {
+      return (this.generator as ContentNavigator).getNewCards(n);
+    }
+    // Pure CardGenerator without legacy support - return empty
+    return [];
+  }
+
+  /**
+   * Get pending reviews via legacy API.
+   * Delegates to the generator if it supports the legacy interface.
+   */
+  async getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]> {
+    // Check if generator has legacy method (ContentNavigator-based generators do)
+    if (
+      'getPendingReviews' in this.generator &&
+      typeof this.generator.getPendingReviews === 'function'
+    ) {
+      return (this.generator as ContentNavigator).getPendingReviews();
+    }
+    // Pure CardGenerator without legacy support - return empty
+    return [];
+  }
+
+  /**
+   * Get the course ID for this pipeline.
+   */
+  getCourseID(): string {
+    return this.course!.getCourseID();
+  }
+}