@vue-skuilder/db 0.1.31-b → 0.1.31

package/dist/index.mjs

@@ -855,8 +855,12 @@ __export(PipelineDebugger_exports, {
   buildRunReport: () => buildRunReport,
   captureRun: () => captureRun,
   mountPipelineDebugger: () => mountPipelineDebugger,
-  pipelineDebugAPI: () => pipelineDebugAPI
+  pipelineDebugAPI: () => pipelineDebugAPI,
+  registerPipelineForDebug: () => registerPipelineForDebug
 });
+function registerPipelineForDebug(pipeline) {
+  _activePipeline = pipeline;
+}
 function getOrigin(card) {
   const firstEntry = card.provenance[0];
   if (!firstEntry) return "unknown";
@@ -884,6 +888,7 @@ function buildRunReport(courseId, courseName, generatorName, generators, generat
     origin: getOrigin(card),
     finalScore: card.score,
     provenance: card.provenance,
+    tags: card.tags,
     selected: selectedIds.has(card.cardId)
   }));
   const reviewsSelected = selectedCards.filter((c) => getOrigin(c) === "review").length;
@@ -939,12 +944,13 @@ function mountPipelineDebugger() {
   win.skuilder = win.skuilder || {};
   win.skuilder.pipeline = pipelineDebugAPI;
 }
