@vue-skuilder/db 0.1.23 → 0.1.25

package/src/core/navigators/index.ts

@@ -6,9 +6,143 @@ export type { CardFilter, FilterContext, CardFilterFactory } from './filters/typ
 // Re-export generator types
 export type { CardGenerator, GeneratorContext, CardGeneratorFactory } from './generators/types';
 
-import { ContentNavigationStrategyData } from '../types/contentNavigationStrategy';
+// Re-export pipeline debugger API
+export {
+  pipelineDebugAPI,
+  mountPipelineDebugger,
+  type PipelineRunReport,
+  type GeneratorSummary,
+  type FilterImpact,
+} from './PipelineDebugger';
+
+import { LearnableWeight } from '../types/contentNavigationStrategy';
+export type { ContentNavigationStrategyData, LearnableWeight } from '../types/contentNavigationStrategy';
+import type { ContentNavigationStrategyData } from '../types/contentNavigationStrategy';
 import { logger } from '../../util/logger';
 
+// ============================================================================
+// NAVIGATOR REGISTRY
+// ============================================================================
+//
+// Static registry of navigator implementations. This allows ContentNavigator.create()
+// to instantiate navigators without relying on dynamic imports, which don't work
+// reliably in all environments (e.g., test runners, bundled code).
+//
+// Usage:
+// 1. Import your navigator class
+// 2. Call registerNavigator('implementingClass', YourNavigatorClass)
+// 3. ContentNavigator.create() will use the registry before falling back to
+//    dynamic import
+//
+// ============================================================================
+
+/**
+ * Type for navigator constructor functions.
+ */
+export type NavigatorConstructor = new (
+  user: UserDBInterface,
+  course: CourseDBInterface,
+  strategyData: ContentNavigationStrategyData
+) => ContentNavigator;
+
+/**
+ * Registry mapping implementingClass names to navigator constructors.
+ * Populated by registerNavigator() and used by ContentNavigator.create().
+ */
+const navigatorRegistry = new Map<string, NavigatorConstructor>();
+
+/**
+ * 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
+ */
+export function registerNavigator(
+  implementingClass: string,
+  constructor: NavigatorConstructor
+): void {
+  navigatorRegistry.set(implementingClass, constructor);
+  logger.debug(`[NavigatorRegistry] Registered: ${implementingClass}`);
+}
+
+/**
+ * Get a navigator constructor from the registry.
+ *
+ * @param implementingClass - The class name to look up
+ * @returns The constructor, or undefined if not registered
+ */
+export function getRegisteredNavigator(implementingClass: string): NavigatorConstructor | undefined {
+  return navigatorRegistry.get(implementingClass);
+}
+
+/**
+ * Check if a navigator is registered.
+ *
+ * @param implementingClass - The class name to check
+ * @returns true if registered, false otherwise
+ */
+export function hasRegisteredNavigator(implementingClass: string): boolean {
+  return navigatorRegistry.has(implementingClass);
+}
+
+/**
+ * Get all registered navigator names.
+ * Useful for debugging and testing.
+ */
+export function getRegisteredNavigatorNames(): string[] {
+  return Array.from(navigatorRegistry.keys());
+}
+
+/**
+ * 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().
+ */
+export async function initializeNavigatorRegistry(): Promise<void> {
+  logger.debug('[NavigatorRegistry] Initializing built-in navigators...');
+
+  // Import and register generators
+  const [eloModule, srsModule] = await Promise.all([
+    import('./generators/elo'),
+    import('./generators/srs'),
+  ]);
+  registerNavigator('elo', eloModule.default);
+  registerNavigator('srs', srsModule.default);
+
+  // Import and register filters
+  const [
+    hierarchyModule,
+    interferenceModule,
+    relativePriorityModule,
+    userTagPreferenceModule,
+  ] = await Promise.all([
+    import('./filters/hierarchyDefinition'),
+    import('./filters/interferenceMitigator'),
+    import('./filters/relativePriority'),
+    import('./filters/userTagPreference'),
+  ]);
+  registerNavigator('hierarchyDefinition', hierarchyModule.default);
+  registerNavigator('interferenceMitigator', interferenceModule.default);
+  registerNavigator('relativePriority', relativePriorityModule.default);
+  registerNavigator('userTagPreference', userTagPreferenceModule.default);
+
+  // Note: eloDistance uses a factory pattern (createEloDistanceFilter) rather than
+  // a ContentNavigator class, so it's not registered here. It's used differently
+  // via Pipeline composition.
+
+  logger.debug(
+    `[NavigatorRegistry] Initialized ${navigatorRegistry.size} navigators: ${getRegisteredNavigatorNames().join(', ')}`
+  );
+}
+
 // ============================================================================
 // NAVIGATION STRATEGY API
 // ============================================================================
