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

package/dist/{index-X6wHrURm.d.ts → index-BWvO-_rJ.d.ts}

@@ -1,4 +1,4 @@
-import { P as PackerConfig, a as PackedCourseData, S as StaticCourseManifest } from './types-DZ5dUqbL.js';
+import { P as PackerConfig, a as PackedCourseData, S as StaticCourseManifest } from './types-CJrLM1Ew.js';
 
 /**
  * Abstraction for file system operations needed by the migrator.

package/dist/{index-m8MMGxxR.d.cts → index-Ba7hYbHj.d.cts}

@@ -1,4 +1,4 @@
-import { P as PackerConfig, a as PackedCourseData, S as StaticCourseManifest } from './types-ZL8tOPQZ.cjs';
+import { P as PackerConfig, a as PackedCourseData, S as StaticCourseManifest } from './types-W8n-B6HG.cjs';
 
 /**
  * Abstraction for file system operations needed by the migrator.

package/dist/index.d.cts

@@ -1,14 +1,113 @@
-import { i as StudyContentSource, U as UserDBInterface, W as WeightedCard, t as SourceBatch, C as CourseDBInterface, D as DataLayerProvider } from './dataLayerProvider-BJqBlMIl.cjs';
-export { K as ActivityRecord, A as AdminDBInterface, w as AssignedCard, h as AssignedContent, v as AssignedCourse, u as AssignedTag, b as ClassroomDBInterface, G as ClassroomRegistration, F as ClassroomRegistrationDesignation, H as ClassroomRegistrationDoc, f as ContentNavigationStrategyData, g as ContentNavigator, r as ContentSourceID, d as CourseInfo, L as CourseRegistration, M as CourseRegistrationDoc, a as CoursesDBInterface, aj as DocumentUpdater, a6 as LearnableWeight, O as Loggable, P as NavigatorConstructor, a2 as NavigatorRole, a3 as NavigatorRoles, a1 as Navigators, a7 as OrchestrationContext, ai as QuotaRoundRobinMixer, R as ReplanHints, ac as ReplanOptions, af as ResponseResult, k as ScheduledCard, ae as SessionAction, ag as SessionController, I as SessionTrackingData, ah as SourceMixer, $ as StrategyContribution, j as StudentClassroomDBInterface, l as StudySessionFailedItem, m as StudySessionFailedNewItem, n as StudySessionFailedReviewItem, S as StudySessionItem, o as StudySessionNewItem, ad as StudySessionRecord, p as StudySessionReviewItem, T as TeacherClassroomDBInterface, J as UserConfig, B as UserCourseSetting, z as UserCourseSettings, y as UserDBAuthenticator, c as UserDBReader, x as UserDBWriter, N as UserOutcomeRecord, E as UsrCrsDataInterface, a8 as computeDeviation, aa as computeEffectiveWeight, a9 as computeSpread, ab as createOrchestrationContext, a0 as getCardOrigin, V as getRegisteredNavigator, Z as getRegisteredNavigatorNames, Y as getRegisteredNavigatorRole, s as getStudySource, X as hasRegisteredNavigator, _ as initializeNavigatorRegistry, a5 as isFilter, a4 as isGenerator, q as isReview, ak as newInterval, Q as registerNavigator } from './dataLayerProvider-BJqBlMIl.cjs';
-export { C as CardData, g as CardHistory, h as CardRecord, b as CourseListData, d as DataShapeData, c as DisplayableData, D as DocType, f as DocTypePrefixes, F as Field, G as GuestUsername, Q as QualifiedCardID, e as QuestionData, i as QuestionRecord, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from './types-legacy-C7r0T4OV.cjs';
-export { BulkCardProcessorConfig, CardFilter, CardFilterFactory, CardGenerator, CardGeneratorFactory, FilterContext, FilterImpact, GeneratorContext, GeneratorSummary, GradientObservation, GradientResult, ImportResult, PeriodUpdateInput, PeriodUpdateResult, PipelineRunReport, SignalConfig, StrategyLearningState, StrategyStateDoc, StrategyStateId, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, computeOutcomeSignal, computeStrategyGradient, docIsDeleted, getCardHistoryID, getDefaultLearnableWeight, importParsedCards, isQuestionRecord, mountPipelineDebugger, mountUserDBDebugger, parseCardHistoryID, pipelineDebugAPI, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, userDBDebugAPI, validateProcessorConfig } from './core/index.cjs';
-import { TagFilter, DataShape, CourseConfig } from '@vue-skuilder/common';
-import { S as StaticCourseManifest } from './types-ZL8tOPQZ.cjs';
-export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig } from './types-ZL8tOPQZ.cjs';
-import { F as FileSystemAdapter } from './index-m8MMGxxR.cjs';
-export { C as CouchDBToStaticPacker, a as FileStats, b as FileSystemError } from './index-m8MMGxxR.cjs';
+import { U as UserDBInterface, s as CourseRegistrationDoc, S as StudySessionItem, W as WeightedCard, R as ReplanHints, h as StudyContentSource, G as GeneratorResult, C as CourseDBInterface } from './contentSource-BMlMwSiG.cjs';
+export { K as ActivityRecord, A as AdminDBInterface, v as AssignedCard, g as AssignedContent, u as AssignedCourse, t as AssignedTag, a4 as CardGenerator, a6 as CardGeneratorFactory, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, H as ClassroomRegistrationDoc, e as ContentNavigationStrategyData, f as ContentNavigator, q as ContentSourceID, d as CourseInfo, L as CourseRegistration, b as CoursesDBInterface, ad as DocumentUpdater, a5 as GeneratorContext, a7 as LearnableWeight, N as NavigatorConstructor, a0 as NavigatorRole, a1 as NavigatorRoles, $ as Navigators, a8 as OrchestrationContext, j as ScheduledCard, I as SessionTrackingData, Z as StrategyContribution, i as StudentClassroomDBInterface, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, n as StudySessionNewItem, o as StudySessionReviewItem, T as TeacherClassroomDBInterface, J as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, M as UserOutcomeRecord, B as UsrCrsDataInterface, a9 as computeDeviation, ab as computeEffectiveWeight, aa as computeSpread, ac as createOrchestrationContext, _ as getCardOrigin, P as getRegisteredNavigator, X as getRegisteredNavigatorNames, V as getRegisteredNavigatorRole, r as getStudySource, Q as hasRegisteredNavigator, Y as initializeNavigatorRegistry, a3 as isFilter, a2 as isGenerator, p as isReview, ae as newInterval, O as registerNavigator } from './contentSource-BMlMwSiG.cjs';
+import { D as DataLayerProvider } from './dataLayerProvider-BEqB8VBR.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';
+export { BulkCardProcessorConfig, CardFilter, CardFilterFactory, FilterContext, FilterImpact, GeneratorSummary, GradientObservation, GradientResult, ImportResult, PeriodUpdateInput, PeriodUpdateResult, PipelineRunReport, SignalConfig, StrategyLearningState, StrategyStateDoc, StrategyStateId, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, computeOutcomeSignal, computeStrategyGradient, docIsDeleted, getCardHistoryID, getDefaultLearnableWeight, importParsedCards, isQuestionRecord, mountPipelineDebugger, mountUserDBDebugger, parseCardHistoryID, pipelineDebugAPI, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, userDBDebugAPI, validateProcessorConfig } from './core/index.cjs';
+import { TaggedPerformance, TagFilter, DataShape, CourseConfig } from '@vue-skuilder/common';
+import { S as StaticCourseManifest } from './types-W8n-B6HG.cjs';
+export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig } from './types-W8n-B6HG.cjs';
+import { F as FileSystemAdapter } from './index-Ba7hYbHj.cjs';
+export { C as CouchDBToStaticPacker, a as FileStats, b as FileSystemError } from './index-Ba7hYbHj.cjs';
 import 'moment';
 
+/**
+ * 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>;
+}
+
+/**
+ * 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[];
+}
+
 interface MigrationOptions {
     chunkBatchSize: number;
     validateRoundTrip: boolean;
@@ -165,6 +264,357 @@ declare function getDbPath(dbName: string): string;
  */
 declare function initializeDataDirectory(): Promise<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[];
