@vue-skuilder/db 0.1.23 → 0.1.25

package/src/core/interfaces/userDB.ts

@@ -7,6 +7,7 @@ import {
 import { CourseElo, Status } from '@vue-skuilder/common';
 import { Moment } from 'moment';
 import { CardHistory, CardRecord, QualifiedCardID } from '../types/types-legacy';
+import { UserOutcomeRecord } from '../types/userOutcome';
 import { UserConfig } from '../types/user';
 import { DocumentUpdater } from '@db/study';
 
@@ -62,6 +63,11 @@ export 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
@@ -151,6 +157,11 @@ export 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
@@ -160,10 +171,18 @@ export 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>;
 }
 
 /**
@@ -222,6 +241,37 @@ export interface UsrCrsDataInterface {
   getCourseSettings(): Promise<UserCourseSettings>;
   updateCourseSettings(updates: UserCourseSetting[]): void; // [ ] return a result of some sort?
   // getRegistrationDoc(): Promise<CourseRegistration>;
+
+  /**
+   * 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>;
 }
 
 export type ClassroomRegistrationDesignation = 'student' | 'teacher' | 'aide' | 'admin';

package/src/core/navigators/Pipeline.ts

@@ -6,6 +6,8 @@ import type { WeightedCard } from './index';
 import type { CardFilter, FilterContext } from './filters/types';
 import type { CardGenerator, GeneratorContext } from './generators/types';
 import { logger } from '../../util/logger';
+import { createOrchestrationContext, OrchestrationContext } from '../orchestration';
+import { captureRun, buildRunReport, type GeneratorSummary, type FilterImpact } from './PipelineDebugger';
 
 // ============================================================================
 // PIPELINE LOGGING HELPERS
@@ -51,14 +53,29 @@ function logExecutionSummary(
   generatedCount: number,
   filterCount: number,
   finalCount: number,
-  topScores: number[]
+  topScores: number[],
+  filterImpacts: Array<{ name: string; boosted: number; penalized: number; passed: number }>
 ): void {
   const scoreDisplay =
     topScores.length > 0 ? topScores.map((s) => s.toFixed(2)).join(', ') : 'none';
 
+  let filterSummary = '';
+  if (filterImpacts.length > 0) {
+    const impacts = filterImpacts.map((f) => {
+      const parts: string[] = [];
+      if (f.boosted > 0) parts.push(`+${f.boosted}`);
+      if (f.penalized > 0) parts.push(`-${f.penalized}`);
+      if (f.passed > 0) parts.push(`=${f.passed}`);
+      return `${f.name}: ${parts.join('/')}`;
+    });
+    filterSummary = `\n  Filter impact: ${impacts.join(', ')}`;
+  }
+
   logger.info(
     `[Pipeline] Execution: ${generatorName} produced ${generatedCount} → ` +
-      `${filterCount} filters → ${finalCount} results (top scores: ${scoreDisplay})`
+      `${filterCount} filters → ${finalCount} results (top scores: ${scoreDisplay})` +
+      filterSummary +
+      `\n  💡 Inspect: window.skuilder.pipeline`
   );
 }
 
@@ -189,17 +206,63 @@ export class Pipeline extends ContentNavigator {
     // Get candidates from generator, passing context
     let cards = await this.generator.getWeightedCards(fetchLimit, context);
     const generatedCount = cards.length;
+    
+    // Capture generator breakdown for debugging (if CompositeGenerator)
+    let generatorSummaries: GeneratorSummary[] | undefined;
+    if ((this.generator as any).generators) {
+      // This is a CompositeGenerator - extract per-generator info from provenance
+      const genMap = new Map<string, { cards: WeightedCard[] }>();
+      for (const card of cards) {
+        const firstProv = card.provenance[0];
+        if (firstProv) {
+          const genName = firstProv.strategyName;
+          if (!genMap.has(genName)) {
+            genMap.set(genName, { cards: [] });
+          }
+          genMap.get(genName)!.cards.push(card);
+        }
+      }
+      generatorSummaries = Array.from(genMap.entries()).map(([name, data]) => {
+        const newCards = data.cards.filter((c) => c.provenance[0]?.reason?.includes('new card'));
+        const reviewCards = data.cards.filter((c) => c.provenance[0]?.reason?.includes('review'));
+        return {
+          name,
+          cardCount: data.cards.length,
+          newCount: newCards.length,
+          reviewCount: reviewCards.length,
+          topScore: Math.max(...data.cards.map((c) => c.score), 0),
+        };
+      });
+    }
 
     logger.debug(`[Pipeline] Generator returned ${generatedCount} candidates`);
 
     // Batch hydrate tags before filters run
     cards = await this.hydrateTags(cards);
+    
+    // Keep a copy of all cards for debug capture (before filtering removes any)
+    const allCardsBeforeFiltering = [...cards];
 
-    // Apply filters sequentially
+    // Apply filters sequentially, tracking impact
+    const filterImpacts: FilterImpact[] = [];
     for (const filter of this.filters) {
       const beforeCount = cards.length;
+      const beforeScores = new Map(cards.map((c) => [c.cardId, c.score]));
       cards = await filter.transform(cards, context);
-      logger.debug(`[Pipeline] Filter '${filter.name}': ${beforeCount} → ${cards.length} cards`);
+      
+      // Count boost/penalize/pass/removed for this filter
+      let boosted = 0, penalized = 0, passed = 0;
+      const removed = beforeCount - cards.length;
+      
+      for (const card of cards) {
+        const before = beforeScores.get(card.cardId) ?? 0;
+        if (card.score > before) boosted++;
+        else if (card.score < before) penalized++;
+        else passed++;
+      }
+      filterImpacts.push({ name: filter.name, boosted, penalized, passed, removed });
+      
+      logger.debug(`[Pipeline] Filter '${filter.name}': ${beforeScores.size} → ${cards.length} cards (↑${boosted} ↓${penalized} =${passed})`);
     }
 
     // Remove zero-score cards (hard filtered)
@@ -218,12 +281,31 @@ export class Pipeline extends ContentNavigator {
       generatedCount,
       this.filters.length,
       result.length,
-      topScores
+      topScores,
+      filterImpacts
     );
 
     // Toggle provenance logging (shows scoring history for top cards):
     logCardProvenance(result, 3);
 
+    // Capture run for debug API
+    try {
+      const courseName = await this.course?.getCourseConfig().then((c) => c.name).catch(() => undefined);
+      const report = buildRunReport(
+        this.course?.getCourseID() || 'unknown',
+        courseName,
+        this.generator.name,
+        generatorSummaries,
+        generatedCount,
+        filterImpacts,
+        allCardsBeforeFiltering,
+        result
+      );
+      captureRun(report);
+    } catch (e) {
+      logger.debug(`[Pipeline] Failed to capture debug run: ${e}`);
+    }
+
     return result;
   }
 
@@ -273,10 +355,14 @@ export class Pipeline extends ContentNavigator {
       logger.debug(`[Pipeline] Could not get user ELO, using default: ${e}`);
     }
 
+    // Initialize orchestration context (used for evolutionary weighting)
+    const orchestration = await createOrchestrationContext(this.user!, this.course!);
+
     return {
       user: this.user!,
       course: this.course!,
       userElo,
+      orchestration,
     };
   }
 
@@ -286,4 +372,45 @@ export class Pipeline extends ContentNavigator {
   getCourseID(): string {
     return this.course!.getCourseID();
   }
+
+  /**
+   * Get orchestration context for outcome recording.
+   */
+  async getOrchestrationContext(): Promise<OrchestrationContext> {
+    return createOrchestrationContext(this.user!, this.course!);
+  }
+
+  /**
+   * Get IDs of all strategies in this pipeline.
+   * Used to record which strategies contributed to an outcome.
+   */
+  getStrategyIds(): string[] {
+    const ids: string[] = [];
+
+    const extractId = (obj: any): string | null => {
+      // Check for strategyId property (ContentNavigator, WeightedFilter)
+      if (obj.strategyId) return obj.strategyId;
+      return null;
+    };
+
+    // Generator(s)
+    const genId = extractId(this.generator);
+    if (genId) ids.push(genId);
+
+    // Inspect CompositeGenerator children (accessing private field via cast)
+    if ((this.generator as any).generators && Array.isArray((this.generator as any).generators)) {
+      (this.generator as any).generators.forEach((g: any) => {
+        const subId = extractId(g);
+        if (subId) ids.push(subId);
+      });
+    }
+
+    // Filters
+    for (const filter of this.filters) {
+      const fId = extractId(filter);
+      if (fId) ids.push(fId);
+    }
+
+    return [...new Set(ids)];
+  }
 }

