@vue-skuilder/db 0.1.18 → 0.1.21

package/src/core/navigators/{srs.ts → generators/srs.ts}

@@ -1,12 +1,12 @@
 import moment from 'moment';
-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 '../interfaces/contentSource';
-import type { CardGenerator, GeneratorContext } from './generators/types';
+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 { CardGenerator, GeneratorContext } from './types';
+import { logger } from '@db/util/logger';
 
 // ============================================================================
 // SRS NAVIGATOR
@@ -95,6 +95,7 @@ export default class SRSNavigator extends ContentNavigator implements CardGenera
         cardId: review.cardId,
         courseId: review.courseId,
         score,
+        reviewID: review._id,
         provenance: [
           {
             strategy: 'srs',
@@ -108,6 +109,8 @@ export default class SRSNavigator extends ContentNavigator implements CardGenera
       };
     });
 
+    logger.debug(`[srsNav] got ${scored.length} weighted cards`);
+
     // Sort by score descending and limit
     return scored.sort((a, b) => b.score - a.score).slice(0, limit);
   }
@@ -160,36 +163,4 @@ export default class SRSNavigator extends ContentNavigator implements CardGenera
 
     return { score, reason };
   }
-
-  /**
-   * Get pending reviews in legacy format.
-   *
-   * Returns all pending reviews for the course, enriched with session item fields.
-   */
-  async getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]> {
-    if (!this.user || !this.course) {
-      throw new Error('SRSNavigator requires user and course to be set');
-    }
-
-    const reviews = await this.user.getPendingReviews(this.course.getCourseID());
-
-    return reviews.map((r) => ({
-      ...r,
-      contentSourceType: 'course' as const,
-      contentSourceID: this.course!.getCourseID(),
-      cardID: r.cardId,
-      courseID: r.courseId,
-      qualifiedID: `${r.courseId}-${r.cardId}`,
-      reviewID: r._id,
-      status: 'review' as const,
-    }));
-  }
-
-  /**
-   * SRS does not generate new cards.
-   * Use ELONavigator or another generator for new cards.
-   */
-  async getNewCards(_n?: number): Promise<StudySessionNewItem[]> {
-    return [];
-  }
 }

package/src/core/navigators/generators/types.ts

@@ -9,7 +9,7 @@ import type { UserDBInterface } from '../../interfaces/userDB';
 // Generators produce candidate cards with initial scores.
 // They are the "source" stage of a navigation pipeline.
 //
-// Examples: ELO (skill proximity), SRS (review scheduling), HardcodedOrder
+// Examples: ELO (skill proximity), SRS (review scheduling)
 //
 // Generators differ from filters:
 // - Generators: produce candidates from DB queries, assign initial scores

package/src/core/navigators/index.ts

@@ -1,10 +1,4 @@
-import {
-  StudyContentSource,
-  UserDBInterface,
-  CourseDBInterface,
-  StudySessionReviewItem,
-  StudySessionNewItem,
-} from '..';
+import { StudyContentSource, UserDBInterface, CourseDBInterface } from '..';
 
 // Re-export filter types
 export type { CardFilter, FilterContext, CardFilterFactory } from './filters/types';
@@ -13,7 +7,6 @@ export type { CardFilter, FilterContext, CardFilterFactory } from './filters/typ
 export type { CardGenerator, GeneratorContext, CardGeneratorFactory } from './generators/types';
 
 import { ContentNavigationStrategyData } from '../types/contentNavigationStrategy';
-import { ScheduledCard } from '../types/user';
 import { logger } from '../../util/logger';
 
 // ============================================================================
@@ -33,7 +26,7 @@ import { logger } from '../../util/logger';
 //    New code should use CardGenerator or CardFilter interfaces directly.
 //
 // 3. CardGenerator vs CardFilter:
-//    - Generators (ELO, SRS, HardcodedOrder) produce candidate cards with scores
+//    - Generators (ELO, SRS) produce candidate cards with scores
 //    - Filters (Hierarchy, Interference, Priority, EloDistance) transform scores
 //
 // 4. Pipeline architecture:
