@vue-skuilder/db 0.1.17 → 0.1.20

package/dist/{userDB-BqwxtJ_7.d.mts → classroomDB-CZdMBiTU.d.ts}

@@ -1,6 +1,6 @@
-import { CourseConfig, ClassroomConfig, CourseElo, Status, SkuilderCourseData as SkuilderCourseData$1, DataShape } from '@vue-skuilder/common';
+import { CourseConfig, ClassroomConfig, CourseElo, Status, SkuilderCourseData as SkuilderCourseData$1, 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.mjs';
+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
@@ -104,103 +104,6 @@ interface ScheduledCard {
     schedulingAgentId: string;
 }
 
-type StudySessionFailedItem = StudySessionFailedNewItem | StudySessionFailedReviewItem;
-interface StudySessionFailedNewItem extends StudySessionItem {
-    status: 'failed-new';
-}
-interface StudySessionFailedReviewItem extends StudySessionReviewItem {
-    status: 'failed-review';
-}
-interface StudySessionNewItem extends StudySessionItem {
-    status: 'new';
-}
-interface StudySessionReviewItem extends StudySessionItem {
-    reviewID: string;
-    status: 'review' | 'failed-review';
-}
-declare function isReview(item: StudySessionItem): item is StudySessionReviewItem;
-interface StudySessionItem {
-    status: 'new' | 'review' | 'failed-new' | 'failed-review';
-    contentSourceType: 'course' | 'classroom';
-    contentSourceID: string;
-    cardID: string;
-    courseID: string;
-    elo?: number;
-}
-interface ContentSourceID {
-    type: 'course' | 'classroom';
-    id: string;
-}
-interface StudyContentSource {
-    getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]>;
-    getNewCards(n?: number): Promise<StudySessionNewItem[]>;
-}
-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;
-}
-
 interface DataLayerResult {
     status: Status;
     message: string;
@@ -255,10 +158,6 @@ interface NavigationStrategyManager {
      * @returns A promise that resolves when the update is complete
      */
     updateNavigationStrategy(id: string, data: ContentNavigationStrategyData): Promise<void>;
-    /**
-     * @returns A content navigation strategy suitable to the current context.
-     */
-    surfaceNavigationStrategy(): Promise<ContentNavigationStrategyData>;
 }
 
 /**
@@ -323,6 +222,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
      */
@@ -424,6 +335,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
      */
@@ -488,6 +410,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
@@ -542,4 +482,387 @@ interface ClassroomRegistrationDoc {
     registrations: ClassroomRegistration[];
 }
 
-export { type AdminDBInterface as A, type ClassroomRegistrationDesignation as B, type CourseDBInterface as C, type DataLayerResult as D, type ClassroomRegistration as E, type ClassroomRegistrationDoc as F, type SessionTrackingData as G, type UserConfig as H, type ActivityRecord as I, type CourseRegistration as J, type DocumentUpdater as K, newInterval as L, type StudySessionNewItem as S, type TeacherClassroomDBInterface as T, type UserDBInterface as U, 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, type StudySessionItem as k, type StudySessionFailedItem as l, type StudySessionFailedNewItem as m, type StudySessionFailedReviewItem as n, isReview as o, type ContentSourceID as p, getStudySource as q, type CourseRegistrationDoc as r, type AssignedTag as s, type AssignedCourse as t, type AssignedCard as u, type UserDBWriter as v, type UserDBAuthenticator as w, type UserCourseSettings as x, type UserCourseSetting as y, type UsrCrsDataInterface as z };
+/**
+ * Tracks a single strategy's contribution to a card's final score.
+ *
+ * Each strategy in the pipeline adds a StrategyContribution entry to the
+ * card's provenance array, creating an audit trail of scoring decisions.
+ */
+interface StrategyContribution {
+    /**
+     * Strategy type (implementing class name).
+     * Examples: 'elo', 'hierarchyDefinition', 'interferenceMitigator'
+     */
+    strategy: string;
+    /**
+     * Human-readable name identifying this specific strategy instance.
+     * Extracted from ContentNavigationStrategyData.name.
+     * Courses may have multiple instances of the same strategy type with
+     * different configurations.
+     *
+     * Examples:
+     * - "ELO (default)"
+     * - "Interference: b/d/p confusion"
+     * - "Interference: phonetic confusables"
+     * - "Priority: Common letters first"
+     */
+    strategyName: string;
+    /**
+     * Unique database document ID for this strategy instance.
+     * Extracted from ContentNavigationStrategyData._id.
+     * Use this to fetch the full strategy configuration document.
+     *
+     * Examples:
+     * - "NAVIGATION_STRATEGY-ELO-default"
+     * - "NAVIGATION_STRATEGY-interference-bdp"
+     * - "NAVIGATION_STRATEGY-priority-common-letters"
+     */
+    strategyId: string;
+    /**
+     * What the strategy did:
+     * - 'generated': Strategy produced this card (generators only)
+     * - 'passed': Strategy evaluated but didn't change score (transparent pass-through)
+     * - 'boosted': Strategy increased the score
+     * - 'penalized': Strategy decreased the score
+     */
+    action: 'generated' | 'passed' | 'boosted' | 'penalized';
+    /** Score after this strategy's processing */
+    score: number;
+    /**
+     * Human-readable explanation of the strategy's decision.
+     *
+     * Examples:
+     * - "ELO distance 75, new card"
+     * - "Prerequisites met: letter-sounds"
+     * - "Interferes with immature tag 'd' (decay 0.8)"
+     * - "High-priority tag 's' (0.95) → boost 1.15x"
+     *
+     * Required for transparency - silent adjusters are anti-patterns.
+     */
+    reason: string;
+}
+/**
+ * A card with a suitability score and provenance trail.
+ *
+ * Scores range from 0-1:
+ * - 1.0 = fully suitable
+ * - 0.0 = hard filter (e.g., prerequisite not met)
+ * - 0.5 = neutral
+ * - Intermediate values = soft preference
+ *
+ * Provenance tracks the scoring pipeline:
+ * - First entry: Generator that produced the card
+ * - Subsequent entries: Filters that transformed the score
+ * - Each entry includes action and human-readable reason
+ */
+interface WeightedCard {
+    cardId: string;
+    courseId: string;
+    /** Suitability score from 0-1 */
+    score: number;
+    /**
+     * Audit trail of strategy contributions.
+     * 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[];
+}
+/**
+ * Extract card origin from provenance trail.
+ *
+ * The first provenance entry (from the generator) indicates whether
+ * this is a new card, review, or failed card. We parse the reason
+ * string to extract this information.
+ *
+ * @param card - Card with provenance trail
+ * @returns Card origin ('new', 'review', or 'failed')
+ */
+declare function getCardOrigin(card: WeightedCard): 'new' | 'review' | 'failed';
+declare enum Navigators {
+    ELO = "elo",
+    SRS = "srs",
+    HARDCODED = "hardcodedOrder",
+    HIERARCHY = "hierarchyDefinition",
+    INTERFERENCE = "interferenceMitigator",
+    RELATIVE_PRIORITY = "relativePriority",
+    USER_TAG_PREFERENCE = "userTagPreference"
+}
+/**
+ * Role classification for navigation strategies.
+ *
+ * - GENERATOR: Produces candidate cards with initial scores
+ * - FILTER: Transforms cards with score multipliers
+ */
+declare enum NavigatorRole {
+    GENERATOR = "generator",
+    FILTER = "filter"
+}
+/**
+ * Registry mapping navigator implementations to their roles.
+ */
+declare const NavigatorRoles: Record<Navigators, NavigatorRole>;
+/**
+ * Check if a navigator implementation is a generator.
+ *
+ * @param impl - Navigator implementation name (e.g., 'elo', 'hierarchyDefinition')
+ * @returns true if the navigator is a generator, false otherwise
+ */
+declare function isGenerator(impl: string): boolean;
+/**
+ * Check if a navigator implementation is a filter.
+ *
+ * @param impl - Navigator implementation name (e.g., 'elo', 'hierarchyDefinition')
+ * @returns true if the navigator is a filter, false otherwise
+ */
+declare function isFilter(impl: string): boolean;
+/**
+ * Abstract base class for navigation strategies.
+ *
+ * This class exists primarily for backward compatibility with legacy code.
+ * New code should use CardGenerator or CardFilter interfaces directly.
+ *
+ * The class implements StudyContentSource for compatibility with SessionController.
+ * Once SessionController migrates to use getWeightedCards() exclusively,
+ * the legacy methods can be removed.
+ */
+declare abstract class ContentNavigator implements StudyContentSource {
+    /** User interface for this navigation session */
+    protected user?: UserDBInterface;
+    /** Course interface for this navigation session */
+    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) */
+    protected strategyId?: string;
+    /**
+     * 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.
+     */
+    constructor(user?: UserDBInterface, course?: CourseDBInterface, strategyData?: ContentNavigationStrategyData);
+    /**
+     * 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;
+    /**
+     * 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 getStrategyState<T>(): Promise<T | null>;
+    /**
+     * 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 putStrategyState<T>(data: T): Promise<void>;
+    /**
+     * Factory method to create navigator instances dynamically.
+     *
+     * @param user - User interface
+     * @param course - Course interface
+     * @param strategyData - Strategy configuration document
+     * @returns the runtime object used to steer a study session.
+     */
+    static create(user: UserDBInterface, course: CourseDBInterface, strategyData: ContentNavigationStrategyData): Promise<ContentNavigator>;
+    /**
+     * 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.
+     *
+     * **This is the PRIMARY API for navigation strategies.**
+     *
+     * Returns cards ranked by suitability score (0-1). Higher scores indicate
+     * better candidates for presentation. Each card includes a provenance trail
+     * documenting how strategies contributed to the final score.
+     *
+     * ## 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.
+     *
+     * @param limit - Maximum cards to return
+     * @returns Cards sorted by score descending, with provenance trails
+     */
+    getWeightedCards(limit: number): Promise<WeightedCard[]>;
+}
+
+type StudySessionFailedItem = StudySessionFailedNewItem | StudySessionFailedReviewItem;
+interface StudySessionFailedNewItem extends StudySessionItem {
+    status: 'failed-new';
+}
+interface StudySessionFailedReviewItem extends StudySessionReviewItem {
+    status: 'failed-review';
+}
+interface StudySessionNewItem extends StudySessionItem {
+    status: 'new';
+}
+interface StudySessionReviewItem extends StudySessionItem {
+    reviewID: string;
+    status: 'review' | 'failed-review';
+}
+declare function isReview(item: StudySessionItem): item is StudySessionReviewItem;
+interface StudySessionItem {
+    status: 'new' | 'review' | 'failed-new' | 'failed-review';
+    contentSourceType: 'course' | 'classroom';
+    contentSourceID: string;
+    cardID: string;
+    courseID: string;
+    elo?: number;
+}
+interface ContentSourceID {
+    type: 'course' | 'classroom';
+    id: string;
+    /**
+     * Optional tag filter for scoped study sessions.
+     * When present, creates a TagFilteredContentSource instead of a regular course source.
+     */
+    tagFilter?: TagFilter;
+}
+/**
+ * Interface for sources that provide study content to SessionController.
+ *
+ * @deprecated This interface will be superseded by ContentNavigator.getWeightedCards().
+ * The getNewCards/getPendingReviews split was an artifact of hard-coded ELO and SRS
+ * strategies. The new API returns unified WeightedCard[] with scores.
+ *
+ * MIGRATION:
+ * - Implement ContentNavigator instead of StudyContentSource directly
+ * - Override getWeightedCards() as the primary method
+ * - Legacy methods can delegate to getWeightedCards() or be left as-is
+ *
+ * See: packages/db/src/core/navigators/ARCHITECTURE.md
+ */
+interface StudyContentSource {
+    /**
+     * Get cards scheduled for review based on SRS algorithm.
+     *
+     * @deprecated Will be replaced by getWeightedCards() which returns scored candidates.
+     * Review urgency will be expressed as a score rather than a separate method.
+     */
+    getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]>;
+    /**
+     * Get new cards for introduction, typically ordered by ELO proximity.
+     *
+     * @deprecated Will be replaced by getWeightedCards() which returns scored candidates.
+     * New card selection and scoring will be unified with review scoring.
+     *
+     * @param n - Maximum number of new cards to return
+     */
+    getNewCards(n?: number): Promise<StudySessionNewItem[]>;
+    /**
+     * Get cards with suitability scores for presentation.
+     *
+     * This is the PRIMARY API for content sources going forward. Returns unified
+     * scored candidates that can be sorted and selected by SessionController.
+     *
+     * The `source` field on WeightedCard indicates origin ('new' | 'review' | 'failed')
+     * for queue routing purposes during the migration period.
+     *
+     * @param limit - Maximum number of cards to return
+     * @returns Cards sorted by score descending
+     */
+    getWeightedCards?(limit: number): Promise<WeightedCard[]>;
+}
+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 };