@vue-skuilder/db 0.1.18 → 0.1.21

package/src/core/navigators/Pipeline.ts

@@ -1,14 +1,90 @@
 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 LOGGING HELPERS
+// ============================================================================
+//
+// Focused logging functions that can be toggled by commenting single lines.
+// Use these to inspect pipeline behavior in development/production.
+//
+
+/**
+ * Log pipeline configuration on construction.
+ * Shows generator and filter chain structure.
+ */
+function logPipelineConfig(generator: CardGenerator, filters: CardFilter[]): void {
+  const filterList =
+    filters.length > 0 ? '\n    - ' + filters.map((f) => f.name).join('\n    - ') : ' none';
+
+  logger.info(
+    `[Pipeline] Configuration:\n` + `  Generator: ${generator.name}\n` + `  Filters:${filterList}`
+  );
+}
+
+/**
+ * Log tag hydration results.
+ * Shows effectiveness of batch query (how many cards/tags were hydrated).
+ */
+function logTagHydration(cards: WeightedCard[], tagsByCard: Map<string, string[]>): void {
+  const totalTags = Array.from(tagsByCard.values()).reduce((sum, tags) => sum + tags.length, 0);
+  const cardsWithTags = Array.from(tagsByCard.values()).filter((tags) => tags.length > 0).length;
+
+  logger.debug(
+    `[Pipeline] Tag hydration: ${cards.length} cards, ` +
+      `${cardsWithTags} have tags (${totalTags} total tags) - single batch query`
+  );
+}
+
+/**
+ * Log pipeline execution summary.
+ * Shows complete flow from generator through filters to final results.
+ */
+function logExecutionSummary(
+  generatorName: string,
+  generatedCount: number,
+  filterCount: number,
+  finalCount: number,
+  topScores: number[]
+): void {
+  const scoreDisplay =
+    topScores.length > 0 ? topScores.map((s) => s.toFixed(2)).join(', ') : 'none';
+
+  logger.info(
+    `[Pipeline] Execution: ${generatorName} produced ${generatedCount} → ` +
+      `${filterCount} filters → ${finalCount} results (top scores: ${scoreDisplay})`
+  );
+}
+
+/**
+ * Log provenance trails for cards.
+ * Shows the complete scoring history for each card through the pipeline.
+ * Useful for debugging why cards scored the way they did.
+ */
+function logCardProvenance(cards: WeightedCard[], maxCards: number = 3): void {
+  const cardsToLog = cards.slice(0, maxCards);
+
+  logger.debug(`[Pipeline] Provenance for top ${cardsToLog.length} cards:`);
+
+  for (const card of cardsToLog) {
+    logger.debug(`[Pipeline]   ${card.cardId} (final score: ${card.score.toFixed(3)}):`);
+
+    for (const entry of card.provenance) {
+      const scoreChange = entry.score.toFixed(3);
+      const action = entry.action.padEnd(9); // Align columns
+      logger.debug(
+        `[Pipeline]     ${action} ${scoreChange} - ${entry.strategyName}: ${entry.reason}`
+      );
+    }
+  }
+}
+
 // ============================================================================
 // PIPELINE
 // ============================================================================
