@vue-skuilder/db 0.1.23 → 0.1.25

package/src/core/navigators/generators/CompositeGenerator.ts

@@ -113,20 +113,66 @@ export default class CompositeGenerator extends ContentNavigator implements Card
       this.generators.map((g) => g.getWeightedCards(limit, context))
     );
 
-    // Group by cardId
-    const byCardId = new Map<string, WeightedCard[]>();
-    for (const cards of results) {
+    // Log per-generator breakdown for transparency
+    const generatorSummaries: string[] = [];
+    results.forEach((cards, index) => {
+      const gen = this.generators[index];
+      const genName = gen.name || `Generator ${index}`;
+      const newCards = cards.filter((c) => c.provenance[0]?.reason?.includes('new card'));
+      const reviewCards = cards.filter((c) => c.provenance[0]?.reason?.includes('review'));
+      
+      if (cards.length > 0) {
+        const topScore = Math.max(...cards.map((c) => c.score)).toFixed(2);
+        const parts: string[] = [];
+        if (newCards.length > 0) parts.push(`${newCards.length} new`);
+        if (reviewCards.length > 0) parts.push(`${reviewCards.length} reviews`);
+        const breakdown = parts.length > 0 ? parts.join(', ') : `${cards.length} cards`;
+        generatorSummaries.push(`${genName}: ${breakdown} (top: ${topScore})`);
+      } else {
+        generatorSummaries.push(`${genName}: 0 cards`);
+      }
+    });
+    logger.info(`[Composite] Generator breakdown: ${generatorSummaries.join(' | ')}`);
+
+    // Group by cardId, tracking the weight of the generator that produced each instance
+    type WeightedResult = { card: WeightedCard; weight: number };
+    const byCardId = new Map<string, WeightedResult[]>();
+
+    results.forEach((cards, index) => {
+      // Access learnable weight if available
+      const gen = this.generators[index] as unknown as ContentNavigator;
+
+      // Determine effective weight
+      let weight = gen.learnable?.weight ?? 1.0;
+      let deviation: number | undefined;
+
+      if (gen.learnable && !gen.staticWeight && context.orchestration) {
+        // Access strategyId (protected field) via type assertion
+        const strategyId = (gen as any).strategyId;
+        if (strategyId) {
+          weight = context.orchestration.getEffectiveWeight(strategyId, gen.learnable);
+          deviation = context.orchestration.getDeviation(strategyId);
+        }
+      }
+
       for (const card of cards) {
+        // Record effective weight in provenance for transparency
+        if (card.provenance.length > 0) {
+          card.provenance[0].effectiveWeight = weight;
+          card.provenance[0].deviation = deviation;
+        }
+
         const existing = byCardId.get(card.cardId) || [];
-        existing.push(card);
+        existing.push({ card, weight });
         byCardId.set(card.cardId, existing);
       }
-    }
+    });
 
     // Aggregate scores
     const merged: WeightedCard[] = [];
