@vue-skuilder/db 0.1.18 → 0.1.20

package/dist/core/index.mjs

@@ -100,6 +100,7 @@ var init_types_legacy = __esm({
       DocType2["SCHEDULED_CARD"] = "SCHEDULED_CARD";
       DocType2["TAG"] = "TAG";
       DocType2["NAVIGATION_STRATEGY"] = "NAVIGATION_STRATEGY";
+      DocType2["STRATEGY_STATE"] = "STRATEGY_STATE";
       return DocType2;
     })(DocType || {});
     DocTypePrefixes = {
@@ -113,7 +114,8 @@ var init_types_legacy = __esm({
       ["QUESTION" /* QUESTIONTYPE */]: "QUESTION",
       ["VIEW" /* VIEW */]: "VIEW",
       ["PEDAGOGY" /* PEDAGOGY */]: "PEDAGOGY",
-      ["NAVIGATION_STRATEGY" /* NAVIGATION_STRATEGY */]: "NAVIGATION_STRATEGY"
+      ["NAVIGATION_STRATEGY" /* NAVIGATION_STRATEGY */]: "NAVIGATION_STRATEGY",
+      ["STRATEGY_STATE" /* STRATEGY_STATE */]: "STRATEGY_STATE"
     };
   }
 });
@@ -876,6 +878,41 @@ __export(Pipeline_exports, {
   Pipeline: () => Pipeline
 });
 import { toCourseElo as toCourseElo2 } from "@vue-skuilder/common";
