@vue-skuilder/db 0.1.30 → 0.1.31-b

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.30",
+  "version": "0.1.31-b",
   "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.30",
+    "@vue-skuilder/common": "0.1.31-b",
     "cross-fetch": "^4.1.0",
     "moment": "^2.29.4",
     "pouchdb": "^9.0.0",

package/src/core/navigators/PipelineDebugger.ts

@@ -1,4 +1,12 @@
 import type { WeightedCard, StrategyContribution } from './index';
+import {
+  getRegisteredNavigatorNames,
+  getRegisteredNavigatorRole,
+  NavigatorRoles,
+  type Navigators,
+  isGenerator,
+  isFilter,
+} from './index';
 import { logger } from '../../util/logger';
 
 // ============================================================================
@@ -381,6 +389,76 @@ export const pipelineDebugAPI = {
     logger.info('[Pipeline Debug] Run history cleared.');
   },
 
+  /**
+   * Show the navigator registry: all registered classes and their roles.
+   *
+   * Useful for verifying that consumer-defined navigators were registered
+   * before pipeline assembly.
+   */
+  showRegistry(): void {
+    const names = getRegisteredNavigatorNames();
+    if (names.length === 0) {
+      logger.info('[Pipeline Debug] Navigator registry is empty.');
+      return;
+    }
+
+    // eslint-disable-next-line no-console
+    console.group('📦 Navigator Registry');
+    // eslint-disable-next-line no-console
+    console.table(
+      names.map((name) => {
+        const registryRole = getRegisteredNavigatorRole(name);
+        const builtinRole = NavigatorRoles[name as Navigators];
+        const effectiveRole = builtinRole || registryRole || '⚠️ NONE';
+        const source = builtinRole ? 'built-in' : registryRole ? 'consumer' : 'unclassified';
+        return {
+          name,
+          role: effectiveRole,
+          source,
+          isGenerator: isGenerator(name),
+          isFilter: isFilter(name),
+        };
+      })
+    );
+    // eslint-disable-next-line no-console
+    console.groupEnd();
+  },
+
+  /**
+   * Show strategy documents from the last pipeline run and how they mapped
+   * to the registry.
+   *
+   * If no runs are captured yet, falls back to showing just the registry.
+   */
+  showStrategies(): void {
+    this.showRegistry();
+
+    if (runHistory.length === 0) {
+      logger.info('[Pipeline Debug] No pipeline runs captured yet — cannot show strategy doc mapping.');
+      return;
+    }
+
+    const run = runHistory[0];
+    // eslint-disable-next-line no-console
+    console.group('🔌 Pipeline Strategy Mapping (last run)');
+    logger.info(`Generator: ${run.generatorName}`);
+    if (run.generators && run.generators.length > 0) {
+      for (const g of run.generators) {
+        logger.info(`  📥 ${g.name}: ${g.cardCount} cards (${g.newCount} new, ${g.reviewCount} reviews)`);
+      }
+    }
+    if (run.filters.length > 0) {
+      logger.info('Filters:');
+      for (const f of run.filters) {
+        logger.info(`  🔸 ${f.name}: ↑${f.boosted} ↓${f.penalized} =${f.passed} ✕${f.removed}`);
+      }
+    } else {
+      logger.info('Filters: (none)');
+    }
+    // eslint-disable-next-line no-console
+    console.groupEnd();
+  },
+
   /**
    * Show help.
    */
@@ -393,6 +471,8 @@ Commands:
   .showRun(id|index)     Show summary of a specific run (by index or ID suffix)
   .showCard(cardId)      Show provenance trail for a specific card
   .explainReviews()      Analyze why reviews were/weren't selected
+  .showRegistry()        Show navigator registry (classes + roles)
+  .showStrategies()      Show registry + strategy mapping 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/generators/elo.ts

@@ -88,30 +88,41 @@ export default class ELONavigator extends ContentNavigator implements CardGenera
     const cardIds = newCards.map((c) => c.cardID);
     const cardEloData = await this.course.getCardEloData(cardIds);
 
-    // Score new cards by ELO distance
+    // Score new cards by ELO distance, then apply weighted sampling without
+    // replacement using the Efraimidis-Spirakis (A-Res) algorithm:
+    //
+    //   key = U ^ (1 / rawScore)   where U ~ Uniform(0, 1)
+    //
+    // Sorting by key descending produces a weighted random sample: high-score
+    // cards are still preferred, but cards with equal scores are shuffled
+    // uniformly rather than deterministically. This prevents the same failed
+    // cards from looping back every session when many cards share similar ELO.
+    //
+    // Edge case: rawScore=0 → key=0, never selected (correct exclusion).
     const scored: WeightedCard[] = newCards.map((c, i) => {
       const cardElo = cardEloData[i]?.global?.score ?? 1000;
       const distance = Math.abs(cardElo - userGlobalElo);
-      const score = Math.max(0, 1 - distance / 500);
+      const rawScore = Math.max(0, 1 - distance / 500);
+      const samplingKey = rawScore > 0 ? Math.random() ** (1 / rawScore) : 0;
 
       return {
         cardId: c.cardID,
         courseId: c.courseID,
-        score,
+        score: samplingKey,
         provenance: [
           {
             strategy: 'elo',
             strategyName: this.strategyName || this.name,
             strategyId: this.strategyId || 'NAVIGATION_STRATEGY-ELO-default',
             action: 'generated',
-            score,
-            reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userGlobalElo)}), new card`,
+            score: samplingKey,
+            reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userGlobalElo)}), raw ${rawScore.toFixed(3)}, key ${samplingKey.toFixed(3)}`,
           },
         ],
       };
     });
 
-    // Sort by score descending
+    // Sort by sampling key descending (weighted sample without replacement)
     scored.sort((a, b) => b.score - a.score);
 
     const result = scored.slice(0, limit);

package/src/study/SpacedRepetition.ts

@@ -2,6 +2,7 @@ import { CardHistory, CardRecord, QuestionRecord } from '@db/core/types/types-le
 import { areQuestionRecords } from '@db/core/util';
 import { Update } from '@db/impl/couch/updateQueue';
 import moment from 'moment';
+import { isTaggedPerformance } from '@vue-skuilder/common';
 import { logger } from '../util/logger';
 
 type Moment = moment.Moment;
@@ -39,7 +40,9 @@ function newQuestionInterval(user: DocumentUpdater, cardHistory: CardHistory<Que
   }
 
   if (currentAttempt.isCorrect) {
-    const skill = Math.min(1.0, Math.max(0.0, currentAttempt.performance as number));
+    const rawPerf = currentAttempt.performance;
+    const numericPerf = isTaggedPerformance(rawPerf) ? rawPerf._global : rawPerf;
+    const skill = Math.min(1.0, Math.max(0.0, numericPerf));
     logger.debug(`Demontrated skill: \t${skill}`);
     const interval: number = lastInterval * (0.75 + skill);
     cardHistory.lapses = getLapses(cardHistory.records);