@vue-skuilder/db 0.1.32-b → 0.1.32-c

package/dist/{contentSource-DF1nUbPQ.d.cts → dataLayerProvider-BJqBlMIl.d.cts}

@@ -1,6 +1,6 @@
-import { CourseConfig, ClassroomConfig, Status, SkuilderCourseData as SkuilderCourseData$1, CourseElo, DataShape, TagFilter } from '@vue-skuilder/common';
+import { CourseConfig, ClassroomConfig, TaggedPerformance, 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-JXDxinpU.cjs';
+import { S as SkuilderCourseData, f as DocTypePrefixes, D as DocType, g as CardHistory, h as CardRecord, Q as QualifiedCardID, T as TagStub, a as Tag } from './types-legacy-C7r0T4OV.cjs';
 
 /**
  * Admin functionality
@@ -85,6 +85,114 @@ interface ContentBase {
     courseID: string;
 }
 
+/**
+ * Service responsible for ELO rating calculations and updates.
+ */
+declare class EloService {
+    private dataLayer;
+    private user;
+    constructor(dataLayer: DataLayerProvider, user: UserDBInterface);
+    /**
+     * Updates both user and card ELO ratings based on user performance.
+     * @param userScore Score between 0-1 representing user performance
+     * @param course_id Course identifier
+     * @param card_id Card identifier
+     * @param userCourseRegDoc User's course registration document (will be mutated)
+     * @param currentCard Current card session record
+     * @param k Optional K-factor for ELO calculation
+     */
+    updateUserAndCardElo(userScore: number, course_id: string, card_id: string, userCourseRegDoc: CourseRegistrationDoc, currentCard: StudySessionRecord, k?: number): Promise<void>;
+    /**
+     * Updates both user and card ELO ratings with per-tag granularity.
+     * Tags in taggedPerformance but not on card will be created dynamically.
+     *
+     * @param taggedPerformance Performance object with _global and per-tag scores
+     * @param course_id Course identifier
+     * @param card_id Card identifier
+     * @param userCourseRegDoc User's course registration document (will be mutated)
+     * @param currentCard Current card session record
+     */
+    updateUserAndCardEloPerTag(taggedPerformance: TaggedPerformance, course_id: string, card_id: string, userCourseRegDoc: CourseRegistrationDoc, currentCard: StudySessionRecord): Promise<void>;
+}
+
+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;
+}
+
 interface DataLayerResult {
     status: Status;
     message: string;
@@ -139,6 +247,455 @@ interface ContentNavigationStrategyData extends SkuilderCourseData {
     staticWeight?: boolean;
 }
 
+/**
+ * Service responsible for Spaced Repetition System (SRS) scheduling logic.
+ */
+declare class SrsService {
+    private user;
+    constructor(user: UserDBInterface);
+    /**
+     * Remove a scheduled review from the user's database.
+     * Used to clean up orphaned reviews (e.g., card deleted from course DB).
+     */
+    removeReview(reviewID: string): void;
+    /**
+     * Calculates the next review time for a card based on its history and
+     * schedules it in the user's database.
+     * @param history The full history of the card.
+     * @param item The study session item, used to determine if a previous review needs to be cleared.
+     */
+    scheduleReview(history: CardHistory<CardRecord>, item: StudySessionItem): Promise<void>;
+}
+
+/**
+ * Service responsible for orchestrating the complete response processing workflow.
+ * Coordinates SRS scheduling and ELO updates for user card interactions.
+ */
+declare class ResponseProcessor {
+    private srsService;
+    private eloService;
+    constructor(srsService: SrsService, eloService: EloService);
+    /**
+     * Parses performance data into global score and optional per-tag scores.
+     *
+     * @param performance - Numeric or structured performance from QuestionRecord
+     * @returns Parsed performance with global score and optional tag scores
+     */
+    private parsePerformance;
+    /**
+     * Processes a user's response to a card, handling SRS scheduling and ELO updates.
+     * @param cardRecord User's response record
+     * @param cardHistory Promise resolving to the card's history
+     * @param studySessionItem Current study session item
+     * @param courseRegistrationDoc User's course registration (for ELO updates)
+     * @param currentCard Current study session record
+     * @param courseId Course identifier
+     * @param cardId Card identifier
+     * @param maxAttemptsPerView Maximum attempts allowed per view
+     * @param maxSessionViews Maximum session views for this card
+     * @param sessionViews Current number of session views
+     * @returns ResponseResult with navigation and UI instructions
+     */
+    processResponse(cardRecord: CardRecord, cardHistory: Promise<CardHistory<CardRecord>>, studySessionItem: StudySessionItem, courseRegistrationDoc: CourseRegistrationDoc, currentCard: StudySessionRecord, courseId: string, cardId: string, maxAttemptsPerView: number, maxSessionViews: number, sessionViews: number): Promise<ResponseResult>;
+    /**
+     * Handles processing for correct responses: SRS scheduling and ELO updates.
+     */
+    private processCorrectResponse;
+    /**
+     * Handles processing for incorrect responses: ELO updates only.
+     */
+    private processIncorrectResponse;
+}
+
+interface HydratedCard<TView = unknown> {
+    item: StudySessionItem;
+    view: TView;
+    data: any[];
+}
+
+declare abstract class Loggable {
+    protected abstract readonly _className: string;
+    protected log(...args: unknown[]): void;
+    protected error(...args: unknown[]): void;
+}
+
+/**
+ * Represents a batch of content fetched from a single StudyContentSource.
+ */
+interface SourceBatch {
+    sourceIndex: number;
+    weighted: WeightedCard[];
+}
+/**
+ * Strategy interface for mixing content from multiple sources into a unified
+ * set of weighted candidates.
+ *
+ * Different implementations can provide different balancing strategies:
+ * - QuotaRoundRobinMixer: Equal representation per source
+ * - MinMaxNormalizingMixer: Score normalization then global sort
+ * - PercentileBucketMixer: Bucketed round-robin
+ * etc.
+ */
+interface SourceMixer {
+    /**
+     * Mix weighted cards from multiple sources into a unified, ordered list.
+     *
+     * @param batches - Content batches from each source
+     * @param limit - Target number of cards to return
+     * @returns Mixed and ordered weighted cards
+     */
+    mix(batches: SourceBatch[], limit: number): WeightedCard[];
+}
+/**
+ * Quota-based mixer with interleaved output.
+ *
+ * Allocates equal representation to each source (top-N by score), then
+ * interleaves the results by dealing from a randomly-shuffled source order.
+ * Within each source, cards are dealt in score-descending order.
+ *
+ * This ensures that cards from different courses are spread throughout the
+ * queue rather than clustered by score bands, which matters because
+ * SessionController consumes queues front-to-back and sessions often end
+ * before reaching the tail.
+ */
+declare class QuotaRoundRobinMixer implements SourceMixer {
+    mix(batches: SourceBatch[], limit: number): WeightedCard[];
+}
+
+/**
+ * Typed ephemeral pipeline hints for a single run.
+ * All fields are optional. Tag/card patterns support `*` wildcards.
+ *
+ * Previously defined in Pipeline.ts; moved here so it's co-exported
+ * with ReplanOptions from the public `@vue-skuilder/db` surface.
+ */
+interface ReplanHints {
+    /** Multiply scores for cards matching these tag patterns. */
+    boostTags?: Record<string, number>;
+    /** Multiply scores for these specific card IDs (glob patterns). */
+    boostCards?: Record<string, number>;
+    /** Cards matching these tag patterns MUST appear in results. */
+    requireTags?: string[];
+    /** These specific card IDs MUST appear in results. */
+    requireCards?: string[];
+    /** Remove cards matching these tag patterns from results. */
+    excludeTags?: string[];
+    /** Remove these specific card IDs from results. */
+    excludeCards?: string[];
+    /**
+     * Debugging label threaded from the replan requester.
+     * Prefixed with `_` to signal it's metadata, not a scoring hint.
+     */
+    _label?: string;
+}
+/**
+ * Options for requesting a mid-session replan.
+ *
+ * All fields are optional — callers can pass just the fields they need.
+ * When omitted, defaults match the existing behaviour (full 20-card
+ * replace with no hints).
+ */
+interface ReplanOptions {
+    /** Scoring hints forwarded to the pipeline (boost/exclude/require). */
+    hints?: ReplanHints;
+    /**
+     * Maximum number of new cards to return from the pipeline.
+     * Default: 20 (the standard session batch size).
+     */
+    limit?: number;
+    /**
+     * How to integrate the new cards into the existing newQ.
+     * - `'replace'` (default): atomically swap the entire newQ.
+     * - `'merge'`: insert new cards at the front, keeping existing cards.
+     */
+    mode?: 'replace' | 'merge';
+    /**
+     * Guarantee that at least this many cards will be served after the
+     * replan, even if the session timer has expired. Prevents intro cards
+     * from surfacing at the end of a session with zero follow-up exercise.
+     * Decremented on each card draw while active.
+     */
+    minFollowUpCards?: number;
+    /**
+     * Human-readable label for debugging / provenance.
+     * Appears in console logs and in card provenance entries created
+     * by ephemeral hint application.
+     */
+    label?: string;
+}
+interface StudySessionRecord {
+    card: {
+        course_id: string;
+        card_id: string;
+        card_elo: number;
+    };
+    item: StudySessionItem;
+    records: CardRecord[];
+}
+
+type SessionAction = 'dismiss-success' | 'dismiss-failed' | 'marked-failed' | 'dismiss-error';
+interface ResponseResult {
+    nextCardAction: Exclude<SessionAction, 'dismiss-error'> | 'none';
+    shouldLoadNextCard: boolean;
+    /**
+     * When true, the card requested deferred advancement via `deferAdvance`.
+     * The record was logged and ELO updated, but navigation was suppressed.
+     * StudySession should stash `nextCardAction` and wait for a
+     * `ready-to-advance` event from the card before calling `nextCard()`.
+     */
+    deferred?: boolean;
+    isCorrect: boolean;
+    performanceScore?: number;
+    shouldClearFeedbackShadow: boolean;
+}
+interface SessionServices {
+    response: ResponseProcessor;
+}
+declare class SessionController<TView = unknown> extends Loggable {
+    _className: string;
+    services: SessionServices;
+    private srsService;
+    private eloService;
+    private hydrationService;
+    private mixer;
+    private dataLayer;
+    private courseNameCache;
+    /**
+     * Default pipeline batch size for new-card planning.
+     * Set via constructor options; falls back to 20 when not specified.
+     * Individual replans can override via `ReplanOptions.limit`.
+     */
+    private _defaultBatchLimit;
+    private sources;
+    private _sessionRecord;
+    set sessionRecord(r: StudySessionRecord[]);
+    private _currentCard;
+    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;
+    /**
+     * When true, suppresses the quality-based auto-replan trigger in
+     * nextCard(). Set after a burst replan (small limit) to prevent the
+     * auto-replan from clobbering the burst cards before they're consumed.
+     * Cleared when the depletion-triggered replan fires (newQ exhausted).
+     */
+    private _suppressQualityReplan;
+    /**
+     * Guards against infinite depletion-triggered replans. Set to true
+     * when a depletion replan fires; cleared when a replan produces
+     * content (newQ.length > 0 after replan) or when an explicit
+     * (non-auto) replan is requested.
+     */
+    private _depletionReplanAttempted;
+    /**
+     * When > 0, the session timer cannot end the session. Decremented on
+     * each nextCard() draw. Set by replans that include `minFollowUpCards`.
+     */
+    private _minCardsGuarantee;
+    private startTime;
+    private endTime;
+    private _secondsRemaining;
+    get secondsRemaining(): number;
+    /** True when a card guarantee is active, preventing timer-based session end. */
+    get hasCardGuarantee(): boolean;
+    get report(): string;
+    get detailedReport(): string;
+    private _intervalHandle;
+    /**
+     * @param sources - Array of content sources to mix for the session
+     * @param time - Session duration in seconds
+     * @param dataLayer - Data layer provider
+     * @param getViewComponent - Function to resolve view components
+     * @param mixer - Optional source mixer strategy (defaults to QuotaRoundRobinMixer)
+     * @param options - Optional session-level configuration
+     * @param options.defaultBatchLimit - Default pipeline batch size (default: 20).
+     *   Smaller values for newer users cause more frequent replans, keeping plans
+     *   aligned with rapidly-changing user state.
+     */
+    constructor(sources: StudyContentSource[], time: number, dataLayer: DataLayerProvider, getViewComponent: (viewId: string) => TView, mixer?: SourceMixer, options?: {
+        defaultBatchLimit?: number;
+    });
+    private tick;
+    /**
+     * Returns a rough, erring toward conservative, guess at
+     * the amount of time the failed cards queue will require
+     * to clean up.
+     *
+     * (seconds)
+     */
+    private estimateCleanupTime;
+    /**
+     * Extremely rough, conservative, estimate of amound of time to complete
+     * all scheduled reviews
+     */
+    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(options?: ReplanOptions | ReplanHints): Promise<void>;
+    /**
+     * Normalise the requestReplan argument. Accepts either a ReplanOptions
+     * object (new API) or a plain Record<string, unknown> (legacy callers
+     * that passed hints directly). Distinguishes the two by checking for
+     * the presence of ReplanOptions-specific keys.
+     */
+    private normalizeReplanOptions;
+    /** 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;
+    reportString(): string;
+    /**
+     * Returns debug information about the current session state.
+     * Used by SessionControllerDebug component for runtime inspection.
+     */
+    getDebugInfo(): {
+        api: {
+            mode: string;
+            description: string;
+        };
+        reviewQueue: {
+            length: number;
+            dequeueCount: number;
+            items: {
+                courseID: any;
+                cardID: any;
+                status: any;
+            }[];
+        };
+        newQueue: {
+            length: number;
+            dequeueCount: number;
+            items: {
+                courseID: any;
+                cardID: any;
+                status: any;
+            }[];
+        };
+        failedQueue: {
+            length: number;
+            dequeueCount: number;
+            items: {
+                courseID: any;
+                cardID: any;
+                status: any;
+            }[];
+        };
+        hydratedCache: {
+            count: number;
+            cardIds: string[];
+        };
+        replan: {
+            inProgress: boolean;
+            suppressQualityReplan: boolean;
+            defaultBatchLimit: number;
+            minCardsGuarantee: number;
+        };
+    };
+    /**
+     * Fetch content using the getWeightedCards API and mix across sources.
+     *
+     * This method:
+     * 1. Fetches weighted cards from each source
+     * 2. Fetches full review data (we need ScheduledCard fields for queue)
+     * 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.
+     * Deterministic: top N items from each queue to ensure coverage.
+     * Failed queue items will typically already be hydrated (from initial render).
+     */
+    private _getItemsToHydrate;
+    /**
+     * Selects the next item to present to the user.
+     * Nondeterministic: uses probability to balance between queues based on session state.
+     */
+    private _selectNextItemToHydrate;
+    nextCard(action?: SessionAction): Promise<HydratedCard<TView> | null>;
+    /**
+     * Public API for processing user responses to cards.
+     * @param cardRecord User's response record
+     * @param cardHistory Promise resolving to the card's history
+     * @param courseRegistrationDoc User's course registration document
+     * @param currentCard Current study session record
+     * @param courseId Course identifier
+     * @param cardId Card identifier
+     * @param maxAttemptsPerView Maximum attempts allowed per view
+     * @param maxSessionViews Maximum session views for this card
+     * @param sessionViews Current number of session views
+     * @returns ResponseResult with navigation and UI instructions
+     */
+    submitResponse(cardRecord: CardRecord, cardHistory: Promise<CardHistory<CardRecord>>, courseRegistrationDoc: CourseRegistrationDoc, currentCard: StudySessionRecord, courseId: string, cardId: string, maxAttemptsPerView: number, maxSessionViews: number, sessionViews: number): Promise<ResponseResult>;
+    private dismissCurrentCard;
+    /**
+     * Remove an item from its source queue after consumption by nextCard().
+     */
+    private removeItemFromQueue;
+    /**
+     * End the session and record learning outcomes.
+     *
+     * This method aggregates all responses from the session and records a
+     * UserOutcomeRecord if evolutionary orchestration is enabled.
+     */
+    endSession(): Promise<void>;
+}
+
 /**
  * A NavigationStrategyManager is an entity which may contain multiple strategies.
  *
@@ -296,84 +853,6 @@ interface CourseDBInterface extends NavigationStrategyManager, StudyContentSourc
     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;
-}
-
 /**
  * Record of a user's learning outcome over a specific period.
  *
@@ -1048,7 +1527,7 @@ declare abstract class ContentNavigator implements StudyContentSource {
      * Set ephemeral hints for the next pipeline run.
      * No-op for non-Pipeline navigators. Pipeline overrides this.
      */
-    setEphemeralHints(_hints: Record<string, unknown>): void;
+    setEphemeralHints(_hints: ReplanHints): void;
 }
 
 type StudySessionFailedItem = StudySessionFailedNewItem | StudySessionFailedReviewItem;
