@vue-skuilder/db 0.1.31-b → 0.1.31

package/dist/impl/couch/index.mjs

@@ -627,8 +627,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";
@@ -656,6 +660,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;
@@ -711,12 +716,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 = {
@@ -918,6 +924,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.
        */
@@ -930,6 +951,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
@@ -941,7 +963,7 @@ Commands:
 Example:
   window.skuilder.pipeline.showLastRun()
   window.skuilder.pipeline.showRun(1)
-  window.skuilder.pipeline.showCard('abc123')
+  await window.skuilder.pipeline.diagnoseCardSpace()
 `);
       }
     };
@@ -1236,6 +1258,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, {
@@ -1430,6 +1515,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))
     });
@@ -1630,6 +1716,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;
         }
@@ -1705,14 +1793,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(
@@ -1721,9 +1833,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,
@@ -1735,7 +1865,7 @@ var init_hierarchyDefinition = __esm({
                 strategyId: this.strategyId || "NAVIGATION_STRATEGY-hierarchy",
                 action,
                 score: finalScore,
-                reason
+                reason: finalReason
               }
             ]
           });
@@ -2424,6 +2554,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(
@@ -2458,6 +2600,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:`);
@@ -2472,7 +2629,7 @@ function logCardProvenance(cards, maxCards = 3) {
     }
   }
 }
-var Pipeline;
+var VERBOSE_RESULTS, Pipeline;
 var init_Pipeline = __esm({
   "src/core/navigators/Pipeline.ts"() {
     "use strict";
@@ -2480,9 +2637,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.
        *
@@ -2503,6 +2682,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.
@@ -2519,13 +2709,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) {
@@ -2554,6 +2746,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) {
@@ -2572,8 +2765,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,
@@ -2583,6 +2785,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);
@@ -2609,6 +2812,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
        */
@@ -2616,14 +2823,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.
        *
@@ -2641,7 +2962,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,
@@ -2685,6 +3009,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;
+      }
     };
   }
 });
@@ -2789,23 +3194,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) {
@@ -2883,6 +3290,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))
@@ -2931,8 +3339,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,
@@ -2987,6 +3397,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";
@@ -3001,6 +3412,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 */,
@@ -3165,6 +3577,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) {
+      }
     };
   }
 });
@@ -3356,15 +3774,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;
@@ -3452,7 +3897,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`);
         }
@@ -3473,7 +3918,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(", "));
@@ -3575,8 +4020,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
         });
@@ -3593,6 +4037,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,
@@ -3659,10 +4111,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
@@ -3696,7 +4151,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) {
@@ -5287,6 +5742,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;
@@ -6164,6 +6622,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 fetch from "cross-fetch";
 async function getCurrentSession() {
@@ -6606,6 +7292,7 @@ var init_couch = __esm({
     init_classroomDB2();
     init_courseAPI();
     init_courseDB();
+    init_CourseSyncService();
     init_CouchDBSyncStrategy();
     isBrowser = typeof window !== "undefined";
     if (isBrowser) {
@@ -6630,6 +7317,7 @@ export {
   ClassroomLookupDB,
   CouchDBSyncStrategy,
   CourseDB,
+  CourseSyncService,
   CoursesDB,
   REVIEW_TIME_FORMAT,
   StudentClassroomDB,