@@ -72,9 +148,16 @@ export class Pipeline extends ContentNavigator {
     this.user = user;
     this.course = course;
 
-    logger.debug(
-      `[Pipeline] Created with generator '${generator.name}' and ${filters.length} filters: ${filters.map((f) => f.name).join(', ')}`
-    );
+    course
+      .getCourseConfig()
+      .then((cfg) => {
+        logger.debug(`[pipeline] Crated pipeline for ${cfg.name}`);
+      })
+      .catch((e) => {
+        logger.error(`[pipeline] Failed to lookup courseCfg: ${e}`);
+      });
+    // Toggle pipeline configuration logging:
+    logPipelineConfig(generator, filters);
   }
 
   /**
@@ -82,10 +165,11 @@ export class Pipeline extends ContentNavigator {
    *
    * 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
+   * 3. Batch hydrate tags for all candidates
+   * 4. Apply each filter sequentially
+   * 5. Remove zero-score cards
+   * 6. Sort by score descending
+   * 7. Return top N
    *
    * @param limit - Maximum number of cards to return
    * @returns Cards sorted by score descending
@@ -104,8 +188,12 @@ export class Pipeline extends ContentNavigator {
 
     // Get candidates from generator, passing context
     let cards = await this.generator.getWeightedCards(fetchLimit, context);
+    const generatedCount = cards.length;
+
+    logger.debug(`[Pipeline] Generator returned ${generatedCount} candidates`);
 
-    logger.debug(`[Pipeline] Generator returned ${cards.length} candidates`);
+    // Batch hydrate tags before filters run
+    cards = await this.hydrateTags(cards);
 
     // Apply filters sequentially
     for (const filter of this.filters) {
@@ -123,16 +211,49 @@ export class Pipeline extends ContentNavigator {
     // 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(', ')}...)`
+    // Toggle execution summary logging:
+    const topScores = result.slice(0, 3).map((c) => c.score);
+    logExecutionSummary(
+      this.generator.name,
+      generatedCount,
+      this.filters.length,
+      result.length,
+      topScores
     );
 
+    // Toggle provenance logging (shows scoring history for top cards):
+    logCardProvenance(result, 3);
+
     return result;
   }
 
+  /**
+   * Batch hydrate tags for all cards.
+   *
+   * Fetches tags for all cards in a single database query and attaches them
+   * to the WeightedCard objects. Filters can then use card.tags instead of
+   * making individual getAppliedTags() calls.
+   *
+   * @param cards - Cards to hydrate
+   * @returns Cards with tags populated
+   */
+  private async hydrateTags(cards: WeightedCard[]): Promise<WeightedCard[]> {
+    if (cards.length === 0) {
+      return cards;
+    }
+
+    const cardIds = cards.map((c) => c.cardId);
+    const tagsByCard = await this.course!.getAppliedTagsBatch(cardIds);
+
+    // Toggle tag hydration logging:
+    logTagHydration(cards, tagsByCard);
+
+    return cards.map((card) => ({
+      ...card,
+      tags: tagsByCard.get(card.cardId) ?? [],
+    }));
+  }
+
   /**
    * Build shared context for generator and filters.
    *
@@ -159,43 +280,6 @@ export class Pipeline extends ContentNavigator {
     };
   }
 
-  // ===========================================================================
-  // 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.
    */

package/src/core/navigators/PipelineAssembler.ts

@@ -7,7 +7,7 @@ import { DocType } from '../types/types-legacy';
 import { logger } from '../../util/logger';
 import type { CourseDBInterface } from '../interfaces/courseDB';
 import type { UserDBInterface } from '../interfaces/userDB';
-import CompositeGenerator from './CompositeGenerator';
+import CompositeGenerator from './generators/CompositeGenerator';
 
 // ============================================================================
 // PIPELINE ASSEMBLER

package/src/core/navigators/defaults.ts

@@ -0,0 +1,84 @@
+import { Navigators } from './index';
+import { Pipeline } from './Pipeline';
+import CompositeGenerator from './generators/CompositeGenerator';
+import ELONavigator from './generators/elo';
+import SRSNavigator from './generators/srs';
+import { createEloDistanceFilter } from './filters/eloDistance';
+import type { ContentNavigationStrategyData } from '../types/contentNavigationStrategy';
+import { DocType } from '../types/types-legacy';
+import type { CourseDBInterface, UserDBInterface } from '../interfaces';
+
+/**
+ * Default navigation pipeline configuration.
+ *
+ * This module provides factory functions for creating the canonical default
+ * navigation pipeline used by both CouchDB and static course implementations.
+ */
+
+/**
+ * Create default ELO navigation strategy data.
+ * Used when no custom strategies are configured.
+ *
+ * @param courseId - The course ID to associate with this strategy
+ * @returns Strategy data for default ELO navigation
+ */
+export function createDefaultEloStrategy(courseId: string): ContentNavigationStrategyData {
+  return {
+    _id: 'NAVIGATION_STRATEGY-ELO-default',
+    docType: DocType.NAVIGATION_STRATEGY,
+    name: 'ELO (default)',
+    description: 'Default ELO-based navigation strategy for new cards',
+    implementingClass: Navigators.ELO,
+    course: courseId,
+    serializedData: '',
+  };
+}
+
+/**
+ * Create default SRS navigation strategy data.
+ * Used when no custom strategies are configured.
+ *
+ * @param courseId - The course ID to associate with this strategy
+ * @returns Strategy data for default SRS navigation
+ */
+export function createDefaultSrsStrategy(courseId: string): ContentNavigationStrategyData {
+  return {
+    _id: 'NAVIGATION_STRATEGY-SRS-default',
+    docType: DocType.NAVIGATION_STRATEGY,
+    name: 'SRS (default)',
+    description: 'Default SRS-based navigation strategy for reviews',
+    implementingClass: Navigators.SRS,
+    course: courseId,
+    serializedData: '',
+  };
+}
+
+/**
+ * Creates the default navigation pipeline for courses with no configured strategies.
+ *
+ * Default: Pipeline(Composite(ELO, SRS), [eloDistanceFilter])
+ * - ELO generator: scores new cards by skill proximity
+ * - SRS generator: scores reviews by overdueness and interval recency
+ * - ELO distance filter: penalizes cards far from user's current level
+ *
+ * This is the canonical default configuration used when:
+ * - No navigation strategy documents exist in the course
+ * - PipelineAssembler fails to build from strategy documents
+ *
+ * @param user - User database interface for accessing user state
+ * @param course - Course database interface for accessing course data
+ * @returns Configured Pipeline ready for use
+ */
+export function createDefaultPipeline(
+  user: UserDBInterface,
+  course: CourseDBInterface
+): Pipeline {
+  const courseId = course.getCourseID();
+  const eloNavigator = new ELONavigator(user, course, createDefaultEloStrategy(courseId));
+  const srsNavigator = new SRSNavigator(user, course, createDefaultSrsStrategy(courseId));
+
+  const compositeGenerator = new CompositeGenerator([eloNavigator, srsNavigator]);
+  const eloDistanceFilter = createEloDistanceFilter();
+
+  return new Pipeline(compositeGenerator, [eloDistanceFilter], user, course);
+}

