@vue-skuilder/db 0.1.18 → 0.1.21

package/CLAUDE.md

@@ -6,7 +6,7 @@ Database abstraction layer providing unified interfaces for CouchDB/PouchDB and
 - Build: `yarn workspace @vue-skuilder/db build`
 - Dev (watch): `yarn workspace @vue-skuilder/db dev`
 - Lint: `yarn workspace @vue-skuilder/db lint:fix`
-- Type check: `tsc --noEmit` (no dedicated script)
+- Test: `yarn workspace @vue-skuilder/db test`
 
 ## Build System
 Uses **tsup** for dual CommonJS/ESM output:
@@ -40,4 +40,4 @@ Multiple entry points for different use cases:
 - **Provider Pattern**: Switchable backend implementations
 - **Dual Export**: Works in both Node.js and browser environments  
 - **Type Safety**: Full TypeScript coverage with strict mode
-- **Sync Strategy**: Configurable online/offline data synchronization
+- **Sync Strategy**: Configurable online/offline data synchronization

package/dist/{classroomDB-BgfrVb8d.d.ts → contentSource-BP9hznNV.d.ts}

@@ -1,6 +1,6 @@
-import { CourseConfig, ClassroomConfig, CourseElo, Status, SkuilderCourseData as SkuilderCourseData$1, DataShape, TagFilter } from '@vue-skuilder/common';
+import { CourseConfig, ClassroomConfig, Status, SkuilderCourseData as SkuilderCourseData$1, CourseElo, DataShape, TagFilter } from '@vue-skuilder/common';
 import { Moment } from 'moment';
