@vue-skuilder/db 0.1.31-b → 0.1.31

package/dist/index.d.cts

@@ -1,6 +1,6 @@
-import { U as UserDBInterface, s as CourseRegistrationDoc, S as StudySessionItem, W as WeightedCard, h as StudyContentSource, C as CourseDBInterface } from './contentSource-B7nXusjk.cjs';
-export { J as ActivityRecord, A as AdminDBInterface, v as AssignedCard, g as AssignedContent, u as AssignedCourse, t as AssignedTag, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, G as ClassroomRegistrationDoc, e as ContentNavigationStrategyData, f as ContentNavigator, q as ContentSourceID, d as CourseInfo, K as CourseRegistration, b as CoursesDBInterface, a8 as DocumentUpdater, a2 as LearnableWeight, N as NavigatorConstructor, _ as NavigatorRole, $ as NavigatorRoles, Z as Navigators, a3 as OrchestrationContext, j as ScheduledCard, H as SessionTrackingData, X as StrategyContribution, i as StudentClassroomDBInterface, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, n as StudySessionNewItem, o as StudySessionReviewItem, T as TeacherClassroomDBInterface, I as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, L as UserOutcomeRecord, B as UsrCrsDataInterface, a4 as computeDeviation, a6 as computeEffectiveWeight, a5 as computeSpread, a7 as createOrchestrationContext, Y as getCardOrigin, O as getRegisteredNavigator, R as getRegisteredNavigatorNames, Q as getRegisteredNavigatorRole, r as getStudySource, P as hasRegisteredNavigator, V as initializeNavigatorRegistry, a1 as isFilter, a0 as isGenerator, p as isReview, a9 as newInterval, M as registerNavigator } from './contentSource-B7nXusjk.cjs';
-import { D as DataLayerProvider } from './dataLayerProvider-BW7HvkMt.cjs';
+import { U as UserDBInterface, s as CourseRegistrationDoc, S as StudySessionItem, W as WeightedCard, h as StudyContentSource, C as CourseDBInterface } from './contentSource-DF1nUbPQ.cjs';
+export { J as ActivityRecord, A as AdminDBInterface, v as AssignedCard, g as AssignedContent, u as AssignedCourse, t as AssignedTag, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, G as ClassroomRegistrationDoc, e as ContentNavigationStrategyData, f as ContentNavigator, q as ContentSourceID, d as CourseInfo, K as CourseRegistration, b as CoursesDBInterface, a8 as DocumentUpdater, a2 as LearnableWeight, N as NavigatorConstructor, _ as NavigatorRole, $ as NavigatorRoles, Z as Navigators, a3 as OrchestrationContext, j as ScheduledCard, H as SessionTrackingData, X as StrategyContribution, i as StudentClassroomDBInterface, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, n as StudySessionNewItem, o as StudySessionReviewItem, T as TeacherClassroomDBInterface, I as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, L as UserOutcomeRecord, B as UsrCrsDataInterface, a4 as computeDeviation, a6 as computeEffectiveWeight, a5 as computeSpread, a7 as createOrchestrationContext, Y as getCardOrigin, O as getRegisteredNavigator, R as getRegisteredNavigatorNames, Q as getRegisteredNavigatorRole, r as getStudySource, P as hasRegisteredNavigator, V as initializeNavigatorRegistry, a1 as isFilter, a0 as isGenerator, p as isReview, a9 as newInterval, M as registerNavigator } from './contentSource-DF1nUbPQ.cjs';
+import { D as DataLayerProvider } from './dataLayerProvider-BQdfJuBN.cjs';
 import { C as CardHistory, c as CardRecord } from './types-legacy-JXDxinpU.cjs';
 export { d as CardData, e as CourseListData, g as DataShapeData, f as DisplayableData, D as DocType, b as DocTypePrefixes, F as Field, G as GuestUsername, Q as QualifiedCardID, h as QuestionData, i as QuestionRecord, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from './types-legacy-JXDxinpU.cjs';
 import { Loggable } from './core/index.cjs';
@@ -344,6 +344,18 @@ declare class SessionController<TView = unknown> extends Loggable {
     private reviewQ;
     private newQ;
     private failedQ;
+    /**
+     * Promise tracking a currently in-progress replan, or null if idle.
+     * Used by nextCard() to await completion before drawing from queues.
+     */
+    private _replanPromise;
+    /**
+     * Number of well-indicated new cards remaining before the queue
+     * degrades to poorly-indicated content. Decremented on each newQ
+     * draw; when it hits 0, a replan is triggered automatically
+     * (user state has changed from completing good cards).
+     */
+    private _wellIndicatedRemaining;
     private startTime;
     private endTime;
     private _secondsRemaining;
@@ -374,6 +386,41 @@ declare class SessionController<TView = unknown> extends Loggable {
      */
     private estimateReviewTime;
     prepareSession(): Promise<void>;
+    /**
+     * Request a mid-session replan. Re-runs the pipeline with current user state
+     * and atomically replaces the newQ contents. Safe to call at any time during
+     * a session — if called while a replan is already in progress, returns the
+     * existing replan promise (no duplicate work).
+     *
+     * Does NOT affect reviewQ or failedQ.
+     *
+     * If nextCard() is called while a replan is in flight, it will automatically
+     * await the replan before drawing from queues, ensuring the user always sees
+     * cards scored against their latest state.
+     *
+     * Typical trigger: application-level code (e.g. after a GPC intro completion)
+     * calls this to ensure newly-unlocked content appears in the session.
+     */
+    requestReplan(hints?: Record<string, unknown>): Promise<void>;
+    /** Minimum well-indicated cards before an additive retry is attempted */
+    private static readonly MIN_WELL_INDICATED;
+    /**
+     * Score threshold for considering a card "well-indicated."
+     * Cards below this score are treated as fallback filler — present only
+     * because no strategy hard-removed them, but likely penalized by one
+     * or more filters. Strategy-agnostic: the SessionController doesn't
+     * know or care which strategy assigned the score.
+     */
+    private static readonly WELL_INDICATED_SCORE;
+    /**
+     * Internal replan execution. Runs the pipeline, builds a new newQ,
+     * atomically swaps it in, and triggers hydration for the new contents.
+     *
+     * If the initial replan produces fewer than MIN_WELL_INDICATED cards that
+     * pass all hierarchy filters, one additive retry is attempted — merging
+     * any new high-quality candidates into the front of the queue.
+     */
+    private _executeReplan;
     addTime(seconds: number): void;
     get failedCount(): number;
     toString(): string;
@@ -418,6 +465,9 @@ declare class SessionController<TView = unknown> extends Loggable {
             count: number;
             cardIds: string[];
         };
+        replan: {
+            inProgress: boolean;
+        };
     };
     /**
      * Fetch content using the getWeightedCards API and mix across sources.
@@ -428,6 +478,17 @@ declare class SessionController<TView = unknown> extends Loggable {
      * 3. Uses SourceMixer to balance content across sources
      * 4. Populates review and new card queues with mixed results
      */
+    /**
+     * Fetch weighted content from all sources and populate session queues.
+     *
+     * @param options.replan - If true, this is a mid-session replan rather than
+     *   initial session setup. Skips review queue population (avoiding duplicates),
+     *   atomically replaces newQ contents, and treats empty results as non-fatal.
+     * @param options.additive - If true (replan only), merge new high-quality
+     *   candidates into the front of the existing newQ instead of replacing it.
+     * @returns Number of "well-indicated" cards (passed all hierarchy filters)
+     *   in the new content. Returns -1 if no content was loaded.
+     */
     private getWeightedContent;
     /**
      * Returns items that should be pre-hydrated.

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { U as UserDBInterface, s as CourseRegistrationDoc, S as StudySessionItem, W as WeightedCard, h as StudyContentSource, C as CourseDBInterface } from './contentSource-ygoFw9oV.js';
-export { J as ActivityRecord, A as AdminDBInterface, v as AssignedCard, g as AssignedContent, u as AssignedCourse, t as AssignedTag, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, G as ClassroomRegistrationDoc, e as ContentNavigationStrategyData, f as ContentNavigator, q as ContentSourceID, d as CourseInfo, K as CourseRegistration, b as CoursesDBInterface, a8 as DocumentUpdater, a2 as LearnableWeight, N as NavigatorConstructor, _ as NavigatorRole, $ as NavigatorRoles, Z as Navigators, a3 as OrchestrationContext, j as ScheduledCard, H as SessionTrackingData, X as StrategyContribution, i as StudentClassroomDBInterface, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, n as StudySessionNewItem, o as StudySessionReviewItem, T as TeacherClassroomDBInterface, I as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, L as UserOutcomeRecord, B as UsrCrsDataInterface, a4 as computeDeviation, a6 as computeEffectiveWeight, a5 as computeSpread, a7 as createOrchestrationContext, Y as getCardOrigin, O as getRegisteredNavigator, R as getRegisteredNavigatorNames, Q as getRegisteredNavigatorRole, r as getStudySource, P as hasRegisteredNavigator, V as initializeNavigatorRegistry, a1 as isFilter, a0 as isGenerator, p as isReview, a9 as newInterval, M as registerNavigator } from './contentSource-ygoFw9oV.js';
-import { D as DataLayerProvider } from './dataLayerProvider-BfXUVDuG.js';
+import { U as UserDBInterface, s as CourseRegistrationDoc, S as StudySessionItem, W as WeightedCard, h as StudyContentSource, C as CourseDBInterface } from './contentSource-Bdwkvqa8.js';
+export { J as ActivityRecord, A as AdminDBInterface, v as AssignedCard, g as AssignedContent, u as AssignedCourse, t as AssignedTag, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, G as ClassroomRegistrationDoc, e as ContentNavigationStrategyData, f as ContentNavigator, q as ContentSourceID, d as CourseInfo, K as CourseRegistration, b as CoursesDBInterface, a8 as DocumentUpdater, a2 as LearnableWeight, N as NavigatorConstructor, _ as NavigatorRole, $ as NavigatorRoles, Z as Navigators, a3 as OrchestrationContext, j as ScheduledCard, H as SessionTrackingData, X as StrategyContribution, i as StudentClassroomDBInterface, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, n as StudySessionNewItem, o as StudySessionReviewItem, T as TeacherClassroomDBInterface, I as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, L as UserOutcomeRecord, B as UsrCrsDataInterface, a4 as computeDeviation, a6 as computeEffectiveWeight, a5 as computeSpread, a7 as createOrchestrationContext, Y as getCardOrigin, O as getRegisteredNavigator, R as getRegisteredNavigatorNames, Q as getRegisteredNavigatorRole, r as getStudySource, P as hasRegisteredNavigator, V as initializeNavigatorRegistry, a1 as isFilter, a0 as isGenerator, p as isReview, a9 as newInterval, M as registerNavigator } from './contentSource-Bdwkvqa8.js';
+import { D as DataLayerProvider } from './dataLayerProvider-BKmVoyJR.js';
 import { C as CardHistory, c as CardRecord } from './types-legacy-JXDxinpU.js';
 export { d as CardData, e as CourseListData, g as DataShapeData, f as DisplayableData, D as DocType, b as DocTypePrefixes, F as Field, G as GuestUsername, Q as QualifiedCardID, h as QuestionData, i as QuestionRecord, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from './types-legacy-JXDxinpU.js';
 import { Loggable } from './core/index.js';
@@ -344,6 +344,18 @@ declare class SessionController<TView = unknown> extends Loggable {
     private reviewQ;
     private newQ;
     private failedQ;
+    /**
+     * Promise tracking a currently in-progress replan, or null if idle.
+     * Used by nextCard() to await completion before drawing from queues.
+     */
+    private _replanPromise;
+    /**
+     * Number of well-indicated new cards remaining before the queue
+     * degrades to poorly-indicated content. Decremented on each newQ
+     * draw; when it hits 0, a replan is triggered automatically
+     * (user state has changed from completing good cards).
+     */
+    private _wellIndicatedRemaining;
     private startTime;
     private endTime;
     private _secondsRemaining;
@@ -374,6 +386,41 @@ declare class SessionController<TView = unknown> extends Loggable {
      */
     private estimateReviewTime;
     prepareSession(): Promise<void>;
+    /**
+     * Request a mid-session replan. Re-runs the pipeline with current user state
+     * and atomically replaces the newQ contents. Safe to call at any time during
+     * a session — if called while a replan is already in progress, returns the
+     * existing replan promise (no duplicate work).
+     *
+     * Does NOT affect reviewQ or failedQ.
+     *
+     * If nextCard() is called while a replan is in flight, it will automatically
+     * await the replan before drawing from queues, ensuring the user always sees
+     * cards scored against their latest state.
+     *
+     * Typical trigger: application-level code (e.g. after a GPC intro completion)
+     * calls this to ensure newly-unlocked content appears in the session.
+     */
+    requestReplan(hints?: Record<string, unknown>): Promise<void>;
+    /** Minimum well-indicated cards before an additive retry is attempted */
+    private static readonly MIN_WELL_INDICATED;
+    /**
+     * Score threshold for considering a card "well-indicated."
+     * Cards below this score are treated as fallback filler — present only
+     * because no strategy hard-removed them, but likely penalized by one
+     * or more filters. Strategy-agnostic: the SessionController doesn't
+     * know or care which strategy assigned the score.
+     */
+    private static readonly WELL_INDICATED_SCORE;
+    /**
+     * Internal replan execution. Runs the pipeline, builds a new newQ,
+     * atomically swaps it in, and triggers hydration for the new contents.
+     *
+     * If the initial replan produces fewer than MIN_WELL_INDICATED cards that
+     * pass all hierarchy filters, one additive retry is attempted — merging
+     * any new high-quality candidates into the front of the queue.
+     */
+    private _executeReplan;
     addTime(seconds: number): void;
     get failedCount(): number;
     toString(): string;
@@ -418,6 +465,9 @@ declare class SessionController<TView = unknown> extends Loggable {
             count: number;
             cardIds: string[];
         };
+        replan: {
+            inProgress: boolean;
+        };
     };
     /**
      * Fetch content using the getWeightedCards API and mix across sources.
@@ -428,6 +478,17 @@ declare class SessionController<TView = unknown> extends Loggable {
      * 3. Uses SourceMixer to balance content across sources
      * 4. Populates review and new card queues with mixed results
      */
+    /**
+     * Fetch weighted content from all sources and populate session queues.
+     *
+     * @param options.replan - If true, this is a mid-session replan rather than
+     *   initial session setup. Skips review queue population (avoiding duplicates),
+     *   atomically replaces newQ contents, and treats empty results as non-fatal.
+     * @param options.additive - If true (replan only), merge new high-quality
+     *   candidates into the front of the existing newQ instead of replacing it.
+     * @returns Number of "well-indicated" cards (passed all hierarchy filters)
+     *   in the new content. Returns -1 if no content was loaded.
+     */
     private getWeightedContent;
     /**
      * Returns items that should be pre-hydrated.