@vue-skuilder/db 0.1.18 → 0.1.20

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

@@ -0,0 +1,232 @@
+import type { ScheduledCard } from '../../types/user';
+import type { CourseDBInterface } from '../../interfaces/courseDB';
+import type { UserDBInterface } from '../../interfaces/userDB';
+import { ContentNavigator } from '../index';
+import type { WeightedCard } from '../index';
+import type { ContentNavigationStrategyData } from '../../types/contentNavigationStrategy';
+import type { StudySessionReviewItem, StudySessionNewItem } from '../..';
+import type { CardFilter, FilterContext } from './types';
+
+// ============================================================================
+// 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().'
+    );
+  }
+
+  // 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/hierarchyDefinition.ts

@@ -158,14 +158,14 @@ export default class HierarchyDefinitionNavigator extends ContentNavigator imple
    * Check if a card is unlocked and generate reason.
    */
   private async checkCardUnlock(
-    cardId: string,
+    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 +214,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

package/src/core/navigators/index.ts

@@ -137,6 +137,11 @@ export interface WeightedCard {
    * 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[];
 }
 
 /**
@@ -173,6 +178,7 @@ export enum Navigators {
   HIERARCHY = 'hierarchyDefinition',
   INTERFERENCE = 'interferenceMitigator',
   RELATIVE_PRIORITY = 'relativePriority',
+  USER_TAG_PREFERENCE = 'userTagPreference',
 }
 
 // ============================================================================
@@ -211,6 +217,7 @@ export const NavigatorRoles: Record<Navigators, NavigatorRole> = {
   [Navigators.HIERARCHY]: NavigatorRole.FILTER,
   [Navigators.INTERFERENCE]: NavigatorRole.FILTER,
   [Navigators.RELATIVE_PRIORITY]: NavigatorRole.FILTER,
+  [Navigators.USER_TAG_PREFERENCE]: NavigatorRole.FILTER,
 };
 
 /**
@@ -275,6 +282,58 @@ export abstract class ContentNavigator implements StudyContentSource {
     }
   }
 
+  // ============================================================================
+  // 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.
    *

package/src/core/navigators/inferredPreference.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

@@ -234,18 +234,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 +301,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,

package/src/core/navigators/relativePriority.ts

@@ -190,28 +190,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));

package/src/core/navigators/userGoal.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;
+}