+function logPipelineConfig(generator, filters) {
+  const filterList = filters.length > 0 ? "\n    - " + filters.map((f) => f.name).join("\n    - ") : " none";
+  logger.info(
+    `[Pipeline] Configuration:
+  Generator: ${generator.name}
+  Filters:${filterList}`
+  );
+}
+function logTagHydration(cards, tagsByCard) {
+  const totalTags = Array.from(tagsByCard.values()).reduce((sum, tags) => sum + tags.length, 0);
+  const cardsWithTags = Array.from(tagsByCard.values()).filter((tags) => tags.length > 0).length;
+  logger.debug(
+    `[Pipeline] Tag hydration: ${cards.length} cards, ${cardsWithTags} have tags (${totalTags} total tags) - single batch query`
+  );
+}
+function logExecutionSummary(generatorName, generatedCount, filterCount, finalCount, topScores) {
+  const scoreDisplay = topScores.length > 0 ? topScores.map((s) => s.toFixed(2)).join(", ") : "none";
+  logger.info(
+    `[Pipeline] Execution: ${generatorName} produced ${generatedCount} \u2192 ${filterCount} filters \u2192 ${finalCount} results (top scores: ${scoreDisplay})`
+  );
+}
+function logCardProvenance(cards, maxCards = 3) {
+  const cardsToLog = cards.slice(0, maxCards);
+  logger.debug(`[Pipeline] Provenance for top ${cardsToLog.length} cards:`);
+  for (const card of cardsToLog) {
+    logger.debug(`[Pipeline]   ${card.cardId} (final score: ${card.score.toFixed(3)}):`);
+    for (const entry of card.provenance) {
+      const scoreChange = entry.score.toFixed(3);
+      const action = entry.action.padEnd(9);
+      logger.debug(
+        `[Pipeline]     ${action} ${scoreChange} - ${entry.strategyName}: ${entry.reason}`
+      );
+    }
+  }
+}
 var Pipeline;
 var init_Pipeline = __esm({
   "src/core/navigators/Pipeline.ts"() {
@@ -899,19 +936,18 @@ var init_Pipeline = __esm({
         this.filters = filters;
         this.user = user;
         this.course = course;
-        logger.debug(
-          `[Pipeline] Created with generator '${generator.name}' and ${filters.length} filters: ${filters.map((f) => f.name).join(", ")}`
-        );
+        logPipelineConfig(generator, filters);
       }
       /**
        * Get weighted cards by running generator and applying filters.
        *
        * 1. Build shared context (user ELO, etc.)
        * 2. Get candidates from generator (passing context)
-       * 3. Apply each filter sequentially
-       * 4. Remove zero-score cards
-       * 5. Sort by score descending
-       * 6. Return top N
+       * 3. Batch hydrate tags for all candidates
+       * 4. Apply each filter sequentially
+       * 5. Remove zero-score cards
+       * 6. Sort by score descending
+       * 7. Return top N
        *
        * @param limit - Maximum number of cards to return
        * @returns Cards sorted by score descending
@@ -924,7 +960,9 @@ var init_Pipeline = __esm({
           `[Pipeline] Fetching ${fetchLimit} candidates from generator '${this.generator.name}'`
         );
         let cards = await this.generator.getWeightedCards(fetchLimit, context);
-        logger.debug(`[Pipeline] Generator returned ${cards.length} candidates`);
+        const generatedCount = cards.length;
+        logger.debug(`[Pipeline] Generator returned ${generatedCount} candidates`);
+        cards = await this.hydrateTags(cards);
         for (const filter of this.filters) {
           const beforeCount = cards.length;
           cards = await filter.transform(cards, context);
@@ -933,11 +971,33 @@ var init_Pipeline = __esm({
         cards = cards.filter((c) => c.score > 0);
         cards.sort((a, b) => b.score - a.score);
         const result = cards.slice(0, limit);
-        logger.debug(
-          `[Pipeline] Returning ${result.length} cards (top scores: ${result.slice(0, 3).map((c) => c.score.toFixed(2)).join(", ")}...)`
-        );
+        const topScores = result.slice(0, 3).map((c) => c.score);
+        logExecutionSummary(this.generator.name, generatedCount, this.filters.length, result.length, topScores);
+        logCardProvenance(result, 3);
         return result;
       }
+      /**
+       * Batch hydrate tags for all cards.
+       *
+       * Fetches tags for all cards in a single database query and attaches them
+       * to the WeightedCard objects. Filters can then use card.tags instead of
+       * making individual getAppliedTags() calls.
+       *
+       * @param cards - Cards to hydrate
+       * @returns Cards with tags populated
+       */
+      async hydrateTags(cards) {
+        if (cards.length === 0) {
+          return cards;
+        }
+        const cardIds = cards.map((c) => c.cardId);
+        const tagsByCard = await this.course.getAppliedTagsBatch(cardIds);
+        logTagHydration(cards, tagsByCard);
+        return cards.map((card) => ({
+          ...card,
+          tags: tagsByCard.get(card.cardId) ?? []
+        }));
+      }
       /**
        * Build shared context for generator and filters.
        *
@@ -1297,15 +1357,144 @@ var init_eloDistance = __esm({
   }
 });
 
+// src/core/navigators/filters/userTagPreference.ts
+var userTagPreference_exports = {};
+__export(userTagPreference_exports, {
+  default: () => UserTagPreferenceFilter
+});
+var UserTagPreferenceFilter;
+var init_userTagPreference = __esm({
+  "src/core/navigators/filters/userTagPreference.ts"() {
+    "use strict";
+    init_navigators();
+    UserTagPreferenceFilter = class extends ContentNavigator {
+      _strategyData;
+      /** Human-readable name for CardFilter interface */
+      name;
+      constructor(user, course, strategyData) {
+        super(user, course, strategyData);
+        this._strategyData = strategyData;
+        this.name = strategyData.name || "User Tag Preferences";
+      }
+      /**
+       * Compute multiplier for a card based on its tags and user preferences.
+       * Returns the maximum multiplier among all matching tags, or 1.0 if no matches.
+       */
+      computeMultiplier(cardTags, boostMap) {
+        const multipliers = cardTags.map((tag) => boostMap[tag]).filter((val) => val !== void 0);
+        if (multipliers.length === 0) {
+          return 1;
+        }
+        return Math.max(...multipliers);
+      }
+      /**
+       * Build human-readable reason for the filter's decision.
+       */
+      buildReason(cardTags, boostMap, multiplier) {
+        const matchingTags = cardTags.filter((tag) => boostMap[tag] === multiplier);
+        if (multiplier === 0) {
+          return `Excluded by user preference: ${matchingTags.join(", ")} (${multiplier}x)`;
+        }
+        if (multiplier < 1) {
+          return `Penalized by user preference: ${matchingTags.join(", ")} (${multiplier.toFixed(2)}x)`;
+        }
+        if (multiplier > 1) {
+          return `Boosted by user preference: ${matchingTags.join(", ")} (${multiplier.toFixed(2)}x)`;
+        }
+        return "No matching user preferences";
+      }
+      /**
+       * CardFilter.transform implementation.
+       *
+       * Apply user tag preferences:
+       * 1. Read preferences from strategy state
+       * 2. If no preferences, pass through unchanged
+       * 3. For each card:
+       *    - Look up tag in boost record
+       *    - If tag found: apply multiplier (0 = exclude, 1 = neutral, >1 = boost)
+       *    - If multiple tags match: use max multiplier
+       *    - Append provenance with clear reason
+       */
+      async transform(cards, _context) {
+        const prefs = await this.getStrategyState();
+        if (!prefs || Object.keys(prefs.boost).length === 0) {
+          return cards.map((card) => ({
+            ...card,
+            provenance: [
+              ...card.provenance,
+              {
+                strategy: "userTagPreference",
+                strategyName: this.strategyName || this.name,
+                strategyId: this.strategyId || this._strategyData._id,
+                action: "passed",
+                score: card.score,
+                reason: "No user tag preferences configured"
+              }
+            ]
+          }));
+        }
+        const adjusted = await Promise.all(
+          cards.map(async (card) => {
+            const cardTags = card.tags ?? [];
+            const multiplier = this.computeMultiplier(cardTags, prefs.boost);
+            const finalScore = Math.min(1, card.score * multiplier);
+            let action;
+            if (multiplier === 0 || multiplier < 1) {
+              action = "penalized";
+            } else if (multiplier > 1) {
+              action = "boosted";
+            } else {
+              action = "passed";
+            }
+            return {
+              ...card,
+              score: finalScore,
+              provenance: [
+                ...card.provenance,
+                {
+                  strategy: "userTagPreference",
+                  strategyName: this.strategyName || this.name,
+                  strategyId: this.strategyId || this._strategyData._id,
+                  action,
+                  score: finalScore,
+                  reason: this.buildReason(cardTags, prefs.boost, multiplier)
+                }
+              ]
+            };
+          })
+        );
+        return adjusted;
+      }
+      /**
+       * Legacy getWeightedCards - throws as filters should not be used as generators.
+       */
+      async getWeightedCards(_limit) {
+        throw new Error(
+          "UserTagPreferenceFilter is a filter and should not be used as a generator. Use Pipeline with a generator and this filter via transform()."
+        );
+      }
+      // Legacy methods - stub implementations since filters don't generate cards
+      async getNewCards(_n) {
+        return [];
+      }
+      async getPendingReviews() {
+        return [];
+      }
+    };
+  }
+});
+
 // src/core/navigators/filters/index.ts
 var filters_exports = {};
 __export(filters_exports, {
+  UserTagPreferenceFilter: () => UserTagPreferenceFilter,
   createEloDistanceFilter: () => createEloDistanceFilter
 });
 var init_filters = __esm({
   "src/core/navigators/filters/index.ts"() {
     "use strict";
     init_eloDistance();
+    init_userTagPreference();
   }
 });
 