package/src/core/navigators/{hierarchyDefinition.ts → filters/hierarchyDefinition.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';
 import { toCourseElo } from '@vue-skuilder/common';
 
 /**
@@ -53,7 +51,6 @@ const DEFAULT_MIN_COUNT = 3;
  */
 export default class HierarchyDefinitionNavigator extends ContentNavigator implements CardFilter {
   private config: HierarchyConfig;
-  private _strategyData: ContentNavigationStrategyData;
 
   /** Human-readable name for CardFilter interface */
   name: string;
@@ -61,12 +58,11 @@ export default class HierarchyDefinitionNavigator extends ContentNavigator imple
   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 || 'Hierarchy Definition';
+    super(user, course, strategyData);
+    this.config = this.parseConfig(strategyData.serializedData);
+    this.name = strategyData.name || 'Hierarchy Definition';
   }
 
   private parseConfig(serializedData: string): HierarchyConfig {
@@ -158,14 +154,14 @@ export default class HierarchyDefinitionNavigator extends ContentNavigator imple
    * Check if a card is unlocked and generate reason.
    */
   private async checkCardUnlock(
-    cardId: string,
-    course: CourseDBInterface,
+    card: WeightedCard,
+    _course: CourseDBInterface,
     unlockedTags: Set<string>,
     masteredTags: Set<string>
   ): Promise<{ isUnlocked: boolean; reason: string }> {
     try {
-      const tagResponse = await course.getAppliedTags(cardId);
-      const cardTags = tagResponse.rows.map((row) => row.value?.name || row.key);
+      // Pipeline hydrates tags before filters run
+      const cardTags = card.tags ?? [];
 
       // Check each tag's prerequisite status
       const lockedTags = cardTags.filter(
@@ -214,7 +210,7 @@ export default class HierarchyDefinitionNavigator extends ContentNavigator imple
 
     for (const card of cards) {
       const { isUnlocked, reason } = await this.checkCardUnlock(
-        card.cardId,
+        card,
         context.course,
         unlockedTags,
         masteredTags
@@ -253,14 +249,4 @@ export default class HierarchyDefinitionNavigator extends ContentNavigator imple
         '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/index.ts

@@ -4,3 +4,6 @@ export type { CardFilter, FilterContext, CardFilterFactory } from './types';
 // Filter implementations
 export { createEloDistanceFilter } from './eloDistance';
 export type { EloDistanceConfig } from './eloDistance';
+
+export { default as UserTagPreferenceFilter } from './userTagPreference';
+export type { UserTagPreferenceState } from './userTagPreference';

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

@@ -0,0 +1,107 @@
+// ============================================================================
+// INFERRED PREFERENCE NAVIGATOR — STUB
+// ============================================================================
+//
+// STATUS: NOT IMPLEMENTED — This file documents architectural intent only.
+//
+// ============================================================================
+//
+// ## Purpose
+//
+// Inferred preferences are learned from user behavior, as opposed to explicit
+// preferences which are configured via UI. The system observes patterns in
+// user interactions and adjusts card selection accordingly.
+//
+// ## Inference Signals
+//
+// Potential signals to learn from:
+//
+// 1. **Card dismissal patterns**: User consistently skips certain card types
+// 2. **Time-on-card**: User spends less time on certain content (boredom?)
+// 3. **Error patterns**: User struggles with certain presentation styles
+// 4. **Session timing**: User performs better at certain times of day
+// 5. **Tag success rates**: User masters some tags faster than others
+//
+// ## Inferred State (Proposed)
+//
+// ```typescript
+// interface InferredPreferenceState {
+//   // Learned tag affinities (positive = user does well, negative = struggles)
+//   tagAffinities: Record<string, number>;
+//
+//   // Presentation style preferences
+//   preferredStyles: {
+//     visualVsText: number;     // -1 to 1 (negative = text, positive = visual)
+//     shortVsLong: number;      // -1 to 1 (negative = long, positive = short)
+//   };
+//
+//   // Temporal patterns
+//   optimalSessionLength: number;  // minutes
+//   optimalTimeOfDay: number;      // hour (0-23)
+//
+//   // Confidence in inferences
+//   sampleSize: number;
+//   lastUpdated: string;
+// }
+// ```
+//
+// ## Relationship to Explicit Preferences
+//
+// - Explicit preferences (UserTagPreferenceFilter) always take precedence
+// - Inferred preferences act as soft suggestions when no explicit pref exists
+// - User can "lock in" an inference as an explicit preference via UI
+// - User can dismiss/override an inference ("I actually like text cards")
+//
+// ## Transparency Requirements
+//
+// Inferred preferences must be:
+//
+// 1. **Visible**: User can see what the system has inferred
+// 2. **Explainable**: "We noticed you master visual cards faster"
+// 3. **Overridable**: User can disable or invert any inference
+// 4. **Forgettable**: User can reset inferences and start fresh
+//
+// ## Implementation Considerations
+//
+// 1. **Cold start**: Need minimum sample size before inferring
+// 2. **Drift**: Preferences may change over time; use decay/recency weighting
+// 3. **Privacy**: Inference data is personal; handle with care
+// 4. **Bias**: Avoid reinforcing accidental patterns as permanent preferences
+//
+// ## Related Files
+//
+// - `filters/userTagPreference.ts` — Explicit preferences (takes precedence)
+// - `userGoal.ts` — Goals (destination, not path)
+// - `../types/strategyState.ts` — Storage mechanism
+//
+// ## Next Steps
+//
+// 1. Define minimum viable inference signals
+// 2. Design inference algorithms (simple heuristics vs ML)
+// 3. Build transparency UI ("Here's what we learned about you")
+// 4. Implement override/dismiss mechanism
+// 5. Add to card record collection for inference input
+//
+// ============================================================================
+
+// Placeholder export to make this a valid module
+export const INFERRED_PREFERENCE_NAVIGATOR_STUB = true;
+
+/**
+ * @stub InferredPreferenceNavigator
+ *
+ * A navigator that learns user preferences from behavior patterns.
+ * See module-level documentation for architectural intent.
+ *
+ * NOT IMPLEMENTED — This is a design placeholder.
+ */
+export interface InferredPreferenceState {
+  /** Learned affinity scores per tag (-1 to 1) */
+  tagAffinities: Record<string, number>;
+
+  /** Number of card interactions used to build inferences */
+  sampleSize: number;
+
+  /** ISO timestamp of last inference update */
+  updatedAt: string;
+}

package/src/core/navigators/{interferenceMitigator.ts → filters/interferenceMitigator.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';
 import { toCourseElo } from '@vue-skuilder/common';
 
 /**
@@ -80,7 +78,6 @@ const DEFAULT_INTERFERENCE_DECAY = 0.8;
  */
 export default class InterferenceMitigatorNavigator extends ContentNavigator implements CardFilter {
   private config: InterferenceConfig;
-  private _strategyData: ContentNavigationStrategyData;
 
   /** Human-readable name for CardFilter interface */
   name: string;
@@ -91,13 +88,12 @@ export default class InterferenceMitigatorNavigator extends ContentNavigator imp
   constructor(
     user: UserDBInterface,
     course: CourseDBInterface,
-    _strategyData: ContentNavigationStrategyData
+    strategyData: ContentNavigationStrategyData
   ) {
-    super(user, course, _strategyData);
-    this._strategyData = _strategyData;
-    this.config = this.parseConfig(_strategyData.serializedData);
+    super(user, course, strategyData);
+    this.config = this.parseConfig(strategyData.serializedData);
     this.interferenceMap = this.buildInterferenceMap();
-    this.name = _strategyData.name || 'Interference Mitigator';
+    this.name = strategyData.name || 'Interference Mitigator';
   }
 
   private parseConfig(serializedData: string): InterferenceConfig {
@@ -234,18 +230,6 @@ export default class InterferenceMitigatorNavigator extends ContentNavigator imp
     return avoid;
   }
 
-  /**
-   * 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((row) => row.value?.name || row.key).filter(Boolean);
-    } catch {
-      return [];
-    }
-  }
-
   /**
    * Compute interference score reduction for a card.
    * Returns: { multiplier, interfering tags, reason }
@@ -313,7 +297,7 @@ export default class InterferenceMitigatorNavigator extends ContentNavigator imp
     const adjusted: WeightedCard[] = [];
 
     for (const card of cards) {
-      const cardTags = await this.getCardTags(card.cardId, context.course);
+      const cardTags = card.tags ?? [];
       const { multiplier, reason } = this.computeInterferenceEffect(
         cardTags,
         tagsToAvoid,
@@ -354,14 +338,4 @@ export default class InterferenceMitigatorNavigator extends ContentNavigator imp
         '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 [];
-  }
 }