@@ -1111,8 +1590,72 @@ interface StudyContentSource {
      * Set ephemeral hints for the next pipeline run.
      * No-op for sources that don't support hints.
      */
-    setEphemeralHints?(hints: Record<string, unknown>): void;
+    setEphemeralHints?(hints: ReplanHints): void;
 }
 declare function getStudySource(source: ContentSourceID, user: UserDBInterface): Promise<StudyContentSource>;
 
-export { NavigatorRoles as $, 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 UserOutcomeRecord as L, registerNavigator as M, type NavigatorConstructor as N, getRegisteredNavigator as O, hasRegisteredNavigator as P, getRegisteredNavigatorRole as Q, getRegisteredNavigatorNames as R, type StudySessionItem as S, type TeacherClassroomDBInterface as T, type UserDBInterface as U, initializeNavigatorRegistry as V, type WeightedCard as W, type StrategyContribution as X, getCardOrigin as Y, Navigators as Z, NavigatorRole as _, type UserDBReader as a, isGenerator as a0, isFilter as a1, type LearnableWeight as a2, type OrchestrationContext as a3, computeDeviation as a4, computeSpread as a5, computeEffectiveWeight as a6, createOrchestrationContext as a7, type DocumentUpdater as a8, newInterval as a9, 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 };
+/**
+ * Main factory interface for data access
+ */
+interface DataLayerProvider {
+    /**
+     * Get the user database interface
+     */
+    getUserDB(): UserDBInterface;
+    /**
+     * Create a UserDBReader for a specific user (admin access required)
+     * Uses session authentication to verify requesting user is admin
+     * @param targetUsername - The username to create a reader for
+     * @throws Error if requesting user is not 'admin'
+     */
+    createUserReaderForUser(targetUsername: string): Promise<UserDBReader>;
+    /**
+     * Get a course database interface
+     */
+    getCourseDB(courseId: string): CourseDBInterface;
+    /**
+     * Get the courses-lookup interface
+     */
+    getCoursesDB(): CoursesDBInterface;
+    /**
+     * Get a classroom database interface
+     */
+    getClassroomDB(classId: string, type: 'student' | 'teacher'): Promise<ClassroomDBInterface>;
+    /**
+     * Get the admin database interface
+     */
+    getAdminDB(): AdminDBInterface;
+    /**
+     * Initialize the data layer
+     */
+    initialize(): Promise<void>;
+    /**
+     * Teardown the data layer
+     */
+    teardown(): Promise<void>;
+    /**
+     * Check if this data layer is read-only
+     */
+    isReadOnly(): boolean;
+    /**
+     * Trigger local replication of a course database.
+     *
+     * When a course opts in via `CourseConfig.localSync.enabled`, this method
+     * replicates the remote course DB to a local PouchDB instance. Subsequent
+     * `getCourseDB()` calls for that course will return a CourseDB that reads
+     * from the local replica (fast, no network) and writes to the remote
+     * (ELO updates, admin ops).
+     *
+     * Safe to call multiple times — concurrent calls coalesce. Returns when
+     * sync is complete (or immediately if already synced / disabled).
+     *
+     * Implementations that don't support local sync may no-op.
+     *
+     * @param courseId - The course to sync locally
+     * @param forceEnabled - Skip CourseConfig check and sync regardless.
+     *   Use when the caller already knows local sync is desired.
+     */
+    ensureCourseSynced?(courseId: string, forceEnabled?: boolean): Promise<void>;
+}
+
+export { type StrategyContribution as $, type AdminDBInterface as A, type UserCourseSetting as B, type CourseDBInterface as C, type DataLayerProvider as D, type UsrCrsDataInterface as E, type ClassroomRegistrationDesignation as F, type ClassroomRegistration as G, type ClassroomRegistrationDoc as H, type SessionTrackingData as I, type UserConfig as J, type ActivityRecord as K, type CourseRegistration as L, type CourseRegistrationDoc as M, type UserOutcomeRecord as N, Loggable as O, type NavigatorConstructor as P, registerNavigator as Q, type ReplanHints as R, type StudySessionItem as S, type TeacherClassroomDBInterface as T, type UserDBInterface as U, getRegisteredNavigator as V, type WeightedCard as W, hasRegisteredNavigator as X, getRegisteredNavigatorRole as Y, getRegisteredNavigatorNames as Z, initializeNavigatorRegistry as _, type CoursesDBInterface as a, getCardOrigin as a0, Navigators as a1, NavigatorRole as a2, NavigatorRoles as a3, isGenerator as a4, isFilter as a5, type LearnableWeight as a6, type OrchestrationContext as a7, computeDeviation as a8, computeSpread as a9, computeEffectiveWeight as aa, createOrchestrationContext as ab, type ReplanOptions as ac, type StudySessionRecord as ad, type SessionAction as ae, type ResponseResult as af, SessionController as ag, type SourceMixer as ah, QuotaRoundRobinMixer as ai, type DocumentUpdater as aj, newInterval as ak, type ClassroomDBInterface as b, type UserDBReader as c, type CourseInfo as d, type DataLayerResult as e, type ContentNavigationStrategyData as f, ContentNavigator as g, type AssignedContent as h, type StudyContentSource as i, type StudentClassroomDBInterface as j, type ScheduledCard as k, type StudySessionFailedItem as l, type StudySessionFailedNewItem as m, type StudySessionFailedReviewItem as n, type StudySessionNewItem as o, type StudySessionReviewItem as p, isReview as q, type ContentSourceID as r, getStudySource as s, type SourceBatch as t, type AssignedTag as u, type AssignedCourse as v, type AssignedCard as w, type UserDBWriter as x, type UserDBAuthenticator as y, type UserCourseSettings as z };