-import { S as SkuilderCourseData, b as DocTypePrefixes, D as DocType, Q as QualifiedCardID, T as TagStub, a as Tag, C as CardHistory, c as CardRecord } from './types-legacy-6ettoclI.js';
+import { S as SkuilderCourseData, b as DocTypePrefixes, D as DocType, Q as QualifiedCardID, T as TagStub, a as Tag, C as CardHistory, c as CardRecord } from './types-legacy-DDY4N-Uq.js';
 
 /**
  * Admin functionality
@@ -26,82 +26,63 @@ interface AdminDBInterface {
     })[]>;
 }
 
-interface SessionTrackingData {
-    peekSessionCount: number;
-    studySessionCount: number;
-    sessionCount: number;
-    firstSessionDate: string;
-    lastSessionDate: string;
-    signupPrompted: boolean;
-    promptDismissalCount: number;
-    studyModeAcknowledged: boolean;
-}
-interface UserConfig {
-    darkMode: boolean;
-    likesConfetti: boolean;
-    sessionTimeLimit: number;
-    email?: string;
-    sessionTracking?: Record<string, SessionTrackingData>;
-}
-interface ActivityRecord {
-    timeStamp: number | string;
-    [key: string]: any;
-}
-interface CourseRegistration {
-    status?: 'active' | 'dropped' | 'maintenance-mode' | 'preview';
-    courseID: string;
-    admin: boolean;
-    moderator: boolean;
-    user: boolean;
-    settings?: {
-        [setting: string]: string | number | boolean;
-    };
-    elo: number | CourseElo;
-}
-interface StudyWeights {
-    [courseID: string]: number;
-}
-interface CourseRegistrationDoc {
-    courses: CourseRegistration[];
-    studyWeight: StudyWeights;
-}
-interface ScheduledCard {
-    _id: PouchDB.Core.DocumentId;
+/**
+ * Classroom management
+ */
+interface ClassroomDBInterface {
     /**
-     * The docID of the card to be reviewed
+     * Get classroom config
      */
-    cardId: PouchDB.Core.DocumentId;
+    getConfig(): ClassroomConfig;
     /**
-     * The ID of the course
+     * Get assigned content
      */
-    courseId: string;
+    getAssignedContent(): Promise<AssignedContent[]>;
+}
+interface TeacherClassroomDBInterface extends ClassroomDBInterface {
     /**
-     * The time at which the card becomes eligible for review.
-     *
-     * (Should probably be UTC adjusted so that performance is
-     * not wonky across time zones)
-     *
-     * Note: Stored as ISO string for PouchDB serialization compatibility,
-     * but can be consumed as Moment objects via moment.utc(reviewTime)
+     * For teacher interfaces: assign content
      */
-    reviewTime: string | Moment;
+    assignContent?(content: AssignedContent): Promise<boolean>;
     /**
-     * The time at which this scheduled event was created.
-     *
-     * Note: Stored as ISO string for PouchDB serialization compatibility,
-     * but can be consumed as Moment objects via moment.utc(scheduledAt)
+     * For teacher interfaces: remove content
      */
-    scheduledAt: string | Moment;
+    removeContent?(content: AssignedContent): Promise<void>;
+}
+/**
+ * Student-facing classroom interface.
+ * Content is accessed via StudyContentSource.getWeightedCards().
+ */
+type StudentClassroomDBInterface = ClassroomDBInterface;
+type AssignedContent = AssignedCourse | AssignedTag | AssignedCard;
+interface AssignedTag extends ContentBase {
+    type: 'tag';
+    tagID: string;
+}
+interface AssignedCourse extends ContentBase {
+    type: 'course';
+}
+interface AssignedCard extends ContentBase {
+    type: 'card';
+    cardID: string;
+}
+interface ContentBase {
+    type: 'course' | 'tag' | 'card';
     /**
-     * Classifying whether this card is scheduled on behalf of a
-     * user-registered course or by as assigned content from a
-     * user-registered classroom
+     * Username of the assigning teacher.
      */
-    scheduledFor: 'course' | 'classroom';
+    assignedBy: string;
     /**
-     * The ID of the course or classroom that requested this card
+     * Date the content was assigned.
      */
-    schedulingAgentId: string;
+    assignedOn: moment.Moment;
+    /**
+     * A 'due' date for this assigned content, for scheduling content
+     * in advance. Content will not be actively pushed to students until
+     * this date.
+     */
+    activeOn: moment.Moment;
+    courseID: string;
 }
 
 interface DataLayerResult {
@@ -178,7 +159,7 @@ interface CourseInfo {
     cardCount: number;
     registeredUsers: number;
 }
-interface CourseDBInterface extends NavigationStrategyManager {
+interface CourseDBInterface extends NavigationStrategyManager, StudyContentSource {
     /**
      * Get course config
      */
@@ -207,10 +188,6 @@ interface CourseDBInterface extends NavigationStrategyManager {
      * Update card ELO rating
      */
     updateCardElo(cardId: string, elo: CourseElo): Promise<PouchDB.Core.Response>;
-    /**
-     * Get new cards for study
-     */
-    getNewCards(limit?: number): Promise<StudySessionNewItem[]>;
     /**
      * Get cards centered at a particular ELO rating
      */
@@ -222,6 +199,18 @@ interface CourseDBInterface extends NavigationStrategyManager {
      * Get tags for a card
      */
     getAppliedTags(cardId: string): Promise<PouchDB.Query.Response<TagStub>>;
+    /**
+     * Get tags for multiple cards in a single batch query.
+     * More efficient than calling getAppliedTags() for each card.
+     *
+     * This method reduces redundant database operations when multiple filters
+     * need tag data for the same cards. The Pipeline uses this to pre-hydrate
+     * tags on WeightedCard objects before filters run.
+     *
+     * @param cardIds - Array of card IDs to fetch tags for
+     * @returns Map from cardId to array of tag names
+     */
+    getAppliedTagsBatch(cardIds: string[]): Promise<Map<string, string[]>>;
     /**
      * Add a tag to a card
      */
@@ -273,6 +262,84 @@ interface CourseDBInterface extends NavigationStrategyManager {
     find(request: PouchDB.Find.FindRequest<any>): Promise<PouchDB.Find.FindResponse<any>>;
 }
 
+interface SessionTrackingData {
+    peekSessionCount: number;
+    studySessionCount: number;
+    sessionCount: number;
+    firstSessionDate: string;
+    lastSessionDate: string;
+    signupPrompted: boolean;
+    promptDismissalCount: number;
+    studyModeAcknowledged: boolean;
+}
+interface UserConfig {
+    darkMode: boolean;
+    likesConfetti: boolean;
+    sessionTimeLimit: number;
+    email?: string;
+    sessionTracking?: Record<string, SessionTrackingData>;
+}
+interface ActivityRecord {
+    timeStamp: number | string;
+    [key: string]: any;
+}
+interface CourseRegistration {
+    status?: 'active' | 'dropped' | 'maintenance-mode' | 'preview';
+    courseID: string;
+    admin: boolean;
+    moderator: boolean;
+    user: boolean;
+    settings?: {
+        [setting: string]: string | number | boolean;
+    };
+    elo: number | CourseElo;
+}
+interface StudyWeights {
+    [courseID: string]: number;
+}
+interface CourseRegistrationDoc {
+    courses: CourseRegistration[];
+    studyWeight: StudyWeights;
+}
+interface ScheduledCard {
+    _id: PouchDB.Core.DocumentId;
+    /**
+     * The docID of the card to be reviewed
+     */
+    cardId: PouchDB.Core.DocumentId;
+    /**
+     * The ID of the course
+     */
+    courseId: string;
+    /**
+     * The time at which the card becomes eligible for review.
+     *
+     * (Should probably be UTC adjusted so that performance is
+     * not wonky across time zones)
+     *
+     * Note: Stored as ISO string for PouchDB serialization compatibility,
+     * but can be consumed as Moment objects via moment.utc(reviewTime)
+     */
+    reviewTime: string | Moment;
+    /**
+     * The time at which this scheduled event was created.
+     *
+     * Note: Stored as ISO string for PouchDB serialization compatibility,
+     * but can be consumed as Moment objects via moment.utc(scheduledAt)
+     */
+    scheduledAt: string | Moment;
+    /**
+     * Classifying whether this card is scheduled on behalf of a
+     * user-registered course or by as assigned content from a
+     * user-registered classroom
+     */
+    scheduledFor: 'course' | 'classroom';
+    /**
+     * The ID of the course or classroom that requested this card
+     */
+    schedulingAgentId: string;
+}
+
 type Update<T> = Partial<T> | ((x: T) => T);
 
 interface DocumentUpdater {
@@ -323,6 +390,17 @@ interface UserDBReader {
      */
     getPendingReviews(courseId?: string): Promise<ScheduledCard[]>;
     getActivityRecords(): Promise<ActivityRecord[]>;
+    /**
+     * Get strategy-specific state for a course.
+     *
+     * Strategies use this to persist preferences, learned patterns, or temporal
+     * tracking data across sessions. Each strategy owns its own namespace.
+     *
+     * @param courseId - The course this state applies to
+     * @param strategyKey - Unique key identifying the strategy (typically class name)
+     * @returns The strategy's data payload, or null if no state exists
+     */
+    getStrategyState<T>(courseId: string, strategyKey: string): Promise<T | null>;
     /**
      * Get user's classroom registrations
      */
@@ -387,6 +465,24 @@ interface UserDBWriter extends DocumentUpdater {
         status: Status;
         error?: string;
     }>;
+    /**
+     * Store strategy-specific state for a course.
+     *
+     * Strategies use this to persist preferences, learned patterns, or temporal
+     * tracking data across sessions. Each strategy owns its own namespace.
+     *
+     * @param courseId - The course this state applies to
+     * @param strategyKey - Unique key identifying the strategy (typically class name)
+     * @param data - The strategy's data payload to store
+     */
+    putStrategyState<T>(courseId: string, strategyKey: string, data: T): Promise<void>;
+    /**
+     * Delete strategy-specific state for a course.
+     *
+     * @param courseId - The course this state applies to
+     * @param strategyKey - Unique key identifying the strategy (typically class name)
+     */
+    deleteStrategyState(courseId: string, strategyKey: string): Promise<void>;
 }
 /**
  * Authentication and account management operations
@@ -524,6 +620,17 @@ 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;
 }
 /**
  * Extract card origin from provenance trail.
@@ -539,10 +646,10 @@ declare function getCardOrigin(card: WeightedCard): 'new' | 'review' | 'failed';
 declare enum Navigators {
     ELO = "elo",
     SRS = "srs",
-    HARDCODED = "hardcodedOrder",
     HIERARCHY = "hierarchyDefinition",
     INTERFERENCE = "interferenceMitigator",
-    RELATIVE_PRIORITY = "relativePriority"
+    RELATIVE_PRIORITY = "relativePriority",
+    USER_TAG_PREFERENCE = "userTagPreference"
 }
 /**
  * Role classification for navigation strategies.
@@ -584,9 +691,9 @@ declare function isFilter(impl: string): boolean;
  */
 declare 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;
     /** Unique document ID for this strategy instance (from ContentNavigationStrategyData._id) */
@@ -595,34 +702,41 @@ declare 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);
     /**
-     * Factory method to create navigator instances dynamically.
+     * Unique key identifying this strategy for state storage.
      *
-     * @param user - User interface
-     * @param course - Course interface
-     * @param strategyData - Strategy configuration document
-     * @returns the runtime object used to steer a study session.
+     * Defaults to the constructor name (e.g., "UserTagPreferenceFilter").
+     * Override in subclasses if multiple instances of the same strategy type
+     * need separate state storage.
      */
-    static create(user: UserDBInterface, course: CourseDBInterface, strategyData: ContentNavigationStrategyData): Promise<ContentNavigator>;
+    protected get strategyKey(): string;
     /**
-     * Get cards scheduled for review.
+     * Get this strategy's persisted state for the current course.
      *
-     * @deprecated This method is part of the legacy StudyContentSource interface.
-     * New strategies should focus on implementing CardGenerator.getWeightedCards() instead.
+     * @returns The strategy's data payload, or null if no state exists
+     * @throws Error if user or course is not initialized
      */
-    abstract getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]>;
+    protected getStrategyState<T>(): Promise<T | null>;
     /**
-     * Get new cards for introduction.
+     * Persist this strategy's state for the current course.
      *
-     * @deprecated This method is part of the legacy StudyContentSource interface.
-     * New strategies should focus on implementing CardGenerator.getWeightedCards() instead.
+     * @param data - The strategy's data payload to store
+     * @throws Error if user or course is not initialized
+     */
+    protected putStrategyState<T>(data: T): Promise<void>;
+    /**
+     * Factory method to create navigator instances dynamically.
      *
-     * @param n - Maximum number of new cards to return
+     * @param user - User interface
+     * @param course - Course interface
+     * @param strategyData - Strategy configuration document
+     * @returns the runtime object used to steer a study session.
      */
-    abstract getNewCards(n?: number): Promise<StudySessionNewItem[]>;
+    static create(user: UserDBInterface, course: CourseDBInterface, strategyData: ContentNavigationStrategyData): Promise<ContentNavigator>;
     /**
      * Get cards with suitability scores and provenance trails.
      *
@@ -632,25 +746,23 @@ declare 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
      */
-    getWeightedCards(limit: number): Promise<WeightedCard[]>;
+    getWeightedCards(_limit: number): Promise<WeightedCard[]>;
 }
 
 type StudySessionFailedItem = StudySessionFailedNewItem | StudySessionFailedReviewItem;
@@ -688,112 +800,23 @@ interface ContentSourceID {
 /**
  * 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.
+ * Content sources return scored candidates via getWeightedCards(), which
+ * SessionController uses to populate study queues.
  *
- * 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
+ * See: packages/db/docs/navigators-architecture.md
  */
 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.
+     * Returns unified scored candidates that can be sorted and selected by SessionController.
+     * The card origin ('new' | 'review' | 'failed') is determined by provenance metadata.
      *
      * @param limit - Maximum number of cards to return
      * @returns Cards sorted by score descending
      */
-    getWeightedCards?(limit: number): Promise<WeightedCard[]>;
+    getWeightedCards(limit: number): Promise<WeightedCard[]>;
 }
 declare function getStudySource(source: ContentSourceID, user: UserDBInterface): Promise<StudyContentSource>;
 
-/**
- * Classroom management
- */
-interface ClassroomDBInterface {
-    /**
-     * Get classroom config
-     */
-    getConfig(): ClassroomConfig;
-    /**
-     * Get assigned content
-     */
-    getAssignedContent(): Promise<AssignedContent[]>;
-}
-interface TeacherClassroomDBInterface extends ClassroomDBInterface {
-    /**
-     * For teacher interfaces: assign content
-     */
-    assignContent?(content: AssignedContent): Promise<boolean>;
-    /**
-     * For teacher interfaces: remove content
-     */
-    removeContent?(content: AssignedContent): Promise<void>;
-}
-interface StudentClassroomDBInterface extends ClassroomDBInterface {
-    /**
-     * For student interfaces: get pending reviews
-     */
-    getPendingReviews?(): Promise<(StudySessionReviewItem & ScheduledCard)[]>;
-    /**
-     * For student interfaces: get new cards
-     */
-    getNewCards?(limit?: number): Promise<StudySessionNewItem[]>;
-}
-type AssignedContent = AssignedCourse | AssignedTag | AssignedCard;
-interface AssignedTag extends ContentBase {
-    type: 'tag';
-    tagID: string;
-}
-interface AssignedCourse extends ContentBase {
-    type: 'course';
-}
-interface AssignedCard extends ContentBase {
-    type: 'card';
-    cardID: string;
-}
-interface ContentBase {
-    type: 'course' | 'tag' | 'card';
-    /**
-     * Username of the assigning teacher.
-     */
-    assignedBy: string;
-    /**
-     * Date the content was assigned.
-     */
-    assignedOn: moment.Moment;
-    /**
-     * A 'due' date for this assigned content, for scheduling content
-     * in advance. Content will not be actively pushed to students until
-     * this date.
-     */
-    activeOn: moment.Moment;
-    courseID: string;
-}
-
-export { type AdminDBInterface as A, type UsrCrsDataInterface as B, type CourseDBInterface as C, type DataLayerResult as D, type ClassroomRegistrationDesignation as E, type ClassroomRegistration as F, type ClassroomRegistrationDoc as G, type SessionTrackingData as H, type UserConfig as I, type ActivityRecord as J, type CourseRegistration as K, type StrategyContribution as L, getCardOrigin as M, Navigators as N, NavigatorRole as O, NavigatorRoles as P, isGenerator as Q, isFilter as R, type StudySessionNewItem as S, type TeacherClassroomDBInterface as T, type UserDBInterface as U, type DocumentUpdater as V, type WeightedCard as W, newInterval as X, type UserDBReader as a, type CoursesDBInterface as b, type ClassroomDBInterface as c, type CourseInfo as d, type ContentNavigationStrategyData as e, type StudySessionReviewItem as f, type ScheduledCard as g, type AssignedContent as h, type StudyContentSource as i, type StudentClassroomDBInterface as j, ContentNavigator as k, type StudySessionItem as l, type StudySessionFailedItem as m, type StudySessionFailedNewItem as n, type StudySessionFailedReviewItem as o, isReview as p, type ContentSourceID as q, getStudySource as r, type CourseRegistrationDoc as s, type AssignedTag as t, type AssignedCourse as u, type AssignedCard as v, type UserDBWriter as w, type UserDBAuthenticator as x, type UserCourseSettings as y, type UserCourseSetting as z };
+export { type AdminDBInterface as A, type UsrCrsDataInterface as B, type CourseDBInterface as C, type DataLayerResult as D, type ClassroomRegistrationDesignation as E, type ClassroomRegistration as F, type ClassroomRegistrationDoc as G, type SessionTrackingData as H, type UserConfig as I, type ActivityRecord as J, type CourseRegistration as K, type StrategyContribution as L, getCardOrigin as M, Navigators as N, NavigatorRole as O, NavigatorRoles as P, isGenerator as Q, isFilter as R, type StudySessionItem as S, type TeacherClassroomDBInterface as T, type UserDBInterface as U, type DocumentUpdater as V, type WeightedCard as W, newInterval as X, type UserDBReader as a, type CoursesDBInterface as b, type ClassroomDBInterface as c, type CourseInfo as d, type ContentNavigationStrategyData as e, ContentNavigator as f, type AssignedContent as g, type StudyContentSource as h, type StudentClassroomDBInterface as i, type ScheduledCard as j, type StudySessionFailedItem as k, type StudySessionFailedNewItem as l, type StudySessionFailedReviewItem as m, type StudySessionNewItem as n, type StudySessionReviewItem as o, isReview as p, type ContentSourceID as q, getStudySource as r, type CourseRegistrationDoc as s, type AssignedTag as t, type AssignedCourse as u, type AssignedCard as v, type UserDBWriter as w, type UserDBAuthenticator as x, type UserCourseSettings as y, type UserCourseSetting as z };