@vue-skuilder/db 0.2.5 → 0.2.8

package/dist/core/index.d.cts

@@ -304,6 +304,73 @@ interface CardFilter {
  */
 type CardFilterFactory<TConfig = unknown> = (config: TConfig) => CardFilter;
 
+interface DiversityRerankOptions {
+    /**
+     * How hard repetition is penalised. Larger → steeper demotion of repeated
+     * distinctive tags. Penalty = 1 / (1 + strength·load).
+     */
+    strength?: number;
+    /**
+     * Minimum penalty multiplier. A card is never demoted below `floor × score`,
+     * however much it repeats. Keeps a strong-but-repeated card from being driven
+     * under downstream "well-indicated" thresholds (which would mislabel it as
+     * filler and could trigger spurious quality-replans). Tunes "perturb ordering"
+     * vs "annihilate candidates."
+     */
+    floor?: number;
+}
+/** Default repetition strength. See DiversityRerankOptions.strength. */
+declare const DIVERSITY_STRENGTH = 0.6;
+/** Default penalty floor. See DiversityRerankOptions.floor. */
+declare const DIVERSITY_FLOOR = 0.3;
+/**
+ * Re-rank a scored candidate pool for answer/concept variety.
+ *
+ * Pure: returns a new array (diversified order, adjusted scores, appended
+ * provenance) and does not mutate the input cards. Cards entering are assumed
+ * to have score > 0 (the Pipeline strips zero-score cards before this stage).
+ * Non-finite scores (mandatory `requireCards`, score = +Infinity) are emitted
+ * untouched and still count toward repetition for later cards.
+ *
+ * @param cards - Post-filter, post-hint candidates.
+ * @param opts  - Optional strength/floor overrides (defaults are sane and
+ *                course-general; promote to strategy config if you ever want
+ *                this learnable under the orchestration layer).
+ * @returns Cards in diversified order with penalised scores.
+ */
+declare function diversityRerank(cards: WeightedCard[], opts?: DiversityRerankOptions): WeightedCard[];
+
+/**
+ * A navigation pipeline that runs a generator and applies filters sequentially.
+ *
+ * Implements StudyContentSource for backward compatibility with SessionController.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * const pipeline = new Pipeline(
+ *   compositeGenerator,  // or single generator
+ *   [eloDistanceFilter, interferenceFilter],
+ *   user,
+ *   course
+ * );
+ *
+ * const cards = await pipeline.getWeightedCards(20);
+ * ```
+ */
+/**
+ * Narrow capability surface for out-of-band, commit-free reads against a live
+ * pipeline (see {@link getActivePipeline}). Kept minimal on purpose — consumers
+ * get the forecast capability, not the whole `Pipeline` class.
+ */
+interface PipelineForecaster {
+    forecast(opts?: {
+        hints?: ReplanHints;
+        unseenOnly?: boolean;
+        threshold?: number;
+        limit?: number;
+    }): Promise<WeightedCard[]>;
+}
 /**
  * Diagnosis of the full card space for the current user.
  */
@@ -325,6 +392,13 @@ interface CardSpaceDiagnosis {
     elapsedMs: number;
 }
 
+/**
+ * The most recently constructed pipeline for the current session, or null if
+ * none has been built yet. This is the supported, non-debug accessor for
+ * out-of-band reads against the live pipeline (e.g. a commit-free
+ * `forecast()`), replacing reach-ins through `window.skuilder.pipeline`.
+ */
+declare function getActivePipeline(): PipelineForecaster | null;
 /**
  * Summary of a single generator's contribution.
  */
@@ -706,4 +780,4 @@ declare const userDBDebugAPI: {
  */
 declare function mountUserDBDebugger(): void;
 
-export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, CardHistory, CardRecord, CourseDBInterface, DocType, DocTypePrefixes, type FilterContext, type FilterImpact, type GeneratorSummary, type GradientObservation, type GradientResult, type ImportResult, LearnableWeight, Loggable, OrchestrationContext, type PeriodUpdateInput, type PeriodUpdateResult, type PipelineRunReport, QuestionRecord, ReplanHints, type SignalConfig, StrategyContribution, type StrategyLearningState, type StrategyStateDoc, type StrategyStateId, UserDBInterface, UserOutcomeRecord, WeightedCard, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, computeOutcomeSignal, computeStrategyGradient, docIsDeleted, getCardHistoryID, getDefaultLearnableWeight, importParsedCards, isQuestionRecord, mountPipelineDebugger, mountUserDBDebugger, parseCardHistoryID, pipelineDebugAPI, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, userDBDebugAPI, validateProcessorConfig };
+export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, CardHistory, CardRecord, CourseDBInterface, DIVERSITY_FLOOR, DIVERSITY_STRENGTH, type DiversityRerankOptions, DocType, DocTypePrefixes, type FilterContext, type FilterImpact, type GeneratorSummary, type GradientObservation, type GradientResult, type ImportResult, LearnableWeight, Loggable, OrchestrationContext, type PeriodUpdateInput, type PeriodUpdateResult, type PipelineForecaster, type PipelineRunReport, QuestionRecord, ReplanHints, type SignalConfig, StrategyContribution, type StrategyLearningState, type StrategyStateDoc, type StrategyStateId, UserDBInterface, UserOutcomeRecord, WeightedCard, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, computeOutcomeSignal, computeStrategyGradient, diversityRerank, docIsDeleted, getActivePipeline, getCardHistoryID, getDefaultLearnableWeight, importParsedCards, isQuestionRecord, mountPipelineDebugger, mountUserDBDebugger, parseCardHistoryID, pipelineDebugAPI, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, userDBDebugAPI, validateProcessorConfig };

