@vue-skuilder/db 0.1.23 → 0.1.25

package/dist/{contentSource-BP9hznNV.d.ts → contentSource-BmnmvH8C.d.ts}

@@ -1,6 +1,6 @@
 import { CourseConfig, ClassroomConfig, Status, SkuilderCourseData as SkuilderCourseData$1, CourseElo, DataShape, TagFilter } from '@vue-skuilder/common';
 import { Moment } from 'moment';
-import { S as SkuilderCourseData, b as DocTypePrefixes, D as DocType, Q as QualifiedCardID, T as TagStub, a as Tag, C as CardHistory, c as CardRecord } from './types-legacy-DDY4N-Uq.js';
+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.js';
 
 /**
  * Admin functionality
@@ -91,6 +91,24 @@ interface DataLayerResult {
     id?: string;
 }
 
+/**
+ * Configuration for an evolutionarily-weighted strategy.
+ *
+ * This structure tracks the "learned" weight of a strategy, representing the
+ * system's confidence in its utility.
+ *
+ * - weight: The best-known multiplier (peak of the bell curve)
+ * - confidence: How certain we are (inverse of variance / spread)
+ * - sampleSize: How many data points informed this weight
+ */
+interface LearnableWeight {
+    /** The current best estimate of optimal weight (multiplier) */
+    weight: number;
+    /** Confidence in this weight (0-1). Higher = narrower exploration spread. */
+    confidence: number;
+    /** Number of outcome observations that contributed to this weight */
+    sampleSize: number;
+}
 /**
  *
  */