@@ -92,6 +226,19 @@ export interface StrategyContribution {
   /** 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.
    *
@@ -260,6 +407,12 @@ export abstract class ContentNavigator implements StudyContentSource {
   /** Unique document ID for this strategy instance (from ContentNavigationStrategyData._id) */
   protected strategyId?: string;
 
+  /** Evolutionary weighting configuration */
+  public learnable?: LearnableWeight;
+
+  /** Whether to bypass deviation (manual/static weighting) */
+  public staticWeight?: boolean;
+
   /**
    * Constructor for standard navigators.
    * Call this from subclass constructors to initialize common fields.
@@ -277,6 +430,8 @@ export abstract class ContentNavigator implements StudyContentSource {
     if (strategyData) {
       this.strategyName = strategyData.name;
       this.strategyId = strategyData._id;
+      this.learnable = strategyData.learnable;
+      this.staticWeight = strategyData.staticWeight;
     }
   }
 
@@ -333,7 +488,13 @@ export abstract class ContentNavigator implements StudyContentSource {
   }
 
   /**
-   * 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
@@ -346,24 +507,53 @@ export abstract class ContentNavigator implements StudyContentSource {
     strategyData: ContentNavigationStrategyData
   ): Promise<ContentNavigator> {
     const implementingClass = strategyData.implementingClass;
+
+    // First, check the registry for a pre-registered constructor
+    const RegisteredImpl = getRegisteredNavigator(implementingClass);
+    if (RegisteredImpl) {
+      logger.debug(`[ContentNavigator.create] Using registered navigator: ${implementingClass}`);
+      return new RegisteredImpl(user, course, strategyData);
+    }
+
+    // Fall back to dynamic import for custom/unknown navigators
+    logger.debug(
+      `[ContentNavigator.create] Navigator not in registry, attempting dynamic import: ${implementingClass}`
+    );
+
     let NavigatorImpl;
 
     // Try different extension variations
     const variations = ['.ts', '.js', ''];
-    const dirs = ['filters', 'generators'];
 
     for (const ext of variations) {
-      for (const dir of dirs) {
-        const loadFrom = `./${dir}/${implementingClass}${ext}`;
-        try {
-          const module = await import(loadFrom);
-          NavigatorImpl = module.default;
-          break; // Break the loop if loading succeeds
-        } catch (e) {
-          // Continue to next variation if this one fails
-          logger.debug(`Failed to load extension from ${loadFrom}:`, e);
-        }
+      // Try generators directory
+      try {
+        const module = await import(`./generators/${implementingClass}${ext}`);
+        NavigatorImpl = module.default;
+        if (NavigatorImpl) break;
+      } catch (e) {
+        logger.debug(`Failed to load generator ${implementingClass}${ext}:`, e);
+      }
+
+      // Try filters directory
+      try {
+        const module = await import(`./filters/${implementingClass}${ext}`);
+        NavigatorImpl = module.default;
+        if (NavigatorImpl) break;
+      } catch (e) {
+        logger.debug(`Failed to load filter ${implementingClass}${ext}:`, e);
+      }
+
+      // Try current directory (legacy)
+      try {
+        const module = await import(`./${implementingClass}${ext}`);
+        NavigatorImpl = module.default;
+        if (NavigatorImpl) break;
+      } catch (e) {
+        logger.debug(`Failed to load legacy ${implementingClass}${ext}:`, e);
       }
+      
+      if (NavigatorImpl) break;
     }
 
     if (!NavigatorImpl) {

package/src/core/orchestration/gradient.ts

@@ -0,0 +1,133 @@
+import { UserOutcomeRecord } from '../types/userOutcome';
+import { GradientObservation, GradientResult } from '../types/learningState';
+import { logger } from '../../util/logger';
+
+/**
+ * Extract (deviation, outcome) observations for a specific strategy
+ * from a collection of UserOutcomeRecords.
+ *
+ * @param outcomes - Collection of outcome records (from multiple users)
+ * @param strategyId - The strategy to extract observations for
+ * @returns Array of gradient observations
+ */
+export function aggregateOutcomesForGradient(
+  outcomes: UserOutcomeRecord[],
+  strategyId: string
+): GradientObservation[] {
+  const observations: GradientObservation[] = [];
+
+  for (const outcome of outcomes) {
+    // Skip if this outcome doesn't have a deviation for this strategy
+    const deviation = outcome.deviations[strategyId];
+    if (deviation === undefined) {
+      continue;
+    }
+
+    observations.push({
+      deviation,
+      outcomeValue: outcome.outcomeValue,
+      weight: 1.0,
+    });
+  }
+
+  logger.debug(
+    `[Orchestration] Aggregated ${observations.length} observations for strategy ${strategyId}`
+  );
+
+  return observations;
+}
+
+/**
+ * Compute linear regression on (deviation, outcome) pairs.
+ *
+ * Uses ordinary least squares to find the best fit line:
+ *   outcome = gradient * deviation + intercept
+ *
+ * The gradient tells us:
+ * - Positive: users with higher deviation (higher weight) had better outcomes
+ *             → we should increase the peak weight
+ * - Negative: users with higher deviation (higher weight) had worse outcomes
+ *             → we should decrease the peak weight
+ * - Near zero: weight doesn't affect outcomes much
+ *             → we're near optimal, increase confidence
+ *
+ * @param observations - Array of (deviation, outcome) pairs
+ * @returns Regression result, or null if insufficient data
+ */
+export function computeStrategyGradient(
+  observations: GradientObservation[]
+): GradientResult | null {
+  const n = observations.length;
+
+  if (n < 3) {
+    logger.debug(`[Orchestration] Insufficient observations for gradient (${n} < 3)`);
+    return null;
+  }
+
+  // Compute means
+  let sumX = 0;
+  let sumY = 0;
+  let sumW = 0;
+
+  for (const obs of observations) {
+    const w = obs.weight ?? 1.0;
+    sumX += obs.deviation * w;
+    sumY += obs.outcomeValue * w;
+    sumW += w;
+  }
+
+  const meanX = sumX / sumW;
+  const meanY = sumY / sumW;
+
+  // Compute slope (gradient) and intercept using weighted least squares
+  let numerator = 0;
+  let denominator = 0;
+  let ssTotal = 0;
+
+  for (const obs of observations) {
+    const w = obs.weight ?? 1.0;
+    const dx = obs.deviation - meanX;
+    const dy = obs.outcomeValue - meanY;
+
+    numerator += w * dx * dy;
+    denominator += w * dx * dx;
+    ssTotal += w * dy * dy;
+  }
+
+  // Avoid division by zero if all deviations are the same
+  if (denominator < 1e-10) {
+    logger.debug(`[Orchestration] No variance in deviations, cannot compute gradient`);
+    return {
+      gradient: 0,
+      intercept: meanY,
+      rSquared: 0,
+      sampleSize: n,
+    };
+  }
+
+  const gradient = numerator / denominator;
+  const intercept = meanY - gradient * meanX;
+
+  // Compute R-squared
+  let ssResidual = 0;
+  for (const obs of observations) {
+    const w = obs.weight ?? 1.0;
+    const predicted = gradient * obs.deviation + intercept;
+    const residual = obs.outcomeValue - predicted;
+    ssResidual += w * residual * residual;
+  }
+
+  const rSquared = ssTotal > 1e-10 ? 1 - ssResidual / ssTotal : 0;
+
+  logger.debug(
+    `[Orchestration] Computed gradient: ${gradient.toFixed(4)}, ` +
+      `intercept: ${intercept.toFixed(4)}, R²: ${rSquared.toFixed(4)}, n=${n}`
+  );
+
+  return {
+    gradient,
+    intercept,
+    rSquared: Math.max(0, Math.min(1, rSquared)), // Clamp to [0,1]
+    sampleSize: n,
+  };
+}

package/src/core/orchestration/index.ts

@@ -0,0 +1,210 @@
+import type { UserDBInterface } from '../interfaces/userDB';
+import type { CourseDBInterface } from '../interfaces/courseDB';
+import type { LearnableWeight } from '../types/contentNavigationStrategy';
+import type { CourseConfig } from '@vue-skuilder/common';
+import { logger } from '../../util/logger';
+
+// Re-export gradient and learning functions
+export { aggregateOutcomesForGradient, computeStrategyGradient } from './gradient';
+export {
+  updateStrategyWeight,
+  updateLearningState,
+  runPeriodUpdate,
+  getDefaultLearnableWeight,
+} from './learning';
+export type { PeriodUpdateInput, PeriodUpdateResult } from './learning';
+
+// Re-export signal functions
+export { computeOutcomeSignal, scoreAccuracyInZone } from './signal';
+export type { SignalConfig } from './signal';
+
+// Re-export recording functions
+export { recordUserOutcome } from './recording';
+
+// Re-export types
+export type { GradientObservation, GradientResult, StrategyLearningState } from '../types/learningState';
+export type { UserOutcomeRecord } from '../types/userOutcome';
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+/**
+ * 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.
+ */
+export 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;
+}
+
+// ============================================================================
+// DEVIATION LOGIC
+// ============================================================================
+
+const MIN_SPREAD = 0.1;
+const MAX_SPREAD = 0.5;
+const MIN_WEIGHT = 0.1;
+const MAX_WEIGHT = 3.0;
+
+/**
+ * FNV-1a hash implementation for deterministic distribution.
+ */
+function fnv1a(str: string): number {
+  let hash = 2166136261;
+  for (let i = 0; i < str.length; i++) {
+    hash ^= str.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}
+
+/**
+ * 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
+ */
+export function computeDeviation(userId: string, strategyId: string, salt: string): number {
+  const input = `${userId}:${strategyId}:${salt}`;
+  const hash = fnv1a(input);
+  
+  // Normalize 32-bit unsigned integer to [0, 1]
+  const normalized = hash / 4294967296;
+  
+  // Map [0, 1] to [-1, 1]
+  return (normalized * 2) - 1;
+}
+
+/**
+ * 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)
+ */
+export function computeSpread(confidence: number): number {
+  // Linear interpolation: confidence 0 -> MAX_SPREAD, confidence 1 -> MIN_SPREAD
+  const clampedConfidence = Math.max(0, Math.min(1, confidence));
+  return MAX_SPREAD - (clampedConfidence * (MAX_SPREAD - MIN_SPREAD));
+}
+
+/**
+ * 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
+ */
+export function computeEffectiveWeight(
+  learnable: LearnableWeight,
+  userId: string,
+  strategyId: string,
+  salt: string
+): number {
+  const deviation = computeDeviation(userId, strategyId, salt);
+  const spread = computeSpread(learnable.confidence);
+  
+  // Apply deviation: effective = weight + (deviation * spread * weight)
+  // We scale the spread relative to the weight itself so it's proportional.
+  // e.g. weight 2.0, deviation -0.5, spread 0.2 -> 2.0 + (-0.5 * 0.2 * 2.0) = 1.8
+  const adjustment = deviation * spread * learnable.weight;
+  
+  const effective = learnable.weight + adjustment;
+  
+  // Clamp to sane bounds to prevent runaway weights or negative multipliers
+  return Math.max(MIN_WEIGHT, Math.min(MAX_WEIGHT, effective));
+}
+
+// ============================================================================
+// CONTEXT FACTORY
+// ============================================================================
+
+/**
+ * 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
+ */
+export async function createOrchestrationContext(
+  user: UserDBInterface,
+  course: CourseDBInterface
+): Promise<OrchestrationContext> {
+  let courseConfig: CourseConfig;
+  try {
+    courseConfig = await course.getCourseConfig();
+  } catch (e) {
+    logger.error(`[Orchestration] Failed to load course config: ${e}`);
+    // Fallback stub if config load fails
+    courseConfig = {
+      name: 'Unknown',
+      description: '',
+      public: false,
+      deleted: false,
+      creator: '',
+      admins: [],
+      moderators: [],
+      dataShapes: [],
+      questionTypes: [],
+      orchestration: { salt: 'default' },
+    };
+  }
+
+  const userId = user.getUsername(); // Or user ID if available on interface
+  const salt = courseConfig.orchestration?.salt || 'default_salt';
+
+  return {
+    user,
+    course,
+    userId,
+    courseConfig,
+    
+    getEffectiveWeight(strategyId: string, learnable: LearnableWeight): number {
+      return computeEffectiveWeight(learnable, userId, strategyId, salt);
+    },
+
+    getDeviation(strategyId: string): number {
+      return computeDeviation(userId, strategyId, salt);
+    }
+  };
+}