+}
+
+/**
+ * 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 StudyContentSource that filters cards based on tag inclusion/exclusion.
  *
@@ -199,7 +649,7 @@ declare class TagFilteredContentSource implements StudyContentSource {
      * @param limit - Maximum number of cards to return
      * @returns Cards sorted by score descending (all scores = 1.0)
      */
-    getWeightedCards(limit: number): Promise<WeightedCard[]>;
+    getWeightedCards(limit: number): Promise<GeneratorResult>;
     /**
      * Clears the cached resolved card IDs.
      * Call this if the underlying tag data may have changed during a session.
@@ -652,4 +1102,4 @@ interface CouchDbUserDoc extends PouchDB.Authentication.User {
     entitlements: UserEntitlements;
 }
 
-export { type AggregatedDocument, type AttachmentUploadResult, type CardPresentation, type CouchDbUserDoc, CourseDBInterface, CourseLookup, type CustomQuestionsData, DEFAULT_MIGRATION_OPTIONS, type DataLayerConfig, DataLayerProvider, type DocumentCounts, ENV, type Entitlement, FileSystemAdapter, type MigrationOptions, type MigrationResult, type MixerCardInfo, type MixerRunReport, NOT_SET, type ProcessedDataShape, type ProcessedQuestionData, type QueueSnapshot, type RestoreProgress, type SessionRunReport, SourceBatch, type SourceSelectionBreakdown, type SourceSummary, StaticCourseManifest, type StaticCourseValidation, StaticToCouchDBMigrator, StudyContentSource, TagFilteredContentSource, type UserAccountStatus, UserDBInterface, type UserEntitlements, type ValidationIssue, type ValidationResult, WeightedCard, _resetDataLayer, captureMixerRun, endSessionTracking, ensureAppDataDirectory, getAppDataDirectory, getDataLayer, getDbPath, initializeDataDirectory, initializeDataLayer, isDataShapeRegistered, isDataShapeSchemaAvailable, isQuestionTypeRegistered, mixerDebugAPI, mountMixerDebugger, mountSessionDebugger, processCustomQuestionsData, recordCardPresentation, registerBlanksCard, registerCustomQuestionTypes, registerDataShape, registerQuestionType, registerSeedData, removeCustomQuestionTypes, removeDataShape, removeQuestionType, sessionDebugAPI, snapshotQueues, startSessionTracking, validateMigration, validateStaticCourse };
+export { type AggregatedDocument, type AttachmentUploadResult, CardHistory, type CardPresentation, CardRecord, type CouchDbUserDoc, CourseDBInterface, CourseLookup, CourseRegistrationDoc, type CustomQuestionsData, DEFAULT_MIGRATION_OPTIONS, type DataLayerConfig, DataLayerProvider, type DocumentCounts, ENV, type Entitlement, FileSystemAdapter, GeneratorResult, Loggable, type MigrationOptions, type MigrationResult, type MixerCardInfo, type MixerRunReport, NOT_SET, type ProcessedDataShape, type ProcessedQuestionData, type QueueSnapshot, QuotaRoundRobinMixer, ReplanHints, type ReplanOptions, type ResponseResult, type RestoreProgress, type SessionAction, SessionController, type SessionRunReport, type SourceBatch, type SourceMixer, type SourceSelectionBreakdown, type SourceSummary, StaticCourseManifest, type StaticCourseValidation, StaticToCouchDBMigrator, StudyContentSource, StudySessionItem, type StudySessionRecord, TagFilteredContentSource, type UserAccountStatus, UserDBInterface, type UserEntitlements, type ValidationIssue, type ValidationResult, WeightedCard, _resetDataLayer, captureMixerRun, endSessionTracking, ensureAppDataDirectory, getAppDataDirectory, getDataLayer, getDbPath, initializeDataDirectory, initializeDataLayer, isDataShapeRegistered, isDataShapeSchemaAvailable, isQuestionTypeRegistered, mixerDebugAPI, mountMixerDebugger, mountSessionDebugger, processCustomQuestionsData, recordCardPresentation, registerBlanksCard, registerCustomQuestionTypes, registerDataShape, registerQuestionType, registerSeedData, removeCustomQuestionTypes, removeDataShape, removeQuestionType, sessionDebugAPI, snapshotQueues, startSessionTracking, validateMigration, validateStaticCourse };