@vue-skuilder/db 0.1.32-c → 0.1.32-e

package/dist/{types-DZ5dUqbL.d.ts → types-CJrLM1Ew.d.ts}

@@ -1,5 +1,5 @@
 import { CourseConfig } from '@vue-skuilder/common';
-import { D as DocType } from './types-legacy-C7r0T4OV.js';
+import { D as DocType } from './types-legacy-JXDxinpU.js';
 
 interface StaticCourseManifest {
     version: string;

package/dist/{types-ZL8tOPQZ.d.cts → types-W8n-B6HG.d.cts}

@@ -1,5 +1,5 @@
 import { CourseConfig } from '@vue-skuilder/common';
-import { D as DocType } from './types-legacy-C7r0T4OV.cjs';
+import { D as DocType } from './types-legacy-JXDxinpU.cjs';
 
 interface StaticCourseManifest {
     version: string;

package/dist/{types-legacy-C7r0T4OV.d.cts → types-legacy-JXDxinpU.d.cts}

@@ -157,4 +157,4 @@ interface QuestionRecord extends CardRecord, Evaluation {
     priorAttemps: number;
 }
 
-export { type CardData as C, DocType as D, type Field as F, GuestUsername as G, type QualifiedCardID as Q, type SkuilderCourseData as S, type TagStub as T, type Tag as a, type CourseListData as b, type DisplayableData as c, type DataShapeData as d, type QuestionData as e, DocTypePrefixes as f, type CardHistory as g, type CardRecord as h, type QuestionRecord as i, log as l };
+export { type CardHistory as C, DocType as D, type Field as F, GuestUsername as G, type QualifiedCardID as Q, type SkuilderCourseData as S, type TagStub as T, type Tag as a, DocTypePrefixes as b, type CardRecord as c, type CardData as d, type CourseListData as e, type DisplayableData as f, type DataShapeData as g, type QuestionData as h, type QuestionRecord as i, log as l };

package/dist/{types-legacy-C7r0T4OV.d.ts → types-legacy-JXDxinpU.d.ts}

@@ -157,4 +157,4 @@ interface QuestionRecord extends CardRecord, Evaluation {
     priorAttemps: number;
 }
 
-export { type CardData as C, DocType as D, type Field as F, GuestUsername as G, type QualifiedCardID as Q, type SkuilderCourseData as S, type TagStub as T, type Tag as a, type CourseListData as b, type DisplayableData as c, type DataShapeData as d, type QuestionData as e, DocTypePrefixes as f, type CardHistory as g, type CardRecord as h, type QuestionRecord as i, log as l };
+export { type CardHistory as C, DocType as D, type Field as F, GuestUsername as G, type QualifiedCardID as Q, type SkuilderCourseData as S, type TagStub as T, type Tag as a, DocTypePrefixes as b, type CardRecord as c, type CardData as d, type CourseListData as e, type DisplayableData as f, type DataShapeData as g, type QuestionData as h, type QuestionRecord as i, log as l };

package/dist/util/packer/index.d.cts

@@ -1,5 +1,5 @@
-export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-ZL8tOPQZ.cjs';
-export { C as CouchDBToStaticPacker } from '../../index-m8MMGxxR.cjs';
+export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-W8n-B6HG.cjs';
+export { C as CouchDBToStaticPacker } from '../../index-Ba7hYbHj.cjs';
 import '@vue-skuilder/common';
-import '../../types-legacy-C7r0T4OV.cjs';
+import '../../types-legacy-JXDxinpU.cjs';
 import 'moment';

package/dist/util/packer/index.d.ts

@@ -1,5 +1,5 @@
-export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-DZ5dUqbL.js';
-export { C as CouchDBToStaticPacker } from '../../index-X6wHrURm.js';
+export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-CJrLM1Ew.js';
+export { C as CouchDBToStaticPacker } from '../../index-BWvO-_rJ.js';
 import '@vue-skuilder/common';
-import '../../types-legacy-C7r0T4OV.js';
+import '../../types-legacy-JXDxinpU.js';
 import 'moment';

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.32-c",
+  "version": "0.1.32-e",
   "description": "Database layer for vue-skuilder",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -48,7 +48,7 @@
   },
   "dependencies": {
     "@nilock2/pouchdb-authentication": "^1.0.2",
-    "@vue-skuilder/common": "0.1.32-c",
+    "@vue-skuilder/common": "0.1.32-e",
     "cross-fetch": "^4.1.0",
     "moment": "^2.29.4",
     "pouchdb": "^9.0.0",

package/src/core/interfaces/contentSource.ts

@@ -1,11 +1,10 @@
 import { getDataLayer } from '@db/factory';
 import { UserDBInterface } from '..';
 import { StudentClassroomDB } from '../../impl/couch/classroomDB';
-import { WeightedCard } from '../navigators';
+import type { GeneratorResult, ReplanHints } from '../navigators/generators/types';
 import { TagFilter, hasActiveFilter } from '@vue-skuilder/common';
 import { TagFilteredContentSource } from '../../study/TagFilteredContentSource';
 import { OrchestrationContext } from '../orchestration';
-import type { ReplanHints } from '@db/study/SessionController';
 
 export type StudySessionFailedItem = StudySessionFailedNewItem | StudySessionFailedReviewItem;
 
@@ -73,7 +72,7 @@ export interface StudyContentSource {
    * @param limit - Maximum number of cards to return
    * @returns Cards sorted by score descending
    */
-  getWeightedCards(limit: number): Promise<WeightedCard[]>;
+  getWeightedCards(limit: number): Promise<GeneratorResult>;
 
   /**
    * Get the orchestration context for this source.

package/src/core/navigators/Pipeline.ts

@@ -5,6 +5,7 @@ import { ContentNavigator } from './index';
 import type { WeightedCard } from './index';
 import type { CardFilter, FilterContext } from './filters/types';
 import type { CardGenerator, GeneratorContext } from './generators/types';
+import type { GeneratorResult } from './generators/types';
 import { logger } from '../../util/logger';
 import { createOrchestrationContext, OrchestrationContext } from '../orchestration';
 import { captureRun, buildRunReport, registerPipelineForDebug, type GeneratorSummary, type FilterImpact } from './PipelineDebugger';
@@ -22,9 +23,9 @@ import { captureRun, buildRunReport, registerPipelineForDebug, type GeneratorSum
 //   'gpc:exercise:t-*'   — all t-variant exercises
 //
 
-// ReplanHints is the canonical type — re-export for consumers that import from Pipeline
-import { ReplanHints } from '@db/study/SessionController';
-export { ReplanHints };
+// ReplanHints is defined in generators/types — re-export for consumers that import from Pipeline
+import type { ReplanHints } from './generators/types';
+export type { ReplanHints };
 
 /**
  * Convert a glob pattern (with `*` wildcards) to a RegExp.
@@ -47,6 +48,54 @@ function cardMatchesTagPattern(card: WeightedCard, pattern: string): boolean {
   return (card.tags ?? []).some((tag) => globMatch(tag, pattern));
 }
 
+function mergeHints(allHints: Array<ReplanHints | null | undefined>): ReplanHints | undefined {
+  const defined = allHints.filter((h): h is ReplanHints => h !== null && h !== undefined);
+  if (defined.length === 0) return undefined;
+
+  const merged: ReplanHints = {};
+
+  const boostTags: Record<string, number> = {};
+  for (const hints of defined) {
+    for (const [pattern, factor] of Object.entries(hints.boostTags ?? {})) {
+      boostTags[pattern] = (boostTags[pattern] ?? 1) * factor;
+    }
+  }
+  if (Object.keys(boostTags).length > 0) {
+    merged.boostTags = boostTags;
+  }
+
+  const boostCards: Record<string, number> = {};
+  for (const hints of defined) {
+    for (const [pattern, factor] of Object.entries(hints.boostCards ?? {})) {
+      boostCards[pattern] = (boostCards[pattern] ?? 1) * factor;
+    }
+  }
+  if (Object.keys(boostCards).length > 0) {
+    merged.boostCards = boostCards;
+  }
+
+  const concatUnique = (
+    field: 'requireTags' | 'requireCards' | 'excludeTags' | 'excludeCards'
+  ): void => {
+    const values = defined.flatMap((h) => h[field] ?? []);
+    if (values.length > 0) {
+      merged[field] = [...new Set(values)];
+    }
+  };
+
+  concatUnique('requireTags');
+  concatUnique('requireCards');
+  concatUnique('excludeTags');
+  concatUnique('excludeCards');
+
+  const labels = defined.map((h) => h._label).filter(Boolean);
+  if (labels.length > 0) {
+    merged._label = labels.join('; ');
+  }
+
+  return Object.keys(merged).length > 0 ? merged : undefined;
+}
+
 // ============================================================================
 // PIPELINE LOGGING HELPERS
 // ============================================================================
@@ -293,7 +342,7 @@ export class Pipeline extends ContentNavigator {
    * @param limit - Maximum number of cards to return
    * @returns Cards sorted by score descending
    */
-  async getWeightedCards(limit: number): Promise<WeightedCard[]> {
+  async getWeightedCards(limit: number): Promise<GeneratorResult> {
     const t0 = performance.now();
 
     // Build shared context once
@@ -311,9 +360,14 @@ export class Pipeline extends ContentNavigator {
     );
 
     // Get candidates from generator, passing context
-    let cards = await this.generator.getWeightedCards(fetchLimit, context);
+    const generatorResult = await this.generator.getWeightedCards(fetchLimit, context);
+    let cards = generatorResult.cards;
     const tGenerate = performance.now();
     const generatedCount = cards.length;
+
+    // Merge generator-emitted hints with any externally supplied one-shot hints
+    const mergedHints = mergeHints([this._ephemeralHints, generatorResult.hints]);
+    this._ephemeralHints = mergedHints ?? null;
     
     // Capture generator breakdown for debugging (if CompositeGenerator)
     let generatorSummaries: GeneratorSummary[] | undefined;
@@ -436,7 +490,7 @@ export class Pipeline extends ContentNavigator {
       logger.debug(`[Pipeline] Failed to capture debug run: ${e}`);
     }
 
-    return result;
+    return { cards: result };
   }
 
   /**

package/src/core/navigators/PipelineDebugger.ts

@@ -36,6 +36,7 @@ export function registerPipelineForDebug(pipeline: Pipeline): void {
 //   window.skuilder.pipeline.showLastRun()
 //   window.skuilder.pipeline.showCard('cardId123')
 //   window.skuilder.pipeline.explainReviews()
+//   window.skuilder.pipeline.showPrescribed()
 //   window.skuilder.pipeline.export()
 //
 // ============================================================================
@@ -389,6 +390,107 @@ export const pipelineDebugAPI = {
     console.groupEnd();
   },
 
+  /**
+   * Show prescribed-related cards from the most recent run.
+   *
+   * Highlights:
+   * - cards directly generated by the prescribed strategy
+   * - blocked prescribed targets mentioned in provenance
+   * - support tags resolved for blocked targets
+   *
+   * @param groupId - Optional prescribed group ID filter (e.g. 'intro-core')
+   */
+  showPrescribed(groupId?: string): void {
+    if (runHistory.length === 0) {
+      logger.info('[Pipeline Debug] No runs captured yet.');
+      return;
+    }
+
+    const run = runHistory[0];
+    const prescribedCards = run.cards.filter((c) =>
+      c.provenance.some((p) => p.strategy === 'prescribed')
+    );
+
+    // eslint-disable-next-line no-console
+    console.group(`🧭 Prescribed Debug (${run.courseId})`);
+
+    if (prescribedCards.length === 0) {
+      logger.info('No prescribed-generated cards were present in the most recent run.');
+      // eslint-disable-next-line no-console
+      console.groupEnd();
+      return;
+    }
+
+    const rows = prescribedCards
+      .map((card) => {
+        const prescribedProv = card.provenance.find((p) => p.strategy === 'prescribed');
+        const reason = prescribedProv?.reason ?? '';
+        const parsedGroup = reason.match(/group=([^;]+)/)?.[1] ?? 'unknown';
+        const mode = reason.match(/mode=([^;]+)/)?.[1] ?? 'unknown';
+        const blocked = reason.match(/blocked=([^;]+)/)?.[1] ?? 'unknown';
+        const blockedTargets = reason.match(/blockedTargets=([^;]+)/)?.[1] ?? 'none';
+        const supportTags = reason.match(/supportTags=([^;]+)/)?.[1] ?? 'none';
+        const multiplier = reason.match(/multiplier=([^;]+)/)?.[1] ?? 'unknown';
+
+        return {
+          group: parsedGroup,
+          mode,
+          cardId: card.cardId,
+          selected: card.selected ? 'yes' : 'no',
+          finalScore: card.finalScore.toFixed(3),
+          blocked,
+          blockedTargets,
+          supportTags,
+          multiplier,
+        };
+      })
+      .filter((row) => !groupId || row.group === groupId)
+      .sort((a, b) => Number(b.finalScore) - Number(a.finalScore));
+
+    if (rows.length === 0) {
+      logger.info(
+        `[Pipeline Debug] No prescribed cards matched group '${groupId}' in the most recent run.`
+      );
+      // eslint-disable-next-line no-console
+      console.groupEnd();
+      return;
+    }
+
+    // eslint-disable-next-line no-console
+    console.table(rows);
+
+    const selectedRows = rows.filter((r) => r.selected === 'yes');
+    const blockedTargetSet = new Set<string>();
+    const supportTagSet = new Set<string>();
+
+    for (const row of rows) {
+      if (row.blockedTargets && row.blockedTargets !== 'none') {
+        row.blockedTargets
+          .split('|')
+          .filter(Boolean)
+          .forEach((t) => blockedTargetSet.add(t));
+      }
+      if (row.supportTags && row.supportTags !== 'none') {
+        row.supportTags
+          .split('|')
+          .filter(Boolean)
+          .forEach((t) => supportTagSet.add(t));
+      }
+    }
+
+    logger.info(`Prescribed cards in run: ${rows.length}`);
+    logger.info(`Selected prescribed cards: ${selectedRows.length}`);
+    logger.info(
+      `Blocked prescribed targets referenced: ${blockedTargetSet.size > 0 ? [...blockedTargetSet].join(', ') : 'none'}`
+    );
+    logger.info(
+      `Resolved support tags referenced: ${supportTagSet.size > 0 ? [...supportTagSet].join(', ') : 'none'}`
+    );
+
+    // eslint-disable-next-line no-console
+    console.groupEnd();
+  },
+
   /**
    * Show all runs in compact format.
    */
@@ -555,6 +657,7 @@ Commands:
   .diagnoseCardSpace()   Scan full card space through filters (async)
   .showRegistry()        Show navigator registry (classes + roles)
   .showStrategies()      Show registry + strategy mapping from last run
+  .showPrescribed(id?)   Show prescribed-generated cards and blocked/support details from last run
   .listRuns()            List all captured runs in table format
   .export()              Export run history as JSON for bug reports
   .clear()               Clear run history

package/src/core/navigators/filters/hierarchyDefinition.ts

@@ -4,6 +4,7 @@ import { ContentNavigator } from '../index';
 import type { WeightedCard } from '../index';
 import type { ContentNavigationStrategyData } from '../../types/contentNavigationStrategy';
 import type { CardFilter, FilterContext } from './types';
+import type { GeneratorResult } from '../generators/types';
 import { toCourseElo } from '@vue-skuilder/common';
 import { logger } from '../../../util/logger';
 
@@ -401,7 +402,7 @@ export default class HierarchyDefinitionNavigator extends ContentNavigator imple
    *
    * Use transform() via Pipeline instead.
    */
-  async getWeightedCards(_limit: number): Promise<WeightedCard[]> {
+  async getWeightedCards(_limit: number): Promise<GeneratorResult> {
     throw new Error(
       'HierarchyDefinitionNavigator is a filter and should not be used as a generator. ' +
         'Use Pipeline with a generator and this filter via transform().'

package/src/core/navigators/filters/interferenceMitigator.ts

@@ -4,6 +4,7 @@ import { ContentNavigator } from '../index';
 import type { WeightedCard } from '../index';
 import type { ContentNavigationStrategyData } from '../../types/contentNavigationStrategy';
 import type { CardFilter, FilterContext } from './types';
+import type { GeneratorResult } from '../generators/types';
 import { toCourseElo } from '@vue-skuilder/common';
 
 /**
@@ -332,7 +333,7 @@ export default class InterferenceMitigatorNavigator extends ContentNavigator imp
    *
    * Use transform() via Pipeline instead.
    */
-  async getWeightedCards(_limit: number): Promise<WeightedCard[]> {
+  async getWeightedCards(_limit: number): Promise<GeneratorResult> {
     throw new Error(
       'InterferenceMitigatorNavigator is a filter and should not be used as a generator. ' +
         'Use Pipeline with a generator and this filter via transform().'

package/src/core/navigators/filters/relativePriority.ts

@@ -4,6 +4,7 @@ import { ContentNavigator } from '../index';
 import type { WeightedCard } from '../index';
 import type { ContentNavigationStrategyData } from '../../types/contentNavigationStrategy';
 import type { CardFilter, FilterContext } from './types';
+import type { GeneratorResult } from '../generators/types';
 
 /**
  * Configuration for the RelativePriority strategy.
@@ -238,7 +239,7 @@ export default class RelativePriorityNavigator extends ContentNavigator implemen
    *
    * Use transform() via Pipeline instead.
    */
-  async getWeightedCards(_limit: number): Promise<WeightedCard[]> {
+  async getWeightedCards(_limit: number): Promise<GeneratorResult> {
     throw new Error(
       'RelativePriorityNavigator is a filter and should not be used as a generator. ' +
         'Use Pipeline with a generator and this filter via transform().'

package/src/core/navigators/filters/userTagPreference.ts

@@ -4,6 +4,7 @@ import { ContentNavigator } from '../index';
 import type { WeightedCard } from '../index';
 import type { ContentNavigationStrategyData } from '../../types/contentNavigationStrategy';
 import type { CardFilter, FilterContext } from './types';
+import type { GeneratorResult } from '../generators/types';
 
 // ============================================================================
 // USER TAG PREFERENCE FILTER
@@ -208,7 +209,7 @@ export default class UserTagPreferenceFilter extends ContentNavigator implements
   /**
    * Legacy getWeightedCards - throws as filters should not be used as generators.
    */
-  async getWeightedCards(_limit: number): Promise<WeightedCard[]> {
+  async getWeightedCards(_limit: number): Promise<GeneratorResult> {
     throw new Error(
       'UserTagPreferenceFilter is a filter and should not be used as a generator. ' +
         'Use Pipeline with a generator and this filter via transform().'

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

@@ -3,7 +3,7 @@ import type { WeightedCard } from '../index';
 import type { ContentNavigationStrategyData } from '../../types/contentNavigationStrategy';
 import type { CourseDBInterface } from '../../interfaces/courseDB';
 import type { UserDBInterface } from '../../interfaces/userDB';
-import type { CardGenerator, GeneratorContext } from './types';
+import type { CardGenerator, GeneratorContext, GeneratorResult, ReplanHints } from './types';
 import { logger } from '../../../util/logger';
 
 // ============================================================================
@@ -37,6 +37,54 @@ export enum AggregationMode {
 const DEFAULT_AGGREGATION_MODE = AggregationMode.FREQUENCY_BOOST;
 const FREQUENCY_BOOST_FACTOR = 0.1;
 
+function mergeHints(allHints: Array<ReplanHints | undefined>): ReplanHints | undefined {
+  const defined = allHints.filter((h): h is ReplanHints => h !== undefined);
+  if (defined.length === 0) return undefined;
+
+  const merged: ReplanHints = {};
+
+  const boostTags: Record<string, number> = {};
+  for (const hints of defined) {
+    for (const [pattern, factor] of Object.entries(hints.boostTags ?? {})) {
+      boostTags[pattern] = (boostTags[pattern] ?? 1) * factor;
+    }
+  }
+  if (Object.keys(boostTags).length > 0) {
+    merged.boostTags = boostTags;
+  }
+
+  const boostCards: Record<string, number> = {};
+  for (const hints of defined) {
+    for (const [pattern, factor] of Object.entries(hints.boostCards ?? {})) {
+      boostCards[pattern] = (boostCards[pattern] ?? 1) * factor;
+    }
+  }
+  if (Object.keys(boostCards).length > 0) {
+    merged.boostCards = boostCards;
+  }
+
+  const concatUnique = (
+    field: 'requireTags' | 'requireCards' | 'excludeTags' | 'excludeCards'
+  ): void => {
+    const values = defined.flatMap((h) => h[field] ?? []);
+    if (values.length > 0) {
+      merged[field] = [...new Set(values)];
+    }
+  };
+
+  concatUnique('requireTags');
+  concatUnique('requireCards');
+  concatUnique('excludeTags');
+  concatUnique('excludeCards');
+
+  const labels = defined.map((h) => h._label).filter(Boolean);
+  if (labels.length > 0) {
+    merged._label = labels.join('; ');
+  }
+
+  return Object.keys(merged).length > 0 ? merged : undefined;
+}
+
 /**
  * Composes multiple generators into a single generator.
  *
@@ -100,7 +148,7 @@ export default class CompositeGenerator extends ContentNavigator implements Card
    * @param limit - Maximum number of cards to return
    * @param context - GeneratorContext passed to child generators (required when called via Pipeline)
    */
-  async getWeightedCards(limit: number, context?: GeneratorContext): Promise<WeightedCard[]> {
+  async getWeightedCards(limit: number, context?: GeneratorContext): Promise<GeneratorResult> {
     if (!context) {
       throw new Error(
         'CompositeGenerator.getWeightedCards requires a GeneratorContext. ' +
@@ -115,7 +163,8 @@ export default class CompositeGenerator extends ContentNavigator implements Card
 
     // Log per-generator breakdown for transparency
     const generatorSummaries: string[] = [];
-    results.forEach((cards, index) => {
+    results.forEach((result, index) => {
+      const cards = result.cards;
       const gen = this.generators[index];
       const genName = gen.name || `Generator ${index}`;
       const newCards = cards.filter((c) => c.provenance[0]?.reason?.includes('new card'));
@@ -138,7 +187,8 @@ export default class CompositeGenerator extends ContentNavigator implements Card
     type WeightedResult = { card: WeightedCard; weight: number };
     const byCardId = new Map<string, WeightedResult[]>();
 
-    results.forEach((cards, index) => {
+    results.forEach((result, index) => {
+      const cards = result.cards;
       // Access learnable weight if available
       const gen = this.generators[index] as unknown as ContentNavigator;
 
@@ -205,7 +255,10 @@ export default class CompositeGenerator extends ContentNavigator implements Card
     }
 
     // Sort by score descending and limit
-    return merged.sort((a, b) => b.score - a.score).slice(0, limit);
+    const cards = merged.sort((a, b) => b.score - a.score).slice(0, limit);
+    const hints = mergeHints(results.map((result) => result.hints));
+
+    return { cards, hints };
   }
 
   /**

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

@@ -4,7 +4,7 @@ import { ContentNavigator } from '../index';
 import type { WeightedCard } from '../index';
 import { toCourseElo } from '@vue-skuilder/common';
 import type { QualifiedCardID } from '../..';
-import type { CardGenerator, GeneratorContext } from './types';
+import type { CardGenerator, GeneratorContext, GeneratorResult } from './types';
 import { logger } from '@db/util/logger';
 
 // ============================================================================
@@ -65,7 +65,7 @@ export default class ELONavigator extends ContentNavigator implements CardGenera
    * @param limit - Maximum number of cards to return
    * @param context - Optional GeneratorContext (used when called via Pipeline)
    */
-  async getWeightedCards(limit: number, context?: GeneratorContext): Promise<WeightedCard[]> {
+  async getWeightedCards(limit: number, context?: GeneratorContext): Promise<GeneratorResult> {
     // Determine user ELO - from context if available, otherwise fetch
     let userGlobalElo: number;
     if (context?.userElo !== undefined) {
@@ -125,18 +125,18 @@ export default class ELONavigator extends ContentNavigator implements CardGenera
     // Sort by sampling key descending (weighted sample without replacement)
     scored.sort((a, b) => b.score - a.score);
 
-    const result = scored.slice(0, limit);
+    const cards = 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(', ');
+    if (cards.length > 0) {
+      const topScores = cards.slice(0, 3).map((c) => c.score.toFixed(2)).join(', ');
       logger.info(
-        `[ELO] Course ${this.course.getCourseID()}: ${result.length} new cards (top scores: ${topScores})`
+        `[ELO] Course ${this.course.getCourseID()}: ${cards.length} new cards (top scores: ${topScores})`
       );
     } else {
       logger.info(`[ELO] Course ${this.course.getCourseID()}: No new cards available`);
     }
 
-    return result;
+    return { cards };
   }
 }