@vue-skuilder/db 0.1.31-b → 0.1.31

package/src/core/navigators/PipelineDebugger.ts

@@ -8,6 +8,21 @@ import {
   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
@@ -76,6 +91,7 @@ export interface PipelineRunReport {
     origin: 'new' | 'review' | 'unknown';
     finalScore: number;
     provenance: StrategyContribution[];
+    tags?: string[];
     selected: boolean;
   }>;
 }
@@ -135,6 +151,7 @@ export function buildRunReport(
     origin: getOrigin(card),
     finalScore: card.score,
     provenance: card.provenance,
+    tags: card.tags,
     selected: selectedIds.has(card.cardId),
   }));
 
@@ -459,6 +476,22 @@ export const pipelineDebugAPI = {
     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.
    */
@@ -471,6 +504,7 @@ 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
@@ -482,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

@@ -140,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 [
@@ -346,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',
@@ -384,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,
@@ -624,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