@vue-skuilder/db 0.1.23 → 0.1.25

package/dist/index.d.ts

@@ -1,15 +1,15 @@
-import { U as UserDBInterface, s as CourseRegistrationDoc, S as StudySessionItem, W as WeightedCard, h as StudyContentSource, C as CourseDBInterface } from './contentSource-BP9hznNV.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, f as ContentNavigator, q as ContentSourceID, d as CourseInfo, K as CourseRegistration, b as CoursesDBInterface, V as DocumentUpdater, O as NavigatorRole, P as NavigatorRoles, N as Navigators, j as ScheduledCard, H as SessionTrackingData, L 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, B as UsrCrsDataInterface, M as getCardOrigin, r as getStudySource, R as isFilter, Q as isGenerator, p as isReview, X as newInterval } from './contentSource-BP9hznNV.js';
-import { D as DataLayerProvider } from './dataLayerProvider-MDTxXq2l.js';
-import { C as CardHistory, c as CardRecord } from './types-legacy-DDY4N-Uq.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-DDY4N-Uq.js';
+import { U as UserDBInterface, s as CourseRegistrationDoc, S as StudySessionItem, W as WeightedCard, h as StudyContentSource, C as CourseDBInterface } from './contentSource-BmnmvH8C.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, a7 as DocumentUpdater, a1 as LearnableWeight, N as NavigatorConstructor, Z as NavigatorRole, _ as NavigatorRoles, Y as Navigators, a2 as OrchestrationContext, j as ScheduledCard, H as SessionTrackingData, V 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, a3 as computeDeviation, a5 as computeEffectiveWeight, a4 as computeSpread, a6 as createOrchestrationContext, X as getCardOrigin, O as getRegisteredNavigator, Q as getRegisteredNavigatorNames, r as getStudySource, P as hasRegisteredNavigator, R as initializeNavigatorRegistry, a0 as isFilter, $ as isGenerator, p as isReview, a8 as newInterval, M as registerNavigator } from './contentSource-BmnmvH8C.js';
+import { D as DataLayerProvider } from './dataLayerProvider-CG9GfaAY.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';
-export { BulkCardProcessorConfig, CardFilter, CardFilterFactory, CardGenerator, CardGeneratorFactory, FilterContext, GeneratorContext, ImportResult, StrategyStateDoc, StrategyStateId, areQuestionRecords, buildStrategyStateId, docIsDeleted, getCardHistoryID, importParsedCards, isQuestionRecord, parseCardHistoryID, validateProcessorConfig } from './core/index.js';
-import { TagFilter, DataShape, CourseConfig } from '@vue-skuilder/common';
-import { S as StaticCourseManifest } from './types-DQaXnuoc.js';
-export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig } from './types-DQaXnuoc.js';
-import { F as FileSystemAdapter } from './index-Dj0SEgk3.js';
-export { C as CouchDBToStaticPacker, a as FileStats, b as FileSystemError } from './index-Dj0SEgk3.js';
+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, parseCardHistoryID, pipelineDebugAPI, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, validateProcessorConfig } from './core/index.js';
+import { TaggedPerformance, TagFilter, DataShape, CourseConfig } from '@vue-skuilder/common';
+import { S as StaticCourseManifest } from './types-CJrLM1Ew.js';
+export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig } from './types-CJrLM1Ew.js';
+import { F as FileSystemAdapter } from './index-BWvO-_rJ.js';
+export { C as CouchDBToStaticPacker, a as FileStats, b as FileSystemError } from './index-BWvO-_rJ.js';
 import 'moment';
 
 /**
@@ -29,6 +29,17 @@ declare class EloService {
      * @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>;
 }
 
 /**
@@ -37,6 +48,11 @@ declare class EloService {
 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.
@@ -54,6 +70,13 @@ 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
@@ -269,16 +292,16 @@ interface SourceMixer {
     mix(batches: SourceBatch[], limit: number): WeightedCard[];
 }
 /**
- * Simple quota-based mixer: allocates equal representation to each source,
- * taking the top-N cards by score from each.
+ * Quota-based mixer with interleaved output.
  *
- * Guarantees balanced representation across sources regardless of absolute
- * score differences. A low-scoring source gets the same quota as a high-scoring
- * source.
+ * 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 is the KISS approach - simple, predictable, and fair in terms of
- * source representation (though not necessarily optimal in terms of absolute
- * card quality).
+ * 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[];
@@ -312,6 +335,8 @@ declare class SessionController<TView = unknown> extends Loggable {
     private eloService;
     private hydrationService;
     private mixer;
+    private dataLayer;
+    private courseNameCache;
     private sources;
     private _sessionRecord;
     set sessionRecord(r: StudySessionRecord[]);
@@ -435,6 +460,13 @@ declare class SessionController<TView = unknown> extends Loggable {
      * 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>;
 }
 
 /**
@@ -487,6 +519,214 @@ declare class TagFilteredContentSource implements StudyContentSource {
     getFilter(): TagFilter;
 }
 
+/**
+ * Summary of a single source's contribution to the mix.
+ */
+interface SourceSummary {
+    sourceIndex: number;
+    sourceId: string;
+    sourceName?: string;
+    totalCards: number;
+    reviewCount: number;
+    newCount: number;
+    topScore: number;
+    bottomScore: number;
+    scoreRange: [number, number];
+    avgScore: number;
+}
+/**
+ * Per-source selection breakdown.
+ */
+interface SourceSelectionBreakdown {
+    sourceId: string;
+    sourceName?: string;
+    reviewsProvided: number;
+    newProvided: number;
+    reviewsSelected: number;
+    newSelected: number;
+    totalSelected: number;
+    selectionRate: number;
+}
+/**
+ * Detailed card information in the mixer context.
+ */
+interface MixerCardInfo {
+    cardId: string;
+    courseId: string;
+    origin: 'review' | 'new' | 'failed' | 'unknown';
+    score: number;
+    sourceIndex: number;
+    selected: boolean;
+    rankInSource?: number;
+    rankInMix?: number;
+}
+/**
+ * Complete record of a single mixer execution.
+ */
+interface MixerRunReport {
+    runId: string;
+    timestamp: Date;
+    mixerType: string;
+    requestedLimit: number;
+    quotaPerSource?: number;
+    sourceSummaries: SourceSummary[];
+    cards: MixerCardInfo[];
+    finalCount: number;
+    reviewsSelected: number;
+    newSelected: number;
+    sourceBreakdowns: SourceSelectionBreakdown[];
+}
+/**
+ * Capture a mixer run for later inspection.
+ */
+declare function captureMixerRun(mixerType: string, batches: SourceBatch[], sourceIds: string[], sourceNames: (string | undefined)[], requestedLimit: number, quotaPerSource: number | undefined, mixedResult: WeightedCard[]): void;
+/**
+ * Console API object exposed on window.skuilder.mixer
+ */
+declare const mixerDebugAPI: {
+    /**
+     * Get raw run history for programmatic access.
+     */
+    readonly runs: MixerRunReport[];
+    /**
+     * Show summary of a specific mixer run.
+     */
+    showRun(idOrIndex?: string | number): void;
+    /**
+     * Show summary of the last mixer run.
+     */
+    showLastMix(): void;
+    /**
+     * Explain source balance in the last run.
+     */
+    explainSourceBalance(): void;
+    /**
+     * Compare score distributions across sources.
+     */
+    compareScores(): void;
+    /**
+     * Show detailed information for a specific card.
+     */
+    showCard(cardId: string): void;
+    /**
+     * Show all runs in compact format.
+     */
+    listRuns(): void;
+    /**
+     * Export run history as JSON for bug reports.
+     */
+    export(): string;
+    /**
+     * Clear run history.
+     */
+    clear(): void;
+    /**
+     * Show help.
+     */
+    help(): void;
+};
+/**
+ * Mount the debug API on window.skuilder.mixer
+ */
+declare function mountMixerDebugger(): void;
+
+/**
+ * Snapshot of queue state at a given moment.
+ */
+interface QueueSnapshot {
+    timestamp: Date;
+    reviewQLength: number;
+    newQLength: number;
+    failedQLength: number;
+    reviewQNext3?: string[];
+    newQNext3?: string[];
+}
+/**
+ * Record of a single card presentation.
+ */
+interface CardPresentation {
+    timestamp: Date;
+    sequenceNumber: number;
+    cardId: string;
+    courseId: string;
+    courseName?: string;
+    origin: 'review' | 'new' | 'failed';
+    queueSource: 'reviewQ' | 'newQ' | 'failedQ';
+    score?: number;
+}
+/**
+ * Complete session execution record.
+ */
+interface SessionRunReport {
+    sessionId: string;
+    startTime: Date;
+    endTime?: Date;
+    initialQueues: QueueSnapshot;
+    presentations: CardPresentation[];
+    queueSnapshots: QueueSnapshot[];
+}
+/**
+ * Start tracking a new session.
+ */
+declare function startSessionTracking(reviewQLength: number, newQLength: number, failedQLength: number): void;
+/**
+ * Record a card presentation.
+ */
+declare function recordCardPresentation(cardId: string, courseId: string, courseName: string | undefined, origin: 'review' | 'new' | 'failed', queueSource: 'reviewQ' | 'newQ' | 'failedQ', score?: number): void;
+/**
+ * Take a snapshot of current queue state.
+ */
+declare function snapshotQueues(reviewQLength: number, newQLength: number, failedQLength: number, reviewQNext3?: string[], newQNext3?: string[]): void;
+/**
+ * End the current session tracking.
+ */
+declare function endSessionTracking(): void;
+/**
+ * Console API object exposed on window.skuilder.session
+ */
+declare const sessionDebugAPI: {
+    /**
+     * Get raw session history for programmatic access.
+     */
+    readonly sessions: SessionRunReport[];
+    /**
+     * Get active session if any.
+     */
+    readonly active: SessionRunReport | null;
+    /**
+     * Show current queue state.
+     */
+    showQueue(): void;
+    /**
+     * Show presentation history for current or past session.
+     */
+    showHistory(sessionIndex?: number): void;
+    /**
+     * Analyze course interleaving pattern.
+     */
+    showInterleaving(sessionIndex?: number): void;
+    /**
+     * List all tracked sessions.
+     */
+    listSessions(): void;
+    /**
+     * Export session history as JSON for bug reports.
+     */
+    export(): string;
+    /**
+     * Clear session history.
+     */
+    clear(): void;
+    /**
+     * Show help.
+     */
+    help(): void;
+};
+/**
+ * Mount the debug API on window.skuilder.session
+ */
+declare function mountSessionDebugger(): void;
+
 interface CourseLookupDoc {
     _id: string;
     _rev: string;
@@ -608,6 +848,24 @@ declare function registerDataShape(dataShape: ProcessedDataShape, courseConfig:
  * Register a question type in the course config
  */
 declare function registerQuestionType(question: ProcessedQuestionData, courseConfig: CourseConfig): boolean;
+/**
+ * Remove a data shape from the course config
+ * @returns true if the data shape was removed, false if it wasn't found
+ */
+declare function removeDataShape(dataShapeName: string, courseConfig: CourseConfig): boolean;
+/**
+ * Remove a question type from the course config
+ * @returns true if the question type was removed, false if it wasn't found
+ */
+declare function removeQuestionType(questionTypeName: string, courseConfig: CourseConfig): boolean;
+/**
+ * Remove data shapes and question types from course config and persist to database
+ */
+declare function removeCustomQuestionTypes(dataShapeNames: string[], questionTypeNames: string[], courseConfig: CourseConfig, courseDB: CourseDBInterface): Promise<{
+    success: boolean;
+    removedCount: number;
+    errorMessage?: string;
+}>;
 /**
  * Register seed data for a question type
  *
@@ -698,4 +956,4 @@ interface CouchDbUserDoc extends PouchDB.Authentication.User {
     entitlements: UserEntitlements;
 }
 
-export { type AggregatedDocument, type AttachmentUploadResult, CardHistory, CardRecord, type CouchDbUserDoc, CourseDBInterface, CourseLookup, CourseRegistrationDoc, type CustomQuestionsData, DEFAULT_MIGRATION_OPTIONS, type DataLayerConfig, DataLayerProvider, type DocumentCounts, ENV, type Entitlement, FileSystemAdapter, Loggable, type MigrationOptions, type MigrationResult, NOT_SET, type ProcessedDataShape, type ProcessedQuestionData, QuotaRoundRobinMixer, type ResponseResult, type RestoreProgress, type SessionAction, SessionController, type SourceBatch, type SourceMixer, StaticCourseManifest, type StaticCourseValidation, StaticToCouchDBMigrator, StudyContentSource, StudySessionItem, type StudySessionRecord, TagFilteredContentSource, type UserAccountStatus, UserDBInterface, type UserEntitlements, type ValidationIssue, type ValidationResult, WeightedCard, _resetDataLayer, ensureAppDataDirectory, getAppDataDirectory, getDataLayer, getDbPath, initializeDataDirectory, initializeDataLayer, isDataShapeRegistered, isDataShapeSchemaAvailable, isQuestionTypeRegistered, processCustomQuestionsData, registerBlanksCard, registerCustomQuestionTypes, registerDataShape, registerQuestionType, registerSeedData, 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, Loggable, type MigrationOptions, type MigrationResult, type MixerCardInfo, type MixerRunReport, NOT_SET, type ProcessedDataShape, type ProcessedQuestionData, type QueueSnapshot, QuotaRoundRobinMixer, 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 };