@vue-skuilder/db 0.1.32-e → 0.1.33-vite8-4

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

@@ -3,9 +3,8 @@ import type { UserDBInterface } from '../../interfaces/userDB';
 import { ContentNavigator } from '../index';
 import type { WeightedCard } from '../index';
 import type { ContentNavigationStrategyData } from '../../types/contentNavigationStrategy';
-import type { CardGenerator, GeneratorContext, GeneratorResult } from './types';
+import type { CardGenerator, GeneratorContext, GeneratorResult, ReplanHints } from './types';
 import { logger } from '@db/util/logger';
-import type { ReplanHints } from '../../study/SessionController';
 
 // ============================================================================
 // PRESCRIBED CARDS GENERATOR
@@ -89,6 +88,7 @@ interface GroupRuntimeState {
   surfaceableTargets: string[];
   targetTags: Map<string, string[]>;
   supportCandidates: string[];
+  discoveredSupportCandidates: string[];
   supportTags: string[];
   pressureMultiplier: number;
   supportMultiplier: number;
@@ -108,11 +108,11 @@ const DEFAULT_HIERARCHY_DEPTH = 2;
 const DEFAULT_MIN_COUNT = 3;
 const BASE_TARGET_SCORE = 1.0;
 const BASE_SUPPORT_SCORE = 0.8;
+const DISCOVERED_SUPPORT_SCORE = 12.0;
 const MAX_TARGET_MULTIPLIER = 8.0;
 const MAX_SUPPORT_MULTIPLIER = 4.0;
-const LOCKED_TAG_PREFIXES = ['concept:'];
-const LESSON_GATE_PENALTY_TAG_HINT = 'concept:';
-const PRESCRIBED_DEBUG_VERSION = 'testversion-prescribed-v2';
+
+const PRESCRIBED_DEBUG_VERSION = 'testversion-prescribed-v3';
 
 function dedupe<T>(arr: T[]): T[] {
   return [...new Set(arr)];
@@ -135,6 +135,31 @@ function matchesTagPattern(tag: string, pattern: string): boolean {
   return re.test(tag);
 }
 
+/**
+ * Extract the word stem from a card ID for deduplication.
+ * ML: c-ml-{word}-{blanks} → {word}
+ * WS: c-ws-{word}-{contrast} → {word}
+ * Other: full cardId as fallback.
+ */
+function extractWordStem(cardId: string): string {
+  for (const prefix of ['c-ml-', 'c-ws-', 'c-spelling-']) {
+    if (cardId.startsWith(prefix)) {
+      const rest = cardId.slice(prefix.length);
+      const lastDash = rest.lastIndexOf('-');
+      return lastDash > 0 ? rest.slice(0, lastDash) : rest;
+    }
+  }
+  return cardId;
+}
+
+/** Fisher-Yates shuffle in place. */
+function shuffleInPlace<T>(arr: T[]): void {
+  for (let i = arr.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [arr[i], arr[j]] = [arr[j], arr[i]];
+  }
+}
+
 function pickTopByScore(cards: WeightedCard[], limit: number): WeightedCard[] {
   return [...cards]
     .sort((a, b) => b.score - a.score || a.cardId.localeCompare(b.cardId))
@@ -201,6 +226,22 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
         ? await this.course.getAppliedTagsBatch(allRelevantIds)
         : new Map<string, string[]>();
 
+    const courseTagDocs = await this.course.getCourseTagStubs().catch(
+      () =>
+        ({
+          rows: [],
+          offset: 0,
+          total_rows: 0,
+        }) as unknown as Awaited<ReturnType<CourseDBInterface['getCourseTagStubs']>>
+    );
+    const cardsByTag = new Map<string, string[]>();
+    for (const row of courseTagDocs.rows ?? []) {
+      const tagDoc = row.doc as { name?: string; taggedCards?: string[] } | undefined;
+      if (tagDoc?.name && Array.isArray(tagDoc.taggedCards)) {
+        cardsByTag.set(tagDoc.name, [...tagDoc.taggedCards]);
+      }
+    }
+
     const nextState: PrescribedProgressState = {
       updatedAt: isoNow(),
       groups: {},
@@ -217,12 +258,46 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
         activeIds,
         seenIds,
         tagsByCard,
+        cardsByTag,
         hierarchyConfigs,
         userTagElo,
         userGlobalElo,
       });
 
       groupRuntimes.push(runtime);
+
+      logger.info(
+        `[Prescribed] Group '${group.id}': ` +
+          `${group.targetCardIds.length} targets total, ` +
+          `${runtime.encounteredTargets.size} encountered, ` +
+          `${runtime.pendingTargets.length} pending ` +
+          `(${runtime.surfaceableTargets.length} surfaceable, ${runtime.blockedTargets.length} blocked), ` +
+          `${runtime.supportCandidates.length} authored support candidates, ` +
+          `${runtime.discoveredSupportCandidates.length} discovered support candidates, ` +
+          `pressure=${runtime.pressureMultiplier.toFixed(2)}`
+      );
+      if (runtime.blockedTargets.length > 0) {
+        logger.info(
+          `[Prescribed] Group '${group.id}' blocked targets: ${runtime.blockedTargets.join(', ')}`
+        );
+        logger.info(
+          `[Prescribed] Group '${group.id}' support tags needed: ${runtime.supportTags.join(', ') || '(none)'}`
+        );
+        logger.info(
+          `[Prescribed] Group '${group.id}' escalation mode: ` +
+            (runtime.supportCandidates.length > 0
+              ? 'direct-support'
+              : runtime.discoveredSupportCandidates.length > 0
+                ? 'inserted-support-candidates'
+                : 'boost-only')
+        );
+        if (runtime.discoveredSupportCandidates.length > 0) {
+          logger.info(
+            `[Prescribed] Group '${group.id}' discovered support candidates: ${runtime.discoveredSupportCandidates.join(', ')}`
+          );
+        }
+      }
+
       nextState.groups[group.id] = this.buildNextGroupState(runtime, progress.groups[group.id]);
 
       const directCards = this.buildDirectTargetCards(
@@ -235,8 +310,13 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
         courseId,
         emittedIds
       );
+      const discoveredSupportCards = this.buildDiscoveredSupportCards(
+        runtime,
+        courseId,
+        emittedIds
+      );
 
-      emitted.push(...directCards, ...supportCards);
+      emitted.push(...directCards, ...supportCards, ...discoveredSupportCards);
     }
 
     const hintSummary = this.buildSupportHintSummary(groupRuntimes);
@@ -251,8 +331,21 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
           }
         : undefined;
 