@@ -137,6 +130,17 @@ 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[];
+  /**
+   * Review document ID (_id from ScheduledCard).
+   * Present when this card originated from SRS review scheduling.
+   * Used by SessionController to track review outcomes and maintain review state.
+   */
+  reviewID?: string;
 }
 
 /**
@@ -169,10 +173,10 @@ export function getCardOrigin(card: WeightedCard): 'new' | 'review' | 'failed' {
 export enum Navigators {
   ELO = 'elo',
   SRS = 'srs',
-  HARDCODED = 'hardcodedOrder',
   HIERARCHY = 'hierarchyDefinition',
   INTERFERENCE = 'interferenceMitigator',
   RELATIVE_PRIORITY = 'relativePriority',
+  USER_TAG_PREFERENCE = 'userTagPreference',
 }
 
 // ============================================================================
@@ -180,7 +184,7 @@ export enum Navigators {
 // ============================================================================
 //
 // Navigators are classified as either generators or filters:
-// - Generators: Produce candidate cards (ELO, SRS, HardcodedOrder)
+// - Generators: Produce candidate cards (ELO, SRS)
 // - Filters: Transform/score candidates (Hierarchy, Interference, RelativePriority)
 //
 // This classification is used by PipelineAssembler to build pipelines:
@@ -207,10 +211,10 @@ export enum NavigatorRole {
 export const NavigatorRoles: Record<Navigators, NavigatorRole> = {
   [Navigators.ELO]: NavigatorRole.GENERATOR,
   [Navigators.SRS]: NavigatorRole.GENERATOR,
-  [Navigators.HARDCODED]: NavigatorRole.GENERATOR,
   [Navigators.HIERARCHY]: NavigatorRole.FILTER,
   [Navigators.INTERFERENCE]: NavigatorRole.FILTER,
   [Navigators.RELATIVE_PRIORITY]: NavigatorRole.FILTER,
+  [Navigators.USER_TAG_PREFERENCE]: NavigatorRole.FILTER,
 };
 
 /**
@@ -245,10 +249,10 @@ export function isFilter(impl: string): boolean {
  */
 export abstract class ContentNavigator implements StudyContentSource {
   /** User interface for this navigation session */
-  protected user?: UserDBInterface;
+  protected user: UserDBInterface;
 
   /** Course interface for this navigation session */
-  protected course?: CourseDBInterface;
+  protected course: CourseDBInterface;
 
   /** Human-readable name for this strategy instance (from ContentNavigationStrategyData.name) */
   protected strategyName?: string;
@@ -260,21 +264,74 @@ export abstract class ContentNavigator implements StudyContentSource {
    * Constructor for standard navigators.
    * Call this from subclass constructors to initialize common fields.
    *
-   * Note: CompositeGenerator doesn't use this pattern and should call super() without args.
+   * Note: CompositeGenerator and Pipeline call super() without args, then set
+   * user/course fields directly if needed.
    */
   constructor(
     user?: UserDBInterface,
     course?: CourseDBInterface,
     strategyData?: ContentNavigationStrategyData
   ) {
-    if (user && course && strategyData) {
-      this.user = user;
-      this.course = course;
+    this.user = user!;
+    this.course = course!;
+    if (strategyData) {
       this.strategyName = strategyData.name;
       this.strategyId = strategyData._id;
     }
   }
 
+  // ============================================================================
+  // STRATEGY STATE HELPERS
+  // ============================================================================
+  //
+  // These methods allow strategies to persist their own state (user preferences,
+  // learned patterns, temporal tracking) in the user database.
+  //
+  // ============================================================================
+
+  /**
+   * Unique key identifying this strategy for state storage.
+   *
+   * Defaults to the constructor name (e.g., "UserTagPreferenceFilter").
+   * Override in subclasses if multiple instances of the same strategy type
+   * need separate state storage.
+   */
+  protected get strategyKey(): string {
+    return this.constructor.name;
+  }
+
+  /**
+   * Get this strategy's persisted state for the current course.
+   *
+   * @returns The strategy's data payload, or null if no state exists
+   * @throws Error if user or course is not initialized
+   */
+  protected async getStrategyState<T>(): Promise<T | null> {
+    if (!this.user || !this.course) {
+      throw new Error(
+        `Cannot get strategy state: navigator not properly initialized. ` +
+          `Ensure user and course are provided to constructor.`
+      );
+    }
+    return this.user.getStrategyState<T>(this.course.getCourseID(), this.strategyKey);
+  }
+
+  /**
+   * Persist this strategy's state for the current course.
+   *
+   * @param data - The strategy's data payload to store
+   * @throws Error if user or course is not initialized
+   */
+  protected async putStrategyState<T>(data: T): Promise<void> {
+    if (!this.user || !this.course) {
+      throw new Error(
+        `Cannot put strategy state: navigator not properly initialized. ` +
+          `Ensure user and course are provided to constructor.`
+      );
+    }
+    return this.user.putStrategyState<T>(this.course.getCourseID(), this.strategyKey, data);
+  }
+
   /**
    * Factory method to create navigator instances dynamically.
    *
@@ -293,15 +350,19 @@ export abstract class ContentNavigator implements StudyContentSource {
 
     // Try different extension variations
     const variations = ['.ts', '.js', ''];
+    const dirs = ['filters', 'generators'];
 
     for (const ext of variations) {
-      try {
-        const module = await import(`./${implementingClass}${ext}`);
-        NavigatorImpl = module.default;
-        break; // Break the loop if loading succeeds
-      } catch (e) {
-        // Continue to next variation if this one fails
-        logger.debug(`Failed to load with extension ${ext}:`, e);
+      for (const dir of dirs) {
+        const loadFrom = `./${dir}/${implementingClass}${ext}`;
+        try {
+          const module = await import(loadFrom);
+          NavigatorImpl = module.default;
+          break; // Break the loop if loading succeeds
+        } catch (e) {
+          // Continue to next variation if this one fails
+          logger.debug(`Failed to load extension from ${loadFrom}:`, e);
+        }
       }
     }
 
@@ -312,24 +373,6 @@ export abstract class ContentNavigator implements StudyContentSource {
     return new NavigatorImpl(user, course, strategyData);
   }
 
-  /**
-   * Get cards scheduled for review.
-   *
-   * @deprecated This method is part of the legacy StudyContentSource interface.
-   * New strategies should focus on implementing CardGenerator.getWeightedCards() instead.
-   */
-  abstract getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]>;
-
-  /**
-   * Get new cards for introduction.
-   *
-   * @deprecated This method is part of the legacy StudyContentSource interface.
-   * New strategies should focus on implementing CardGenerator.getWeightedCards() instead.
-   *
-   * @param n - Maximum number of new cards to return
-   */
-  abstract getNewCards(n?: number): Promise<StudySessionNewItem[]>;
-
   /**
    * Get cards with suitability scores and provenance trails.
    *
@@ -339,62 +382,23 @@ export abstract class ContentNavigator implements StudyContentSource {
    * better candidates for presentation. Each card includes a provenance trail
    * documenting how strategies contributed to the final score.
    *
+   * ## Implementation Required
+   * All navigation strategies MUST override this method. The base class does
+   * not provide a default implementation.
+   *
    * ## For Generators
    * Override this method to generate candidates and compute scores based on
    * your strategy's logic (e.g., ELO proximity, review urgency). Create the
    * initial provenance entry with action='generated'.
    *
-   * ## Default Implementation
-   * The base class provides a backward-compatible default that:
-   * 1. Calls legacy getNewCards() and getPendingReviews()
-   * 2. Assigns score=1.0 to all cards
-   * 3. Creates minimal provenance from legacy methods
-   * 4. Returns combined results up to limit
-   *
-   * This allows existing strategies to work without modification while
-   * new strategies can override with proper scoring and provenance.
+   * ## For Filters
+   * Filters should implement the CardFilter interface instead and be composed
+   * via Pipeline. Filters do not directly implement getWeightedCards().
    *
    * @param limit - Maximum cards to return
    * @returns Cards sorted by score descending, with provenance trails
    */
-  async getWeightedCards(limit: number): Promise<WeightedCard[]> {
-    // Default implementation: delegate to legacy methods, assign score=1.0
-    const newCards = await this.getNewCards(limit);
-    const reviews = await this.getPendingReviews();
-
-    const weighted: WeightedCard[] = [
-      ...newCards.map((c) => ({
-        cardId: c.cardID,
-        courseId: c.courseID,
-        score: 1.0,
-        provenance: [
-          {
-            strategy: 'legacy',
-            strategyName: this.strategyName || 'Legacy API',
-            strategyId: this.strategyId || 'legacy-fallback',
-            action: 'generated' as const,
-            score: 1.0,
-            reason: 'Generated via legacy getNewCards(), new card',
-          },
-        ],
-      })),
-      ...reviews.map((r) => ({
-        cardId: r.cardID,
-        courseId: r.courseID,
-        score: 1.0,
-        provenance: [
-          {
-            strategy: 'legacy',
-            strategyName: this.strategyName || 'Legacy API',
-            strategyId: this.strategyId || 'legacy-fallback',
-            action: 'generated' as const,
-            score: 1.0,
-            reason: 'Generated via legacy getPendingReviews(), review',
-          },
-        ],
-      })),
-    ];
-
-    return weighted.slice(0, limit);
+  async getWeightedCards(_limit: number): Promise<WeightedCard[]> {
+    throw new Error(`${this.constructor.name} must implement getWeightedCards(). `);
   }
 }

package/src/core/types/strategyState.ts

@@ -0,0 +1,84 @@
+import { DocType, DocTypePrefixes } from './types-legacy';
+
+/**
+ * Template literal type for strategy state document IDs.
+ *
+ * Format: `STRATEGY_STATE-{courseId}-{strategyKey}`
+ */
+export type StrategyStateId =
+  `${(typeof DocTypePrefixes)[DocType.STRATEGY_STATE]}::${string}::${string}`;
+
+/**
+ * Document storing strategy-specific state in the user database.
+ *
+ * Each strategy can persist its own state (user preferences, learned patterns,
+ * temporal tracking, etc.) using this document type. The state is scoped to
+ * a (user, course, strategy) tuple.
+ *
+ * ## Use Cases
+ *
+ * 1. **Explicit user preferences**: User configures tag filters, difficulty
+ *    preferences, or learning goals. UI writes to strategy state.
+ *
+ * 2. **Learned/temporal state**: Strategy tracks patterns over time, e.g.,
+ *    "when did I last introduce confusable concepts together?"
+ *
+ * 3. **Adaptive personalization**: Strategy infers user preferences from
+ *    behavior and stores them for future sessions.
+ *
+ * ## Storage Location
+ *
+ * These documents live in the **user database**, not the course database.
+ * They sync with the user's data across devices.
+ *
+ * ## Document ID Format
+ *
+ * `STRATEGY_STATE::{courseId}::{strategyKey}`
+ *
+ * Example: `STRATEGY_STATE::piano-basics::UserTagPreferenceFilter`
+ *
+ * @template T - The shape of the strategy-specific data payload
+ */
+export interface StrategyStateDoc<T = unknown> {
+  _id: StrategyStateId;
+  _rev?: string;
+  docType: DocType.STRATEGY_STATE;
+
+  /**
+   * The course this state applies to.
+   */
+  courseId: string;
+
+  /**
+   * Unique key identifying the strategy instance.
+   * Typically the strategy class name (e.g., "UserTagPreferenceFilter",
+   * "InterferenceMitigatorNavigator").
+   *
+   * If a course has multiple instances of the same strategy type with
+   * different configurations, use a more specific key.
+   */
+  strategyKey: string;
+
+  /**
+   * Strategy-specific data payload.
+   * Each strategy defines its own schema for this field.
+   */
+  data: T;
+
+  /**
+   * ISO timestamp of last update.
+   * Use `moment.utc(updatedAt)` to parse into a Moment object.
+   */
+  updatedAt: string;
+}
+
+/**
+ * Build the document ID for a strategy state document.
+ *
+ * @param courseId - The course ID
+ * @param strategyKey - The strategy key (typically class name)
+ * @returns The document ID in format `STRATEGY_STATE::{courseId}::{strategyKey}`
+ */
+export function buildStrategyStateId(courseId: string, strategyKey: string): StrategyStateId {
+  return `STRATEGY_STATE::${courseId}::${strategyKey}`;
+}

package/src/core/types/types-legacy.ts

@@ -19,6 +19,7 @@ export enum DocType {
   SCHEDULED_CARD = 'SCHEDULED_CARD',
   TAG = 'TAG',
   NAVIGATION_STRATEGY = 'NAVIGATION_STRATEGY',
+  STRATEGY_STATE = 'STRATEGY_STATE',
 }
 
 export interface QualifiedCardID {
@@ -103,6 +104,7 @@ export const DocTypePrefixes = {
   [DocType.VIEW]: 'VIEW',
   [DocType.PEDAGOGY]: 'PEDAGOGY',
   [DocType.NAVIGATION_STRATEGY]: 'NAVIGATION_STRATEGY',
+  [DocType.STRATEGY_STATE]: 'STRATEGY_STATE',
 } as const;
 
 export interface CardHistory<T extends CardRecord> {

package/src/impl/common/BaseUserDB.ts

@@ -1,4 +1,4 @@
-import { DocType, DocTypePrefixes } from '@db/core';
+import { DocType, DocTypePrefixes, StrategyStateDoc, buildStrategyStateId } from '@db/core';
 import { getCardHistoryID } from '@db/core/util';
 import { CourseElo, Status } from '@vue-skuilder/common';
 import moment, { Moment } from 'moment';
@@ -1046,6 +1046,61 @@ Currently logged-in as ${this._username}.`
   public async updateUserElo(courseId: string, elo: CourseElo): Promise<PouchDB.Core.Response> {
     return updateUserElo(this._username, courseId, elo);
   }
+
+  public async getStrategyState<T>(courseId: string, strategyKey: string): Promise<T | null> {
+    const docId = buildStrategyStateId(courseId, strategyKey);
+    try {
+      const doc = await this.localDB.get<StrategyStateDoc<T>>(docId);
+      return doc.data;
+    } catch (e) {
+      const err = e as PouchError;
+      if (err.status === 404) {
+        return null;
+      }
+      throw e;
+    }
+  }
+
+  public async putStrategyState<T>(courseId: string, strategyKey: string, data: T): Promise<void> {
+    const docId = buildStrategyStateId(courseId, strategyKey);
+    let existingRev: string | undefined;
+
+    try {
+      const existing = await this.localDB.get<StrategyStateDoc<T>>(docId);
+      existingRev = existing._rev;
+    } catch (e) {
+      const err = e as PouchError;
+      if (err.status !== 404) {
+        throw e;
+      }
+    }
+
+    const doc: StrategyStateDoc<T> = {
+      _id: docId,
+      _rev: existingRev,
+      docType: DocType.STRATEGY_STATE,
+      courseId,
+      strategyKey,
+      data,
+      updatedAt: new Date().toISOString(),
+    };
+
+    await this.localDB.put(doc);
+  }
+
+  public async deleteStrategyState(courseId: string, strategyKey: string): Promise<void> {
+    const docId = buildStrategyStateId(courseId, strategyKey);
+    try {
+      const doc = await this.localDB.get(docId);
+      await this.localDB.remove(doc);
+    } catch (e) {
+      const err = e as PouchError;
+      if (err.status === 404) {
+        return;
+      }
+      throw e;
+    }
+  }
 }
 
 export function accomodateGuest(): {
@@ -1056,7 +1111,9 @@ export function accomodateGuest(): {
 
   // Check if localStorage is available (browser environment)
   if (typeof localStorage === 'undefined') {
-    logger.log('[funnel] localStorage not available (Node.js environment), returning default guest');
+    logger.log(
+      '[funnel] localStorage not available (Node.js environment), returning default guest'
+    );
     return {
       username: GuestUsername + 'nodejs-test',
       firstVisit: true,
@@ -1125,11 +1182,21 @@ export function accomodateGuest(): {
       bytes[8] = (bytes[8] & 0x3f) | 0x80; // Variant 10
 
       const uuid = [
-        Array.from(bytes.slice(0, 4)).map(b => b.toString(16).padStart(2, '0')).join(''),
-        Array.from(bytes.slice(4, 6)).map(b => b.toString(16).padStart(2, '0')).join(''),
-        Array.from(bytes.slice(6, 8)).map(b => b.toString(16).padStart(2, '0')).join(''),
-        Array.from(bytes.slice(8, 10)).map(b => b.toString(16).padStart(2, '0')).join(''),
-        Array.from(bytes.slice(10, 16)).map(b => b.toString(16).padStart(2, '0')).join(''),
+        Array.from(bytes.slice(0, 4))
+          .map((b) => b.toString(16).padStart(2, '0'))
+          .join(''),
+        Array.from(bytes.slice(4, 6))
+          .map((b) => b.toString(16).padStart(2, '0'))
+          .join(''),
+        Array.from(bytes.slice(6, 8))
+          .map((b) => b.toString(16).padStart(2, '0'))
+          .join(''),
+        Array.from(bytes.slice(8, 10))
+          .map((b) => b.toString(16).padStart(2, '0'))
+          .join(''),
+        Array.from(bytes.slice(10, 16))
+          .map((b) => b.toString(16).padStart(2, '0'))
+          .join(''),
       ].join('-');
 
       logger.log('[funnel] Generated UUID using crypto.getRandomValues():', uuid);

package/src/impl/couch/adminDB.ts

@@ -80,8 +80,7 @@ export class AdminDB implements AdminDBInterface {
       }
     }
 
-    const dbs = await Promise.all(promisedCRDbs);
-    return dbs.map((db) => {
+    return promisedCRDbs.map((db) => {
       return {
         ...db.getConfig(),
         _id: db._id,