-    for (const [, cards] of byCardId) {
-      const aggregatedScore = this.aggregateScores(cards);
+    for (const [, items] of byCardId) {
+      const cards = items.map((i) => i.card);
+      const aggregatedScore = this.aggregateScores(items);
       const finalScore = Math.min(1.0, aggregatedScore); // Clamp to [0, 1]
 
       // Merge provenance from all generators that produced this card
@@ -138,7 +184,7 @@ export default class CompositeGenerator extends ContentNavigator implements Card
         finalScore > initialScore ? 'boosted' : finalScore < initialScore ? 'penalized' : 'passed';
 
       // Build reason explaining the aggregation
-      const reason = this.buildAggregationReason(cards, finalScore);
+      const reason = this.buildAggregationReason(items, finalScore);
 
       // Append composite provenance entry
       merged.push({
@@ -165,12 +211,18 @@ export default class CompositeGenerator extends ContentNavigator implements Card
   /**
    * Build human-readable reason for score aggregation.
    */
-  private buildAggregationReason(cards: WeightedCard[], finalScore: number): string {
+  private buildAggregationReason(
+    items: { card: WeightedCard; weight: number }[],
+    finalScore: number
+  ): string {
+    const cards = items.map((i) => i.card);
     const count = cards.length;
     const scores = cards.map((c) => c.score.toFixed(2)).join(', ');
 
     if (count === 1) {
-      return `Single generator, score ${finalScore.toFixed(2)}`;
+      const weightMsg =
+        Math.abs(items[0].weight - 1.0) > 0.001 ? ` (w=${items[0].weight.toFixed(2)})` : '';
+      return `Single generator, score ${finalScore.toFixed(2)}${weightMsg}`;
     }
 
     const strategies = cards.map((c) => c.provenance[0]?.strategy || 'unknown').join(', ');
@@ -180,12 +232,16 @@ export default class CompositeGenerator extends ContentNavigator implements Card
         return `Max of ${count} generators (${strategies}): scores [${scores}] → ${finalScore.toFixed(2)}`;
 
       case AggregationMode.AVERAGE:
-        return `Average of ${count} generators (${strategies}): scores [${scores}] → ${finalScore.toFixed(2)}`;
+        return `Weighted Avg of ${count} generators (${strategies}): scores [${scores}] → ${finalScore.toFixed(2)}`;
 
       case AggregationMode.FREQUENCY_BOOST: {
-        const avg = cards.reduce((sum, c) => sum + c.score, 0) / count;
+        // Recalculate basic weighted avg for display
+        const totalWeight = items.reduce((sum, i) => sum + i.weight, 0);
+        const weightedSum = items.reduce((sum, i) => sum + i.card.score * i.weight, 0);
+        const avg = totalWeight > 0 ? weightedSum / totalWeight : 0;
+
         const boost = 1 + FREQUENCY_BOOST_FACTOR * (count - 1);
-        return `Frequency boost from ${count} generators (${strategies}): avg ${avg.toFixed(2)} × ${boost.toFixed(2)} → ${finalScore.toFixed(2)}`;
+        return `Frequency boost from ${count} generators (${strategies}): w-avg ${avg.toFixed(2)} × ${boost.toFixed(2)} → ${finalScore.toFixed(2)}`;
       }
 
       default:
@@ -196,19 +252,26 @@ export default class CompositeGenerator extends ContentNavigator implements Card
   /**
    * Aggregate scores from multiple generators for the same card.
    */
-  private aggregateScores(cards: WeightedCard[]): number {
-    const scores = cards.map((c) => c.score);
+  private aggregateScores(items: { card: WeightedCard; weight: number }[]): number {
+    const scores = items.map((i) => i.card.score);
 
     switch (this.aggregationMode) {
       case AggregationMode.MAX:
         return Math.max(...scores);
 
-      case AggregationMode.AVERAGE:
-        return scores.reduce((sum, s) => sum + s, 0) / scores.length;
+      case AggregationMode.AVERAGE: {
+        const totalWeight = items.reduce((sum, i) => sum + i.weight, 0);
+        if (totalWeight === 0) return 0;
+        const weightedSum = items.reduce((sum, i) => sum + i.card.score * i.weight, 0);
+        return weightedSum / totalWeight;
+      }
 
       case AggregationMode.FREQUENCY_BOOST: {
-        const avg = scores.reduce((sum, s) => sum + s, 0) / scores.length;
-        const frequencyBoost = 1 + FREQUENCY_BOOST_FACTOR * (cards.length - 1);
+        const totalWeight = items.reduce((sum, i) => sum + i.weight, 0);
+        const weightedSum = items.reduce((sum, i) => sum + i.card.score * i.weight, 0);
+        const avg = totalWeight > 0 ? weightedSum / totalWeight : 0;
+
+        const frequencyBoost = 1 + FREQUENCY_BOOST_FACTOR * (items.length - 1);
         return avg * frequencyBoost;
       }
 

package/src/core/navigators/generators/elo.ts

@@ -5,6 +5,7 @@ import type { WeightedCard } from '../index';
 import { toCourseElo } from '@vue-skuilder/common';
 import type { QualifiedCardID } from '../..';
 import type { CardGenerator, GeneratorContext } from './types';
+import { logger } from '@db/util/logger';
 
 // ============================================================================
 // ELO NAVIGATOR
@@ -113,6 +114,18 @@ export default class ELONavigator extends ContentNavigator implements CardGenera
     // Sort by score descending
     scored.sort((a, b) => b.score - a.score);
 
-    return scored.slice(0, limit);
+    const result = scored.slice(0, limit);
+
+    // Log summary for transparency
+    if (result.length > 0) {
+      const topScores = result.slice(0, 3).map((c) => c.score.toFixed(2)).join(', ');
+      logger.info(
+        `[ELO] Course ${this.course.getCourseID()}: ${result.length} new cards (top scores: ${topScores})`
+      );
+    } else {
+      logger.info(`[ELO] Course ${this.course.getCourseID()}: No new cards available`);
+    }
+
+    return result;
   }
 }

package/src/core/navigators/generators/srs.ts

@@ -14,26 +14,49 @@ import { logger } from '@db/util/logger';
 //
 // A generator strategy that scores review cards by urgency.
 //
-// Urgency is determined by two factors:
+// Urgency is determined by three factors:
 // 1. Overdueness - how far past the scheduled review time
 // 2. Interval recency - shorter scheduled intervals indicate "novel content in progress"
+// 3. Backlog pressure - when too many reviews pile up, urgency increases globally
 //
 // A card with a 3-day interval that's 2 days overdue is more urgent than a card
 // with a 6-month interval that's 2 days overdue. The shorter interval represents
 // active learning at higher resolution.
 //
+// DESIGN PHILOSOPHY: SRS scheduling times are "eligibility dates" not hard "due dates".
+// When a card becomes eligible, it is "okish" to review now, but reviewing a little
+// later may be optimal. We don't aim to always beat review queues to zero (death spiral),
+// but rather maintain a healthy backlog of eligible reviews so the system can gracefully
+// handle usage upticks or breaks.
+//
 // This navigator only handles reviews - it does not generate new cards.
 // For new cards, use ELONavigator or another generator via CompositeGenerator.
 //
 // ============================================================================
 
+/**
+ * Default healthy backlog size.
+ * When due reviews exceed this, backlog pressure kicks in.
+ * Can be overridden via strategy config.
+ */
+const DEFAULT_HEALTHY_BACKLOG = 20;
+
+/**
+ * Maximum backlog pressure contribution to score.
+ * At 3x healthy backlog, pressure maxes out.
+ */
+const MAX_BACKLOG_PRESSURE = 0.5;
+
 /**
  * Configuration for the SRS strategy.
- * Currently minimal - the algorithm is not parameterized.
  */
-// eslint-disable-next-line @typescript-eslint/no-empty-object-type
 export interface SRSConfig {
-  // Future: configurable urgency curves, thresholds, etc.
+  /**
+   * Target "healthy" backlog size.
+   * When due reviews exceed this, urgency increases globally.
+   * Default: 20
+   */
+  healthyBacklog?: number;
 }
 
 /**
@@ -45,6 +68,7 @@ export interface SRSConfig {
  * Higher scores indicate more urgent reviews:
  * - Cards that are more overdue (relative to their interval) score higher
  * - Cards with shorter intervals (recent learning) score higher
+ * - When backlog exceeds "healthy" threshold, all reviews get urgency boost
  *
  * Only returns cards that are actually due (reviewTime has passed).
  * Does not generate new cards - use with CompositeGenerator for mixed content.
@@ -53,6 +77,9 @@ export default class SRSNavigator extends ContentNavigator implements CardGenera
   /** Human-readable name for CardGenerator interface */
   name: string;
 
+  /** Healthy backlog threshold - when exceeded, backlog pressure kicks in */
+  private healthyBacklog: number;
+
   constructor(
     user: UserDBInterface,
     course: CourseDBInterface,
@@ -60,6 +87,23 @@ export default class SRSNavigator extends ContentNavigator implements CardGenera
   ) {
     super(user, course, strategyData as ContentNavigationStrategyData);
     this.name = strategyData?.name || 'SRS';
+
+    // Parse config from serializedData if available
+    const config = this.parseConfig(strategyData?.serializedData);
+    this.healthyBacklog = config.healthyBacklog ?? DEFAULT_HEALTHY_BACKLOG;
+  }
+
+  /**
+   * Parse configuration from serialized JSON.
+   */
+  private parseConfig(serializedData?: string): SRSConfig {
+    if (!serializedData) return {};
+    try {
+      return JSON.parse(serializedData) as SRSConfig;
+    } catch {
+      logger.warn('[SRS] Failed to parse strategy config, using defaults');
+      return {};
+    }
   }
 
   /**
@@ -68,6 +112,7 @@ export default class SRSNavigator extends ContentNavigator implements CardGenera
    * Score formula combines:
    * - Relative overdueness: hoursOverdue / intervalHours
    * - Interval recency: exponential decay favoring shorter intervals
+   * - Backlog pressure: boost when due reviews exceed healthy threshold
    *
    * Cards not yet due are excluded (not scored as 0).
    *
@@ -82,14 +127,48 @@ export default class SRSNavigator extends ContentNavigator implements CardGenera
       throw new Error('SRSNavigator requires user and course to be set');
     }
 
-    const reviews = await this.user.getPendingReviews(this.course.getCourseID());
+    const courseId = this.course.getCourseID();
+    const reviews = await this.user.getPendingReviews(courseId);
     const now = moment.utc();
 
     // Filter to only cards that are actually due
     const dueReviews = reviews.filter((r) => now.isAfter(moment.utc(r.reviewTime)));
 
+    // Compute backlog pressure - applies globally to all reviews
+    const backlogPressure = this.computeBacklogPressure(dueReviews.length);
+
+    // Log review status for transparency
+    if (dueReviews.length > 0) {
+      const pressureNote =
+        backlogPressure > 0
+          ? ` [backlog pressure: +${backlogPressure.toFixed(2)}]`
+          : ` [healthy backlog]`;
+      logger.info(
+        `[SRS] Course ${courseId}: ${dueReviews.length} reviews due now (of ${reviews.length} scheduled)${pressureNote}`
+      );
+    } else if (reviews.length > 0) {
+      // Reviews exist but none are due yet - show when next one is due
+      const sortedByDue = [...reviews].sort((a, b) =>
+        moment.utc(a.reviewTime).diff(moment.utc(b.reviewTime))
+      );
+      const nextDue = sortedByDue[0];
+      const nextDueTime = moment.utc(nextDue.reviewTime);
+      const untilDue = moment.duration(nextDueTime.diff(now));
+      const untilDueStr =
+        untilDue.asHours() < 1
+          ? `${Math.round(untilDue.asMinutes())}m`
+          : untilDue.asHours() < 24
+            ? `${Math.round(untilDue.asHours())}h`
+            : `${Math.round(untilDue.asDays())}d`;
+      logger.info(
+        `[SRS] Course ${courseId}: 0 reviews due now (${reviews.length} scheduled, next in ${untilDueStr})`
+      );
+    } else {
+      logger.info(`[SRS] Course ${courseId}: No reviews scheduled`);
+    }
+
     const scored = dueReviews.map((review) => {
-      const { score, reason } = this.computeUrgencyScore(review, now);
+      const { score, reason } = this.computeUrgencyScore(review, now, backlogPressure);
 
       return {
         cardId: review.cardId,
@@ -109,16 +188,41 @@ export default class SRSNavigator extends ContentNavigator implements CardGenera
       };
     });
 
-    logger.debug(`[srsNav] got ${scored.length} weighted cards`);
-
     // Sort by score descending and limit
     return scored.sort((a, b) => b.score - a.score).slice(0, limit);
   }
 
+  /**
+   * Compute backlog pressure based on number of due reviews.
+   *
+   * Backlog pressure is 0 when at or below healthy threshold,
+   * and increases linearly above it, maxing out at MAX_BACKLOG_PRESSURE.
+   *
+   * Examples (with default healthyBacklog=20):
+   * - 10 due reviews → 0.00 (healthy)
+   * - 20 due reviews → 0.00 (at threshold)
+   * - 40 due reviews → 0.25 (2x threshold)
+   * - 60 due reviews → 0.50 (3x threshold, maxed)
+   *
+   * @param dueCount - Number of reviews currently due
+   * @returns Backlog pressure score to add to urgency (0 to MAX_BACKLOG_PRESSURE)
+   */
+  private computeBacklogPressure(dueCount: number): number {
+    if (dueCount <= this.healthyBacklog) {
+      return 0;
+    }
+
+    // Linear increase: at 2x healthy, pressure = 0.25; at 3x, pressure = 0.50
+    const excess = dueCount - this.healthyBacklog;
+    const pressure = (excess / this.healthyBacklog) * (MAX_BACKLOG_PRESSURE / 2);
+
+    return Math.min(MAX_BACKLOG_PRESSURE, pressure);
+  }
+
   /**
    * Compute urgency score for a review card.
    *
-   * Two factors:
+   * Three factors:
    * 1. Relative overdueness = hoursOverdue / intervalHours
    *    - 2 days overdue on 3-day interval = 0.67 (urgent)
    *    - 2 days overdue on 180-day interval = 0.01 (not urgent)
@@ -128,12 +232,22 @@ export default class SRSNavigator extends ContentNavigator implements CardGenera
    *    - 30 days (720h) → ~0.56
    *    - 180 days → ~0.30
    *
-   * Combined: base 0.5 + weighted average of factors * 0.45
-   * Result range: approximately 0.5 to 0.95
+   * 3. Backlog pressure = global boost when review backlog exceeds healthy threshold
+   *    - At healthy backlog: 0
+   *    - At 2x healthy: +0.25
+   *    - At 3x+ healthy: +0.50 (max)
+   *
+   * Combined: base 0.5 + (urgency factors * 0.45) + backlog pressure
+   * Result range: 0.5 to 1.0 (uncapped to allow high-urgency reviews to compete with new cards)
+   *
+   * @param review - The scheduled card to score
+   * @param now - Current time
+   * @param backlogPressure - Pre-computed backlog pressure (0 to 0.5)
    */
   private computeUrgencyScore(
     review: ScheduledCard,
-    now: moment.Moment
+    now: moment.Moment,
+    backlogPressure: number
   ): { score: number; reason: string } {
     const scheduledAt = moment.utc(review.scheduledAt);
     const due = moment.utc(review.reviewTime);
@@ -154,13 +268,27 @@ export default class SRSNavigator extends ContentNavigator implements CardGenera
     const overdueContribution = Math.min(1.0, Math.max(0, relativeOverdue));
     const urgency = overdueContribution * 0.5 + recencyFactor * 0.5;
 
-    // Final score: base 0.5 + urgency contribution, capped at 0.95
-    const score = Math.min(0.95, 0.5 + urgency * 0.45);
+    // Final score: base 0.5 + urgency contribution + backlog pressure
+    // Uncapped at 1.0 (no 0.95 ceiling) - allows high-urgency reviews to compete with new cards
+    const baseScore = 0.5 + urgency * 0.45;
+    const score = Math.min(1.0, baseScore + backlogPressure);
 
-    const reason =
-      `${Math.round(hoursOverdue)}h overdue (interval: ${Math.round(intervalHours)}h, ` +
-      `relative: ${relativeOverdue.toFixed(2)}), recency: ${recencyFactor.toFixed(2)}, review`;
+    // Build reason string with all contributing factors
+    const reasonParts = [
+      `${Math.round(hoursOverdue)}h overdue`,
+      `interval: ${Math.round(intervalHours)}h`,
+      `relative: ${relativeOverdue.toFixed(2)}`,
+      `recency: ${recencyFactor.toFixed(2)}`,
+    ];
+
+    if (backlogPressure > 0) {
+      reasonParts.push(`backlog: +${backlogPressure.toFixed(2)}`);
+    }
+
+    reasonParts.push('review');
+
+    const reason = reasonParts.join(', ');
 
     return { score, reason };
   }
-}
+}

package/src/core/navigators/generators/types.ts

@@ -1,6 +1,7 @@
 import type { WeightedCard } from '../index';
 import type { CourseDBInterface } from '../../interfaces/courseDB';
 import type { UserDBInterface } from '../../interfaces/userDB';
+import type { OrchestrationContext } from '../../orchestration';
 
 // ============================================================================
 // CARD GENERATOR INTERFACE
@@ -34,6 +35,9 @@ export interface GeneratorContext {
   /** User's global ELO score for this course */
   userElo: number;
 
+  /** Orchestration context for evolutionary weighting */
+  orchestration?: OrchestrationContext;
+
   // Future extensions:
   // - user's tag-level ELO data
   // - course config