+    if (hints) {
+      const tagEntries = Object.entries(hints.boostTags ?? {}) as Array<[string, number]>;
+      logger.info(
+        `[Prescribed] Emitting ${tagEntries.length} boost hint(s): ` +
+          tagEntries.map(([tag, mult]) => `${tag}×${mult.toFixed(1)}`).join(', ')
+      );
+    } else {
+      logger.info('[Prescribed] No hints to emit (no blocked targets or no support tags)');
+    }
+
     if (emitted.length === 0) {
-      logger.debug('[Prescribed] No prescribed targets/support emitted this run');
+      logger.info(
+        '[Prescribed] 0 cards emitted (all targets blocked, authored/discovered support candidates exhausted)' +
+          (hints ? ' — boost hints emitted but may not survive filters' : '')
+      );
       await this.putStrategyState(nextState).catch((e) => {
         logger.debug(`[Prescribed] Failed to persist empty-state update: ${e}`);
       });
@@ -292,7 +385,8 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
     logger.info(
       `[Prescribed] Emitting ${finalCards.length} cards ` +
         `(${finalCards.filter((c) => c.provenance[0]?.reason.includes('mode=target')).length} target, ` +
-        `${finalCards.filter((c) => c.provenance[0]?.reason.includes('mode=support')).length} support)`
+        `${finalCards.filter((c) => c.provenance[0]?.reason.includes('mode=support')).length} support, ` +
+        `${finalCards.filter((c) => c.provenance[0]?.reason.includes('mode=discovered-support')).length} discovered support)`
     );
 
     return hints ? { cards: finalCards, hints } : { cards: finalCards };
@@ -325,14 +419,22 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
 
   private parseConfig(serializedData: string): PrescribedConfig {
     try {
-      const parsed = JSON.parse(serializedData);
+      const parsed = JSON.parse(serializedData) as { groups?: unknown[] };
       const groupsRaw = Array.isArray(parsed.groups) ? parsed.groups : [];
       const groups: PrescribedGroupConfig[] = groupsRaw
-        .map((raw: any, i: number) => ({
+        .map((raw: any, i: number): PrescribedGroupConfig => ({
           id: typeof raw.id === 'string' && raw.id.trim().length > 0 ? raw.id : `group-${i + 1}`,
-          targetCardIds: dedupe(Array.isArray(raw.targetCardIds) ? raw.targetCardIds.filter((v: unknown) => typeof v === 'string') : []),
-          supportCardIds: dedupe(Array.isArray(raw.supportCardIds) ? raw.supportCardIds.filter((v: unknown) => typeof v === 'string') : []),
-          supportTagPatterns: dedupe(Array.isArray(raw.supportTagPatterns) ? raw.supportTagPatterns.filter((v: unknown) => typeof v === 'string') : []),
+          targetCardIds: dedupe(
+            (Array.isArray(raw.targetCardIds) ? raw.targetCardIds.filter((v: unknown): v is string => typeof v === 'string') : [])
+          ),
+          supportCardIds: dedupe(
+            (Array.isArray(raw.supportCardIds) ? raw.supportCardIds.filter((v: unknown): v is string => typeof v === 'string') : [])
+          ),
+          supportTagPatterns: dedupe(
+            (Array.isArray(raw.supportTagPatterns)
+              ? raw.supportTagPatterns.filter((v: unknown): v is string => typeof v === 'string')
+              : [])
+          ),
           freshnessWindowSessions:
             typeof raw.freshnessWindowSessions === 'number' ? raw.freshnessWindowSessions : DEFAULT_FRESHNESS_WINDOW,
           maxDirectTargetsPerRun:
@@ -358,12 +460,12 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
 
   private async loadHierarchyConfigs(): Promise<HierarchyConfig[]> {
     try {
-      const strategies = await this.course.getNavigationStrategies();
+      const strategies = await this.course.getAllNavigationStrategies();
       return strategies
-        .filter((s) => s.implementingClass === 'hierarchyDefinition')
-        .map((s) => {
+        .filter((s: ContentNavigationStrategyData) => s.implementingClass === 'hierarchyDefinition')
+        .map((s: ContentNavigationStrategyData) => {
           try {
-            const parsed = JSON.parse(s.serializedData);
+            const parsed = JSON.parse(s.serializedData) as { prerequisites?: Record<string, TagPrerequisite[]> };
             return {
               prerequisites: parsed.prerequisites || {},
             } as HierarchyConfig;
@@ -383,6 +485,7 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
     activeIds: Set<string>;
     seenIds: Set<string>;
     tagsByCard: Map<string, string[]>;
+    cardsByTag: Map<string, string[]>;
     hierarchyConfigs: HierarchyConfig[];
     userTagElo: Record<string, { score: number; count: number }>;
     userGlobalElo: number;
@@ -393,6 +496,7 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
       activeIds,
       seenIds,
       tagsByCard,
+      cardsByTag,
       hierarchyConfigs,
       userTagElo,
       userGlobalElo,
@@ -468,6 +572,28 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
       ),
     ]).filter((id) => !activeIds.has(id) && !seenIds.has(id));
 
+    const discoveredSupportCandidates =
+      blockedTargets.length > 0 && supportTags.size > 0 && supportCandidates.length === 0
+        ? this.findDiscoveredSupportCards({
+            supportTags: [...supportTags],
+            cardsByTag,
+            activeIds,
+            seenIds,
+            excludedIds: new Set([
+              ...group.targetCardIds,
+              ...(group.supportCardIds ?? []),
+            ]),
+            limit: group.maxSupportCardsPerRun ?? DEFAULT_MAX_SUPPORT_PER_RUN,
+          })
+        : [];
+
+    if (blockedTargets.length > 0 && supportTags.size > 0 && discoveredSupportCandidates.length === 0) {
+      logger.info(
+        `[Prescribed] Group '${group.id}' discovered 0 broader support candidates ` +
+          `(blocked=${blockedTargets.length}; authoredSupport=${supportCandidates.length})`
+      );
+    }
+
     const sessionsSinceSurfaced = priorState?.sessionsSinceSurfaced ?? 0;
     const freshnessWindow = group.freshnessWindowSessions ?? DEFAULT_FRESHNESS_WINDOW;
     const staleSessions = Math.max(0, sessionsSinceSurfaced - freshnessWindow);
@@ -488,6 +614,7 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
       surfaceableTargets,
       targetTags,
       supportCandidates,
+      discoveredSupportCandidates,
       supportTags: [...supportTags],
       pressureMultiplier,
       supportMultiplier,
@@ -594,6 +721,50 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
     return cards;
   }
 
+  private buildDiscoveredSupportCards(
+    runtime: GroupRuntimeState,
+    courseId: string,
+    emittedIds: Set<string>
+  ): WeightedCard[] {
+    if (runtime.blockedTargets.length === 0 || runtime.discoveredSupportCandidates.length === 0) {
+      return [];
+    }
+
+    const maxSupport = runtime.group.maxSupportCardsPerRun ?? DEFAULT_MAX_SUPPORT_PER_RUN;
+    const supportIds = runtime.discoveredSupportCandidates
+      .filter((id) => !emittedIds.has(id))
+      .slice(0, maxSupport);
+
+    const cards: WeightedCard[] = [];
+    for (const cardId of supportIds) {
+      emittedIds.add(cardId);
+      cards.push({
+        cardId,
+        courseId,
+        score: DISCOVERED_SUPPORT_SCORE * runtime.supportMultiplier,
+        provenance: [
+          {
+            strategy: 'prescribed',
+            strategyName: this.strategyName || this.name,
+            strategyId: this.strategyId || 'NAVIGATION_STRATEGY-prescribed',
+            action: 'generated' as const,
+            score: DISCOVERED_SUPPORT_SCORE * runtime.supportMultiplier,
+            reason:
+              `mode=discovered-support;group=${runtime.group.id};pending=${runtime.pendingTargets.length};` +
+              `blocked=${runtime.blockedTargets.length};` +
+              `blockedTargets=${runtime.blockedTargets.join('|') || 'none'};` +
+              `supportCard=${cardId};` +
+              `supportTags=${runtime.supportTags.join('|') || 'none'};` +
+              `multiplier=${runtime.supportMultiplier.toFixed(2)};` +
+              `testversion=${runtime.debugVersion}`,
+          },
+        ],
+      });
+    }
+
+    return cards;
+  }
+
   private findSupportCardsByTags(
     group: PrescribedGroupConfig,
     tagsByCard: Map<string, string[]>,
@@ -626,6 +797,63 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
     return [...candidates];
   }
 
+  private findDiscoveredSupportCards(args: {
+    supportTags: string[];
+    cardsByTag: Map<string, string[]>;
+    activeIds: Set<string>;
+    seenIds: Set<string>;
+    excludedIds: Set<string>;
+    limit: number;
+  }): string[] {
+    const { supportTags, cardsByTag, activeIds, seenIds, excludedIds, limit } = args;
+
+    const byCardId = new Map<string, { cardId: string; matches: number }>();
+
+    for (const supportTag of supportTags) {
+      const taggedCards = cardsByTag.get(supportTag) ?? [];
+      for (const cardId of taggedCards) {
+        if (activeIds.has(cardId) || seenIds.has(cardId) || excludedIds.has(cardId)) {
+          continue;
+        }
+        const existing = byCardId.get(cardId);
+        if (existing) {
+          existing.matches += 1;
+        } else {
+          byCardId.set(cardId, { cardId, matches: 1 });
+        }
+      }
+    }
+
+    const candidates = [...byCardId.values()]
+      .sort((a, b) => b.matches - a.matches || a.cardId.localeCompare(b.cardId));
+
+    // Diversify by word stem — avoid returning 4 variants of "year".
+    // ML cards follow c-ml-{word}-{blanks}, so the stem is everything before
+    // the last dash-delimited segment of digits/commas.
+    const usedStems = new Set<string>();
+    const diverse: typeof candidates = [];
+    const deferred: typeof candidates = [];
+
+    for (const entry of candidates) {
+      const stem = extractWordStem(entry.cardId);
+      if (!usedStems.has(stem)) {
+        usedStems.add(stem);
+        diverse.push(entry);
+      } else {
+        deferred.push(entry);
+      }
+    }
+
+    // Combine diverse-first, then deferred for overflow, and shuffle within
+    // each tier so we don't always pick the same card for a given word.
+    shuffleInPlace(diverse);
+    shuffleInPlace(deferred);
+
+    return [...diverse, ...deferred]
+      .slice(0, limit)
+      .map((entry) => entry.cardId);
+  }
+
   private resolveBlockedSupportTags(
     targetTags: string[],
     hierarchyConfigs: HierarchyConfig[],
@@ -697,7 +925,6 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
     out: Set<string>
   ): void {
     if (depth < 0 || visited.has(tag)) return;
-    if (this.isHardGatedTag(tag)) return;
 
     visited.add(tag);
 
@@ -732,10 +959,7 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
     }
   }
 
-  private isHardGatedTag(tag: string): boolean {
-    return LOCKED_TAG_PREFIXES.some((prefix) => tag.startsWith(prefix)) &&
-      tag.startsWith(LESSON_GATE_PENALTY_TAG_HINT);
-  }
+
 
   private isPrerequisiteMet(
     prereq: TagPrerequisite,

package/tests/core/navigators/CompositeGenerator.test.ts

@@ -3,7 +3,7 @@ import CompositeGenerator, {
   AggregationMode,
 } from '../../../src/core/navigators/generators/CompositeGenerator';
 import { ContentNavigator, WeightedCard } from '../../../src/core/navigators/index';
-import { GeneratorContext } from '../../../src/core/navigators/generators/types';
+import { GeneratorContext, GeneratorResult } from '../../../src/core/navigators/generators/types';
 import { UserDBInterface } from '../../../src/core/interfaces/userDB';
 import { CourseDBInterface } from '../../../src/core/interfaces/courseDB';
 
@@ -41,8 +41,8 @@ class MockGenerator extends ContentNavigator {
     this.mockWeightedCards = cards;
   }
 
-  async getWeightedCards(limit: number): Promise<WeightedCard[]> {
-    return this.mockWeightedCards.slice(0, limit);
+  async getWeightedCards(limit: number): Promise<GeneratorResult> {
+    return { cards: this.mockWeightedCards.slice(0, limit) };
   }
 }
 
@@ -96,7 +96,7 @@ describe('CompositeGenerator', () => {
       ]);
 
       const composite = new CompositeGenerator([generator]);
-      const result = await composite.getWeightedCards(10, mockContext);
+      const { cards: result } = await composite.getWeightedCards(10, mockContext);
 
       expect(result).toHaveLength(2);
       expect(result[0].cardId).toBe('card-1');
@@ -114,7 +114,7 @@ describe('CompositeGenerator', () => {
       ]);
 
       const composite = new CompositeGenerator([generator]);
-      const result = await composite.getWeightedCards(2, mockContext);
+      const { cards: result } = await composite.getWeightedCards(2, mockContext);
 
       expect(result).toHaveLength(2);
       expect(result[0].cardId).toBe('card-1');
@@ -137,7 +137,7 @@ describe('CompositeGenerator', () => {
       ]);
 
       const composite = new CompositeGenerator([gen1, gen2], AggregationMode.AVERAGE);
-      const result = await composite.getWeightedCards(10, mockContext);
+      const { cards: result } = await composite.getWeightedCards(10, mockContext);
 
       // Should have 3 unique cards
       expect(result).toHaveLength(3);
@@ -157,7 +157,7 @@ describe('CompositeGenerator', () => {
       gen2.setWeightedCards([makeWeightedCard('card-1', 'course-1', 0.9, 'new')]);
 
       const composite = new CompositeGenerator([gen1, gen2], AggregationMode.MAX);
-      const result = await composite.getWeightedCards(10, mockContext);
+      const { cards: result } = await composite.getWeightedCards(10, mockContext);
 
       expect(result).toHaveLength(1);
       expect(result[0].score).toBe(0.9);
@@ -173,7 +173,7 @@ describe('CompositeGenerator', () => {
       gen2.setWeightedCards([makeWeightedCard('card-1', 'course-1', 0.6, 'new')]);
 
       const composite = new CompositeGenerator([gen1, gen2], AggregationMode.AVERAGE);
-      const result = await composite.getWeightedCards(10, mockContext);
+      const { cards: result } = await composite.getWeightedCards(10, mockContext);
 
       expect(result).toHaveLength(1);
       expect(result[0].score).toBeCloseTo(0.7); // (0.8 + 0.6) / 2
@@ -190,7 +190,7 @@ describe('CompositeGenerator', () => {
       gen3.setWeightedCards([makeWeightedCard('card-1', 'course-1', 0.6, 'new')]);
 
       const composite = new CompositeGenerator([gen1, gen2, gen3], AggregationMode.AVERAGE);
-      const result = await composite.getWeightedCards(10, mockContext);
+      const { cards: result } = await composite.getWeightedCards(10, mockContext);
 
       expect(result).toHaveLength(1);
       expect(result[0].score).toBeCloseTo(0.7); // (0.9 + 0.6 + 0.6) / 3
@@ -206,7 +206,7 @@ describe('CompositeGenerator', () => {
       gen2.setWeightedCards([makeWeightedCard('card-1', 'course-1', 0.6, 'new')]);
 
       const composite = new CompositeGenerator([gen1, gen2]); // default mode
-      const result = await composite.getWeightedCards(10, mockContext);
+      const { cards: result } = await composite.getWeightedCards(10, mockContext);
 
       expect(result).toHaveLength(1);
       // avg = (0.8 + 0.6) / 2 = 0.7
@@ -226,7 +226,7 @@ describe('CompositeGenerator', () => {
       gen3.setWeightedCards([makeWeightedCard('card-1', 'course-1', 0.6, 'new')]);
 
       const composite = new CompositeGenerator([gen1, gen2, gen3]);
-      const result = await composite.getWeightedCards(10, mockContext);
+      const { cards: result } = await composite.getWeightedCards(10, mockContext);
 
       expect(result).toHaveLength(1);
       // avg = 0.6
@@ -243,7 +243,7 @@ describe('CompositeGenerator', () => {
       gen2.setWeightedCards([makeWeightedCard('card-2', 'course-1', 0.6, 'new')]);
 
       const composite = new CompositeGenerator([gen1, gen2]);
-      const result = await composite.getWeightedCards(10, mockContext);
+      const { cards: result } = await composite.getWeightedCards(10, mockContext);
 
       expect(result).toHaveLength(2);
       // No boost for single-generator cards
@@ -254,42 +254,6 @@ describe('CompositeGenerator', () => {
     });
   });
 
-  describe('score clamping', () => {
-    it('clamps boosted scores to maximum of 1.0', async () => {
-      const gen1 = new MockGenerator();
-      gen1.setWeightedCards([makeWeightedCard('card-1', 'course-1', 0.9, 'new')]);
-
-      const gen2 = new MockGenerator();
-      gen2.setWeightedCards([makeWeightedCard('card-1', 'course-1', 0.9, 'new')]);
-
-      const composite = new CompositeGenerator([gen1, gen2]);
-      const result = await composite.getWeightedCards(10, mockContext);
-
-      expect(result).toHaveLength(1);
-      // avg = 0.9, boost = 1.1, result = 0.99 (would be 0.99, not clamped)
-      // But with higher scores:
-      expect(result[0].score).toBeLessThanOrEqual(1.0);
-    });
-
-    it('clamps to 1.0 when boosted score exceeds maximum', async () => {
-      const gen1 = new MockGenerator();
-      gen1.setWeightedCards([makeWeightedCard('card-1', 'course-1', 1.0, 'new')]);
-
-      const gen2 = new MockGenerator();
-      gen2.setWeightedCards([makeWeightedCard('card-1', 'course-1', 1.0, 'new')]);
-
-      const gen3 = new MockGenerator();
-      gen3.setWeightedCards([makeWeightedCard('card-1', 'course-1', 1.0, 'new')]);
-
-      const composite = new CompositeGenerator([gen1, gen2, gen3]);
-      const result = await composite.getWeightedCards(10, mockContext);
-
-      expect(result).toHaveLength(1);
-      // avg = 1.0, boost = 1.2, result would be 1.2 but clamped to 1.0
-      expect(result[0].score).toBe(1.0);
-    });
-  });
-
   describe('sorting and limiting', () => {
     it('returns cards sorted by score descending', async () => {
       const gen1 = new MockGenerator();
@@ -300,7 +264,7 @@ describe('CompositeGenerator', () => {
       ]);
 
       const composite = new CompositeGenerator([gen1]);
-      const result = await composite.getWeightedCards(10, mockContext);
+      const { cards: result } = await composite.getWeightedCards(10, mockContext);
 
       expect(result).toHaveLength(3);
       expect(result[0].cardId).toBe('card-high');
@@ -319,7 +283,7 @@ describe('CompositeGenerator', () => {
       gen2.setWeightedCards([makeWeightedCard('card-boosted', 'course-1', 0.5, 'new')]);
 
       const composite = new CompositeGenerator([gen1, gen2]);
-      const result = await composite.getWeightedCards(10, mockContext);
+      const { cards: result } = await composite.getWeightedCards(10, mockContext);
 
       expect(result).toHaveLength(2);
       // card-boosted: avg=0.5, boost=1.1, final=0.55

package/tests/core/navigators/Pipeline.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { Pipeline } from '../../../src/core/navigators/Pipeline';
 import { WeightedCard, ContentNavigator } from '../../../src/core/navigators/index';
 import { CardFilter, FilterContext } from '../../../src/core/navigators/filters/types';
+import type { GeneratorResult } from '../../../src/core/navigators/generators/types';
 
 import { CourseDBInterface } from '../../../src/core/interfaces/courseDB';
 import { UserDBInterface } from '../../../src/core/interfaces/userDB';
@@ -22,8 +23,8 @@ class MockGenerator extends ContentNavigator {
     this.cards = cards;
   }
 
-  async getWeightedCards(limit: number): Promise<WeightedCard[]> {
-    return this.cards.slice(0, limit);
+  async getWeightedCards(limit: number): Promise<GeneratorResult> {
+    return { cards: this.cards.slice(0, limit) };
   }
 }
 
@@ -143,7 +144,7 @@ describe('Pipeline', () => {
       const generator = new MockGenerator(cards);
       const pipeline = new Pipeline(generator, [], mockUser, mockCourse);
 
-      const result = await pipeline.getWeightedCards(10);
+      const { cards: result } = await pipeline.getWeightedCards(10);
 
       expect(result).toHaveLength(2);
       expect(result[0].cardId).toBe('card-1');
@@ -155,7 +156,7 @@ describe('Pipeline', () => {
       const generator = new MockGenerator(cards);
       const pipeline = new Pipeline(generator, [], mockUser, mockCourse);
 
-      const result = await pipeline.getWeightedCards(10);
+      const { cards: result } = await pipeline.getWeightedCards(10);
 
       expect(result[0].cardId).toBe('high');
       expect(result[1].cardId).toBe('mid');
@@ -172,7 +173,7 @@ describe('Pipeline', () => {
       const generator = new MockGenerator(cards);
       const pipeline = new Pipeline(generator, [], mockUser, mockCourse);
 
-      const result = await pipeline.getWeightedCards(2);
+      const { cards: result } = await pipeline.getWeightedCards(2);
 
       expect(result).toHaveLength(2);
       expect(result[0].cardId).toBe('card-1');
@@ -183,7 +184,7 @@ describe('Pipeline', () => {
       const generator = new MockGenerator([]);
       const pipeline = new Pipeline(generator, [], mockUser, mockCourse);
 
-      const result = await pipeline.getWeightedCards(10);
+      const { cards: result } = await pipeline.getWeightedCards(10);
 
       expect(result).toHaveLength(0);
     });
@@ -196,7 +197,7 @@ describe('Pipeline', () => {
       const filter = createMultiplierFilter('Half', 0.5);
       const pipeline = new Pipeline(generator, [filter], mockUser, mockCourse);
 
-      const result = await pipeline.getWeightedCards(10);
+      const { cards: result } = await pipeline.getWeightedCards(10);
 
       expect(result[0].score).toBe(0.5); // 1.0 * 0.5
       expect(result[1].score).toBe(0.4); // 0.8 * 0.5
@@ -209,7 +210,7 @@ describe('Pipeline', () => {
       const filter2 = createMultiplierFilter('Double', 2.0);
       const pipeline = new Pipeline(generator, [filter1, filter2], mockUser, mockCourse);
 
-      const result = await pipeline.getWeightedCards(10);
+      const { cards: result } = await pipeline.getWeightedCards(10);
 
       // 1.0 * 0.5 * 2.0 = 1.0
       expect(result[0].score).toBe(1.0);
@@ -221,7 +222,7 @@ describe('Pipeline', () => {
       const filter = createBlockingFilter('Blocker', ['block']);
       const pipeline = new Pipeline(generator, [filter], mockUser, mockCourse);
 
-      const result = await pipeline.getWeightedCards(10);
+      const { cards: result } = await pipeline.getWeightedCards(10);
 
       expect(result).toHaveLength(1);
       expect(result[0].cardId).toBe('keep');
@@ -234,7 +235,7 @@ describe('Pipeline', () => {
       const filter2 = createMultiplierFilter('Filter B', 0.8);
       const pipeline = new Pipeline(generator, [filter1, filter2], mockUser, mockCourse);
 
-      const result = await pipeline.getWeightedCards(10);
+      const { cards: result } = await pipeline.getWeightedCards(10);
 
       expect(result[0].provenance).toHaveLength(3); // generator + 2 filters
       expect(result[0].provenance[0].strategyName).toBe('Test Generator');
@@ -253,12 +254,12 @@ describe('Pipeline', () => {
       // Order: A then B
       const generator1 = new MockGenerator([...cards]);
       const pipeline1 = new Pipeline(generator1, [filterA, filterB], mockUser, mockCourse);
-      const result1 = await pipeline1.getWeightedCards(10);
+      const { cards: result1 } = await pipeline1.getWeightedCards(10);
 
       // Order: B then A
       const generator2 = new MockGenerator([...cards]);
       const pipeline2 = new Pipeline(generator2, [filterB, filterA], mockUser, mockCourse);
-      const result2 = await pipeline2.getWeightedCards(10);
+      const { cards: result2 } = await pipeline2.getWeightedCards(10);
 
       // Both should yield 1.0 * 0.5 * 0.8 = 0.4
       expect(result1[0].score).toBeCloseTo(0.4);