@vue-skuilder/db 0.1.20 → 0.1.22

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-CZdMBiTU.d.ts → contentSource-BP9hznNV.d.ts}

@@ -1,4 +1,4 @@
-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-DDY4N-Uq.js';
 
@@ -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
      */
@@ -285,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 {
@@ -570,6 +625,12 @@ interface WeightedCard {
      * 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.
@@ -585,7 +646,6 @@ declare function getCardOrigin(card: WeightedCard): 'new' | 'review' | 'failed';
 declare enum Navigators {
     ELO = "elo",
     SRS = "srs",
-    HARDCODED = "hardcodedOrder",
     HIERARCHY = "hierarchyDefinition",
     INTERFERENCE = "interferenceMitigator",
     RELATIVE_PRIORITY = "relativePriority",
@@ -631,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) */
@@ -642,7 +702,8 @@ 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);
     /**
@@ -676,22 +737,6 @@ declare abstract class ContentNavigator implements StudyContentSource {
      * @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.
      *
@@ -701,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;
@@ -757,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.
- *
- * MIGRATION:
- * - Implement ContentNavigator instead of StudyContentSource directly
- * - Override getWeightedCards() as the primary method
- * - Legacy methods can delegate to getWeightedCards() or be left as-is
+ * Content sources return scored candidates via getWeightedCards(), which
+ * SessionController uses to populate study queues.
  *
- * 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 };