package/dist/core/index.d.ts

@@ -304,6 +304,73 @@ interface CardFilter {
  */
 type CardFilterFactory<TConfig = unknown> = (config: TConfig) => CardFilter;
 
+interface DiversityRerankOptions {
+    /**
+     * How hard repetition is penalised. Larger → steeper demotion of repeated
+     * distinctive tags. Penalty = 1 / (1 + strength·load).
+     */
+    strength?: number;
+    /**
+     * Minimum penalty multiplier. A card is never demoted below `floor × score`,
+     * however much it repeats. Keeps a strong-but-repeated card from being driven
+     * under downstream "well-indicated" thresholds (which would mislabel it as
+     * filler and could trigger spurious quality-replans). Tunes "perturb ordering"
+     * vs "annihilate candidates."
+     */
+    floor?: number;
+}
+/** Default repetition strength. See DiversityRerankOptions.strength. */
+declare const DIVERSITY_STRENGTH = 0.6;
+/** Default penalty floor. See DiversityRerankOptions.floor. */
+declare const DIVERSITY_FLOOR = 0.3;
+/**
+ * Re-rank a scored candidate pool for answer/concept variety.
+ *
+ * Pure: returns a new array (diversified order, adjusted scores, appended
+ * provenance) and does not mutate the input cards. Cards entering are assumed
+ * to have score > 0 (the Pipeline strips zero-score cards before this stage).
+ * Non-finite scores (mandatory `requireCards`, score = +Infinity) are emitted
+ * untouched and still count toward repetition for later cards.
+ *
+ * @param cards - Post-filter, post-hint candidates.
+ * @param opts  - Optional strength/floor overrides (defaults are sane and
+ *                course-general; promote to strategy config if you ever want
+ *                this learnable under the orchestration layer).
+ * @returns Cards in diversified order with penalised scores.
+ */
+declare function diversityRerank(cards: WeightedCard[], opts?: DiversityRerankOptions): WeightedCard[];
+
+/**
+ * A navigation pipeline that runs a generator and applies filters sequentially.
+ *
+ * Implements StudyContentSource for backward compatibility with SessionController.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * const pipeline = new Pipeline(
+ *   compositeGenerator,  // or single generator
+ *   [eloDistanceFilter, interferenceFilter],
+ *   user,
+ *   course
+ * );
+ *
+ * const cards = await pipeline.getWeightedCards(20);
+ * ```
+ */
+/**
+ * Narrow capability surface for out-of-band, commit-free reads against a live
+ * pipeline (see {@link getActivePipeline}). Kept minimal on purpose — consumers
+ * get the forecast capability, not the whole `Pipeline` class.
+ */
+interface PipelineForecaster {
+    forecast(opts?: {
+        hints?: ReplanHints;
+        unseenOnly?: boolean;
+        threshold?: number;
+        limit?: number;
+    }): Promise<WeightedCard[]>;
+}
 /**
  * Diagnosis of the full card space for the current user.
  */
@@ -325,6 +392,13 @@ interface CardSpaceDiagnosis {
     elapsedMs: number;
 }
 
+/**
+ * The most recently constructed pipeline for the current session, or null if
+ * none has been built yet. This is the supported, non-debug accessor for
+ * out-of-band reads against the live pipeline (e.g. a commit-free
+ * `forecast()`), replacing reach-ins through `window.skuilder.pipeline`.
+ */
+declare function getActivePipeline(): PipelineForecaster | null;
 /**
  * Summary of a single generator's contribution.
  */
@@ -706,4 +780,4 @@ declare const userDBDebugAPI: {
  */
 declare function mountUserDBDebugger(): void;
 
-export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, CardHistory, CardRecord, CourseDBInterface, DocType, DocTypePrefixes, type FilterContext, type FilterImpact, type GeneratorSummary, type GradientObservation, type GradientResult, type ImportResult, LearnableWeight, Loggable, OrchestrationContext, type PeriodUpdateInput, type PeriodUpdateResult, type PipelineRunReport, QuestionRecord, ReplanHints, type SignalConfig, StrategyContribution, type StrategyLearningState, type StrategyStateDoc, type StrategyStateId, UserDBInterface, UserOutcomeRecord, WeightedCard, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, computeOutcomeSignal, computeStrategyGradient, docIsDeleted, getCardHistoryID, getDefaultLearnableWeight, importParsedCards, isQuestionRecord, mountPipelineDebugger, mountUserDBDebugger, parseCardHistoryID, pipelineDebugAPI, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, userDBDebugAPI, validateProcessorConfig };
+export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, CardHistory, CardRecord, CourseDBInterface, DIVERSITY_FLOOR, DIVERSITY_STRENGTH, type DiversityRerankOptions, DocType, DocTypePrefixes, type FilterContext, type FilterImpact, type GeneratorSummary, type GradientObservation, type GradientResult, type ImportResult, LearnableWeight, Loggable, OrchestrationContext, type PeriodUpdateInput, type PeriodUpdateResult, type PipelineForecaster, type PipelineRunReport, QuestionRecord, ReplanHints, type SignalConfig, StrategyContribution, type StrategyLearningState, type StrategyStateDoc, type StrategyStateId, UserDBInterface, UserOutcomeRecord, WeightedCard, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, computeOutcomeSignal, computeStrategyGradient, diversityRerank, docIsDeleted, getActivePipeline, getCardHistoryID, getDefaultLearnableWeight, importParsedCards, isQuestionRecord, mountPipelineDebugger, mountUserDBDebugger, parseCardHistoryID, pipelineDebugAPI, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, userDBDebugAPI, validateProcessorConfig };