@@ -108,6 +126,17 @@ interface ContentNavigationStrategyData extends SkuilderCourseData {
      by the implementing class's constructor at runtime.
     */
     serializedData: string;
+    /**
+     * Evolutionary weighting configuration.
+     * If present, the strategy's influence is scaled by this weight.
+     * If omitted, weight defaults to 1.0.
+     */
+    learnable?: LearnableWeight;
+    /**
+     * If true, the weight is applied exactly as configured, without
+     * per-user deviation. Used for manual tuning or A/B testing.
+     */
+    staticWeight?: boolean;
 }
 
 /**
@@ -340,6 +369,50 @@ interface ScheduledCard {
     schedulingAgentId: string;
 }
 
+/**
+ * Record of a user's learning outcome over a specific period.
+ *
+ * Used by the evolutionary orchestration system to correlate strategy
+ * deviations with learning success.
+ *
+ * Stored in the UserDB.
+ */
+interface UserOutcomeRecord {
+    /**
+     * Unique ID: "USER_OUTCOME::{courseId}::{userId}::{timestamp}"
+     * Timestamp corresponds to periodEnd.
+     */
+    _id: string;
+    docType: DocType.USER_OUTCOME;
+    courseId: string;
+    userId: string;
+    /** Start of the measurement period (ISO timestamp) */
+    periodStart: string;
+    /** End of the measurement period (ISO timestamp) */
+    periodEnd: string;
+    /**
+     * The computed signal value (e.g., 0.85 for 85% accuracy).
+     * This is the 'Y' in the regression analysis.
+     *
+     * Higher values indicate better learning outcomes.
+     */
+    outcomeValue: number;
+    /**
+     * Snapshot of active deviations during this period.
+     * Maps strategyId -> deviation value used [-1.0, 1.0].
+     * This provides the 'X' values for regression analysis.
+     */
+    deviations: Record<string, number>;
+    metadata: {
+        sessionsCount: number;
+        cardsSeen: number;
+        eloStart: number;
+        eloEnd: number;
+        /** The algorithm used to compute outcomeValue (e.g. "accuracy_in_zone") */
+        signalType: string;
+    };
+}
+
 type Update<T> = Partial<T> | ((x: T) => T);
 
 interface DocumentUpdater {
@@ -396,6 +469,11 @@ interface UserDBReader {
      * Strategies use this to persist preferences, learned patterns, or temporal
      * tracking data across sessions. Each strategy owns its own namespace.
      *
+     * @deprecated Use `getCourseInterface(courseId).getStrategyState(strategyKey)` instead.
+     * Direct use bypasses course-scoping safety — the courseId parameter is unguarded,
+     * allowing accidental cross-course data access. The course-scoped interface binds
+     * courseId once at construction.
+     *
      * @param courseId - The course this state applies to
      * @param strategyKey - Unique key identifying the strategy (typically class name)
      * @returns The strategy's data payload, or null if no state exists
@@ -471,6 +549,11 @@ interface UserDBWriter extends DocumentUpdater {
      * Strategies use this to persist preferences, learned patterns, or temporal
      * tracking data across sessions. Each strategy owns its own namespace.
      *
+     * @deprecated Use `getCourseInterface(courseId).putStrategyState(strategyKey, data)` instead.
+     * Direct use bypasses course-scoping safety — the courseId parameter is unguarded,
+     * allowing accidental cross-course data writes. The course-scoped interface binds
+     * courseId once at construction.
+     *
      * @param courseId - The course this state applies to
      * @param strategyKey - Unique key identifying the strategy (typically class name)
      * @param data - The strategy's data payload to store
@@ -479,10 +562,17 @@ interface UserDBWriter extends DocumentUpdater {
     /**
      * Delete strategy-specific state for a course.
      *
+     * @deprecated Use `getCourseInterface(courseId).deleteStrategyState(strategyKey)` instead.
+     * Direct use bypasses course-scoping safety.
+     *
      * @param courseId - The course this state applies to
      * @param strategyKey - Unique key identifying the strategy (typically class name)
      */
     deleteStrategyState(courseId: string, strategyKey: string): Promise<void>;
+    /**
+     * Record a user learning outcome for evolutionary orchestration.
+     */
+    putUserOutcome(record: UserOutcomeRecord): Promise<void>;
 }
 /**
  * Authentication and account management operations
@@ -527,6 +617,34 @@ interface UsrCrsDataInterface {
     getScheduledReviewCount(): Promise<number>;
     getCourseSettings(): Promise<UserCourseSettings>;
     updateCourseSettings(updates: UserCourseSetting[]): void;
+    /**
+     * Get strategy-specific state for this course.
+     *
+     * Course-scoped alternative to `UserDBInterface.getStrategyState()`.
+     * The courseId is bound at construction via `getCourseInterface(courseId)`,
+     * so callers cannot accidentally access another course's state.
+     *
+     * @param strategyKey - Unique key identifying the state document
+     * @returns The state payload, or null if no state exists
+     */
+    getStrategyState<T>(strategyKey: string): Promise<T | null>;
+    /**
+     * Store strategy-specific state for this course.
+     *
+     * Course-scoped alternative to `UserDBInterface.putStrategyState()`.
+     *
+     * @param strategyKey - Unique key identifying the state document
+     * @param data - The state payload to store
+     */
+    putStrategyState<T>(strategyKey: string, data: T): Promise<void>;
+    /**
+     * Delete strategy-specific state for this course.
+     *
+     * Course-scoped alternative to `UserDBInterface.deleteStrategyState()`.
+     *
+     * @param strategyKey - Unique key identifying the state document
+     */
+    deleteStrategyState(strategyKey: string): Promise<void>;
 }
 type ClassroomRegistrationDesignation = 'student' | 'teacher' | 'aide' | 'admin';
 interface ClassroomRegistration {
@@ -537,6 +655,127 @@ interface ClassroomRegistrationDoc {
     registrations: ClassroomRegistration[];
 }
 
+/**
+ * Context for orchestration decisions during a session.
+ *
+ * Provides access to user/course data and helper methods for determining
+ * effective strategy weights based on the user's cohort assignment.
+ */
+interface OrchestrationContext {
+    user: UserDBInterface;
+    course: CourseDBInterface;
+    userId: string;
+    courseConfig: CourseConfig;
+    /**
+     * Calculate the effective weight for a strategy for this user.
+     *
+     * Applies deviation based on the user's cohort assignment (derived from
+     * userId, strategyId, and course salt).
+     *
+     * @param strategyId - Unique ID of the strategy
+     * @param learnable - The strategy's learning configuration
+     * @returns Effective weight multiplier (typically 0.1 - 3.0)
+     */
+    getEffectiveWeight(strategyId: string, learnable: LearnableWeight): number;
+    /**
+     * Get the deviation factor for this user/strategy.
+     * Range [-1.0, 1.0].
+     */
+    getDeviation(strategyId: string): number;
+}
+/**
+ * Compute a user's deviation for a specific strategy.
+ *
+ * Returns a value in [-1, 1] that is:
+ * 1. Deterministic for the same (user, strategy, salt) tuple
+ * 2. Uniformly distributed across users
+ * 3. Uncorrelated between different strategies (due to strategyId in hash)
+ * 4. Rotatable by changing the salt
+ *
+ * @param userId - ID of the user
+ * @param strategyId - ID of the strategy
+ * @param salt - Random seed from course config
+ * @returns Deviation factor between -1.0 and 1.0
+ */
+declare function computeDeviation(userId: string, strategyId: string, salt: string): number;
+/**
+ * Compute the exploration spread based on confidence.
+ *
+ * - Low confidence (0.0) -> Max spread (Explore broadly)
+ * - High confidence (1.0) -> Min spread (Exploit known good weight)
+ *
+ * @param confidence - Confidence level 0-1
+ * @returns Spread magnitude (half-width of the distribution)
+ */
+declare function computeSpread(confidence: number): number;
+/**
+ * Calculate the effective weight for a strategy instance.
+ *
+ * Combines the learnable weight (peak) with the user's deviation and the
+ * allowed spread (based on confidence).
+ *
+ * @param learnable - Strategy learning config
+ * @param userId - User ID
+ * @param strategyId - Strategy ID
+ * @param salt - Course salt
+ * @returns Effective weight multiplier
+ */
+declare function computeEffectiveWeight(learnable: LearnableWeight, userId: string, strategyId: string, salt: string): number;
+/**
+ * Create an orchestration context for a study session.
+ *
+ * Fetches necessary configuration to enable deterministic weight calculation.
+ *
+ * @param user - User DB interface
+ * @param course - Course DB interface
+ * @returns Initialized orchestration context
+ */
+declare function createOrchestrationContext(user: UserDBInterface, course: CourseDBInterface): Promise<OrchestrationContext>;
+
+/**
+ * Type for navigator constructor functions.
+ */
+type NavigatorConstructor = new (user: UserDBInterface, course: CourseDBInterface, strategyData: ContentNavigationStrategyData) => ContentNavigator;
+/**
+ * Register a navigator implementation.
+ *
+ * Call this to make a navigator available for instantiation by
+ * ContentNavigator.create() without relying on dynamic imports.
+ *
+ * @param implementingClass - The class name (e.g., 'elo', 'hierarchyDefinition')
+ * @param constructor - The navigator class constructor
+ */
+declare function registerNavigator(implementingClass: string, constructor: NavigatorConstructor): void;
+/**
+ * Get a navigator constructor from the registry.
+ *
+ * @param implementingClass - The class name to look up
+ * @returns The constructor, or undefined if not registered
+ */
+declare function getRegisteredNavigator(implementingClass: string): NavigatorConstructor | undefined;
+/**
+ * Check if a navigator is registered.
+ *
+ * @param implementingClass - The class name to check
+ * @returns true if registered, false otherwise
+ */
+declare function hasRegisteredNavigator(implementingClass: string): boolean;
+/**
+ * Get all registered navigator names.
+ * Useful for debugging and testing.
+ */
+declare function getRegisteredNavigatorNames(): string[];
+/**
+ * Initialize the navigator registry with all built-in navigators.
+ *
+ * This function dynamically imports all standard navigator implementations
+ * and registers them. Call this once at application startup to ensure
+ * all navigators are available.
+ *
+ * In test environments, this may need to be called explicitly before
+ * using ContentNavigator.create().
+ */
+declare function initializeNavigatorRegistry(): Promise<void>;
 /**
  * Tracks a single strategy's contribution to a card's final score.
  *
@@ -583,6 +822,17 @@ interface StrategyContribution {
     action: 'generated' | 'passed' | 'boosted' | 'penalized';
     /** Score after this strategy's processing */
     score: number;
+    /**
+     * The effective weight applied for this strategy instance.
+     * If using evolutionary orchestration, this includes deviation.
+     * If omitted, implies weight 1.0 (legacy behavior).
+     */
+    effectiveWeight?: number;
+    /**
+     * The deviation factor applied to this user's cohort for this strategy.
+     * Range [-1.0, 1.0].
+     */
+    deviation?: number;
     /**
      * Human-readable explanation of the strategy's decision.
      *
@@ -698,6 +948,10 @@ declare abstract class ContentNavigator implements StudyContentSource {
     protected strategyName?: string;
     /** Unique document ID for this strategy instance (from ContentNavigationStrategyData._id) */
     protected strategyId?: string;
+    /** Evolutionary weighting configuration */
+    learnable?: LearnableWeight;
+    /** Whether to bypass deviation (manual/static weighting) */
+    staticWeight?: boolean;
     /**
      * Constructor for standard navigators.
      * Call this from subclass constructors to initialize common fields.
@@ -729,7 +983,13 @@ declare abstract class ContentNavigator implements StudyContentSource {
      */
     protected putStrategyState<T>(data: T): Promise<void>;
     /**
-     * Factory method to create navigator instances dynamically.
+     * Factory method to create navigator instances.
+     *
+     * First checks the navigator registry for a pre-registered constructor.
+     * If not found, falls back to dynamic import (for custom navigators).
+     *
+     * For reliable operation in test environments, call initializeNavigatorRegistry()
+     * before using this method.
      *
      * @param user - User interface
      * @param course - Course interface
@@ -816,7 +1076,12 @@ interface StudyContentSource {
      * @returns Cards sorted by score descending
      */
     getWeightedCards(limit: number): Promise<WeightedCard[]>;
+    /**
+     * Get the orchestration context for this source.
+     * Used for recording learning outcomes.
+     */
+    getOrchestrationContext?(): Promise<OrchestrationContext>;
 }
 declare function getStudySource(source: ContentSourceID, user: UserDBInterface): Promise<StudyContentSource>;
 
-export { type AdminDBInterface as A, type UsrCrsDataInterface as B, type CourseDBInterface as C, type DataLayerResult as D, type ClassroomRegistrationDesignation as E, type ClassroomRegistration as F, type ClassroomRegistrationDoc as G, type SessionTrackingData as H, type UserConfig as I, type ActivityRecord as J, type CourseRegistration as K, type StrategyContribution as L, getCardOrigin as M, Navigators as N, NavigatorRole as O, NavigatorRoles as P, isGenerator as Q, isFilter as R, type StudySessionItem as S, type TeacherClassroomDBInterface as T, type UserDBInterface as U, type DocumentUpdater as V, type WeightedCard as W, newInterval as X, type UserDBReader as a, type CoursesDBInterface as b, type ClassroomDBInterface as c, type CourseInfo as d, type ContentNavigationStrategyData as e, ContentNavigator as f, type AssignedContent as g, type StudyContentSource as h, type StudentClassroomDBInterface as i, type ScheduledCard as j, type StudySessionFailedItem as k, type StudySessionFailedNewItem as l, type StudySessionFailedReviewItem as m, type StudySessionNewItem as n, type StudySessionReviewItem as o, isReview as p, type ContentSourceID as q, getStudySource as r, type CourseRegistrationDoc as s, type AssignedTag as t, type AssignedCourse as u, type AssignedCard as v, type UserDBWriter as w, type UserDBAuthenticator as x, type UserCourseSettings as y, type UserCourseSetting as z };
+export { isGenerator 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, getRegisteredNavigatorNames as Q, initializeNavigatorRegistry as R, type StudySessionItem as S, type TeacherClassroomDBInterface as T, type UserDBInterface as U, type StrategyContribution as V, type WeightedCard as W, getCardOrigin as X, Navigators as Y, NavigatorRole as Z, NavigatorRoles as _, type UserDBReader as a, isFilter as a0, type LearnableWeight as a1, type OrchestrationContext as a2, computeDeviation as a3, computeSpread as a4, computeEffectiveWeight as a5, createOrchestrationContext as a6, type DocumentUpdater as a7, newInterval as a8, 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 };