@vue-skuilder/db 0.1.31-a → 0.1.31

package/src/core/navigators/PipelineDebugger.ts

@@ -1,5 +1,28 @@
 import type { WeightedCard, StrategyContribution } from './index';
+import {
+  getRegisteredNavigatorNames,
+  getRegisteredNavigatorRole,
+  NavigatorRoles,
+  type Navigators,
+  isGenerator,
+  isFilter,
+} from './index';
 import { logger } from '../../util/logger';
+import type { Pipeline, CardSpaceDiagnosis } from './Pipeline';
+
+/**
+ * Captured reference to the most recently created Pipeline instance.
+ * Used by the debug API to run diagnostics against the live pipeline.
+ */
+let _activePipeline: Pipeline | null = null;
+
+/**
+ * Register a pipeline instance for diagnostic access.
+ * Called by Pipeline constructor.
+ */
+export function registerPipelineForDebug(pipeline: Pipeline): void {
+  _activePipeline = pipeline;
+}
 
 // ============================================================================
 // PIPELINE DEBUGGER
@@ -68,6 +91,7 @@ export interface PipelineRunReport {
     origin: 'new' | 'review' | 'unknown';
     finalScore: number;
     provenance: StrategyContribution[];
+    tags?: string[];
     selected: boolean;
   }>;
 }
@@ -127,6 +151,7 @@ export function buildRunReport(
     origin: getOrigin(card),
     finalScore: card.score,
     provenance: card.provenance,
+    tags: card.tags,
     selected: selectedIds.has(card.cardId),
   }));
 
@@ -381,6 +406,92 @@ 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();
+  },
+
+  /**
+   * Scan the full card space through the filter chain for the current user.
+   *
+   * Reports how many cards are well-indicated and how many are new.
+   * Use this to understand how the search space grows during onboarding.
+   *
+   * @param threshold - Score threshold for "well indicated" (default 0.10)
+   */
+  async diagnoseCardSpace(threshold?: number): Promise<CardSpaceDiagnosis | null> {
+    if (!_activePipeline) {
+      logger.info('[Pipeline Debug] No active pipeline. Run a session first.');
+      return null;
+    }
+    return _activePipeline.diagnoseCardSpace({ threshold });
+  },
+
   /**
    * Show help.
    */
@@ -393,6 +504,9 @@ 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
+  .diagnoseCardSpace()   Scan full card space through filters (async)
+  .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
@@ -402,7 +516,7 @@ Commands:
 Example:
   window.skuilder.pipeline.showLastRun()
   window.skuilder.pipeline.showRun(1)