@@ -1538,10 +1727,9 @@ var init_hierarchyDefinition = __esm({
       /**
        * Check if a card is unlocked and generate reason.
        */
-      async checkCardUnlock(cardId, course, unlockedTags, masteredTags) {
+      async checkCardUnlock(card, course, unlockedTags, masteredTags) {
         try {
-          const tagResponse = await course.getAppliedTags(cardId);
-          const cardTags = tagResponse.rows.map((row) => row.value?.name || row.key);
+          const cardTags = card.tags ?? [];
           const lockedTags = cardTags.filter(
             (tag) => this.hasPrerequisites(tag) && !unlockedTags.has(tag)
           );
@@ -1578,7 +1766,7 @@ var init_hierarchyDefinition = __esm({
         const gated = [];
         for (const card of cards) {
           const { isUnlocked, reason } = await this.checkCardUnlock(
-            card.cardId,
+            card,
             context.course,
             unlockedTags,
             masteredTags
@@ -1624,6 +1812,19 @@ var init_hierarchyDefinition = __esm({
   }
 });
 
+// src/core/navigators/inferredPreference.ts
+var inferredPreference_exports = {};
+__export(inferredPreference_exports, {
+  INFERRED_PREFERENCE_NAVIGATOR_STUB: () => INFERRED_PREFERENCE_NAVIGATOR_STUB
+});
+var INFERRED_PREFERENCE_NAVIGATOR_STUB;
+var init_inferredPreference = __esm({
+  "src/core/navigators/inferredPreference.ts"() {
+    "use strict";
+    INFERRED_PREFERENCE_NAVIGATOR_STUB = true;
+  }
+});
+
 // src/core/navigators/interferenceMitigator.ts
 var interferenceMitigator_exports = {};
 __export(interferenceMitigator_exports, {
@@ -1755,17 +1956,6 @@ var init_interferenceMitigator = __esm({
         }
         return avoid;
       }
-      /**
-       * Get tags for a single card
-       */
-      async getCardTags(cardId, course) {
-        try {
-          const tagResponse = await course.getAppliedTags(cardId);
-          return tagResponse.rows.map((row) => row.value?.name || row.key).filter(Boolean);
-        } catch {
-          return [];
-        }
-      }
       /**
        * Compute interference score reduction for a card.
        * Returns: { multiplier, interfering tags, reason }
@@ -1817,7 +2007,7 @@ var init_interferenceMitigator = __esm({
         const tagsToAvoid = this.getTagsToAvoid(immatureTags);
         const adjusted = [];
         for (const card of cards) {
-          const cardTags = await this.getCardTags(card.cardId, context.course);
+          const cardTags = card.tags ?? [];
           const { multiplier, reason } = this.computeInterferenceEffect(
             cardTags,
             tagsToAvoid,
@@ -1962,27 +2152,16 @@ var init_relativePriority = __esm({
           return `Low-priority tags: ${tagList}${more} (priority ${priority.toFixed(2)} \u2192 reduce ${boostFactor.toFixed(2)}x \u2192 ${finalScore.toFixed(2)})`;
         }
       }
-      /**
-       * Get tags for a single card.
-       */
-      async getCardTags(cardId, course) {
-        try {
-          const tagResponse = await course.getAppliedTags(cardId);
-          return tagResponse.rows.map((r) => r.doc?.name).filter((x) => !!x);
-        } catch {
-          return [];
-        }
-      }
       /**
        * CardFilter.transform implementation.
        *
        * Apply priority-adjusted scoring. Cards with high-priority tags get boosted,
        * cards with low-priority tags get reduced scores.
        */
-      async transform(cards, context) {
+      async transform(cards, _context) {
         const adjusted = await Promise.all(
           cards.map(async (card) => {
-            const cardTags = await this.getCardTags(card.cardId, context.course);
+            const cardTags = card.tags ?? [];
             const priority = this.computeCardPriority(cardTags);
             const boostFactor = this.computeBoostFactor(priority);
             const finalScore = Math.max(0, Math.min(1, card.score * boostFactor));
@@ -2149,6 +2328,19 @@ var init_srs = __esm({
   }
 });
 
+// src/core/navigators/userGoal.ts
+var userGoal_exports = {};
+__export(userGoal_exports, {
+  USER_GOAL_NAVIGATOR_STUB: () => USER_GOAL_NAVIGATOR_STUB
+});
+var USER_GOAL_NAVIGATOR_STUB;
+var init_userGoal = __esm({
+  "src/core/navigators/userGoal.ts"() {
+    "use strict";
+    USER_GOAL_NAVIGATOR_STUB = true;
+  }
+});
+
 // import("./**/*") in src/core/navigators/index.ts
 var globImport;
 var init_ = __esm({
@@ -2161,14 +2353,17 @@ var init_ = __esm({
       "./filters/eloDistance.ts": () => Promise.resolve().then(() => (init_eloDistance(), eloDistance_exports)),
       "./filters/index.ts": () => Promise.resolve().then(() => (init_filters(), filters_exports)),
       "./filters/types.ts": () => Promise.resolve().then(() => (init_types(), types_exports)),
+      "./filters/userTagPreference.ts": () => Promise.resolve().then(() => (init_userTagPreference(), userTagPreference_exports)),
       "./generators/index.ts": () => Promise.resolve().then(() => (init_generators(), generators_exports)),
       "./generators/types.ts": () => Promise.resolve().then(() => (init_types2(), types_exports2)),
       "./hardcodedOrder.ts": () => Promise.resolve().then(() => (init_hardcodedOrder(), hardcodedOrder_exports)),
       "./hierarchyDefinition.ts": () => Promise.resolve().then(() => (init_hierarchyDefinition(), hierarchyDefinition_exports)),
       "./index.ts": () => Promise.resolve().then(() => (init_navigators(), navigators_exports)),
+      "./inferredPreference.ts": () => Promise.resolve().then(() => (init_inferredPreference(), inferredPreference_exports)),
       "./interferenceMitigator.ts": () => Promise.resolve().then(() => (init_interferenceMitigator(), interferenceMitigator_exports)),
       "./relativePriority.ts": () => Promise.resolve().then(() => (init_relativePriority(), relativePriority_exports)),
-      "./srs.ts": () => Promise.resolve().then(() => (init_srs(), srs_exports))
+      "./srs.ts": () => Promise.resolve().then(() => (init_srs(), srs_exports)),
+      "./userGoal.ts": () => Promise.resolve().then(() => (init_userGoal(), userGoal_exports))
     });
   }
 });
@@ -2217,6 +2412,7 @@ var init_navigators = __esm({
       Navigators2["HIERARCHY"] = "hierarchyDefinition";
       Navigators2["INTERFERENCE"] = "interferenceMitigator";
       Navigators2["RELATIVE_PRIORITY"] = "relativePriority";
+      Navigators2["USER_TAG_PREFERENCE"] = "userTagPreference";
       return Navigators2;
     })(Navigators || {});
     NavigatorRole = /* @__PURE__ */ ((NavigatorRole2) => {
@@ -2230,7 +2426,8 @@ var init_navigators = __esm({
       ["hardcodedOrder" /* HARDCODED */]: "generator" /* GENERATOR */,
       ["hierarchyDefinition" /* HIERARCHY */]: "filter" /* FILTER */,
       ["interferenceMitigator" /* INTERFERENCE */]: "filter" /* FILTER */,
-      ["relativePriority" /* RELATIVE_PRIORITY */]: "filter" /* FILTER */
+      ["relativePriority" /* RELATIVE_PRIORITY */]: "filter" /* FILTER */,
+      ["userTagPreference" /* USER_TAG_PREFERENCE */]: "filter" /* FILTER */
     };
     ContentNavigator = class {
       /** User interface for this navigation session */
@@ -2255,6 +2452,52 @@ var init_navigators = __esm({
           this.strategyId = strategyData._id;
         }
       }
+      // ============================================================================
+      // STRATEGY STATE HELPERS
+      // ============================================================================
+      //
+      // These methods allow strategies to persist their own state (user preferences,
+      // learned patterns, temporal tracking) in the user database.
+      //
+      // ============================================================================
+      /**
+       * Unique key identifying this strategy for state storage.
+       *
+       * Defaults to the constructor name (e.g., "UserTagPreferenceFilter").
+       * Override in subclasses if multiple instances of the same strategy type
+       * need separate state storage.
+       */
+      get strategyKey() {
+        return this.constructor.name;
+      }
+      /**
+       * Get this strategy's persisted state for the current course.
+       *
+       * @returns The strategy's data payload, or null if no state exists
+       * @throws Error if user or course is not initialized
+       */
+      async getStrategyState() {
+        if (!this.user || !this.course) {
+          throw new Error(
+            `Cannot get strategy state: navigator not properly initialized. Ensure user and course are provided to constructor.`
+          );
+        }
+        return this.user.getStrategyState(this.course.getCourseID(), this.strategyKey);
+      }
+      /**
+       * Persist this strategy's state for the current course.
+       *
+       * @param data - The strategy's data payload to store
+       * @throws Error if user or course is not initialized
+       */
+      async putStrategyState(data) {
+        if (!this.user || !this.course) {
+          throw new Error(
+            `Cannot put strategy state: navigator not properly initialized. Ensure user and course are provided to constructor.`
+          );
+        }
+        return this.user.putStrategyState(this.course.getCourseID(), this.strategyKey, data);
+      }
       /**
        * Factory method to create navigator instances dynamically.
        *
@@ -2584,15 +2827,6 @@ var init_courseDB = __esm({
             ret[r.id] = r.doc.id_displayable_data;
           }
         });
-        await Promise.all(
-          cards.rows.map((r) => {
-            return async () => {
-              if (isSuccessRow(r)) {
-                ret[r.id] = r.doc.id_displayable_data;
-              }
-            };
-          })
-        );
         return ret;
       }
       async getCardsByELO(elo, cardLimit) {
@@ -2677,6 +2911,28 @@ ${above.rows.map((r) => `	${r.id}-${r.key}
           throw new Error(`Failed to find tags for card ${this.id}-${cardId}`);
         }
       }
+      async getAppliedTagsBatch(cardIds) {
+        if (cardIds.length === 0) {
+          return /* @__PURE__ */ new Map();
+        }
+        const db = getCourseDB2(this.id);
+        const result = await db.query("getTags", {
+          keys: cardIds,
+          include_docs: false
+        });
+        const tagsByCard = /* @__PURE__ */ new Map();
+        for (const cardId of cardIds) {
+          tagsByCard.set(cardId, []);
+        }
+        for (const row of result.rows) {
+          const cardId = row.key;
+          const tagName = row.value?.name;
+          if (tagName && tagsByCard.has(cardId)) {
+            tagsByCard.get(cardId).push(tagName);
+          }
+        }
+        return tagsByCard;
+      }
       async addTagToCard(cardId, tagId, updateELO) {
         return await addTagToCard(
           this.id,
@@ -4263,6 +4519,55 @@ Currently logged-in as ${this._username}.`
       async updateUserElo(courseId, elo) {
         return updateUserElo(this._username, courseId, elo);
       }
+      async getStrategyState(courseId, strategyKey) {
+        const docId = buildStrategyStateId(courseId, strategyKey);
+        try {
+          const doc = await this.localDB.get(docId);
+          return doc.data;
+        } catch (e) {
+          const err = e;
+          if (err.status === 404) {
+            return null;
+          }
+          throw e;
+        }
+      }
+      async putStrategyState(courseId, strategyKey, data) {
+        const docId = buildStrategyStateId(courseId, strategyKey);
+        let existingRev;
+        try {
+          const existing = await this.localDB.get(docId);
+          existingRev = existing._rev;
+        } catch (e) {
+          const err = e;
+          if (err.status !== 404) {
+            throw e;
+          }
+        }
+        const doc = {
+          _id: docId,
+          _rev: existingRev,
+          docType: "STRATEGY_STATE" /* STRATEGY_STATE */,
+          courseId,
+          strategyKey,
+          data,
+          updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+        };
+        await this.localDB.put(doc);
+      }
+      async deleteStrategyState(courseId, strategyKey) {
+        const docId = buildStrategyStateId(courseId, strategyKey);
+        try {
+          const doc = await this.localDB.get(docId);
+          await this.localDB.remove(doc);
+        } catch (e) {
+          const err = e;
+          if (err.status === 404) {
+            return;
+          }
+          throw e;
+        }
+      }
     };
     userCoursesDoc = "CourseRegistrations";
     userClassroomsDoc = "ClassroomRegistrations";
@@ -4575,6 +4880,16 @@ var init_user = __esm({
   }
 });
 
+// src/core/types/strategyState.ts
+function buildStrategyStateId(courseId, strategyKey) {
+  return `STRATEGY_STATE::${courseId}::${strategyKey}`;
+}
+var init_strategyState = __esm({
+  "src/core/types/strategyState.ts"() {
+    "use strict";
+  }
+});
+
 // src/core/bulkImport/cardProcessor.ts
 import { Status as Status4 } from "@vue-skuilder/common";
 async function importParsedCards(parsedCards, courseDB, config) {
@@ -4717,6 +5032,7 @@ var init_core = __esm({
     init_interfaces();
     init_types_legacy();
     init_user();
+    init_strategyState();
     init_Loggable();
     init_util();
     init_navigators();
@@ -4734,6 +5050,7 @@ export {
   NavigatorRoles,
   Navigators,
   areQuestionRecords,
+  buildStrategyStateId,
   docIsDeleted,
   getCardHistoryID,
   getCardOrigin,