package/dist/core/index.js

@@ -719,12 +719,102 @@ var init_courseLookupDB = __esm({
   }
 });
 
+// src/core/navigators/diversityRerank.ts
+var diversityRerank_exports = {};
+__export(diversityRerank_exports, {
+  DIVERSITY_FLOOR: () => DIVERSITY_FLOOR,
+  DIVERSITY_STRENGTH: () => DIVERSITY_STRENGTH,
+  diversityRerank: () => diversityRerank
+});
+function diversityRerank(cards, opts = {}) {
+  const strength = opts.strength ?? DIVERSITY_STRENGTH;
+  const floor = opts.floor ?? DIVERSITY_FLOOR;
+  const n = cards.length;
+  if (n <= 1) return cards;
+  const df = /* @__PURE__ */ new Map();
+  for (const card of cards) {
+    for (const tag of card.tags ?? []) {
+      df.set(tag, (df.get(tag) ?? 0) + 1);
+    }
+  }
+  const idf = /* @__PURE__ */ new Map();
+  for (const [tag, freq] of df) {
+    idf.set(tag, Math.log(n / freq));
+  }
+  const remaining = [...cards];
+  const emittedCount = /* @__PURE__ */ new Map();
+  const out = [];
+  const repetitionLoad = (card) => {
+    let load = 0;
+    for (const tag of card.tags ?? []) {
+      const seen = emittedCount.get(tag);
+      if (seen) load += (idf.get(tag) ?? 0) * seen;
+    }
+    return load;
+  };
+  while (remaining.length > 0) {
+    let bestIdx = 0;
+    let bestValue = -Infinity;
+    let bestPenalty = 1;
+    let bestLoad = 0;
+    for (let i = 0; i < remaining.length; i++) {
+      const card = remaining[i];
+      const load = repetitionLoad(card);
+      const penalty = load > 0 ? Math.max(floor, 1 / (1 + strength * load)) : 1;
+      const value = card.score * penalty;
+      if (value > bestValue) {
+        bestValue = value;
+        bestIdx = i;
+        bestPenalty = penalty;
+        bestLoad = load;
+      }
+    }
+    const [picked] = remaining.splice(bestIdx, 1);
+    if (Number.isFinite(picked.score) && bestPenalty < 1) {
+      const newScore = picked.score * bestPenalty;
+      out.push({
+        ...picked,
+        score: newScore,
+        provenance: [
+          ...picked.provenance,
+          {
+            strategy: STRATEGY,
+            strategyId: STRATEGY_ID,
+            strategyName: STRATEGY_NAME,
+            action: "penalized",
+            score: newScore,
+            reason: `repeated tags (load ${bestLoad.toFixed(2)}) \u2192 \xD7${bestPenalty.toFixed(2)}`
+          }
+        ]
+      });
+    } else {
+      out.push(picked);
+    }
+    for (const tag of picked.tags ?? []) {
+      emittedCount.set(tag, (emittedCount.get(tag) ?? 0) + 1);
+    }
+  }
+  return out;
+}
+var DIVERSITY_STRENGTH, DIVERSITY_FLOOR, STRATEGY, STRATEGY_ID, STRATEGY_NAME;
+var init_diversityRerank = __esm({
+  "src/core/navigators/diversityRerank.ts"() {
+    "use strict";
+    DIVERSITY_STRENGTH = 0.6;
+    DIVERSITY_FLOOR = 0.3;
+    STRATEGY = "diversityRerank";
+    STRATEGY_ID = "DIVERSITY_RERANK";
+    STRATEGY_NAME = "Diversity Re-rank";
+  }
+});
+
 // src/core/navigators/PipelineDebugger.ts
 var PipelineDebugger_exports = {};
 __export(PipelineDebugger_exports, {
   buildRunReport: () => buildRunReport,
   captureRun: () => captureRun,
   clearRunHistory: () => clearRunHistory,
+  getActivePipeline: () => getActivePipeline,
   mountPipelineDebugger: () => mountPipelineDebugger,
   pipelineDebugAPI: () => pipelineDebugAPI,
   registerPipelineForDebug: () => registerPipelineForDebug
@@ -732,6 +822,9 @@ __export(PipelineDebugger_exports, {
 function registerPipelineForDebug(pipeline) {
   _activePipeline = pipeline;
 }
+function getActivePipeline() {
+  return _activePipeline;
+}
 function clearRunHistory() {
   runHistory.length = 0;
 }
@@ -1914,7 +2007,7 @@ function shuffleInPlace(arr) {
 function pickTopByScore(cards, limit) {
   return [...cards].sort((a, b) => b.score - a.score || a.cardId.localeCompare(b.cardId)).slice(0, limit);
 }
-var DEFAULT_FRESHNESS_WINDOW, DEFAULT_MAX_DIRECT_PER_RUN, DEFAULT_MAX_SUPPORT_PER_RUN, DEFAULT_HIERARCHY_DEPTH, DEFAULT_MIN_COUNT, BASE_TARGET_SCORE, BASE_SUPPORT_SCORE, DISCOVERED_SUPPORT_SCORE, MAX_TARGET_MULTIPLIER, MAX_SUPPORT_MULTIPLIER, PRESCRIBED_DEBUG_VERSION, PrescribedCardsGenerator;
+var DEFAULT_FRESHNESS_WINDOW, DEFAULT_MAX_DIRECT_PER_RUN, DEFAULT_MAX_SUPPORT_PER_RUN, DEFAULT_HIERARCHY_DEPTH, DEFAULT_MIN_COUNT, DEFAULT_PRACTICE_MIN_COUNT, DEFAULT_MAX_PRACTICE_PER_RUN, BASE_TARGET_SCORE, BASE_SUPPORT_SCORE, DISCOVERED_SUPPORT_SCORE, BASE_PRACTICE_SCORE, MAX_TARGET_MULTIPLIER, MAX_SUPPORT_MULTIPLIER, PRESCRIBED_DEBUG_VERSION, PrescribedCardsGenerator;
 var init_prescribed = __esm({
   "src/core/navigators/generators/prescribed.ts"() {
     "use strict";
@@ -1925,9 +2018,12 @@ var init_prescribed = __esm({
     DEFAULT_MAX_SUPPORT_PER_RUN = 3;
     DEFAULT_HIERARCHY_DEPTH = 2;
     DEFAULT_MIN_COUNT = 3;
+    DEFAULT_PRACTICE_MIN_COUNT = 3;
+    DEFAULT_MAX_PRACTICE_PER_RUN = 4;
     BASE_TARGET_SCORE = 1;
     BASE_SUPPORT_SCORE = 0.8;
     DISCOVERED_SUPPORT_SCORE = 12;
+    BASE_PRACTICE_SCORE = 1;
     MAX_TARGET_MULTIPLIER = 8;
     MAX_SUPPORT_MULTIPLIER = 4;
     PRESCRIBED_DEBUG_VERSION = "testversion-prescribed-v3";
@@ -2035,7 +2131,18 @@ var init_prescribed = __esm({
             courseId,
             emittedIds
           );
-          emitted.push(...directCards, ...supportCards, ...discoveredSupportCards);
+          const practiceCards = this.buildPracticeCards({
+            group,
+            courseId,
+            emittedIds,
+            cardsByTag,
+            hierarchyConfigs,
+            userTagElo,
+            userGlobalElo,
+            activeIds,
+            seenIds
+          });
+          emitted.push(...directCards, ...supportCards, ...discoveredSupportCards, ...practiceCards);
         }
         const hintSummary = this.buildSupportHintSummary(groupRuntimes);
         const hints = Object.keys(hintSummary.boostTags).length > 0 ? {
@@ -2063,6 +2170,7 @@ var init_prescribed = __esm({
         const surfacedByGroup = /* @__PURE__ */ new Map();
         for (const card of finalCards) {
           const prov = card.provenance[0];
+          if (prov?.reason.includes("mode=practice")) continue;
           const groupId = prov?.reason.match(/group=([^;]+)/)?.[1];
           const mode = prov?.reason.includes("mode=support") ? "supportIds" : "targetIds";
           if (!groupId) continue;
@@ -2132,7 +2240,12 @@ var init_prescribed = __esm({
               enabled: raw.hierarchyWalk?.enabled !== false,
               maxDepth: typeof raw.hierarchyWalk?.maxDepth === "number" ? raw.hierarchyWalk.maxDepth : DEFAULT_HIERARCHY_DEPTH
             },
-            retireOnEncounter: raw.retireOnEncounter !== false
+            retireOnEncounter: raw.retireOnEncounter !== false,
+            practiceTagPatterns: dedupe(
+              Array.isArray(raw.practiceTagPatterns) ? raw.practiceTagPatterns.filter((v) => typeof v === "string") : []
+            ),
+            practiceMinCount: typeof raw.practiceMinCount === "number" ? raw.practiceMinCount : DEFAULT_PRACTICE_MIN_COUNT,
+            maxPracticeCardsPerRun: typeof raw.maxPracticeCardsPerRun === "number" ? raw.maxPracticeCardsPerRun : DEFAULT_MAX_PRACTICE_PER_RUN
           })).filter((g) => g.targetCardIds.length > 0);
           return { groups };
         } catch {
@@ -2355,6 +2468,92 @@ var init_prescribed = __esm({
         }
         return cards;
       }
+      /**
+       * Emit drill cards for *unlocked-but-under-practiced* skills.
+       *
+       * For each course tag matching the group's `practiceTagPatterns` that is both
+       * unlocked (all hierarchy prerequisites met — i.e. the learner has been
+       * introduced to it) and under-practiced (per-tag attempt count below
+       * `practiceMinCount`), this resolves cards carrying that tag and emits them
+       * into the candidate pool. It exists because global-ELO retrieval
+       * systematically fails to fetch the (low-ELO) drill cards for a
+       * freshly-introduced skill — putting them in the pool here lets the pipeline's
+       * scoring + the durable per-skill boost order them. Ordering/emphasis is NOT
+       * this method's job; it only guarantees presence.
+       *
+       * Fully data-driven: the unlock relation comes from the hierarchy config and
+       * practice-status from per-tag ELO. No card-id or tag-namespace hard-coding.
+       */
+      buildPracticeCards(args) {
+        const {
+          group,
+          courseId,
+          emittedIds,
+          cardsByTag,
+          hierarchyConfigs,
+          userTagElo,
+          userGlobalElo,
+          activeIds,
+          seenIds
+        } = args;
+        const patterns = group.practiceTagPatterns ?? [];
+        if (patterns.length === 0) return [];
+        const practiceMinCount = group.practiceMinCount ?? DEFAULT_PRACTICE_MIN_COUNT;
+        const maxPractice = group.maxPracticeCardsPerRun ?? DEFAULT_MAX_PRACTICE_PER_RUN;
+        const practiceTags = [...cardsByTag.keys()].filter(
+          (tag) => patterns.some((p) => matchesTagPattern(tag, p)) && this.isUnlockedGatedSkill(tag, hierarchyConfigs, userTagElo, userGlobalElo) && (userTagElo[tag]?.count ?? 0) < practiceMinCount
+        );
+        if (practiceTags.length === 0) return [];
+        const practiceCardIds = this.findDiscoveredSupportCards({
+          supportTags: practiceTags,
+          cardsByTag,
+          activeIds,
+          seenIds,
+          excludedIds: emittedIds,
+          limit: maxPractice
+        });
+        if (practiceCardIds.length === 0) return [];
+        logger.info(
+          `[Prescribed] Group '${group.id}' practice: ${practiceTags.length} unlocked under-practiced skill(s), emitting ${practiceCardIds.length} drill card(s)`
+        );
+        const cards = [];
+        for (const cardId of practiceCardIds) {
+          emittedIds.add(cardId);
+          cards.push({
+            cardId,
+            courseId,
+            score: BASE_PRACTICE_SCORE,
+            provenance: [
+              {
+                strategy: "prescribed",
+                strategyName: this.strategyName || this.name,
+                strategyId: this.strategyId || "NAVIGATION_STRATEGY-prescribed",
+                action: "generated",
+                score: BASE_PRACTICE_SCORE,
+                reason: `mode=practice;group=${group.id};underPracticedSkills=${practiceTags.length};practiceTags=${practiceTags.slice(0, 8).join("|")}${practiceTags.length > 8 ? "|\u2026" : ""};testversion=${PRESCRIBED_DEBUG_VERSION}`
+              }
+            ]
+          });
+        }
+        return cards;
+      }
+      /**
+       * True for a skill that was *gated and is now reached*: it has at least one
+       * declared hierarchy prerequisite set, and every set is fully satisfied by the
+       * learner's per-tag ELO. This deliberately EXCLUDES tags with no prerequisites
+       * — an ungated tag was never "introduced" in the curricular sense, so it isn't
+       * a post-intro drill target (e.g. whole-word spelling tags that share the
+       * `gpc:exercise:*` prefix but have no intro gate). Those are left to normal
+       * ELO retrieval. This is the precise population the retrieval gap strands:
+       * just-unlocked, low-ELO skills.
+       */
+      isUnlockedGatedSkill(tag, hierarchyConfigs, userTagElo, userGlobalElo) {
+        const prereqSets = hierarchyConfigs.map((hierarchy) => hierarchy.prerequisites[tag]).filter((prereqs) => Array.isArray(prereqs) && prereqs.length > 0);
+        if (prereqSets.length === 0) return false;
+        return prereqSets.every(
+          (prereqs) => prereqs.every((pr) => this.isPrerequisiteMet(pr, userTagElo[pr.tag], userGlobalElo))
+        );
+      }
       findSupportCardsByTags(group, tagsByCard, supportTags) {
         if (supportTags.length === 0) {
           return [];
@@ -4148,7 +4347,7 @@ function logResultCards(cards) {
   for (let i = 0; i < cards.length; i++) {
     const c = cards[i];
     const tags = c.tags?.slice(0, 3).join(", ") || "";
-    const filters = c.provenance.filter((p) => p.strategy === "hierarchyDefinition" || p.strategy === "priorityDefinition" || p.strategy === "interferenceFilter" || p.strategy === "letterGating" || p.strategy === "ephemeralHint").map((p) => {
+    const filters = c.provenance.filter((p) => p.strategy === "hierarchyDefinition" || p.strategy === "priorityDefinition" || p.strategy === "interferenceFilter" || p.strategy === "letterGating" || p.strategy === "ephemeralHint" || p.strategy === "diversityRerank").map((p) => {
       const arrow = p.action === "boosted" ? "\u2191" : p.action === "penalized" ? "\u2193" : "=";
       return `${p.strategyName}${arrow}${p.score.toFixed(2)}`;
     }).join(" | ");
@@ -4180,6 +4379,7 @@ var init_Pipeline = __esm({
     init_logger();
     init_orchestration();
     init_PipelineDebugger();
+    init_diversityRerank();
     VERBOSE_RESULTS = true;
     Pipeline = class extends ContentNavigator {
       generator;
@@ -4353,6 +4553,7 @@ var init_Pipeline = __esm({
           this._ephemeralHints = null;
           cards = this.applyHints(cards, hints, allCardsBeforeFiltering);
         }
+        cards = diversityRerank(cards);
         cards.sort((a, b) => b.score - a.score);
         const tFilter = performance.now();
         const result = cards.slice(0, limit);
@@ -4656,6 +4857,68 @@ var init_Pipeline = __esm({
       // ---------------------------------------------------------------------------
       // Card-space diagnostic
       // ---------------------------------------------------------------------------
+      /**
+       * Commit-free forecast: score the user's full card space through the filter
+       * chain and return the cards that are currently *reachable* (score >=
+       * threshold), optionally nudged by caller-supplied hints and/or restricted
+       * to cards the user hasn't seen yet.
+       *
+       * This is a GENERIC primitive — it returns scored, tag-hydrated cards and
+       * stops there. It has no knowledge of any particular tag convention; callers
+       * decide what the surviving cards mean (e.g. filter to their own "intro"
+       * tag family). Nothing is written and no session is started.
+       *
+       * The optional `hints` are the "out-of-band kick": they run through the same
+       * {@link applyHints} path a live replan uses, so the two semantics carry over —
+       *   - `boostTags`/`boostCards` reweight *within* gating (a gated score-0 card
+       *     stays out), and
+       *   - `requireTags`/`requireCards` inject from the full pre-filter pool,
+       *     *bypassing* gating (use when you want a card regardless of reachability).
+       * Note `unseenOnly` is applied LAST, so it can drop a `require`d card that the
+       * user has already seen — pass `unseenOnly: false` if that matters.
+       *
+       * Cost note: like {@link diagnoseCardSpace}, this scans every card through the
+       * filters, so it's heavier than a normal replan. Intended for one-shot
+       * out-of-band use (e.g. a session-end "what's next" snapshot), not the hot path.
+       *
+       * @param opts.hints       Optional ephemeral hints to apply after the filter chain.
+       * @param opts.unseenOnly  Only return cards the user hasn't encountered (default true).
+       * @param opts.threshold   Min score to count as reachable (default 0.10).
+       * @param opts.limit       Optional cap on results (already sorted desc).
+       */
+      async forecast(opts) {
+        const threshold = opts?.threshold ?? 0.1;
+        const unseenOnly = opts?.unseenOnly ?? true;
+        const courseId = this.course.getCourseID();
+        const allCardIds = await this.course.getAllCardIds();
+        let cards = allCardIds.map((cardId) => ({
+          cardId,
+          courseId,
+          score: 1,
+          provenance: []
+        }));
+        cards = await this.hydrateTags(cards);
+        const fullPool = cards.slice();
+        const context = await this.buildContext();
+        for (const filter of this.filters) {
+          cards = await filter.transform(cards, context);
+        }
+        if (opts?.hints) {
+          cards = this.applyHints(cards, opts.hints, fullPool);
+        }
+        cards = cards.filter((c) => c.score >= threshold);
+        if (unseenOnly) {
+          let encountered;
+          try {
+            encountered = new Set(await this.user.getSeenCards(courseId));
+          } catch {
+            encountered = /* @__PURE__ */ new Set();
+          }
+          cards = cards.filter((c) => !encountered.has(c.cardId));
+        }
+        cards.sort((a, b) => b.score - a.score);
+        return opts?.limit ? cards.slice(0, opts.limit) : cards;
+      }
       /**
        * Scan every card in the course through the filter chain and report
        * how many are "well indicated" (score >= threshold) for the current user.
@@ -4921,6 +5184,7 @@ var init_3 = __esm({
       "./PipelineAssembler.ts": () => Promise.resolve().then(() => (init_PipelineAssembler(), PipelineAssembler_exports)),
       "./PipelineDebugger.ts": () => Promise.resolve().then(() => (init_PipelineDebugger(), PipelineDebugger_exports)),
       "./defaults.ts": () => Promise.resolve().then(() => (init_defaults(), defaults_exports)),
+      "./diversityRerank.ts": () => Promise.resolve().then(() => (init_diversityRerank(), diversityRerank_exports)),
       "./filters/WeightedFilter.ts": () => Promise.resolve().then(() => (init_WeightedFilter(), WeightedFilter_exports)),
       "./filters/eloDistance.ts": () => Promise.resolve().then(() => (init_eloDistance(), eloDistance_exports)),
       "./filters/hierarchyDefinition.ts": () => Promise.resolve().then(() => (init_hierarchyDefinition(), hierarchyDefinition_exports)),
@@ -4946,9 +5210,13 @@ var init_3 = __esm({
 var navigators_exports = {};
 __export(navigators_exports, {
   ContentNavigator: () => ContentNavigator,
+  DIVERSITY_FLOOR: () => DIVERSITY_FLOOR,
+  DIVERSITY_STRENGTH: () => DIVERSITY_STRENGTH,
   NavigatorRole: () => NavigatorRole,
   NavigatorRoles: () => NavigatorRoles,
   Navigators: () => Navigators,
+  diversityRerank: () => diversityRerank,
+  getActivePipeline: () => getActivePipeline,
   getCardOrigin: () => getCardOrigin,
   getRegisteredNavigator: () => getRegisteredNavigator,
   getRegisteredNavigatorNames: () => getRegisteredNavigatorNames,
@@ -5032,6 +5300,7 @@ var navigatorRegistry, Navigators, NavigatorRole, NavigatorRoles, ContentNavigat
 var init_navigators = __esm({
   "src/core/navigators/index.ts"() {
     "use strict";
+    init_diversityRerank();
     init_PipelineDebugger();
     init_logger();
     init_();
@@ -8039,6 +8308,8 @@ Examples:
 var core_exports = {};
 __export(core_exports, {
   ContentNavigator: () => ContentNavigator,
+  DIVERSITY_FLOOR: () => DIVERSITY_FLOOR,
+  DIVERSITY_STRENGTH: () => DIVERSITY_STRENGTH,
   DocType: () => DocType,
   DocTypePrefixes: () => DocTypePrefixes,
   GuestUsername: () => GuestUsername,
@@ -8055,7 +8326,9 @@ __export(core_exports, {
   computeSpread: () => computeSpread,
   computeStrategyGradient: () => computeStrategyGradient,
   createOrchestrationContext: () => createOrchestrationContext,
+  diversityRerank: () => diversityRerank,
   docIsDeleted: () => docIsDeleted,
+  getActivePipeline: () => getActivePipeline,
   getCardHistoryID: () => getCardHistoryID,
   getCardOrigin: () => getCardOrigin,
   getDefaultLearnableWeight: () => getDefaultLearnableWeight,
@@ -8104,6 +8377,8 @@ init_core();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ContentNavigator,
+  DIVERSITY_FLOOR,
+  DIVERSITY_STRENGTH,
   DocType,
   DocTypePrefixes,
   GuestUsername,
@@ -8120,7 +8395,9 @@ init_core();
   computeSpread,
   computeStrategyGradient,
   createOrchestrationContext,
+  diversityRerank,
   docIsDeleted,
+  getActivePipeline,
   getCardHistoryID,
   getCardOrigin,
   getDefaultLearnableWeight,