-  window.skuilder.pipeline.showCard('abc123')
+  await window.skuilder.pipeline.diagnoseCardSpace()
 `);
   },
 };

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

@@ -20,6 +20,15 @@ interface TagPrerequisite {
     /** Minimum interaction count (default: 3) */
     minCount?: number;
   };
+  /**
+   * Score multiplier applied to cards that carry this prereq tag while
+   * the gate is still closed. Steers the pipeline toward cards that help
+   * unlock the gated content. Falls away once the prereq is met.
+   *
+   * Example: `preReqBoost: 1.3` gives a 30% score increase to cards
+   * tagged `gpc:expose:t-T` while `gpc:intro:t-T` is still locked.
+   */
+  preReqBoost?: number;
 }
 
 /**
@@ -38,7 +47,7 @@ const DEFAULT_MIN_COUNT = 3;
  * A filter strategy that gates cards based on prerequisite mastery.
  *
  * Cards are locked until the user masters all prerequisite tags.
- * Locked cards receive score * 0.01 (strong penalty, not hard filter).
+ * Locked cards receive score * 0.05 (strong penalty, not hard filter).
  *
  * Mastery is determined by:
  * - User's ELO for the tag exceeds threshold (or avgElo if not specified)
@@ -94,8 +103,13 @@ export default class HierarchyDefinitionNavigator extends ContentNavigator imple
 
     if (prereq.masteryThreshold?.minElo !== undefined) {
       return userTagElo.score >= prereq.masteryThreshold.minElo;
+    } else if (prereq.masteryThreshold?.minCount !== undefined) {
+      // Explicit minCount without minElo: count alone is sufficient.
+      // The config author specified a concrete interaction threshold —
+      // don't additionally require above-average ELO.
+      return true;
     } else {
-      // Default: user ELO for tag > global user ELO (proxy for "above average")
+      // No thresholds specified at all: fall back to above-average ELO
       return userTagElo.score >= userGlobalElo;
     }
   }
@@ -195,17 +209,51 @@ export default class HierarchyDefinitionNavigator extends ContentNavigator imple
     }
   }
 
+  /**
+   * Build a map of prereq tag → max configured boost for all *closed* gates.
+   *
+   * When a gate is closed (prereqs unmet), cards carrying that gate's prereq
+   * tags get boosted — steering the pipeline toward content that helps unlock
+   * the gated material. Once the gate opens, the boost disappears.
+   */
+  private getPreReqBoosts(
+    unlockedTags: Set<string>,
+    masteredTags: Set<string>
+  ): Map<string, number> {
+    const boosts = new Map<string, number>();
+
+    for (const [tagId, prereqs] of Object.entries(this.config.prerequisites)) {
+      // Only boost prereqs of closed gates
+      if (unlockedTags.has(tagId)) continue;
+
+      for (const prereq of prereqs) {
+        if (!prereq.preReqBoost || prereq.preReqBoost <= 1.0) continue;
+        // Only boost prereqs that aren't already met
+        if (masteredTags.has(prereq.tag)) continue;
+
+        const existing = boosts.get(prereq.tag) ?? 1.0;
+        boosts.set(prereq.tag, Math.max(existing, prereq.preReqBoost));
+      }
+    }
+
+    return boosts;
+  }
+
   /**
    * CardFilter.transform implementation.
    *
-   * Apply prerequisite gating to cards. Cards with locked tags receive score * 0.01.
+   * Two effects:
+   * 1. Cards with locked tags receive score * 0.05 (gating penalty)
+   * 2. Cards carrying prereq tags of closed gates receive a configured
+   *    boost (preReqBoost), steering toward content that unlocks gates
    */
   async transform(cards: WeightedCard[], context: FilterContext): Promise<WeightedCard[]> {
     // Get mastery state
     const masteredTags = await this.getMasteredTags(context);
     const unlockedTags = this.getUnlockedTags(masteredTags);
+    const preReqBoosts = this.getPreReqBoosts(unlockedTags, masteredTags);
 
-    // Apply prerequisite gating as score multiplier
+    // Apply prerequisite gating + prereq boosting
     const gated: WeightedCard[] = [];
 
     for (const card of cards) {
@@ -215,9 +263,31 @@ export default class HierarchyDefinitionNavigator extends ContentNavigator imple
         unlockedTags,
         masteredTags
       );
-      const LOCKED_PENALTY = 0.01;
-      const finalScore = isUnlocked ? card.score : card.score * LOCKED_PENALTY;
-      const action = isUnlocked ? 'passed' : 'penalized';
+      const LOCKED_PENALTY = 0.02;
+      let finalScore = isUnlocked ? card.score : card.score * LOCKED_PENALTY;
+      let action: 'passed' | 'penalized' | 'boosted' = isUnlocked ? 'passed' : 'penalized';
+      let finalReason = reason;
+
+      // Apply prereq boost to cards that passed gating (don't boost locked cards)
+      if (isUnlocked && preReqBoosts.size > 0) {
+        const cardTags = card.tags ?? [];
+        let maxBoost = 1.0;
+        const boostedPrereqs: string[] = [];
+
+        for (const tag of cardTags) {
+          const boost = preReqBoosts.get(tag);
+          if (boost && boost > maxBoost) {
+            maxBoost = boost;
+            boostedPrereqs.push(tag);
+          }
+        }
+
+        if (maxBoost > 1.0) {
+          finalScore *= maxBoost;
+          action = 'boosted';
+          finalReason = `${reason} | preReqBoost ×${maxBoost.toFixed(2)} for ${boostedPrereqs.join(', ')}`;
+        }
+      }
 
       gated.push({
         ...card,
@@ -230,7 +300,7 @@ export default class HierarchyDefinitionNavigator extends ContentNavigator imple
             strategyId: this.strategyId || 'NAVIGATION_STRATEGY-hierarchy',
             action,
             score: finalScore,
-            reason,
+            reason: finalReason,
           },
         ],
       });

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

@@ -0,0 +1,95 @@
+import type { CourseDBInterface } from '../../interfaces/courseDB';
+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 } from './types';
+import { logger } from '@db/util/logger';
+
+// ============================================================================
+// PRESCRIBED CARDS GENERATOR
+// ============================================================================
+//
+// A generator that always emits a configured list of card IDs at score 1.0.
+//
+// Use case: Cold-start curriculum bootstrapping. Ensures critical cards
+// (e.g., intro-s, early WS exercises) are always in the candidate set
+// regardless of ELO proximity sampling. Filters (hierarchy, priority)
+// still run — cards whose utility has expired get penalized normally
+// and drop out of the top-N selection.
+//
+// Config format:
+//   { "cardIds": ["c-intro-s-S", "c-ws-sit-abc123", ...] }
+//
+// ============================================================================
+
+interface PrescribedConfig {
+  cardIds: string[];
+}
+
+export default class PrescribedCardsGenerator extends ContentNavigator implements CardGenerator {
+  name: string;
+  private config: PrescribedConfig;
+
+  constructor(
+    user: UserDBInterface,
+    course: CourseDBInterface,
+    strategyData: ContentNavigationStrategyData
+  ) {
+    super(user, course, strategyData);
+    this.name = strategyData.name || 'Prescribed Cards';
+
+    try {
+      const parsed = JSON.parse(strategyData.serializedData);
+      this.config = { cardIds: parsed.cardIds || [] };
+    } catch {
+      this.config = { cardIds: [] };
+    }
+
+    logger.debug(
+      `[Prescribed] Initialized with ${this.config.cardIds.length} prescribed cards`
+    );
+  }
+
+  async getWeightedCards(limit: number, _context?: GeneratorContext): Promise<WeightedCard[]> {
+    if (this.config.cardIds.length === 0) {
+      return [];
+    }
+
+    const courseId = this.course.getCourseID();
+
+    // Filter out cards the user has already interacted with
+    const activeCards = await this.user.getActiveCards();
+    const activeIds = new Set(activeCards.map((ac) => ac.cardID));
+    const eligibleIds = this.config.cardIds.filter((id) => !activeIds.has(id));
+
+    if (eligibleIds.length === 0) {
+      logger.debug('[Prescribed] All prescribed cards already active, returning empty');
+      return [];
+    }
+
+    // Emit at score 1.0 — CompositeGenerator deduplicates, and if ELO
+    // also surfaces the same card, the composite picks the higher score.
+    const cards: WeightedCard[] = eligibleIds.slice(0, limit).map((cardId) => ({
+      cardId,
+      courseId,
+      score: 1.0,
+      provenance: [
+        {
+          strategy: 'prescribed',
+          strategyName: this.strategyName || this.name,
+          strategyId: this.strategyId || 'NAVIGATION_STRATEGY-prescribed',
+          action: 'generated' as const,
+          score: 1.0,
+          reason: `Prescribed card (${eligibleIds.length} eligible of ${this.config.cardIds.length} configured)`,
+        },
+      ],
+    }));
+
+    logger.info(
+      `[Prescribed] Emitting ${cards.length} cards (${eligibleIds.length} eligible, ${activeIds.size} already active)`
+    );
+
+    return cards;
+  }
+}

package/src/core/navigators/index.ts

@@ -46,10 +46,20 @@ export type NavigatorConstructor = new (
 ) => ContentNavigator;
 
 /**
- * Registry mapping implementingClass names to navigator constructors.
+ * Entry in the navigator registry, storing the constructor and an optional
+ * pipeline role. The role is used by PipelineAssembler to classify
+ * consumer-registered navigators that aren't in the built-in Navigators enum.
+ */
+interface NavigatorRegistryEntry {
+  constructor: NavigatorConstructor;
+  role?: NavigatorRole;
+}
+
+/**
+ * Registry mapping implementingClass names to navigator entries.
  * Populated by registerNavigator() and used by ContentNavigator.create().
  */
-const navigatorRegistry = new Map<string, NavigatorConstructor>();
+const navigatorRegistry = new Map<string, NavigatorRegistryEntry>();
 
 /**
  * Register a navigator implementation.
@@ -57,15 +67,21 @@ const navigatorRegistry = new Map<string, NavigatorConstructor>();
  * Call this to make a navigator available for instantiation by
  * ContentNavigator.create() without relying on dynamic imports.
  *
- * @param implementingClass - The class name (e.g., 'elo', 'hierarchyDefinition')
+ * Passing a `role` is optional for built-in navigators (whose roles are in
+ * the hardcoded `NavigatorRoles` record), but **required** for consumer-
+ * defined navigators that need to participate in pipeline assembly.
+ *
+ * @param implementingClass - The class name (e.g., 'elo', 'letterGatingFilter')
  * @param constructor - The navigator class constructor
+ * @param role - Optional pipeline role (GENERATOR or FILTER)
  */
 export function registerNavigator(
   implementingClass: string,
-  constructor: NavigatorConstructor
+  constructor: NavigatorConstructor,
+  role?: NavigatorRole
 ): void {
-  navigatorRegistry.set(implementingClass, constructor);
-  logger.debug(`[NavigatorRegistry] Registered: ${implementingClass}`);
+  navigatorRegistry.set(implementingClass, { constructor, role });
+  logger.debug(`[NavigatorRegistry] Registered: ${implementingClass}${role ? ` (${role})` : ''}`);
 }
 
 /**
@@ -75,7 +91,7 @@ export function registerNavigator(
  * @returns The constructor, or undefined if not registered
  */
 export function getRegisteredNavigator(implementingClass: string): NavigatorConstructor | undefined {
-  return navigatorRegistry.get(implementingClass);
+  return navigatorRegistry.get(implementingClass)?.constructor;
 }
 
 /**
@@ -88,6 +104,16 @@ export function hasRegisteredNavigator(implementingClass: string): boolean {
   return navigatorRegistry.has(implementingClass);
 }
 
+/**
+ * Get the registered role for a navigator, if one was provided at registration.
+ *
+ * @param implementingClass - The class name to look up
+ * @returns The role, or undefined if not registered or no role was specified
+ */
+export function getRegisteredNavigatorRole(implementingClass: string): NavigatorRole | undefined {
+  return navigatorRegistry.get(implementingClass)?.role;
+}
+
 /**
  * Get all registered navigator names.
  * Useful for debugging and testing.
@@ -114,8 +140,10 @@ export async function initializeNavigatorRegistry(): Promise<void> {
     import('./generators/elo'),
     import('./generators/srs'),
   ]);
+  const prescribedModule = await import('./generators/prescribed');
   registerNavigator('elo', eloModule.default);
   registerNavigator('srs', srsModule.default);
+  registerNavigator('prescribed', prescribedModule.default);
 
   // Import and register filters
   const [
@@ -320,6 +348,7 @@ export function getCardOrigin(card: WeightedCard): 'new' | 'review' | 'failed' {
 export enum Navigators {
   ELO = 'elo',
   SRS = 'srs',
+  PRESCRIBED = 'prescribed',
   HIERARCHY = 'hierarchyDefinition',
   INTERFERENCE = 'interferenceMitigator',
   RELATIVE_PRIORITY = 'relativePriority',
@@ -358,6 +387,7 @@ export enum NavigatorRole {
 export const NavigatorRoles: Record<Navigators, NavigatorRole> = {
   [Navigators.ELO]: NavigatorRole.GENERATOR,
   [Navigators.SRS]: NavigatorRole.GENERATOR,
+  [Navigators.PRESCRIBED]: NavigatorRole.GENERATOR,
   [Navigators.HIERARCHY]: NavigatorRole.FILTER,
   [Navigators.INTERFERENCE]: NavigatorRole.FILTER,
   [Navigators.RELATIVE_PRIORITY]: NavigatorRole.FILTER,
@@ -371,17 +401,24 @@ export const NavigatorRoles: Record<Navigators, NavigatorRole> = {
  * @returns true if the navigator is a generator, false otherwise
  */
 export function isGenerator(impl: string): boolean {
-  return NavigatorRoles[impl as Navigators] === NavigatorRole.GENERATOR;
+  if (NavigatorRoles[impl as Navigators] === NavigatorRole.GENERATOR) return true;
+  // Fallback: check the registry for consumer-registered navigators
+  return getRegisteredNavigatorRole(impl) === NavigatorRole.GENERATOR;
 }
 
 /**
  * Check if a navigator implementation is a filter.
  *
- * @param impl - Navigator implementation name (e.g., 'elo', 'hierarchyDefinition')
+ * Checks the built-in NavigatorRoles enum first, then falls back to the
+ * navigator registry for consumer-registered navigators.
+ *
+ * @param impl - Navigator implementation name (e.g., 'elo', 'letterGatingFilter')
  * @returns true if the navigator is a filter, false otherwise
  */
 export function isFilter(impl: string): boolean {
-  return NavigatorRoles[impl as Navigators] === NavigatorRole.FILTER;
+  if (NavigatorRoles[impl as Navigators] === NavigatorRole.FILTER) return true;
+  // Fallback: check the registry for consumer-registered navigators
+  return getRegisteredNavigatorRole(impl) === NavigatorRole.FILTER;
 }
 
 /**
@@ -591,4 +628,12 @@ export abstract class ContentNavigator implements StudyContentSource {
   async getWeightedCards(_limit: number): Promise<WeightedCard[]> {
     throw new Error(`${this.constructor.name} must implement getWeightedCards(). `);
   }
+
+  /**
+   * Set ephemeral hints for the next pipeline run.
+   * No-op for non-Pipeline navigators. Pipeline overrides this.
+   */
+  setEphemeralHints(_hints: Record<string, unknown>): void {
+    // no-op — only Pipeline implements this
+  }
 }

package/src/impl/common/BaseUserDB.ts

@@ -174,10 +174,13 @@ Currently logged-in as ${this._username}.`
       const docsToDelete = allDocs.rows
         .filter((row) => {
           const id = row.id;
-          // Delete user progress data but preserve core user documents
+          // Delete user progress data but preserve authentication and user identity
           return (
             id.startsWith(DocTypePrefixes[DocType.CARDRECORD]) || // Card interaction history
             id.startsWith(DocTypePrefixes[DocType.SCHEDULED_CARD]) || // Scheduled reviews
+            id.startsWith(DocTypePrefixes[DocType.STRATEGY_STATE]) || // Strategy state (user prefs, progression)
+            id.startsWith(DocTypePrefixes[DocType.USER_OUTCOME]) || // Evolutionary orchestration outcomes
+            id.startsWith(DocTypePrefixes[DocType.STRATEGY_LEARNING_STATE]) || // Strategy learning state
             id === BaseUser.DOC_IDS.COURSE_REGISTRATIONS || // Course registrations
             id === BaseUser.DOC_IDS.CLASSROOM_REGISTRATIONS || // Classroom registrations
             id === BaseUser.DOC_IDS.CONFIG // User config