package/src/core/navigators/PipelineAssembler.ts

@@ -1,13 +1,14 @@
 import type { ContentNavigationStrategyData } from '../types/contentNavigationStrategy';
-import { ContentNavigator, isGenerator, isFilter, Navigators } from './index';
+import { ContentNavigator, isGenerator, isFilter } from './index';
 import type { CardFilter } from './filters/types';
+import { WeightedFilter } from './filters/WeightedFilter';
 import type { CardGenerator } from './generators/types';
 import { Pipeline } from './Pipeline';
-import { DocType } from '../types/types-legacy';
 import { logger } from '../../util/logger';
 import type { CourseDBInterface } from '../interfaces/courseDB';
 import type { UserDBInterface } from '../interfaces/userDB';
 import CompositeGenerator from './generators/CompositeGenerator';
+import { createDefaultEloStrategy, createDefaultSrsStrategy } from './defaults';
 
 // ============================================================================
 // PIPELINE ASSEMBLER
@@ -102,13 +103,15 @@ export class PipelineAssembler {
       }
     }
 
-    // If no generator but filters exist, use default ELO generator
+    // If no generator but filters exist, use default ELO and SRS generators
     if (generatorStrategies.length === 0) {
       if (filterStrategies.length > 0) {
         logger.debug(
-          '[PipelineAssembler] No generator found, using default ELO with configured filters'
+          '[PipelineAssembler] No generator found, using default ELO and SRS with configured filters'
         );
-        generatorStrategies.push(this.makeDefaultEloStrategy(course.getCourseID()));
+        const courseId = course.getCourseID();
+        generatorStrategies.push(createDefaultEloStrategy(courseId));
+        generatorStrategies.push(createDefaultSrsStrategy(courseId));
       } else {
         warnings.push('No generator strategy found');
         return {
@@ -149,7 +152,19 @@ export class PipelineAssembler {
         const nav = await ContentNavigator.create(user, course, filterStrategy);
         // The navigator implements CardFilter
         if ('transform' in nav && typeof nav.transform === 'function') {
-          filters.push(nav as unknown as CardFilter);
+          let filter = nav as unknown as CardFilter;
+
+          // Apply evolutionary weighting wrapper if configured
+          if (filterStrategy.learnable) {
+            filter = new WeightedFilter(
+              filter,
+              filterStrategy.learnable,
+              filterStrategy.staticWeight,
+              filterStrategy._id
+            );
+          }
+
+          filters.push(filter);
           logger.debug(`[PipelineAssembler] Added filter: ${filterStrategy.name}`);
         } else {
           warnings.push(
@@ -175,20 +190,4 @@ export class PipelineAssembler {
       warnings,
     };
   }
-
-  /**
-   * Creates a default ELO generator strategy.
-   * Used when filters are configured but no generator is specified.
-   */
-  private makeDefaultEloStrategy(courseId: string): ContentNavigationStrategyData {
-    return {
-      _id: 'NAVIGATION_STRATEGY-ELO-default',
-      course: courseId,
-      docType: DocType.NAVIGATION_STRATEGY,
-      name: 'ELO (default)',
-      description: 'Default ELO-based generator',
-      implementingClass: Navigators.ELO,
-      serializedData: '',
-    };
-  }
 }