-var MAX_RUNS, runHistory, pipelineDebugAPI;
+var _activePipeline, MAX_RUNS, runHistory, pipelineDebugAPI;
 var init_PipelineDebugger = __esm({
   "src/core/navigators/PipelineDebugger.ts"() {
     "use strict";
     init_navigators();
     init_logger();
+    _activePipeline = null;
     MAX_RUNS = 10;
     runHistory = [];
     pipelineDebugAPI = {
@@ -1146,6 +1152,21 @@ var init_PipelineDebugger = __esm({
         }
         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) {
+        if (!_activePipeline) {
+          logger.info("[Pipeline Debug] No active pipeline. Run a session first.");
+          return null;
+        }
+        return _activePipeline.diagnoseCardSpace({ threshold });
+      },
       /**
        * Show help.
        */
@@ -1158,6 +1179,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
@@ -1169,7 +1191,7 @@ Commands:
 Example:
   window.skuilder.pipeline.showLastRun()
   window.skuilder.pipeline.showRun(1)
-  window.skuilder.pipeline.showCard('abc123')
+  await window.skuilder.pipeline.diagnoseCardSpace()
 `);
       }
     };
@@ -1464,6 +1486,69 @@ var init_generators = __esm({
   }
 });
 
+// src/core/navigators/generators/prescribed.ts
+var prescribed_exports = {};
+__export(prescribed_exports, {
+  default: () => PrescribedCardsGenerator
+});
+var PrescribedCardsGenerator;
+var init_prescribed = __esm({
+  "src/core/navigators/generators/prescribed.ts"() {
+    "use strict";
+    init_navigators();
+    init_logger();
+    PrescribedCardsGenerator = class extends ContentNavigator {
+      name;
+      config;
+      constructor(user, course, strategyData) {
+        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, _context) {
+        if (this.config.cardIds.length === 0) {
+          return [];
+        }
+        const courseId = this.course.getCourseID();
+        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 [];
+        }
+        const cards = eligibleIds.slice(0, limit).map((cardId) => ({
+          cardId,
+          courseId,
+          score: 1,
+          provenance: [
+            {
+              strategy: "prescribed",
+              strategyName: this.strategyName || this.name,
+              strategyId: this.strategyId || "NAVIGATION_STRATEGY-prescribed",
+              action: "generated",
+              score: 1,
+              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;
+      }
+    };
+  }
+});
+
 // src/core/navigators/generators/srs.ts
 var srs_exports = {};
 __export(srs_exports, {
@@ -1658,6 +1743,7 @@ var init_ = __esm({
       "./generators/CompositeGenerator.ts": () => Promise.resolve().then(() => (init_CompositeGenerator(), CompositeGenerator_exports)),
       "./generators/elo.ts": () => Promise.resolve().then(() => (init_elo(), elo_exports)),
       "./generators/index.ts": () => Promise.resolve().then(() => (init_generators(), generators_exports)),
+      "./generators/prescribed.ts": () => Promise.resolve().then(() => (init_prescribed(), prescribed_exports)),
       "./generators/srs.ts": () => Promise.resolve().then(() => (init_srs(), srs_exports)),
       "./generators/types.ts": () => Promise.resolve().then(() => (init_types(), types_exports))
     });
@@ -1858,6 +1944,8 @@ var init_hierarchyDefinition = __esm({
         if (userTagElo.count < minCount) return false;
         if (prereq.masteryThreshold?.minElo !== void 0) {
           return userTagElo.score >= prereq.masteryThreshold.minElo;
+        } else if (prereq.masteryThreshold?.minCount !== void 0) {
+          return true;
         } else {
           return userTagElo.score >= userGlobalElo;
         }
@@ -1933,14 +2021,38 @@ var init_hierarchyDefinition = __esm({
           };
         }
       }
+      /**
+       * 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.
+       */
+      getPreReqBoosts(unlockedTags, masteredTags) {
+        const boosts = /* @__PURE__ */ new Map();
+        for (const [tagId, prereqs] of Object.entries(this.config.prerequisites)) {
+          if (unlockedTags.has(tagId)) continue;
+          for (const prereq of prereqs) {
+            if (!prereq.preReqBoost || prereq.preReqBoost <= 1) continue;
+            if (masteredTags.has(prereq.tag)) continue;
+            const existing = boosts.get(prereq.tag) ?? 1;
+            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, context) {
         const masteredTags = await this.getMasteredTags(context);
         const unlockedTags = this.getUnlockedTags(masteredTags);
+        const preReqBoosts = this.getPreReqBoosts(unlockedTags, masteredTags);
         const gated = [];
         for (const card of cards) {
           const { isUnlocked, reason } = await this.checkCardUnlock(
@@ -1949,9 +2061,27 @@ var init_hierarchyDefinition = __esm({
             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 = isUnlocked ? "passed" : "penalized";
+          let finalReason = reason;
+          if (isUnlocked && preReqBoosts.size > 0) {
+            const cardTags = card.tags ?? [];
+            let maxBoost = 1;
+            const boostedPrereqs = [];
+            for (const tag of cardTags) {
+              const boost = preReqBoosts.get(tag);
+              if (boost && boost > maxBoost) {
+                maxBoost = boost;
+                boostedPrereqs.push(tag);
+              }
+            }
+            if (maxBoost > 1) {
+              finalScore *= maxBoost;
+              action = "boosted";
+              finalReason = `${reason} | preReqBoost \xD7${maxBoost.toFixed(2)} for ${boostedPrereqs.join(", ")}`;
+            }
+          }
           gated.push({
             ...card,
             score: finalScore,
@@ -1963,7 +2093,7 @@ var init_hierarchyDefinition = __esm({
                 strategyId: this.strategyId || "NAVIGATION_STRATEGY-hierarchy",
                 action,
                 score: finalScore,
-                reason
+                reason: finalReason
               }
             ]
           });
@@ -2898,6 +3028,18 @@ __export(Pipeline_exports, {
   Pipeline: () => Pipeline
 });
 import { toCourseElo as toCourseElo5 } from "@vue-skuilder/common";
+function globToRegex(pattern) {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+  const withWildcards = escaped.replace(/\*/g, ".*");
+  return new RegExp(`^${withWildcards}$`);
+}
+function globMatch(value, pattern) {
+  if (!pattern.includes("*")) return value === pattern;
+  return globToRegex(pattern).test(value);
+}
+function cardMatchesTagPattern(card, pattern) {
+  return (card.tags ?? []).some((tag) => globMatch(tag, pattern));
+}
 function logPipelineConfig(generator, filters) {
   const filterList = filters.length > 0 ? "\n    - " + filters.map((f) => f.name).join("\n    - ") : " none";
   logger.info(
@@ -2932,6 +3074,21 @@ function logExecutionSummary(generatorName, generatedCount, filterCount, finalCo
   \u{1F4A1} Inspect: window.skuilder.pipeline`
   );
 }
+function logResultCards(cards) {
+  if (!VERBOSE_RESULTS || cards.length === 0) return;
+  logger.info(`[Pipeline] Results (${cards.length} 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 arrow = p.action === "boosted" ? "\u2191" : p.action === "penalized" ? "\u2193" : "=";
+      return `${p.strategyName}${arrow}${p.score.toFixed(2)}`;
+    }).join(" | ");
+    logger.info(
+      `[Pipeline]   ${String(i + 1).padStart(2)}. ${c.score.toFixed(4)}  ${c.cardId}  [${tags}]${filters ? `  {${filters}}` : ""}`
+    );
+  }
+}
 function logCardProvenance(cards, maxCards = 3) {
   const cardsToLog = cards.slice(0, maxCards);
   logger.debug(`[Pipeline] Provenance for top ${cardsToLog.length} cards:`);
@@ -2946,7 +3103,7 @@ function logCardProvenance(cards, maxCards = 3) {
     }
   }
 }
-var Pipeline;
+var VERBOSE_RESULTS, Pipeline;
 var init_Pipeline = __esm({
   "src/core/navigators/Pipeline.ts"() {
     "use strict";
@@ -2954,9 +3111,31 @@ var init_Pipeline = __esm({
     init_logger();
     init_orchestration();
     init_PipelineDebugger();
+    VERBOSE_RESULTS = true;
     Pipeline = class extends ContentNavigator {
       generator;
       filters;
+      /**
+       * Cached orchestration context. Course config and salt don't change within
+       * a page load, so we build the orchestration context once and reuse it on
+       * subsequent getWeightedCards() calls (e.g. mid-session replans).
+       *
+       * This eliminates a remote getCourseConfig() round trip per pipeline run.
+       */
+      _cachedOrchestration = null;
+      /**
+       * Persistent tag cache. Maps cardId → tag names.
+       *
+       * Tags are static within a session (they're set at card generation time),
+       * so we cache them across pipeline runs. On replans, many of the same cards
+       * reappear — cache hits avoid redundant remote getAppliedTagsBatch() queries.
+       */
+      _tagCache = /* @__PURE__ */ new Map();
+      /**
+       * One-shot replan hints. Applied after the filter chain on the next
+       * getWeightedCards() call, then cleared.
+       */
+      _ephemeralHints = null;
       /**
        * Create a new pipeline.
        *
@@ -2977,6 +3156,17 @@ var init_Pipeline = __esm({
           logger.error(`[pipeline] Failed to lookup courseCfg: ${e}`);
         });
         logPipelineConfig(generator, filters);
+        registerPipelineForDebug(this);
+      }
+      /**
+       * Set one-shot hints for the next pipeline run.
+       * Consumed after one getWeightedCards() call, then cleared.
+       *
+       * Overrides ContentNavigator.setEphemeralHints() no-op.
+       */
+      setEphemeralHints(hints) {
+        this._ephemeralHints = hints;
+        logger.info(`[Pipeline] Ephemeral hints set: ${JSON.stringify(hints)}`);
       }
       /**
        * Get weighted cards by running generator and applying filters.
@@ -2993,13 +3183,15 @@ var init_Pipeline = __esm({
        * @returns Cards sorted by score descending
        */
       async getWeightedCards(limit) {
+        const t0 = performance.now();
         const context = await this.buildContext();
-        const overFetchMultiplier = 2 + this.filters.length * 0.5;
-        const fetchLimit = Math.ceil(limit * overFetchMultiplier);
+        const tContext = performance.now();
+        const fetchLimit = 500;
         logger.debug(
           `[Pipeline] Fetching ${fetchLimit} candidates from generator '${this.generator.name}'`
         );
         let cards = await this.generator.getWeightedCards(fetchLimit, context);
+        const tGenerate = performance.now();
         const generatedCount = cards.length;
         let generatorSummaries;
         if (this.generator.generators) {
@@ -3028,6 +3220,7 @@ var init_Pipeline = __esm({
         }
         logger.debug(`[Pipeline] Generator returned ${generatedCount} candidates`);
         cards = await this.hydrateTags(cards);
+        const tHydrate = performance.now();
         const allCardsBeforeFiltering = [...cards];
         const filterImpacts = [];
         for (const filter of this.filters) {
@@ -3046,8 +3239,17 @@ var init_Pipeline = __esm({
           logger.debug(`[Pipeline] Filter '${filter.name}': ${beforeScores.size} \u2192 ${cards.length} cards (\u2191${boosted} \u2193${penalized} =${passed})`);
         }
         cards = cards.filter((c) => c.score > 0);
+        const hints = this._ephemeralHints;
+        if (hints) {
+          this._ephemeralHints = null;
+          cards = this.applyHints(cards, hints, allCardsBeforeFiltering);
+        }
         cards.sort((a, b) => b.score - a.score);
+        const tFilter = performance.now();
         const result = cards.slice(0, limit);
+        logger.info(
+          `[Pipeline:timing] total=${(tFilter - t0).toFixed(0)}ms (context=${(tContext - t0).toFixed(0)} generate=${(tGenerate - tContext).toFixed(0)} hydrate=${(tHydrate - tGenerate).toFixed(0)} filter=${(tFilter - tHydrate).toFixed(0)})`
+        );
         const topScores = result.slice(0, 3).map((c) => c.score);
         logExecutionSummary(
           this.generator.name,
@@ -3057,6 +3259,7 @@ var init_Pipeline = __esm({
           topScores,
           filterImpacts
         );
+        logResultCards(result);
         logCardProvenance(result, 3);
         try {
           const courseName = await this.course?.getCourseConfig().then((c) => c.name).catch(() => void 0);
@@ -3083,6 +3286,10 @@ var init_Pipeline = __esm({
        * to the WeightedCard objects. Filters can then use card.tags instead of
        * making individual getAppliedTags() calls.
        *
+       * Uses a persistent tag cache across pipeline runs — tags are static within
+       * a session, so cards seen in a prior run (e.g. before a replan) don't
+       * require a second DB query.
+       *
        * @param cards - Cards to hydrate
        * @returns Cards with tags populated
        */
@@ -3090,14 +3297,128 @@ var init_Pipeline = __esm({
         if (cards.length === 0) {
           return cards;
         }
-        const cardIds = cards.map((c) => c.cardId);
-        const tagsByCard = await this.course.getAppliedTagsBatch(cardIds);
+        const uncachedIds = [];
+        for (const card of cards) {
+          if (!this._tagCache.has(card.cardId)) {
+            uncachedIds.push(card.cardId);
+          }
+        }
+        if (uncachedIds.length > 0) {
+          const freshTags = await this.course.getAppliedTagsBatch(uncachedIds);
+          for (const [cardId, tags] of freshTags) {
+            this._tagCache.set(cardId, tags);
+          }
+        }
+        const tagsByCard = /* @__PURE__ */ new Map();
+        for (const card of cards) {
+          tagsByCard.set(card.cardId, this._tagCache.get(card.cardId) ?? []);
+        }
         logTagHydration(cards, tagsByCard);
         return cards.map((card) => ({
           ...card,
-          tags: tagsByCard.get(card.cardId) ?? []
+          tags: this._tagCache.get(card.cardId) ?? []
         }));
       }
+      // ---------------------------------------------------------------------------
+      // Ephemeral hints application
+      // ---------------------------------------------------------------------------
+      /**
+       * Apply one-shot replan hints to the post-filter card set.
+       *
+       * Order of operations:
+       *   1. Exclude (remove unwanted cards)
+       *   2. Boost (multiply scores)
+       *   3. Require (inject must-have cards from the full pre-filter pool)
+       *
+       * @param cards - Post-filter cards (score > 0)
+       * @param hints - The ephemeral hints to apply
+       * @param allCards - Full pre-filter card pool (for require injection)
+       */
+      applyHints(cards, hints, allCards) {
+        const beforeCount = cards.length;
+        if (hints.excludeCards?.length) {
+          cards = cards.filter(
+            (c) => !hints.excludeCards.some((pat) => globMatch(c.cardId, pat))
+          );
+        }
+        if (hints.excludeTags?.length) {
+          cards = cards.filter(
+            (c) => !hints.excludeTags.some((pat) => cardMatchesTagPattern(c, pat))
+          );
+        }
+        if (hints.boostTags) {
+          for (const [pattern, factor] of Object.entries(hints.boostTags)) {
+            for (const card of cards) {
+              if (cardMatchesTagPattern(card, pattern)) {
+                card.score *= factor;
+                card.provenance.push({
+                  strategy: "ephemeralHint",
+                  strategyId: "ephemeral-hint",
+                  strategyName: "Replan Hint",
+                  action: "boosted",
+                  score: card.score,
+                  reason: `boostTag ${pattern} \xD7${factor}`
+                });
+              }
+            }
+          }
+        }
+        if (hints.boostCards) {
+          for (const [pattern, factor] of Object.entries(hints.boostCards)) {
+            for (const card of cards) {
+              if (globMatch(card.cardId, pattern)) {
+                card.score *= factor;
+                card.provenance.push({
+                  strategy: "ephemeralHint",
+                  strategyId: "ephemeral-hint",
+                  strategyName: "Replan Hint",
+                  action: "boosted",
+                  score: card.score,
+                  reason: `boostCard ${pattern} \xD7${factor}`
+                });
+              }
+            }
+          }
+        }
+        const cardIds = new Set(cards.map((c) => c.cardId));
+        const inject = (card, reason) => {
+          if (!cardIds.has(card.cardId)) {
+            const floorScore = Math.max(card.score, 1);
+            cards.push({
+              ...card,
+              score: floorScore,
+              provenance: [
+                ...card.provenance,
+                {
+                  strategy: "ephemeralHint",
+                  strategyId: "ephemeral-hint",
+                  strategyName: "Replan Hint",
+                  action: "boosted",
+                  score: floorScore,
+                  reason
+                }
+              ]
+            });
+            cardIds.add(card.cardId);
+          }
+        };
+        if (hints.requireCards?.length) {
+          for (const pattern of hints.requireCards) {
+            for (const card of allCards) {
+              if (globMatch(card.cardId, pattern)) inject(card, `requireCard ${pattern}`);
+            }
+          }
+        }
+        if (hints.requireTags?.length) {
+          for (const pattern of hints.requireTags) {
+            for (const card of allCards) {
+              if (cardMatchesTagPattern(card, pattern)) inject(card, `requireTag ${pattern}`);
+            }
+          }
+        }
+        logger.info(`[Pipeline] Hints applied: ${beforeCount} \u2192 ${cards.length} cards`);
+        return cards;
+      }
       /**
        * Build shared context for generator and filters.
        *
@@ -3115,7 +3436,10 @@ var init_Pipeline = __esm({
         } catch (e) {
           logger.debug(`[Pipeline] Could not get user ELO, using default: ${e}`);
         }
-        const orchestration = await createOrchestrationContext(this.user, this.course);
+        if (!this._cachedOrchestration) {
+          this._cachedOrchestration = await createOrchestrationContext(this.user, this.course);
+        }
+        const orchestration = this._cachedOrchestration;
         return {
           user: this.user,
           course: this.course,
@@ -3159,6 +3483,87 @@ var init_Pipeline = __esm({
         }
         return [...new Set(ids)];
       }
+      // ---------------------------------------------------------------------------
+      // Card-space diagnostic
+      // ---------------------------------------------------------------------------
+      /**
+       * Scan every card in the course through the filter chain and report
+       * how many are "well indicated" (score >= threshold) for the current user.
+       *
+       * Also reports how many well-indicated cards the user has NOT yet encountered.
+       *
+       * Exposed via `window.skuilder.pipeline.diagnoseCardSpace()`.
+       */
+      async diagnoseCardSpace(opts) {
+        const THRESHOLD = opts?.threshold ?? 0.1;
+        const t0 = performance.now();
+        const allCardIds = await this.course.getAllCardIds();
+        let cards = allCardIds.map((cardId) => ({
+          cardId,
+          courseId: this.course.getCourseID(),
+          score: 1,
+          provenance: []
+        }));
+        cards = await this.hydrateTags(cards);
+        const context = await this.buildContext();
+        const filterBreakdown = [];
+        for (const filter of this.filters) {
+          cards = await filter.transform(cards, context);
+          const wi = cards.filter((c) => c.score >= THRESHOLD).length;
+          filterBreakdown.push({ name: filter.name, wellIndicated: wi });
+        }
+        const wellIndicated = cards.filter((c) => c.score >= THRESHOLD);
+        const wellIndicatedIds = new Set(wellIndicated.map((c) => c.cardId));
+        let encounteredIds;
+        try {
+          const courseId = this.course.getCourseID();
+          const seenCards = await this.user.getSeenCards(courseId);
+          encounteredIds = new Set(seenCards);
+        } catch {
+          encounteredIds = /* @__PURE__ */ new Set();
+        }
+        const wellIndicatedNew = wellIndicated.filter((c) => !encounteredIds.has(c.cardId));
+        const byType = /* @__PURE__ */ new Map();
+        for (const card of cards) {
+          const type = card.cardId.split("-")[1] || "unknown";
+          if (!byType.has(type)) {
+            byType.set(type, { total: 0, wellIndicated: 0, new: 0 });
+          }
+          const entry = byType.get(type);
+          entry.total++;
+          if (card.score >= THRESHOLD) {
+            entry.wellIndicated++;
+            if (!encounteredIds.has(card.cardId)) entry.new++;
+          }
+        }
+        const elapsed = performance.now() - t0;
+        const result = {
+          totalCards: allCardIds.length,
+          threshold: THRESHOLD,
+          wellIndicated: wellIndicatedIds.size,
+          encountered: encounteredIds.size,
+          wellIndicatedNew: wellIndicatedNew.length,
+          byType: Object.fromEntries(byType),
+          filterBreakdown,
+          elapsedMs: Math.round(elapsed)
+        };
+        logger.info(`[Pipeline:diagnose] Card space scan (${result.elapsedMs}ms):`);
+        logger.info(`[Pipeline:diagnose]   Total cards: ${result.totalCards}`);
+        logger.info(`[Pipeline:diagnose]   Well-indicated (score >= ${THRESHOLD}): ${result.wellIndicated}`);
+        logger.info(`[Pipeline:diagnose]   Encountered: ${result.encountered}`);
+        logger.info(`[Pipeline:diagnose]   Well-indicated & new: ${result.wellIndicatedNew}`);
+        logger.info(`[Pipeline:diagnose]   By type:`);
+        for (const [type, counts] of byType) {
+          logger.info(
+            `[Pipeline:diagnose]     ${type}: ${counts.wellIndicated}/${counts.total} well-indicated, ${counts.new} new`
+          );
+        }
+        logger.info(`[Pipeline:diagnose]   After each filter:`);
+        for (const fb of filterBreakdown) {
+          logger.info(`[Pipeline:diagnose]     ${fb.name}: ${fb.wellIndicated} well-indicated`);
+        }
+        return result;
+      }
     };
   }
 });
@@ -3263,23 +3668,25 @@ var init_PipelineAssembler = __esm({
             warnings.push(`Unknown strategy type '${s.implementingClass}', skipping: ${s.name}`);
           }
         }
+        const courseId = course.getCourseID();
+        const hasElo = generatorStrategies.some((s) => s.implementingClass === "elo" /* ELO */);
+        const hasSrs = generatorStrategies.some((s) => s.implementingClass === "srs" /* SRS */);
+        if (!hasElo) {
+          logger.debug("[PipelineAssembler] No ELO generator configured, adding default");
+          generatorStrategies.push(createDefaultEloStrategy(courseId));
+        }
+        if (!hasSrs) {
+          logger.debug("[PipelineAssembler] No SRS generator configured, adding default");
+          generatorStrategies.push(createDefaultSrsStrategy(courseId));
+        }
         if (generatorStrategies.length === 0) {
-          if (filterStrategies.length > 0) {
-            logger.debug(
-              "[PipelineAssembler] No generator found, using default ELO and SRS with configured filters"
-            );
-            const courseId = course.getCourseID();
-            generatorStrategies.push(createDefaultEloStrategy(courseId));
-            generatorStrategies.push(createDefaultSrsStrategy(courseId));
-          } else {
-            warnings.push("No generator strategy found");
-            return {
-              pipeline: null,
-              generatorStrategies: [],
-              filterStrategies: [],
-              warnings
-            };
-          }
+          warnings.push("No generator strategy found");
+          return {
+            pipeline: null,
+            generatorStrategies: [],
+            filterStrategies: [],
+            warnings
+          };
         }
         let generator;
         if (generatorStrategies.length === 1) {
@@ -3357,6 +3764,7 @@ var init_3 = __esm({
       "./generators/CompositeGenerator.ts": () => Promise.resolve().then(() => (init_CompositeGenerator(), CompositeGenerator_exports)),
       "./generators/elo.ts": () => Promise.resolve().then(() => (init_elo(), elo_exports)),
       "./generators/index.ts": () => Promise.resolve().then(() => (init_generators(), generators_exports)),
+      "./generators/prescribed.ts": () => Promise.resolve().then(() => (init_prescribed(), prescribed_exports)),
       "./generators/srs.ts": () => Promise.resolve().then(() => (init_srs(), srs_exports)),
       "./generators/types.ts": () => Promise.resolve().then(() => (init_types(), types_exports)),
       "./index.ts": () => Promise.resolve().then(() => (init_navigators(), navigators_exports))
@@ -3405,8 +3813,10 @@ async function initializeNavigatorRegistry() {
     Promise.resolve().then(() => (init_elo(), elo_exports)),
     Promise.resolve().then(() => (init_srs(), srs_exports))
   ]);
+  const prescribedModule = await Promise.resolve().then(() => (init_prescribed(), prescribed_exports));
   registerNavigator("elo", eloModule.default);
   registerNavigator("srs", srsModule.default);
+  registerNavigator("prescribed", prescribedModule.default);
   const [
     hierarchyModule,
     interferenceModule,
@@ -3461,6 +3871,7 @@ var init_navigators = __esm({
     Navigators = /* @__PURE__ */ ((Navigators2) => {
       Navigators2["ELO"] = "elo";
       Navigators2["SRS"] = "srs";
+      Navigators2["PRESCRIBED"] = "prescribed";
       Navigators2["HIERARCHY"] = "hierarchyDefinition";
       Navigators2["INTERFERENCE"] = "interferenceMitigator";
       Navigators2["RELATIVE_PRIORITY"] = "relativePriority";
@@ -3475,6 +3886,7 @@ var init_navigators = __esm({
     NavigatorRoles = {
       ["elo" /* ELO */]: "generator" /* GENERATOR */,
       ["srs" /* SRS */]: "generator" /* GENERATOR */,
+      ["prescribed" /* PRESCRIBED */]: "generator" /* GENERATOR */,
       ["hierarchyDefinition" /* HIERARCHY */]: "filter" /* FILTER */,
       ["interferenceMitigator" /* INTERFERENCE */]: "filter" /* FILTER */,
       ["relativePriority" /* RELATIVE_PRIORITY */]: "filter" /* FILTER */,
@@ -3639,6 +4051,12 @@ var init_navigators = __esm({
       async getWeightedCards(_limit) {
         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) {
+      }
     };
   }
 });
@@ -3788,15 +4206,42 @@ var init_courseDB = __esm({
       // private log(msg: string): void {
       //   log(`CourseLog: ${this.id}\n  ${msg}`);
       // }
+      /**
+       * Primary database handle used for all **read** operations (queries, gets).
+       *
+       * When local sync is active, this points to the local PouchDB replica for
+       * fast, network-free reads. Otherwise it points to the remote CouchDB.
+       */
       db;
+      /**
+       * Remote database handle used for all **write** operations.
+       *
+       * Always points to the remote CouchDB so that writes (ELO updates, tag
+       * mutations, admin operations) aggregate on the server. The local replica
+       * is a read-only snapshot that refreshes on the next page load.
+       *
+       * When local sync is NOT active, this is the same instance as `this.db`.
+       */
+      remoteDB;
       id;
       _getCurrentUser;
       updateQueue;
-      constructor(id, userLookup) {
+      /**
+       * @param id - Course ID
+       * @param userLookup - Async function returning the current user DB
+       * @param localDB - Optional local PouchDB replica for reads. When provided,
+       *   `this.db` uses the local replica and `this.remoteDB` stays remote.
+       *   The UpdateQueue reads from remote and writes to remote (local `_rev`
+       *   values may be stale, so read-modify-write cycles must go through
+       *   the remote DB to avoid conflicts).
+       */
+      constructor(id, userLookup, localDB) {
         this.id = id;
-        this.db = getCourseDB2(this.id);
+        const remote = getCourseDB2(this.id);
+        this.remoteDB = remote;
+        this.db = localDB ?? remote;
         this._getCurrentUser = userLookup;
-        this.updateQueue = new UpdateQueue(this.db);
+        this.updateQueue = new UpdateQueue(this.remoteDB, this.remoteDB);
       }
       getCourseID() {
         return this.id;
@@ -3884,7 +4329,7 @@ var init_courseDB = __esm({
         };
       }
       async removeCard(id) {
-        const doc = await this.db.get(id);
+        const doc = await this.remoteDB.get(id);
         if (!doc.docType || !(doc.docType === "CARD" /* CARD */)) {
           throw new Error(`failed to remove ${id} from course ${this.id}. id does not point to a card`);
         }
@@ -3905,7 +4350,7 @@ var init_courseDB = __esm({
         } catch (error) {
           logger.error(`Error removing card ${id} from tags: ${error}`);
         }
-        return this.db.remove(doc);
+        return this.remoteDB.remove(doc);
       }
       async getCardDisplayableDataIDs(id) {
         logger.debug(id.join(", "));
@@ -4007,8 +4452,7 @@ ${above.rows.map((r) => `	${r.id}-${r.key}
         if (cardIds.length === 0) {
           return /* @__PURE__ */ new Map();
         }
-        const db = getCourseDB2(this.id);
-        const result = await db.query("getTags", {
+        const result = await this.db.query("getTags", {
           keys: cardIds,
           include_docs: false
         });
@@ -4025,6 +4469,14 @@ ${above.rows.map((r) => `	${r.id}-${r.key}
         }
         return tagsByCard;
       }
+      async getAllCardIds() {
+        const result = await this.db.allDocs({
+          startkey: "CARD-",
+          endkey: "CARD-\uFFF0",
+          include_docs: false
+        });
+        return result.rows.map((row) => row.id);
+      }
       async addTagToCard(cardId, tagId, updateELO) {
         return await addTagToCard(
           this.id,
@@ -4091,10 +4543,13 @@ ${above.rows.map((r) => `	${r.id}-${r.key}
         }
       }
       async getCourseDoc(id, options) {
-        return await getCourseDoc(this.id, id, options);
+        return await this.db.get(id, options);
       }
       async getCourseDocs(ids, options = {}) {
-        return await getCourseDocs(this.id, ids, options);
+        return await this.db.allDocs({
+          ...options,
+          keys: ids
+        });
       }
       ////////////////////////////////////
       // NavigationStrategyManager implementation
@@ -4128,7 +4583,7 @@ ${above.rows.map((r) => `	${r.id}-${r.key}
       }
       async addNavigationStrategy(data) {
         logger.debug(`[courseDB] Adding navigation strategy: ${data._id}`);
-        return this.db.put(data).then(() => {
+        return this.remoteDB.put(data).then(() => {
         });
       }
       updateNavigationStrategy(id, data) {
@@ -4685,6 +5140,234 @@ var init_adminDB2 = __esm({
   }
 });
 
+// src/impl/couch/CourseSyncService.ts
+var CourseSyncService;
+var init_CourseSyncService = __esm({
+  "src/impl/couch/CourseSyncService.ts"() {
+    "use strict";
+    init_pouchdb_setup();
+    init_couch();
+    init_logger();
+    CourseSyncService = class _CourseSyncService {
+      static instance = null;
+      entries = /* @__PURE__ */ new Map();
+      constructor() {
+      }
+      static getInstance() {
+        if (!_CourseSyncService.instance) {
+          _CourseSyncService.instance = new _CourseSyncService();
+        }
+        return _CourseSyncService.instance;
+      }
+      /**
+       * Reset the singleton (for testing).
+       */
+      static resetInstance() {
+        if (_CourseSyncService.instance) {
+          for (const [, entry] of _CourseSyncService.instance.entries) {
+            if (entry.localDB) {
+              entry.localDB.close().catch(() => {
+              });
+            }
+          }
+          _CourseSyncService.instance.entries.clear();
+        }
+        _CourseSyncService.instance = null;
+      }
+      // --------------------------------------------------------------------------
+      // Public API
+      // --------------------------------------------------------------------------
+      /**
+       * Ensure a course's local replica is synced.
+       *
+       * On first call for a course:
+       *   1. Fetches CourseConfig from remote to check localSync.enabled
+       *   2. If enabled, performs one-shot replication remote → local
+       *   3. Pre-warms PouchDB view indices (elo, getTags)
+       *
+       * On subsequent calls: returns immediately if already synced, or awaits
+       * the in-flight sync if one is in progress.
+       *
+       * Safe to call multiple times — concurrent calls coalesce to one sync.
+       *
+       * @param courseId - The course to sync
+       * @param forceEnabled - Skip the CourseConfig check and sync regardless.
+       *   Useful when the caller already knows local sync is desired (e.g.,
+       *   LettersPractice hardcodes this).
+       */
+      async ensureSynced(courseId, forceEnabled) {
+        const existing = this.entries.get(courseId);
+        if (existing?.status.state === "ready") {
+          return;
+        }
+        if (existing?.status.state === "disabled") {
+          return;
+        }
+        if (existing?.readyPromise) {
+          return existing.readyPromise;
+        }
+        const entry = {
+          localDB: null,
+          status: { state: "not-started" },
+          readyPromise: null
+        };
+        this.entries.set(courseId, entry);
+        entry.readyPromise = this.performSync(courseId, entry, forceEnabled);
+        return entry.readyPromise;
+      }
+      /**
+       * Get the local PouchDB for a course, or null if not available.
+       *
+       * Returns null when:
+       *   - Local sync is not enabled for this course
+       *   - Sync has not been triggered yet
+       *   - Sync is still in progress
+       *   - Sync failed
+       */
+      getLocalDB(courseId) {
+        const entry = this.entries.get(courseId);
+        if (entry?.status.state === "ready" && entry.localDB) {
+          return entry.localDB;
+        }
+        return null;
+      }
+      /**
+       * Check whether a course has a ready local replica.
+       */
+      isReady(courseId) {
+        return this.entries.get(courseId)?.status.state === "ready";
+      }
+      /**
+       * Get detailed sync status for a course.
+       */
+      getStatus(courseId) {
+        return this.entries.get(courseId)?.status ?? { state: "not-started" };
+      }
+      // --------------------------------------------------------------------------
+      // Internal
+      // --------------------------------------------------------------------------
+      async performSync(courseId, entry, forceEnabled) {
+        try {
+          if (!forceEnabled) {
+            entry.status = { state: "checking-config" };
+            const enabled = await this.checkLocalSyncEnabled(courseId);
+            if (!enabled) {
+              entry.status = { state: "disabled" };
+              entry.readyPromise = null;
+              logger.debug(
+                `[CourseSyncService] Local sync disabled for course ${courseId}`
+              );
+              return;
+            }
+          }
+          entry.status = { state: "syncing" };
+          const localDBName = this.localDBName(courseId);
+          const localDB = new pouchdb_setup_default(localDBName);
+          entry.localDB = localDB;
+          const remoteDB = this.getRemoteDB(courseId);
+          const syncStart = Date.now();
+          logger.info(
+            `[CourseSyncService] Starting one-shot replication for course ${courseId}`
+          );
+          const result = await this.replicate(remoteDB, localDB);
+          const syncTimeMs = Date.now() - syncStart;
+          logger.info(
+            `[CourseSyncService] Replication complete for course ${courseId}: ${result.docs_written} docs in ${syncTimeMs}ms`
+          );
+          entry.status = { state: "warming-views" };
+          const warmStart = Date.now();
+          await this.warmViewIndices(localDB);
+          const viewWarmTimeMs = Date.now() - warmStart;
+          logger.info(
+            `[CourseSyncService] View indices warmed for course ${courseId} in ${viewWarmTimeMs}ms`
+          );
+          entry.status = {
+            state: "ready",
+            docsReplicated: result.docs_written,
+            syncTimeMs,
+            viewWarmTimeMs
+          };
+        } catch (e) {
+          const errorMsg = e instanceof Error ? e.message : String(e);
+          logger.error(
+            `[CourseSyncService] Sync failed for course ${courseId}: ${errorMsg}`
+          );
+          entry.status = { state: "error", error: errorMsg };
+          entry.readyPromise = null;
+          if (entry.localDB) {
+            try {
+              await entry.localDB.destroy();
+            } catch {
+            }
+            entry.localDB = null;
+          }
+        }
+      }
+      /**
+       * Check CourseConfig.localSync.enabled on the remote DB.
+       */
+      async checkLocalSyncEnabled(courseId) {
+        try {
+          const remoteDB = this.getRemoteDB(courseId);
+          const config = await remoteDB.get("CourseConfig");
+          return config.localSync?.enabled === true;
+        } catch (e) {
+          logger.warn(
+            `[CourseSyncService] Could not read CourseConfig for ${courseId}, assuming local sync disabled: ${e}`
+          );
+          return false;
+        }
+      }
+      /**
+       * One-shot replication from remote to local.
+       */
+      replicate(source, target) {
+        return new Promise((resolve, reject) => {
+          void pouchdb_setup_default.replicate(source, target, {
+            // One-shot, not live. Local is a read-only snapshot.
+          }).on("complete", (info) => {
+            resolve(info);
+          }).on("error", (err) => {
+            reject(err);
+          });
+        });
+      }
+      /**
+       * Pre-warm PouchDB view indices by running a minimal query against each
+       * design doc. This forces PouchDB to build the MapReduce index now
+       * (during a loading phase) rather than on first pipeline query.
+       */
+      async warmViewIndices(localDB) {
+        const viewsToWarm = ["elo", "getTags"];
+        for (const viewName of viewsToWarm) {
+          try {
+            await localDB.query(viewName, { limit: 1 });
+            logger.debug(
+              `[CourseSyncService] Warmed view index: ${viewName}`
+            );
+          } catch (e) {
+            logger.debug(
+              `[CourseSyncService] Could not warm view ${viewName}: ${e}`
+            );
+          }
+        }
+      }
+      /**
+       * Get a remote PouchDB handle for a course.
+       */
+      getRemoteDB(courseId) {
+        return getCourseDB2(courseId);
+      }
+      /**
+       * Local DB naming convention.
+       */
+      localDBName(courseId) {
+        return `coursedb-local-${courseId}`;
+      }
+    };
+  }
+});
+
 // src/impl/couch/auth.ts
 import fetch2 from "cross-fetch";
 async function getCurrentSession() {
@@ -4985,15 +5668,6 @@ function getCourseDB2(courseID) {
     createPouchDBConfig()
   );
 }
-function getCourseDocs(courseID, docIDs, options = {}) {
-  return getCourseDB2(courseID).allDocs({
-    ...options,
-    keys: docIDs
-  });
-}
-function getCourseDoc(courseID, docID, options = {}) {
-  return getCourseDB2(courseID).get(docID, options);
-}
 function filterAllDocsByPrefix2(db, prefix, opts) {
   const options = {
     startkey: prefix,
@@ -5024,6 +5698,7 @@ var init_couch = __esm({
     init_classroomDB2();
     init_courseAPI();
     init_courseDB();
+    init_CourseSyncService();
     init_CouchDBSyncStrategy();
     isBrowser = typeof window !== "undefined";
     if (isBrowser) {
@@ -5324,6 +5999,9 @@ Currently logged-in as ${this._username}.`
             const id = row.id;
             return id.startsWith(DocTypePrefixes["CARDRECORD" /* CARDRECORD */]) || // Card interaction history
             id.startsWith(DocTypePrefixes["SCHEDULED_CARD" /* SCHEDULED_CARD */]) || // Scheduled reviews
+            id.startsWith(DocTypePrefixes["STRATEGY_STATE" /* STRATEGY_STATE */]) || // Strategy state (user prefs, progression)
+            id.startsWith(DocTypePrefixes["USER_OUTCOME" /* USER_OUTCOME */]) || // Evolutionary orchestration outcomes
+            id.startsWith(DocTypePrefixes["STRATEGY_LEARNING_STATE" /* 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;
@@ -6120,6 +6798,7 @@ var init_PouchDataLayerProvider = __esm({
     init_adminDB2();
     init_classroomDB2();
     init_courseDB();
+    init_CourseSyncService();
     init_common();
     init_CouchDBSyncStrategy();
     CouchDataLayerProvider = class {
@@ -6159,7 +6838,22 @@ var init_PouchDataLayerProvider = __esm({
         return this.userDB;
       }
       getCourseDB(courseId) {
-        return new CourseDB(courseId, async () => this.getUserDB());
+        const localDB = CourseSyncService.getInstance().getLocalDB(courseId);
+        return new CourseDB(courseId, async () => this.getUserDB(), localDB ?? void 0);
+      }
+      /**
+       * Trigger local sync for a course. Call during app initialization or
+       * pre-session loading for courses that opt in via CourseConfig.localSync.
+       *
+       * Safe to call multiple times — concurrent calls coalesce. Returns when
+       * sync is complete (or immediately if already synced / disabled).
+       *
+       * @param courseId - The course to sync locally
+       * @param forceEnabled - Skip CourseConfig check and sync regardless.
+       *   Use when the caller already knows local sync is desired.
+       */
+      async ensureCourseSynced(courseId, forceEnabled) {
+        return CourseSyncService.getInstance().ensureSynced(courseId, forceEnabled);
       }
       getCoursesDB() {
         return new CoursesDB(this._courseIDs);
@@ -6787,6 +7481,10 @@ var init_courseDB2 = __esm({
         }
         return tagsByCard;
       }
+      async getAllCardIds() {
+        const tagsIndex = await this.unpacker.getTagsIndex();
+        return Object.keys(tagsIndex.byCard);
+      }
       async addTagToCard(_cardId, _tagId) {
         throw new Error("Cannot modify tags in static mode");
       }
@@ -8337,8 +9035,10 @@ function newQuestionInterval(user, cardHistory) {
   const lastInterval = lastSuccessfulInterval(records);
   if (lastInterval > cardHistory.bestInterval) {
     cardHistory.bestInterval = lastInterval;
-    void user.update(cardHistory._id, {
+    user.update(cardHistory._id, {
       bestInterval: lastInterval
+    }).catch((e) => {
+      logger.warn(`[SpacedRepetition] Failed to update bestInterval for ${cardHistory._id}: ${e?.message ?? e}`);
     });
   }
   if (currentAttempt.isCorrect) {
@@ -9004,6 +9704,46 @@ var ItemQueue = class {
       return null;
     }
   }
+  /**
+   * Atomically replace all queue contents with new items.
+   *
+   * Used by mid-session replanning to swap the queue without a window where
+   * it's empty (avoiding dead-air if nextCard() is called concurrently).
+   *
+   * Preserves dequeueCount (cumulative across the session).
+   * Resets seenCardIds to match the new contents — cards from the old queue
+   * that don't appear in the new set can be re-added in future replans.
+   */
+  replaceAll(items, cardIdExtractor) {
+    this.q = [];
+    this.seenCardIds = [];
+    for (const item of items) {
+      const cardId = cardIdExtractor(item);
+      if (!this.seenCardIds.includes(cardId)) {
+        this.seenCardIds.push(cardId);
+        this.q.push(item);
+      }
+    }
+  }
+  /**
+   * Merge new items into the front of the queue, skipping duplicates.
+   * Used by additive replans to inject high-quality candidates without
+   * discarding the existing queue contents.
+   */
+  mergeToFront(items, cardIdExtractor) {
+    let added = 0;
+    const toInsert = [];
+    for (const item of items) {
+      const cardId = cardIdExtractor(item);
+      if (!this.seenCardIds.includes(cardId)) {
+        this.seenCardIds.push(cardId);
+        toInsert.push(item);
+        added++;
+      }
+    }
+    this.q.unshift(...toInsert);
+    return added;
+  }
   get toString() {
     return `${typeof this.q[0]}:
 ` + this.q.map((i) => `	${i.courseID}+${i.cardID}: ${i.status}`).join("\n");
@@ -11087,7 +11827,7 @@ mountSessionDebugger();
 
 // src/study/SessionController.ts
 init_logger();
-var SessionController = class extends Loggable {
+var SessionController = class _SessionController extends Loggable {
   _className = "SessionController";
   services;
   srsService;
@@ -11108,6 +11848,18 @@ var SessionController = class extends Loggable {
   newQ = new ItemQueue();
   failedQ = new ItemQueue();
   // END   Session card stores
+  /**
+   * Promise tracking a currently in-progress replan, or null if idle.
+   * Used by nextCard() to await completion before drawing from queues.
+   */
+  _replanPromise = null;
+  /**
+   * Number of well-indicated new cards remaining before the queue
+   * degrades to poorly-indicated content. Decremented on each newQ
+   * draw; when it hits 0, a replan is triggered automatically
+   * (user state has changed from completing good cards).
+   */
+  _wellIndicatedRemaining = 0;
   startTime;
   endTime;
   _secondsRemaining;
@@ -11201,13 +11953,83 @@ var SessionController = class extends Loggable {
         "[SessionController] All content sources must implement getWeightedCards()."
       );
     }
-    await this.getWeightedContent();
+    const wellIndicated = await this.getWeightedContent();
+    this._wellIndicatedRemaining = wellIndicated;
+    if (wellIndicated >= 0 && wellIndicated < _SessionController.MIN_WELL_INDICATED) {
+      this.log(
+        `[Init] Only ${wellIndicated}/${_SessionController.MIN_WELL_INDICATED} well-indicated cards in initial load`
+      );
+    }
     await this.hydrationService.ensureHydratedCards();
     startSessionTracking(this.reviewQ.length, this.newQ.length, this.failedQ.length);
     this._intervalHandle = setInterval(() => {
       this.tick();
     }, 1e3);
   }
+  /**
+   * Request a mid-session replan. Re-runs the pipeline with current user state
+   * and atomically replaces the newQ contents. Safe to call at any time during
+   * a session — if called while a replan is already in progress, returns the
+   * existing replan promise (no duplicate work).
+   *
+   * Does NOT affect reviewQ or failedQ.
+   *
+   * If nextCard() is called while a replan is in flight, it will automatically
+   * await the replan before drawing from queues, ensuring the user always sees
+   * cards scored against their latest state.
+   *
+   * Typical trigger: application-level code (e.g. after a GPC intro completion)
+   * calls this to ensure newly-unlocked content appears in the session.
+   */
+  async requestReplan(hints) {
+    if (this._replanPromise) {
+      this.log("Replan already in progress, awaiting existing replan");
+      return this._replanPromise;
+    }
+    if (hints) {
+      for (const source of this.sources) {
+        this.log(`[Hints] source type=${source.constructor.name}, hasMethod=${typeof source.setEphemeralHints}`);
+        source.setEphemeralHints?.(hints);
+      }
+    }
+    this.log(`Mid-session replan requested${hints ? ` (hints: ${JSON.stringify(hints)})` : ""}`);
+    this._replanPromise = this._executeReplan();
+    try {
+      await this._replanPromise;
+    } finally {
+      this._replanPromise = null;
+    }
+  }
+  /** Minimum well-indicated cards before an additive retry is attempted */
+  static MIN_WELL_INDICATED = 5;
+  /**
+   * Score threshold for considering a card "well-indicated."
+   * Cards below this score are treated as fallback filler — present only
+   * because no strategy hard-removed them, but likely penalized by one
+   * or more filters. Strategy-agnostic: the SessionController doesn't
+   * know or care which strategy assigned the score.
+   */
+  static WELL_INDICATED_SCORE = 0.1;
+  /**
+   * Internal replan execution. Runs the pipeline, builds a new newQ,
+   * atomically swaps it in, and triggers hydration for the new contents.
+   *
+   * If the initial replan produces fewer than MIN_WELL_INDICATED cards that
+   * pass all hierarchy filters, one additive retry is attempted — merging
+   * any new high-quality candidates into the front of the queue.
+   */
+  async _executeReplan() {
+    const wellIndicated = await this.getWeightedContent({ replan: true });
+    this._wellIndicatedRemaining = wellIndicated;
+    if (wellIndicated >= 0 && wellIndicated < _SessionController.MIN_WELL_INDICATED) {
+      this.log(
+        `[Replan] Only ${wellIndicated}/${_SessionController.MIN_WELL_INDICATED} well-indicated cards after replan`
+      );
+    }
+    await this.hydrationService.ensureHydratedCards();
+    this.log(`Replan complete: newQ now has ${this.newQ.length} cards`);
+    snapshotQueues(this.reviewQ.length, this.newQ.length, this.failedQ.length);
+  }
   addTime(seconds) {
     this.endTime = new Date(this.endTime.valueOf() + 1e3 * seconds);
   }
@@ -11263,6 +12085,9 @@ var SessionController = class extends Loggable {
       hydratedCache: {
         count: this.hydrationService.hydratedCount,
         cardIds: this.hydrationService.getHydratedCardIds()
+      },
+      replan: {
+        inProgress: this._replanPromise !== null
       }
     };
   }
@@ -11275,7 +12100,20 @@ var SessionController = class extends Loggable {
    * 3. Uses SourceMixer to balance content across sources
    * 4. Populates review and new card queues with mixed results
    */
-  async getWeightedContent() {
+  /**
+   * Fetch weighted content from all sources and populate session queues.
+   *
+   * @param options.replan - If true, this is a mid-session replan rather than
+   *   initial session setup. Skips review queue population (avoiding duplicates),
+   *   atomically replaces newQ contents, and treats empty results as non-fatal.
+   * @param options.additive - If true (replan only), merge new high-quality
+   *   candidates into the front of the existing newQ instead of replacing it.
+   * @returns Number of "well-indicated" cards (passed all hierarchy filters)
+   *   in the new content. Returns -1 if no content was loaded.
+   */
+  async getWeightedContent(options) {
+    const replan = options?.replan ?? false;
+    const additive = options?.additive ?? false;
     const limit = 20;
     const batches = [];
     for (let i = 0; i < this.sources.length; i++) {
@@ -11294,6 +12132,10 @@ var SessionController = class extends Loggable {
       }
     }
     if (batches.length === 0) {
+      if (replan) {
+        this.log("Replan: no content from any source, keeping existing newQ");
+        return -1;
+      }
       throw new Error(
         `Cannot start session: failed to load content from all ${this.sources.length} source(s). Check logs for details.`
       );
@@ -11305,10 +12147,12 @@ var SessionController = class extends Loggable {
     });
     await Promise.all(
       sourceIds.map(async (id) => {
-        try {
-          const config = await this.dataLayer.getCoursesDB().getCourseConfig(id);
-          this.courseNameCache.set(id, config.name);
-        } catch {
+        if (!this.courseNameCache.has(id)) {
+          try {
+            const config = await this.dataLayer.getCoursesDB().getCourseConfig(id);
+            this.courseNameCache.set(id, config.name);
+          } catch {
+          }
         }
       })
     );
@@ -11326,20 +12170,26 @@ var SessionController = class extends Loggable {
     const reviewWeighted = mixedWeighted.filter((w) => getCardOrigin(w) === "review");
     const newWeighted = mixedWeighted.filter((w) => getCardOrigin(w) === "new");
     logger.debug(`[reviews] got ${reviewWeighted.length} reviews from mixer`);
-    let report = "Mixed content session created with:\n";
-    for (const w of reviewWeighted) {
-      const reviewItem = {
-        cardID: w.cardId,
-        courseID: w.courseId,
-        contentSourceType: "course",
-        contentSourceID: w.courseId,
-        reviewID: w.reviewID,
-        status: "review"
-      };
-      this.reviewQ.add(reviewItem, reviewItem.cardID);
-      report += `Review: ${w.courseId}::${w.cardId} (score: ${w.score.toFixed(2)})
+    let report = replan ? "Replan content:\n" : "Mixed content session created with:\n";
+    if (!replan) {
+      for (const w of reviewWeighted) {
+        const reviewItem = {
+          cardID: w.cardId,
+          courseID: w.courseId,
+          contentSourceType: "course",
+          contentSourceID: w.courseId,
+          reviewID: w.reviewID,
+          status: "review"
+        };
+        this.reviewQ.add(reviewItem, reviewItem.cardID);
+        report += `Review: ${w.courseId}::${w.cardId} (score: ${w.score.toFixed(2)})
 `;
+      }
     }
+    const wellIndicated = newWeighted.filter(
+      (w) => w.score >= _SessionController.WELL_INDICATED_SCORE
+    ).length;
+    const newItems = [];
     for (const w of newWeighted) {
       const newItem = {
         cardID: w.cardId,
@@ -11348,11 +12198,23 @@ var SessionController = class extends Loggable {
         contentSourceID: w.courseId,
         status: "new"
       };
-      this.newQ.add(newItem, newItem.cardID);
+      newItems.push(newItem);
       report += `New: ${w.courseId}::${w.cardId} (score: ${w.score.toFixed(2)})
 `;
     }
+    if (additive) {
+      const added = this.newQ.mergeToFront(newItems, (item) => item.cardID);
+      report += `Additive merge: ${added} new cards added to front of newQ
+`;
+    } else if (replan) {
+      this.newQ.replaceAll(newItems, (item) => item.cardID);
+    } else {
+      for (const item of newItems) {
+        this.newQ.add(item, item.cardID);
+      }
+    }
     this.log(report);
+    return wellIndicated;
   }
   /**
    * Returns items that should be pre-hydrated.
@@ -11429,6 +12291,17 @@ var SessionController = class extends Loggable {
   }
   async nextCard(action = "dismiss-success") {
     this.dismissCurrentCard(action);
+    if (this._replanPromise) {
+      this.log("nextCard: awaiting in-flight replan before drawing");
+      await this._replanPromise;
+    }
+    const REPLAN_BUFFER = 3;
+    if (this._wellIndicatedRemaining <= REPLAN_BUFFER && this.newQ.length > 0 && !this._replanPromise) {
+      this.log(
+        `[AutoReplan] ${this._wellIndicatedRemaining} well-indicated cards remaining (newQ: ${this.newQ.length}). Triggering background replan.`
+      );
+      void this.requestReplan();
+    }
     if (this._secondsRemaining <= 0 && this.failedQ.length === 0) {
       this._currentCard = null;
       endSessionTracking();
@@ -11542,6 +12415,9 @@ var SessionController = class extends Loggable {
       this.reviewQ.dequeue((queueItem) => queueItem.cardID);
     } else if (this.newQ.peek(0)?.cardID === item.cardID) {
       this.newQ.dequeue((queueItem) => queueItem.cardID);
+      if (this._wellIndicatedRemaining > 0) {
+        this._wellIndicatedRemaining--;
+      }
     } else if (this.failedQ.peek(0)?.cardID === item.cardID) {
       this.failedQ.dequeue((queueItem) => queueItem.cardID);
     }