@vue-skuilder/db 0.1.22 → 0.1.24

package/dist/impl/static/index.mjs

@@ -1,7 +1,17 @@
+var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __glob = (map) => (path2) => {
+  var fn = map[path2];
+  if (fn) return fn();
+  throw new Error("Module not found in bundle: " + path2);
+};
 var __esm = (fn, res) => function __init() {
   return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
 };
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
 
 // src/util/logger.ts
 var isDevelopment, logger;
@@ -88,7 +98,9 @@ var init_types_legacy = __esm({
       ["VIEW" /* VIEW */]: "VIEW",
       ["PEDAGOGY" /* PEDAGOGY */]: "PEDAGOGY",
       ["NAVIGATION_STRATEGY" /* NAVIGATION_STRATEGY */]: "NAVIGATION_STRATEGY",
-      ["STRATEGY_STATE" /* STRATEGY_STATE */]: "STRATEGY_STATE"
+      ["STRATEGY_STATE" /* STRATEGY_STATE */]: "STRATEGY_STATE",
+      ["USER_OUTCOME" /* USER_OUTCOME */]: "USER_OUTCOME",
+      ["STRATEGY_LEARNING_STATE" /* STRATEGY_LEARNING_STATE */]: "STRATEGY_LEARNING_STATE"
     };
   }
 });
@@ -461,173 +473,1382 @@ var init_courseLookupDB = __esm({
   }
 });
 
-// src/core/navigators/index.ts
-function isGenerator(impl) {
-  return NavigatorRoles[impl] === "generator" /* GENERATOR */;
-}
-function isFilter(impl) {
-  return NavigatorRoles[impl] === "filter" /* FILTER */;
-}
-var NavigatorRoles, ContentNavigator;
-var init_navigators = __esm({
-  "src/core/navigators/index.ts"() {
+// src/core/navigators/generators/CompositeGenerator.ts
+var CompositeGenerator_exports = {};
+__export(CompositeGenerator_exports, {
+  AggregationMode: () => AggregationMode,
+  default: () => CompositeGenerator
+});
+var AggregationMode, DEFAULT_AGGREGATION_MODE, FREQUENCY_BOOST_FACTOR, CompositeGenerator;
+var init_CompositeGenerator = __esm({
+  "src/core/navigators/generators/CompositeGenerator.ts"() {
     "use strict";
+    init_navigators();
     init_logger();
-    NavigatorRoles = {
-      ["elo" /* ELO */]: "generator" /* GENERATOR */,
-      ["srs" /* SRS */]: "generator" /* GENERATOR */,
-      ["hierarchyDefinition" /* HIERARCHY */]: "filter" /* FILTER */,
-      ["interferenceMitigator" /* INTERFERENCE */]: "filter" /* FILTER */,
-      ["relativePriority" /* RELATIVE_PRIORITY */]: "filter" /* FILTER */,
-      ["userTagPreference" /* USER_TAG_PREFERENCE */]: "filter" /* FILTER */
-    };
-    ContentNavigator = class {
-      /** User interface for this navigation session */
-      user;
-      /** Course interface for this navigation session */
-      course;
-      /** Human-readable name for this strategy instance (from ContentNavigationStrategyData.name) */
-      strategyName;
-      /** Unique document ID for this strategy instance (from ContentNavigationStrategyData._id) */
-      strategyId;
-      /**
-       * Constructor for standard navigators.
-       * Call this from subclass constructors to initialize common fields.
-       *
-       * Note: CompositeGenerator and Pipeline call super() without args, then set
-       * user/course fields directly if needed.
-       */
-      constructor(user, course, strategyData) {
-        this.user = user;
-        this.course = course;
-        if (strategyData) {
-          this.strategyName = strategyData.name;
-          this.strategyId = strategyData._id;
+    AggregationMode = /* @__PURE__ */ ((AggregationMode2) => {
+      AggregationMode2["MAX"] = "max";
+      AggregationMode2["AVERAGE"] = "average";
+      AggregationMode2["FREQUENCY_BOOST"] = "frequencyBoost";
+      return AggregationMode2;
+    })(AggregationMode || {});
+    DEFAULT_AGGREGATION_MODE = "frequencyBoost" /* FREQUENCY_BOOST */;
+    FREQUENCY_BOOST_FACTOR = 0.1;
+    CompositeGenerator = class _CompositeGenerator extends ContentNavigator {
+      /** Human-readable name for CardGenerator interface */
+      name = "Composite Generator";
+      generators;
+      aggregationMode;
+      constructor(generators, aggregationMode = DEFAULT_AGGREGATION_MODE) {
+        super();
+        this.generators = generators;
+        this.aggregationMode = aggregationMode;
+        if (generators.length === 0) {
+          throw new Error("CompositeGenerator requires at least one generator");
         }
+        logger.debug(
+          `[CompositeGenerator] Created with ${generators.length} generators, mode: ${aggregationMode}`
+        );
       }
-      // ============================================================================
-      // 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.
+       * Creates a CompositeGenerator from strategy data.
        *
-       * Defaults to the constructor name (e.g., "UserTagPreferenceFilter").
-       * Override in subclasses if multiple instances of the same strategy type
-       * need separate state storage.
+       * This is a convenience factory for use by PipelineAssembler.
        */
-      get strategyKey() {
-        return this.constructor.name;
+      static async fromStrategies(user, course, strategies, aggregationMode = DEFAULT_AGGREGATION_MODE) {
+        const generators = await Promise.all(
+          strategies.map((s) => ContentNavigator.create(user, course, s))
+        );
+        return new _CompositeGenerator(generators, aggregationMode);
       }
       /**
-       * Get this strategy's persisted state for the current course.
+       * Get weighted cards from all generators, merge and deduplicate.
        *
-       * @returns The strategy's data payload, or null if no state exists
-       * @throws Error if user or course is not initialized
+       * Cards appearing in multiple generators receive a score boost.
+       * Provenance tracks which generators produced each card and how scores were aggregated.
+       *
+       * This method supports both the legacy signature (limit only) and the
+       * CardGenerator interface signature (limit, context).
+       *
+       * @param limit - Maximum number of cards to return
+       * @param context - GeneratorContext passed to child generators (required when called via Pipeline)
        */
-      async getStrategyState() {
-        if (!this.user || !this.course) {
+      async getWeightedCards(limit, context) {
+        if (!context) {
           throw new Error(
-            `Cannot get strategy state: navigator not properly initialized. Ensure user and course are provided to constructor.`
+            "CompositeGenerator.getWeightedCards requires a GeneratorContext. It should be called via Pipeline, not directly."
           );
         }
-        return this.user.getStrategyState(this.course.getCourseID(), this.strategyKey);
+        const results = await Promise.all(
+          this.generators.map((g) => g.getWeightedCards(limit, context))
+        );
+        const byCardId = /* @__PURE__ */ new Map();
+        results.forEach((cards, index) => {
+          const gen = this.generators[index];
+          let weight = gen.learnable?.weight ?? 1;
+          let deviation;
+          if (gen.learnable && !gen.staticWeight && context.orchestration) {
+            const strategyId = gen.strategyId;
+            if (strategyId) {
+              weight = context.orchestration.getEffectiveWeight(strategyId, gen.learnable);
+              deviation = context.orchestration.getDeviation(strategyId);
+            }
+          }
+          for (const card of cards) {
+            if (card.provenance.length > 0) {
+              card.provenance[0].effectiveWeight = weight;
+              card.provenance[0].deviation = deviation;
+            }
+            const existing = byCardId.get(card.cardId) || [];
+            existing.push({ card, weight });
+            byCardId.set(card.cardId, existing);
+          }
+        });
+        const merged = [];
+        for (const [, items] of byCardId) {
+          const cards = items.map((i) => i.card);
+          const aggregatedScore = this.aggregateScores(items);
+          const finalScore = Math.min(1, aggregatedScore);
+          const mergedProvenance = cards.flatMap((c) => c.provenance);
+          const initialScore = cards[0].score;
+          const action = finalScore > initialScore ? "boosted" : finalScore < initialScore ? "penalized" : "passed";
+          const reason = this.buildAggregationReason(items, finalScore);
+          merged.push({
+            ...cards[0],
+            score: finalScore,
+            provenance: [
+              ...mergedProvenance,
+              {
+                strategy: "composite",
+                strategyName: "Composite Generator",
+                strategyId: "COMPOSITE_GENERATOR",
+                action,
+                score: finalScore,
+                reason
+              }
+            ]
+          });
+        }
+        return merged.sort((a, b) => b.score - a.score).slice(0, limit);
       }
       /**
-       * 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
+       * Build human-readable reason for score aggregation.
        */
-      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.`
-          );
+      buildAggregationReason(items, finalScore) {
+        const cards = items.map((i) => i.card);
+        const count = cards.length;
+        const scores = cards.map((c) => c.score.toFixed(2)).join(", ");
+        if (count === 1) {
+          const weightMsg = Math.abs(items[0].weight - 1) > 1e-3 ? ` (w=${items[0].weight.toFixed(2)})` : "";
+          return `Single generator, score ${finalScore.toFixed(2)}${weightMsg}`;
+        }
+        const strategies = cards.map((c) => c.provenance[0]?.strategy || "unknown").join(", ");
+        switch (this.aggregationMode) {
+          case "max" /* MAX */:
+            return `Max of ${count} generators (${strategies}): scores [${scores}] \u2192 ${finalScore.toFixed(2)}`;
+          case "average" /* AVERAGE */:
+            return `Weighted Avg of ${count} generators (${strategies}): scores [${scores}] \u2192 ${finalScore.toFixed(2)}`;
+          case "frequencyBoost" /* FREQUENCY_BOOST */: {
+            const totalWeight = items.reduce((sum, i) => sum + i.weight, 0);
+            const weightedSum = items.reduce((sum, i) => sum + i.card.score * i.weight, 0);
+            const avg = totalWeight > 0 ? weightedSum / totalWeight : 0;
+            const boost = 1 + FREQUENCY_BOOST_FACTOR * (count - 1);
+            return `Frequency boost from ${count} generators (${strategies}): w-avg ${avg.toFixed(2)} \xD7 ${boost.toFixed(2)} \u2192 ${finalScore.toFixed(2)}`;
+          }
+          default:
+            return `Aggregated from ${count} generators: ${finalScore.toFixed(2)}`;
         }
-        return this.user.putStrategyState(this.course.getCourseID(), this.strategyKey, data);
       }
       /**
-       * Factory method to create navigator instances dynamically.
-       *
-       * @param user - User interface
-       * @param course - Course interface
-       * @param strategyData - Strategy configuration document
-       * @returns the runtime object used to steer a study session.
+       * Aggregate scores from multiple generators for the same card.
        */
-      static async create(user, course, strategyData) {
-        const implementingClass = strategyData.implementingClass;
-        let NavigatorImpl;
-        const variations = [".ts", ".js", ""];
-        const dirs = ["filters", "generators"];
-        for (const ext of variations) {
-          for (const dir of dirs) {
-            const loadFrom = `./${dir}/${implementingClass}${ext}`;
-            try {
-              const module = await import(loadFrom);
-              NavigatorImpl = module.default;
-              break;
-            } catch (e) {
-              logger.debug(`Failed to load extension from ${loadFrom}:`, e);
-            }
+      aggregateScores(items) {
+        const scores = items.map((i) => i.card.score);
+        switch (this.aggregationMode) {
+          case "max" /* MAX */:
+            return Math.max(...scores);
+          case "average" /* AVERAGE */: {
+            const totalWeight = items.reduce((sum, i) => sum + i.weight, 0);
+            if (totalWeight === 0) return 0;
+            const weightedSum = items.reduce((sum, i) => sum + i.card.score * i.weight, 0);
+            return weightedSum / totalWeight;
           }
+          case "frequencyBoost" /* FREQUENCY_BOOST */: {
+            const totalWeight = items.reduce((sum, i) => sum + i.weight, 0);
+            const weightedSum = items.reduce((sum, i) => sum + i.card.score * i.weight, 0);
+            const avg = totalWeight > 0 ? weightedSum / totalWeight : 0;
+            const frequencyBoost = 1 + FREQUENCY_BOOST_FACTOR * (items.length - 1);
+            return avg * frequencyBoost;
+          }
+          default:
+            return scores[0];
         }
-        if (!NavigatorImpl) {
-          throw new Error(`Could not load navigator implementation for: ${implementingClass}`);
-        }
-        return new NavigatorImpl(user, course, strategyData);
+      }
+    };
+  }
+});
+
+// src/core/navigators/generators/elo.ts
+var elo_exports = {};
+__export(elo_exports, {
+  default: () => ELONavigator
+});
+import { toCourseElo as toCourseElo2 } from "@vue-skuilder/common";
+var ELONavigator;
+var init_elo = __esm({
+  "src/core/navigators/generators/elo.ts"() {
+    "use strict";
+    init_navigators();
+    ELONavigator = class extends ContentNavigator {
+      /** Human-readable name for CardGenerator interface */
+      name;
+      constructor(user, course, strategyData) {
+        super(user, course, strategyData);
+        this.name = strategyData?.name || "ELO";
       }
       /**
-       * Get cards with suitability scores and provenance trails.
-       *
-       * **This is the PRIMARY API for navigation strategies.**
-       *
-       * Returns cards ranked by suitability score (0-1). Higher scores indicate
-       * better candidates for presentation. Each card includes a provenance trail
-       * documenting how strategies contributed to the final score.
+       * Get new cards with suitability scores based on ELO distance.
        *
-       * ## Implementation Required
-       * All navigation strategies MUST override this method. The base class does
-       * not provide a default implementation.
+       * Cards closer to user's ELO get higher scores.
+       * Score formula: max(0, 1 - distance / 500)
        *
-       * ## For Generators
-       * Override this method to generate candidates and compute scores based on
-       * your strategy's logic (e.g., ELO proximity, review urgency). Create the
-       * initial provenance entry with action='generated'.
+       * NOTE: This generator only handles NEW cards. Reviews are handled by
+       * SRSNavigator. Use CompositeGenerator to combine both.
        *
-       * ## For Filters
-       * Filters should implement the CardFilter interface instead and be composed
-       * via Pipeline. Filters do not directly implement getWeightedCards().
+       * This method supports both the legacy signature (limit only) and the
+       * CardGenerator interface signature (limit, context).
        *
-       * @param limit - Maximum cards to return
-       * @returns Cards sorted by score descending, with provenance trails
+       * @param limit - Maximum number of cards to return
+       * @param context - Optional GeneratorContext (used when called via Pipeline)
        */
-      async getWeightedCards(_limit) {
-        throw new Error(`${this.constructor.name} must implement getWeightedCards(). `);
-      }
-    };
-  }
-});
-
-// src/core/navigators/Pipeline.ts
-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`
+      async getWeightedCards(limit, context) {
+        let userGlobalElo;
+        if (context?.userElo !== void 0) {
+          userGlobalElo = context.userElo;
+        } else {
+          const courseReg = await this.user.getCourseRegDoc(this.course.getCourseID());
+          const userElo = toCourseElo2(courseReg.elo);
+          userGlobalElo = userElo.global.score;
+        }
+        const activeCards = await this.user.getActiveCards();
+        const newCards = (await this.course.getCardsCenteredAtELO(
+          { limit, elo: "user" },
+          (c) => !activeCards.some((ac) => c.cardID === ac.cardID)
+        )).map((c) => ({ ...c, status: "new" }));
+        const cardIds = newCards.map((c) => c.cardID);
+        const cardEloData = await this.course.getCardEloData(cardIds);
+        const scored = newCards.map((c, i) => {
+          const cardElo = cardEloData[i]?.global?.score ?? 1e3;
+          const distance = Math.abs(cardElo - userGlobalElo);
+          const score = Math.max(0, 1 - distance / 500);
+          return {
+            cardId: c.cardID,
+            courseId: c.courseID,
+            score,
+            provenance: [
+              {
+                strategy: "elo",
+                strategyName: this.strategyName || this.name,
+                strategyId: this.strategyId || "NAVIGATION_STRATEGY-ELO-default",
+                action: "generated",
+                score,
+                reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userGlobalElo)}), new card`
+              }
+            ]
+          };
+        });
+        scored.sort((a, b) => b.score - a.score);
+        return scored.slice(0, limit);
+      }
+    };
+  }
+});
+
+// src/core/navigators/generators/index.ts
+var generators_exports = {};
+var init_generators = __esm({
+  "src/core/navigators/generators/index.ts"() {
+    "use strict";
+  }
+});
+
+// src/core/navigators/generators/srs.ts
+var srs_exports = {};
+__export(srs_exports, {
+  default: () => SRSNavigator
+});
+import moment3 from "moment";
+var SRSNavigator;
+var init_srs = __esm({
+  "src/core/navigators/generators/srs.ts"() {
+    "use strict";
+    init_navigators();
+    init_logger();
+    SRSNavigator = class extends ContentNavigator {
+      /** Human-readable name for CardGenerator interface */
+      name;
+      constructor(user, course, strategyData) {
+        super(user, course, strategyData);
+        this.name = strategyData?.name || "SRS";
+      }
+      /**
+       * Get review cards scored by urgency.
+       *
+       * Score formula combines:
+       * - Relative overdueness: hoursOverdue / intervalHours
+       * - Interval recency: exponential decay favoring shorter intervals
+       *
+       * Cards not yet due are excluded (not scored as 0).
+       *
+       * This method supports both the legacy signature (limit only) and the
+       * CardGenerator interface signature (limit, context).
+       *
+       * @param limit - Maximum number of cards to return
+       * @param _context - Optional GeneratorContext (currently unused, but required for interface)
+       */
+      async getWeightedCards(limit, _context) {
+        if (!this.user || !this.course) {
+          throw new Error("SRSNavigator requires user and course to be set");
+        }
+        const reviews = await this.user.getPendingReviews(this.course.getCourseID());
+        const now = moment3.utc();
+        const dueReviews = reviews.filter((r) => now.isAfter(moment3.utc(r.reviewTime)));
+        const scored = dueReviews.map((review) => {
+          const { score, reason } = this.computeUrgencyScore(review, now);
+          return {
+            cardId: review.cardId,
+            courseId: review.courseId,
+            score,
+            reviewID: review._id,
+            provenance: [
+              {
+                strategy: "srs",
+                strategyName: this.strategyName || this.name,
+                strategyId: this.strategyId || "NAVIGATION_STRATEGY-SRS-default",
+                action: "generated",
+                score,
+                reason
+              }
+            ]
+          };
+        });
+        logger.debug(`[srsNav] got ${scored.length} weighted cards`);
+        return scored.sort((a, b) => b.score - a.score).slice(0, limit);
+      }
+      /**
+       * Compute urgency score for a review card.
+       *
+       * Two factors:
+       * 1. Relative overdueness = hoursOverdue / intervalHours
+       *    - 2 days overdue on 3-day interval = 0.67 (urgent)
+       *    - 2 days overdue on 180-day interval = 0.01 (not urgent)
+       *
+       * 2. Interval recency factor = 0.3 + 0.7 * exp(-intervalHours / 720)
+       *    - 24h interval → ~1.0 (very recent learning)
+       *    - 30 days (720h) → ~0.56
+       *    - 180 days → ~0.30
+       *
+       * Combined: base 0.5 + weighted average of factors * 0.45
+       * Result range: approximately 0.5 to 0.95
+       */
+      computeUrgencyScore(review, now) {
+        const scheduledAt = moment3.utc(review.scheduledAt);
+        const due = moment3.utc(review.reviewTime);
+        const intervalHours = Math.max(1, due.diff(scheduledAt, "hours"));
+        const hoursOverdue = now.diff(due, "hours");
+        const relativeOverdue = hoursOverdue / intervalHours;
+        const recencyFactor = 0.3 + 0.7 * Math.exp(-intervalHours / 720);
+        const overdueContribution = Math.min(1, Math.max(0, relativeOverdue));
+        const urgency = overdueContribution * 0.5 + recencyFactor * 0.5;
+        const score = Math.min(0.95, 0.5 + urgency * 0.45);
+        const reason = `${Math.round(hoursOverdue)}h overdue (interval: ${Math.round(intervalHours)}h, relative: ${relativeOverdue.toFixed(2)}), recency: ${recencyFactor.toFixed(2)}, review`;
+        return { score, reason };
+      }
+    };
+  }
+});
+
+// src/core/navigators/generators/types.ts
+var types_exports = {};
+var init_types = __esm({
+  "src/core/navigators/generators/types.ts"() {
+    "use strict";
+  }
+});
+
+// import("./generators/**/*") in src/core/navigators/index.ts
+var globImport_generators;
+var init_ = __esm({
+  'import("./generators/**/*") in src/core/navigators/index.ts'() {
+    globImport_generators = __glob({
+      "./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/srs.ts": () => Promise.resolve().then(() => (init_srs(), srs_exports)),
+      "./generators/types.ts": () => Promise.resolve().then(() => (init_types(), types_exports))
+    });
+  }
+});
+
+// src/core/types/contentNavigationStrategy.ts
+var DEFAULT_LEARNABLE_WEIGHT;
+var init_contentNavigationStrategy = __esm({
+  "src/core/types/contentNavigationStrategy.ts"() {
+    "use strict";
+    DEFAULT_LEARNABLE_WEIGHT = {
+      weight: 1,
+      confidence: 0.1,
+      // Low confidence initially = wide exploration
+      sampleSize: 0
+    };
+  }
+});
+
+// src/core/navigators/filters/WeightedFilter.ts
+var WeightedFilter_exports = {};
+__export(WeightedFilter_exports, {
+  WeightedFilter: () => WeightedFilter
+});
+var WeightedFilter;
+var init_WeightedFilter = __esm({
+  "src/core/navigators/filters/WeightedFilter.ts"() {
+    "use strict";
+    init_contentNavigationStrategy();
+    WeightedFilter = class {
+      name;
+      inner;
+      learnable;
+      staticWeight;
+      strategyId;
+      constructor(inner, learnable = DEFAULT_LEARNABLE_WEIGHT, staticWeight = false, strategyId) {
+        this.inner = inner;
+        this.name = inner.name;
+        this.learnable = learnable;
+        this.staticWeight = staticWeight;
+        this.strategyId = strategyId;
+      }
+      /**
+       * Apply the inner filter, then scale its effect by the configured weight.
+       */
+      async transform(cards, context) {
+        let effectiveWeight = this.learnable.weight;
+        let deviation;
+        if (!this.staticWeight && context.orchestration) {
+          const strategyId = this.strategyId || this.inner.strategyId || this.name;
+          effectiveWeight = context.orchestration.getEffectiveWeight(strategyId, this.learnable);
+          deviation = context.orchestration.getDeviation(strategyId);
+        }
+        if (Math.abs(effectiveWeight - 1) < 1e-3) {
+          return this.inner.transform(cards, context);
+        }
+        const originalScores = /* @__PURE__ */ new Map();
+        for (const card of cards) {
+          originalScores.set(card.cardId, card.score);
+        }
+        const transformedCards = await this.inner.transform(cards, context);
+        return transformedCards.map((card) => {
+          const originalScore = originalScores.get(card.cardId);
+          if (originalScore === void 0 || originalScore === 0 || card.score === 0) {
+            return card;
+          }
+          const rawEffect = card.score / originalScore;
+          if (Math.abs(rawEffect - 1) < 1e-4) {
+            return card;
+          }
+          const weightedEffect = Math.pow(rawEffect, effectiveWeight);
+          const newScore = originalScore * weightedEffect;
+          const lastProvIndex = card.provenance.length - 1;
+          const lastProv = card.provenance[lastProvIndex];
+          if (lastProv) {
+            const updatedProvenance = [...card.provenance];
+            updatedProvenance[lastProvIndex] = {
+              ...lastProv,
+              score: newScore,
+              effectiveWeight,
+              deviation
+              // We can optionally append to the reason, but the structured field is key
+            };
+            return {
+              ...card,
+              score: newScore,
+              provenance: updatedProvenance
+            };
+          }
+          return {
+            ...card,
+            score: newScore
+          };
+        });
+      }
+    };
+  }
+});
+
+// src/core/navigators/filters/eloDistance.ts
+var eloDistance_exports = {};
+__export(eloDistance_exports, {
+  DEFAULT_HALF_LIFE: () => DEFAULT_HALF_LIFE,
+  DEFAULT_MAX_MULTIPLIER: () => DEFAULT_MAX_MULTIPLIER,
+  DEFAULT_MIN_MULTIPLIER: () => DEFAULT_MIN_MULTIPLIER,
+  createEloDistanceFilter: () => createEloDistanceFilter
+});
+function computeMultiplier(distance, halfLife, minMultiplier, maxMultiplier) {
+  const normalizedDistance = distance / halfLife;
+  const decay = Math.exp(-(normalizedDistance * normalizedDistance));
+  return minMultiplier + (maxMultiplier - minMultiplier) * decay;
+}
+function createEloDistanceFilter(config) {
+  const halfLife = config?.halfLife ?? DEFAULT_HALF_LIFE;
+  const minMultiplier = config?.minMultiplier ?? DEFAULT_MIN_MULTIPLIER;
+  const maxMultiplier = config?.maxMultiplier ?? DEFAULT_MAX_MULTIPLIER;
+  return {
+    name: "ELO Distance Filter",
+    async transform(cards, context) {
+      const { course, userElo } = context;
+      const cardIds = cards.map((c) => c.cardId);
+      const cardElos = await course.getCardEloData(cardIds);
+      return cards.map((card, i) => {
+        const cardElo = cardElos[i]?.global?.score ?? 1e3;
+        const distance = Math.abs(cardElo - userElo);
+        const multiplier = computeMultiplier(distance, halfLife, minMultiplier, maxMultiplier);
+        const newScore = card.score * multiplier;
+        const action = multiplier < maxMultiplier - 0.01 ? "penalized" : "passed";
+        return {
+          ...card,
+          score: newScore,
+          provenance: [
+            ...card.provenance,
+            {
+              strategy: "eloDistance",
+              strategyName: "ELO Distance Filter",
+              strategyId: "ELO_DISTANCE_FILTER",
+              action,
+              score: newScore,
+              reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userElo)}) \u2192 ${multiplier.toFixed(2)}x`
+            }
+          ]
+        };
+      });
+    }
+  };
+}
+var DEFAULT_HALF_LIFE, DEFAULT_MIN_MULTIPLIER, DEFAULT_MAX_MULTIPLIER;
+var init_eloDistance = __esm({
+  "src/core/navigators/filters/eloDistance.ts"() {
+    "use strict";
+    DEFAULT_HALF_LIFE = 200;
+    DEFAULT_MIN_MULTIPLIER = 0.3;
+    DEFAULT_MAX_MULTIPLIER = 1;
+  }
+});
+
+// src/core/navigators/filters/hierarchyDefinition.ts
+var hierarchyDefinition_exports = {};
+__export(hierarchyDefinition_exports, {
+  default: () => HierarchyDefinitionNavigator
+});
+import { toCourseElo as toCourseElo3 } from "@vue-skuilder/common";
+var DEFAULT_MIN_COUNT, HierarchyDefinitionNavigator;
+var init_hierarchyDefinition = __esm({
+  "src/core/navigators/filters/hierarchyDefinition.ts"() {
+    "use strict";
+    init_navigators();
+    DEFAULT_MIN_COUNT = 3;
+    HierarchyDefinitionNavigator = class extends ContentNavigator {
+      config;
+      /** Human-readable name for CardFilter interface */
+      name;
+      constructor(user, course, strategyData) {
+        super(user, course, strategyData);
+        this.config = this.parseConfig(strategyData.serializedData);
+        this.name = strategyData.name || "Hierarchy Definition";
+      }
+      parseConfig(serializedData) {
+        try {
+          const parsed = JSON.parse(serializedData);
+          return {
+            prerequisites: parsed.prerequisites || {}
+          };
+        } catch {
+          return {
+            prerequisites: {}
+          };
+        }
+      }
+      /**
+       * Check if a specific prerequisite is satisfied
+       */
+      isPrerequisiteMet(prereq, userTagElo, userGlobalElo) {
+        if (!userTagElo) return false;
+        const minCount = prereq.masteryThreshold?.minCount ?? DEFAULT_MIN_COUNT;
+        if (userTagElo.count < minCount) return false;
+        if (prereq.masteryThreshold?.minElo !== void 0) {
+          return userTagElo.score >= prereq.masteryThreshold.minElo;
+        } else {
+          return userTagElo.score >= userGlobalElo;
+        }
+      }
+      /**
+       * Get the set of tags the user has mastered.
+       * A tag is "mastered" if it appears as a prerequisite somewhere and meets its threshold.
+       */
+      async getMasteredTags(context) {
+        const mastered = /* @__PURE__ */ new Set();
+        try {
+          const courseReg = await context.user.getCourseRegDoc(context.course.getCourseID());
+          const userElo = toCourseElo3(courseReg.elo);
+          for (const prereqs of Object.values(this.config.prerequisites)) {
+            for (const prereq of prereqs) {
+              const tagElo = userElo.tags[prereq.tag];
+              if (this.isPrerequisiteMet(prereq, tagElo, userElo.global.score)) {
+                mastered.add(prereq.tag);
+              }
+            }
+          }
+        } catch {
+        }
+        return mastered;
+      }
+      /**
+       * Get the set of tags that are unlocked (prerequisites met)
+       */
+      getUnlockedTags(masteredTags) {
+        const unlocked = /* @__PURE__ */ new Set();
+        for (const [tagId, prereqs] of Object.entries(this.config.prerequisites)) {
+          const allPrereqsMet = prereqs.every((prereq) => masteredTags.has(prereq.tag));
+          if (allPrereqsMet) {
+            unlocked.add(tagId);
+          }
+        }
+        return unlocked;
+      }
+      /**
+       * Check if a tag has prerequisites defined in config
+       */
+      hasPrerequisites(tagId) {
+        return tagId in this.config.prerequisites;
+      }
+      /**
+       * Check if a card is unlocked and generate reason.
+       */
+      async checkCardUnlock(card, _course, unlockedTags, masteredTags) {
+        try {
+          const cardTags = card.tags ?? [];
+          const lockedTags = cardTags.filter(
+            (tag) => this.hasPrerequisites(tag) && !unlockedTags.has(tag)
+          );
+          if (lockedTags.length === 0) {
+            const tagList = cardTags.length > 0 ? cardTags.join(", ") : "none";
+            return {
+              isUnlocked: true,
+              reason: `Prerequisites met, tags: ${tagList}`
+            };
+          }
+          const missingPrereqs = lockedTags.flatMap((tag) => {
+            const prereqs = this.config.prerequisites[tag] || [];
+            return prereqs.filter((p) => !masteredTags.has(p.tag)).map((p) => p.tag);
+          });
+          return {
+            isUnlocked: false,
+            reason: `Blocked: missing prerequisites ${missingPrereqs.join(", ")} for tags ${lockedTags.join(", ")}`
+          };
+        } catch {
+          return {
+            isUnlocked: true,
+            reason: "Prerequisites check skipped (tag lookup failed)"
+          };
+        }
+      }
+      /**
+       * CardFilter.transform implementation.
+       *
+       * Apply prerequisite gating to cards. Cards with locked tags receive score: 0.
+       */
+      async transform(cards, context) {
+        const masteredTags = await this.getMasteredTags(context);
+        const unlockedTags = this.getUnlockedTags(masteredTags);
+        const gated = [];
+        for (const card of cards) {
+          const { isUnlocked, reason } = await this.checkCardUnlock(
+            card,
+            context.course,
+            unlockedTags,
+            masteredTags
+          );
+          const finalScore = isUnlocked ? card.score : 0;
+          const action = isUnlocked ? "passed" : "penalized";
+          gated.push({
+            ...card,
+            score: finalScore,
+            provenance: [
+              ...card.provenance,
+              {
+                strategy: "hierarchyDefinition",
+                strategyName: this.strategyName || this.name,
+                strategyId: this.strategyId || "NAVIGATION_STRATEGY-hierarchy",
+                action,
+                score: finalScore,
+                reason
+              }
+            ]
+          });
+        }
+        return gated;
+      }
+      /**
+       * Legacy getWeightedCards - now throws as filters should not be used as generators.
+       *
+       * Use transform() via Pipeline instead.
+       */
+      async getWeightedCards(_limit) {
+        throw new Error(
+          "HierarchyDefinitionNavigator is a filter and should not be used as a generator. Use Pipeline with a generator and this filter via transform()."
+        );
+      }
+    };
+  }
+});
+
+// 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()."
+        );
+      }
+    };
+  }
+});
+
+// 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();
+  }
+});
+
+// src/core/navigators/filters/inferredPreferenceStub.ts
+var inferredPreferenceStub_exports = {};
+__export(inferredPreferenceStub_exports, {
+  INFERRED_PREFERENCE_NAVIGATOR_STUB: () => INFERRED_PREFERENCE_NAVIGATOR_STUB
+});
+var INFERRED_PREFERENCE_NAVIGATOR_STUB;
+var init_inferredPreferenceStub = __esm({
+  "src/core/navigators/filters/inferredPreferenceStub.ts"() {
+    "use strict";
+    INFERRED_PREFERENCE_NAVIGATOR_STUB = true;
+  }
+});
+
+// src/core/navigators/filters/interferenceMitigator.ts
+var interferenceMitigator_exports = {};
+__export(interferenceMitigator_exports, {
+  default: () => InterferenceMitigatorNavigator
+});
+import { toCourseElo as toCourseElo4 } from "@vue-skuilder/common";
+var DEFAULT_MIN_COUNT2, DEFAULT_MIN_ELAPSED_DAYS, DEFAULT_INTERFERENCE_DECAY, InterferenceMitigatorNavigator;
+var init_interferenceMitigator = __esm({
+  "src/core/navigators/filters/interferenceMitigator.ts"() {
+    "use strict";
+    init_navigators();
+    DEFAULT_MIN_COUNT2 = 10;
+    DEFAULT_MIN_ELAPSED_DAYS = 3;
+    DEFAULT_INTERFERENCE_DECAY = 0.8;
+    InterferenceMitigatorNavigator = class extends ContentNavigator {
+      config;
+      /** Human-readable name for CardFilter interface */
+      name;
+      /** Precomputed map: tag -> set of { partner, decay } it interferes with */
+      interferenceMap;
+      constructor(user, course, strategyData) {
+        super(user, course, strategyData);
+        this.config = this.parseConfig(strategyData.serializedData);
+        this.interferenceMap = this.buildInterferenceMap();
+        this.name = strategyData.name || "Interference Mitigator";
+      }
+      parseConfig(serializedData) {
+        try {
+          const parsed = JSON.parse(serializedData);
+          let sets = parsed.interferenceSets || [];
+          if (sets.length > 0 && Array.isArray(sets[0])) {
+            sets = sets.map((tags) => ({ tags }));
+          }
+          return {
+            interferenceSets: sets,
+            maturityThreshold: {
+              minCount: parsed.maturityThreshold?.minCount ?? DEFAULT_MIN_COUNT2,
+              minElo: parsed.maturityThreshold?.minElo,
+              minElapsedDays: parsed.maturityThreshold?.minElapsedDays ?? DEFAULT_MIN_ELAPSED_DAYS
+            },
+            defaultDecay: parsed.defaultDecay ?? DEFAULT_INTERFERENCE_DECAY
+          };
+        } catch {
+          return {
+            interferenceSets: [],
+            maturityThreshold: {
+              minCount: DEFAULT_MIN_COUNT2,
+              minElapsedDays: DEFAULT_MIN_ELAPSED_DAYS
+            },
+            defaultDecay: DEFAULT_INTERFERENCE_DECAY
+          };
+        }
+      }
+      /**
+       * Build a map from each tag to its interference partners with decay coefficients.
+       * If tags A, B, C are in an interference group with decay 0.8, then:
+       * - A interferes with B (decay 0.8) and C (decay 0.8)
+       * - B interferes with A (decay 0.8) and C (decay 0.8)
+       * - etc.
+       */
+      buildInterferenceMap() {
+        const map = /* @__PURE__ */ new Map();
+        for (const group of this.config.interferenceSets) {
+          const decay = group.decay ?? this.config.defaultDecay ?? DEFAULT_INTERFERENCE_DECAY;
+          for (const tag of group.tags) {
+            if (!map.has(tag)) {
+              map.set(tag, []);
+            }
+            const partners = map.get(tag);
+            for (const other of group.tags) {
+              if (other !== tag) {
+                const existing = partners.find((p) => p.partner === other);
+                if (existing) {
+                  existing.decay = Math.max(existing.decay, decay);
+                } else {
+                  partners.push({ partner: other, decay });
+                }
+              }
+            }
+          }
+        }
+        return map;
+      }
+      /**
+       * Get the set of tags that are currently immature for this user.
+       * A tag is immature if the user has interacted with it but hasn't
+       * reached the maturity threshold.
+       */
+      async getImmatureTags(context) {
+        const immature = /* @__PURE__ */ new Set();
+        try {
+          const courseReg = await context.user.getCourseRegDoc(context.course.getCourseID());
+          const userElo = toCourseElo4(courseReg.elo);
+          const minCount = this.config.maturityThreshold?.minCount ?? DEFAULT_MIN_COUNT2;
+          const minElo = this.config.maturityThreshold?.minElo;
+          const minElapsedDays = this.config.maturityThreshold?.minElapsedDays ?? DEFAULT_MIN_ELAPSED_DAYS;
+          const minCountForElapsed = minElapsedDays * 2;
+          for (const [tagId, tagElo] of Object.entries(userElo.tags)) {
+            if (tagElo.count === 0) continue;
+            const belowCount = tagElo.count < minCount;
+            const belowElo = minElo !== void 0 && tagElo.score < minElo;
+            const belowElapsed = tagElo.count < minCountForElapsed;
+            if (belowCount || belowElo || belowElapsed) {
+              immature.add(tagId);
+            }
+          }
+        } catch {
+        }
+        return immature;
+      }
+      /**
+       * Get all tags that interfere with any immature tag, along with their decay coefficients.
+       * These are the tags we want to avoid introducing.
+       */
+      getTagsToAvoid(immatureTags) {
+        const avoid = /* @__PURE__ */ new Map();
+        for (const immatureTag of immatureTags) {
+          const partners = this.interferenceMap.get(immatureTag);
+          if (partners) {
+            for (const { partner, decay } of partners) {
+              if (!immatureTags.has(partner)) {
+                const existing = avoid.get(partner) ?? 0;
+                avoid.set(partner, Math.max(existing, decay));
+              }
+            }
+          }
+        }
+        return avoid;
+      }
+      /**
+       * Compute interference score reduction for a card.
+       * Returns: { multiplier, interfering tags, reason }
+       */
+      computeInterferenceEffect(cardTags, tagsToAvoid, immatureTags) {
+        if (tagsToAvoid.size === 0) {
+          return {
+            multiplier: 1,
+            interferingTags: [],
+            reason: "No interference detected"
+          };
+        }
+        let multiplier = 1;
+        const interferingTags = [];
+        for (const tag of cardTags) {
+          const decay = tagsToAvoid.get(tag);
+          if (decay !== void 0) {
+            interferingTags.push(tag);
+            multiplier *= 1 - decay;
+          }
+        }
+        if (interferingTags.length === 0) {
+          return {
+            multiplier: 1,
+            interferingTags: [],
+            reason: "No interference detected"
+          };
+        }
+        const causingTags = /* @__PURE__ */ new Set();
+        for (const tag of interferingTags) {
+          for (const immatureTag of immatureTags) {
+            const partners = this.interferenceMap.get(immatureTag);
+            if (partners?.some((p) => p.partner === tag)) {
+              causingTags.add(immatureTag);
+            }
+          }
+        }
+        const reason = `Interferes with immature tags ${Array.from(causingTags).join(", ")} (tags: ${interferingTags.join(", ")}, multiplier: ${multiplier.toFixed(2)})`;
+        return { multiplier, interferingTags, reason };
+      }
+      /**
+       * CardFilter.transform implementation.
+       *
+       * Apply interference-aware scoring. Cards with tags that interfere with
+       * immature learnings get reduced scores.
+       */
+      async transform(cards, context) {
+        const immatureTags = await this.getImmatureTags(context);
+        const tagsToAvoid = this.getTagsToAvoid(immatureTags);
+        const adjusted = [];
+        for (const card of cards) {
+          const cardTags = card.tags ?? [];
+          const { multiplier, reason } = this.computeInterferenceEffect(
+            cardTags,
+            tagsToAvoid,
+            immatureTags
+          );
+          const finalScore = card.score * multiplier;
+          const action = multiplier < 1 ? "penalized" : multiplier > 1 ? "boosted" : "passed";
+          adjusted.push({
+            ...card,
+            score: finalScore,
+            provenance: [
+              ...card.provenance,
+              {
+                strategy: "interferenceMitigator",
+                strategyName: this.strategyName || this.name,
+                strategyId: this.strategyId || "NAVIGATION_STRATEGY-interference",
+                action,
+                score: finalScore,
+                reason
+              }
+            ]
+          });
+        }
+        return adjusted;
+      }
+      /**
+       * Legacy getWeightedCards - now throws as filters should not be used as generators.
+       *
+       * Use transform() via Pipeline instead.
+       */
+      async getWeightedCards(_limit) {
+        throw new Error(
+          "InterferenceMitigatorNavigator is a filter and should not be used as a generator. Use Pipeline with a generator and this filter via transform()."
+        );
+      }
+    };
+  }
+});
+
+// src/core/navigators/filters/relativePriority.ts
+var relativePriority_exports = {};
+__export(relativePriority_exports, {
+  default: () => RelativePriorityNavigator
+});
+var DEFAULT_PRIORITY, DEFAULT_PRIORITY_INFLUENCE, DEFAULT_COMBINE_MODE, RelativePriorityNavigator;
+var init_relativePriority = __esm({
+  "src/core/navigators/filters/relativePriority.ts"() {
+    "use strict";
+    init_navigators();
+    DEFAULT_PRIORITY = 0.5;
+    DEFAULT_PRIORITY_INFLUENCE = 0.5;
+    DEFAULT_COMBINE_MODE = "max";
+    RelativePriorityNavigator = class extends ContentNavigator {
+      config;
+      /** Human-readable name for CardFilter interface */
+      name;
+      constructor(user, course, strategyData) {
+        super(user, course, strategyData);
+        this.config = this.parseConfig(strategyData.serializedData);
+        this.name = strategyData.name || "Relative Priority";
+      }
+      parseConfig(serializedData) {
+        try {
+          const parsed = JSON.parse(serializedData);
+          return {
+            tagPriorities: parsed.tagPriorities || {},
+            defaultPriority: parsed.defaultPriority ?? DEFAULT_PRIORITY,
+            combineMode: parsed.combineMode ?? DEFAULT_COMBINE_MODE,
+            priorityInfluence: parsed.priorityInfluence ?? DEFAULT_PRIORITY_INFLUENCE
+          };
+        } catch {
+          return {
+            tagPriorities: {},
+            defaultPriority: DEFAULT_PRIORITY,
+            combineMode: DEFAULT_COMBINE_MODE,
+            priorityInfluence: DEFAULT_PRIORITY_INFLUENCE
+          };
+        }
+      }
+      /**
+       * Look up the priority for a tag.
+       */
+      getTagPriority(tagId) {
+        return this.config.tagPriorities[tagId] ?? this.config.defaultPriority ?? DEFAULT_PRIORITY;
+      }
+      /**
+       * Compute combined priority for a card based on its tags.
+       */
+      computeCardPriority(cardTags) {
+        if (cardTags.length === 0) {
+          return this.config.defaultPriority ?? DEFAULT_PRIORITY;
+        }
+        const priorities = cardTags.map((tag) => this.getTagPriority(tag));
+        switch (this.config.combineMode) {
+          case "max":
+            return Math.max(...priorities);
+          case "min":
+            return Math.min(...priorities);
+          case "average":
+            return priorities.reduce((sum, p) => sum + p, 0) / priorities.length;
+          default:
+            return Math.max(...priorities);
+        }
+      }
+      /**
+       * Compute boost factor based on priority.
+       *
+       * The formula: 1 + (priority - 0.5) * priorityInfluence
+       *
+       * This creates a multiplier centered around 1.0:
+       * - Priority 1.0 with influence 0.5 → 1.25 (25% boost)
+       * - Priority 0.5 with any influence → 1.00 (neutral)
+       * - Priority 0.0 with influence 0.5 → 0.75 (25% reduction)
+       */
+      computeBoostFactor(priority) {
+        const influence = this.config.priorityInfluence ?? DEFAULT_PRIORITY_INFLUENCE;
+        return 1 + (priority - 0.5) * influence;
+      }
+      /**
+       * Build human-readable reason for priority adjustment.
+       */
+      buildPriorityReason(cardTags, priority, boostFactor, finalScore) {
+        if (cardTags.length === 0) {
+          return `No tags, neutral priority (${priority.toFixed(2)})`;
+        }
+        const tagList = cardTags.slice(0, 3).join(", ");
+        const more = cardTags.length > 3 ? ` (+${cardTags.length - 3} more)` : "";
+        if (boostFactor === 1) {
+          return `Neutral priority (${priority.toFixed(2)}) for tags: ${tagList}${more}`;
+        } else if (boostFactor > 1) {
+          return `High-priority tags: ${tagList}${more} (priority ${priority.toFixed(2)} \u2192 boost ${boostFactor.toFixed(2)}x \u2192 ${finalScore.toFixed(2)})`;
+        } else {
+          return `Low-priority tags: ${tagList}${more} (priority ${priority.toFixed(2)} \u2192 reduce ${boostFactor.toFixed(2)}x \u2192 ${finalScore.toFixed(2)})`;
+        }
+      }
+      /**
+       * 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) {
+        const adjusted = await Promise.all(
+          cards.map(async (card) => {
+            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));
+            const action = boostFactor > 1 ? "boosted" : boostFactor < 1 ? "penalized" : "passed";
+            const reason = this.buildPriorityReason(cardTags, priority, boostFactor, finalScore);
+            return {
+              ...card,
+              score: finalScore,
+              provenance: [
+                ...card.provenance,
+                {
+                  strategy: "relativePriority",
+                  strategyName: this.strategyName || this.name,
+                  strategyId: this.strategyId || "NAVIGATION_STRATEGY-priority",
+                  action,
+                  score: finalScore,
+                  reason
+                }
+              ]
+            };
+          })
+        );
+        return adjusted;
+      }
+      /**
+       * Legacy getWeightedCards - now throws as filters should not be used as generators.
+       *
+       * Use transform() via Pipeline instead.
+       */
+      async getWeightedCards(_limit) {
+        throw new Error(
+          "RelativePriorityNavigator is a filter and should not be used as a generator. Use Pipeline with a generator and this filter via transform()."
+        );
+      }
+    };
+  }
+});
+
+// src/core/navigators/filters/types.ts
+var types_exports2 = {};
+var init_types2 = __esm({
+  "src/core/navigators/filters/types.ts"() {
+    "use strict";
+  }
+});
+
+// src/core/navigators/filters/userGoalStub.ts
+var userGoalStub_exports = {};
+__export(userGoalStub_exports, {
+  USER_GOAL_NAVIGATOR_STUB: () => USER_GOAL_NAVIGATOR_STUB
+});
+var USER_GOAL_NAVIGATOR_STUB;
+var init_userGoalStub = __esm({
+  "src/core/navigators/filters/userGoalStub.ts"() {
+    "use strict";
+    USER_GOAL_NAVIGATOR_STUB = true;
+  }
+});
+
+// import("./filters/**/*") in src/core/navigators/index.ts
+var globImport_filters;
+var init_2 = __esm({
+  'import("./filters/**/*") in src/core/navigators/index.ts'() {
+    globImport_filters = __glob({
+      "./filters/WeightedFilter.ts": () => Promise.resolve().then(() => (init_WeightedFilter(), WeightedFilter_exports)),
+      "./filters/eloDistance.ts": () => Promise.resolve().then(() => (init_eloDistance(), eloDistance_exports)),
+      "./filters/hierarchyDefinition.ts": () => Promise.resolve().then(() => (init_hierarchyDefinition(), hierarchyDefinition_exports)),
+      "./filters/index.ts": () => Promise.resolve().then(() => (init_filters(), filters_exports)),
+      "./filters/inferredPreferenceStub.ts": () => Promise.resolve().then(() => (init_inferredPreferenceStub(), inferredPreferenceStub_exports)),
+      "./filters/interferenceMitigator.ts": () => Promise.resolve().then(() => (init_interferenceMitigator(), interferenceMitigator_exports)),
+      "./filters/relativePriority.ts": () => Promise.resolve().then(() => (init_relativePriority(), relativePriority_exports)),
+      "./filters/types.ts": () => Promise.resolve().then(() => (init_types2(), types_exports2)),
+      "./filters/userGoalStub.ts": () => Promise.resolve().then(() => (init_userGoalStub(), userGoalStub_exports)),
+      "./filters/userTagPreference.ts": () => Promise.resolve().then(() => (init_userTagPreference(), userTagPreference_exports))
+    });
+  }
+});
+
+// src/core/orchestration/gradient.ts
+var init_gradient = __esm({
+  "src/core/orchestration/gradient.ts"() {
+    "use strict";
+    init_logger();
+  }
+});
+
+// src/core/orchestration/learning.ts
+var init_learning = __esm({
+  "src/core/orchestration/learning.ts"() {
+    "use strict";
+    init_contentNavigationStrategy();
+    init_types_legacy();
+    init_logger();
+  }
+});
+
+// src/core/orchestration/signal.ts
+var init_signal = __esm({
+  "src/core/orchestration/signal.ts"() {
+    "use strict";
+  }
+});
+
+// src/core/orchestration/recording.ts
+var init_recording = __esm({
+  "src/core/orchestration/recording.ts"() {
+    "use strict";
+    init_signal();
+    init_types_legacy();
+    init_logger();
+  }
+});
+
+// src/core/orchestration/index.ts
+function fnv1a(str) {
+  let hash = 2166136261;
+  for (let i = 0; i < str.length; i++) {
+    hash ^= str.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}
+function computeDeviation(userId, strategyId, salt) {
+  const input = `${userId}:${strategyId}:${salt}`;
+  const hash = fnv1a(input);
+  const normalized = hash / 4294967296;
+  return normalized * 2 - 1;
+}
+function computeSpread(confidence) {
+  const clampedConfidence = Math.max(0, Math.min(1, confidence));
+  return MAX_SPREAD - clampedConfidence * (MAX_SPREAD - MIN_SPREAD);
+}
+function computeEffectiveWeight(learnable, userId, strategyId, salt) {
+  const deviation = computeDeviation(userId, strategyId, salt);
+  const spread = computeSpread(learnable.confidence);
+  const adjustment = deviation * spread * learnable.weight;
+  const effective = learnable.weight + adjustment;
+  return Math.max(MIN_WEIGHT, Math.min(MAX_WEIGHT, effective));
+}
+async function createOrchestrationContext(user, course) {
+  let courseConfig;
+  try {
+    courseConfig = await course.getCourseConfig();
+  } catch (e) {
+    logger.error(`[Orchestration] Failed to load course config: ${e}`);
+    courseConfig = {
+      name: "Unknown",
+      description: "",
+      public: false,
+      deleted: false,
+      creator: "",
+      admins: [],
+      moderators: [],
+      dataShapes: [],
+      questionTypes: [],
+      orchestration: { salt: "default" }
+    };
+  }
+  const userId = user.getUsername();
+  const salt = courseConfig.orchestration?.salt || "default_salt";
+  return {
+    user,
+    course,
+    userId,
+    courseConfig,
+    getEffectiveWeight(strategyId, learnable) {
+      return computeEffectiveWeight(learnable, userId, strategyId, salt);
+    },
+    getDeviation(strategyId) {
+      return computeDeviation(userId, strategyId, salt);
+    }
+  };
+}
+var MIN_SPREAD, MAX_SPREAD, MIN_WEIGHT, MAX_WEIGHT;
+var init_orchestration = __esm({
+  "src/core/orchestration/index.ts"() {
+    "use strict";
+    init_logger();
+    init_gradient();
+    init_learning();
+    init_signal();
+    init_recording();
+    MIN_SPREAD = 0.1;
+    MAX_SPREAD = 0.5;
+    MIN_WEIGHT = 0.1;
+    MAX_WEIGHT = 3;
+  }
+});
+
+// src/core/navigators/Pipeline.ts
+var Pipeline_exports = {};
+__export(Pipeline_exports, {
+  Pipeline: () => Pipeline
+});
+import { toCourseElo as toCourseElo5 } 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) {
@@ -656,6 +1877,7 @@ var init_Pipeline = __esm({
     "use strict";
     init_navigators();
     init_logger();
+    init_orchestration();
     Pipeline = class extends ContentNavigator {
       generator;
       filters;
@@ -738,191 +1960,90 @@ var init_Pipeline = __esm({
         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.
-       *
-       * Called once per getWeightedCards() invocation.
-       * Contains data that the generator and multiple filters might need.
-       *
-       * The context satisfies both GeneratorContext and FilterContext interfaces.
-       */
-      async buildContext() {
-        let userElo = 1e3;
-        try {
-          const courseReg = await this.user.getCourseRegDoc(this.course.getCourseID());
-          const courseElo = toCourseElo2(courseReg.elo);
-          userElo = courseElo.global.score;
-        } catch (e) {
-          logger.debug(`[Pipeline] Could not get user ELO, using default: ${e}`);
-        }
-        return {
-          user: this.user,
-          course: this.course,
-          userElo
-        };
-      }
-      /**
-       * Get the course ID for this pipeline.
-       */
-      getCourseID() {
-        return this.course.getCourseID();
-      }
-    };
-  }
-});
-
-// src/core/navigators/generators/CompositeGenerator.ts
-var DEFAULT_AGGREGATION_MODE, FREQUENCY_BOOST_FACTOR, CompositeGenerator;
-var init_CompositeGenerator = __esm({
-  "src/core/navigators/generators/CompositeGenerator.ts"() {
-    "use strict";
-    init_navigators();
-    init_logger();
-    DEFAULT_AGGREGATION_MODE = "frequencyBoost" /* FREQUENCY_BOOST */;
-    FREQUENCY_BOOST_FACTOR = 0.1;
-    CompositeGenerator = class _CompositeGenerator extends ContentNavigator {
-      /** Human-readable name for CardGenerator interface */
-      name = "Composite Generator";
-      generators;
-      aggregationMode;
-      constructor(generators, aggregationMode = DEFAULT_AGGREGATION_MODE) {
-        super();
-        this.generators = generators;
-        this.aggregationMode = aggregationMode;
-        if (generators.length === 0) {
-          throw new Error("CompositeGenerator requires at least one generator");
-        }
-        logger.debug(
-          `[CompositeGenerator] Created with ${generators.length} generators, mode: ${aggregationMode}`
-        );
-      }
-      /**
-       * Creates a CompositeGenerator from strategy data.
-       *
-       * This is a convenience factory for use by PipelineAssembler.
-       */
-      static async fromStrategies(user, course, strategies, aggregationMode = DEFAULT_AGGREGATION_MODE) {
-        const generators = await Promise.all(
-          strategies.map((s) => ContentNavigator.create(user, course, s))
-        );
-        return new _CompositeGenerator(generators, aggregationMode);
-      }
-      /**
-       * Get weighted cards from all generators, merge and deduplicate.
-       *
-       * Cards appearing in multiple generators receive a score boost.
-       * Provenance tracks which generators produced each card and how scores were aggregated.
-       *
-       * This method supports both the legacy signature (limit only) and the
-       * CardGenerator interface signature (limit, context).
-       *
-       * @param limit - Maximum number of cards to return
-       * @param context - GeneratorContext passed to child generators (required when called via Pipeline)
-       */
-      async getWeightedCards(limit, context) {
-        if (!context) {
-          throw new Error(
-            "CompositeGenerator.getWeightedCards requires a GeneratorContext. It should be called via Pipeline, not directly."
-          );
-        }
-        const results = await Promise.all(
-          this.generators.map((g) => g.getWeightedCards(limit, context))
-        );
-        const byCardId = /* @__PURE__ */ new Map();
-        for (const cards of results) {
-          for (const card of cards) {
-            const existing = byCardId.get(card.cardId) || [];
-            existing.push(card);
-            byCardId.set(card.cardId, existing);
-          }
-        }
-        const merged = [];
-        for (const [, cards] of byCardId) {
-          const aggregatedScore = this.aggregateScores(cards);
-          const finalScore = Math.min(1, aggregatedScore);
-          const mergedProvenance = cards.flatMap((c) => c.provenance);
-          const initialScore = cards[0].score;
-          const action = finalScore > initialScore ? "boosted" : finalScore < initialScore ? "penalized" : "passed";
-          const reason = this.buildAggregationReason(cards, finalScore);
-          merged.push({
-            ...cards[0],
-            score: finalScore,
-            provenance: [
-              ...mergedProvenance,
-              {
-                strategy: "composite",
-                strategyName: "Composite Generator",
-                strategyId: "COMPOSITE_GENERATOR",
-                action,
-                score: finalScore,
-                reason
-              }
-            ]
-          });
-        }
-        return merged.sort((a, b) => b.score - a.score).slice(0, limit);
+        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 human-readable reason for score aggregation.
+       * Build shared context for generator and filters.
+       *
+       * Called once per getWeightedCards() invocation.
+       * Contains data that the generator and multiple filters might need.
+       *
+       * The context satisfies both GeneratorContext and FilterContext interfaces.
        */
-      buildAggregationReason(cards, finalScore) {
-        const count = cards.length;
-        const scores = cards.map((c) => c.score.toFixed(2)).join(", ");
-        if (count === 1) {
-          return `Single generator, score ${finalScore.toFixed(2)}`;
-        }
-        const strategies = cards.map((c) => c.provenance[0]?.strategy || "unknown").join(", ");
-        switch (this.aggregationMode) {
-          case "max" /* MAX */:
-            return `Max of ${count} generators (${strategies}): scores [${scores}] \u2192 ${finalScore.toFixed(2)}`;
-          case "average" /* AVERAGE */:
-            return `Average of ${count} generators (${strategies}): scores [${scores}] \u2192 ${finalScore.toFixed(2)}`;
-          case "frequencyBoost" /* FREQUENCY_BOOST */: {
-            const avg = cards.reduce((sum, c) => sum + c.score, 0) / count;
-            const boost = 1 + FREQUENCY_BOOST_FACTOR * (count - 1);
-            return `Frequency boost from ${count} generators (${strategies}): avg ${avg.toFixed(2)} \xD7 ${boost.toFixed(2)} \u2192 ${finalScore.toFixed(2)}`;
-          }
-          default:
-            return `Aggregated from ${count} generators: ${finalScore.toFixed(2)}`;
+      async buildContext() {
+        let userElo = 1e3;
+        try {
+          const courseReg = await this.user.getCourseRegDoc(this.course.getCourseID());
+          const courseElo = toCourseElo5(courseReg.elo);
+          userElo = courseElo.global.score;
+        } catch (e) {
+          logger.debug(`[Pipeline] Could not get user ELO, using default: ${e}`);
         }
+        const orchestration = await createOrchestrationContext(this.user, this.course);
+        return {
+          user: this.user,
+          course: this.course,
+          userElo,
+          orchestration
+        };
       }
       /**
-       * Aggregate scores from multiple generators for the same card.
+       * Get the course ID for this pipeline.
        */
-      aggregateScores(cards) {
-        const scores = cards.map((c) => c.score);
-        switch (this.aggregationMode) {
-          case "max" /* MAX */:
-            return Math.max(...scores);
-          case "average" /* AVERAGE */:
-            return scores.reduce((sum, s) => sum + s, 0) / scores.length;
-          case "frequencyBoost" /* FREQUENCY_BOOST */: {
-            const avg = scores.reduce((sum, s) => sum + s, 0) / scores.length;
-            const frequencyBoost = 1 + FREQUENCY_BOOST_FACTOR * (cards.length - 1);
-            return avg * frequencyBoost;
-          }
-          default:
-            return scores[0];
+      getCourseID() {
+        return this.course.getCourseID();
+      }
+      /**
+       * Get orchestration context for outcome recording.
+       */
+      async getOrchestrationContext() {
+        return createOrchestrationContext(this.user, this.course);
+      }
+      /**
+       * Get IDs of all strategies in this pipeline.
+       * Used to record which strategies contributed to an outcome.
+       */
+      getStrategyIds() {
+        const ids = [];
+        const extractId = (obj) => {
+          if (obj.strategyId) return obj.strategyId;
+          return null;
+        };
+        const genId = extractId(this.generator);
+        if (genId) ids.push(genId);
+        if (this.generator.generators && Array.isArray(this.generator.generators)) {
+          this.generator.generators.forEach((g) => {
+            const subId = extractId(g);
+            if (subId) ids.push(subId);
+          });
+        }
+        for (const filter of this.filters) {
+          const fId = extractId(filter);
+          if (fId) ids.push(fId);
         }
+        return [...new Set(ids)];
       }
     };
   }
 });
 
 // src/core/navigators/PipelineAssembler.ts
+var PipelineAssembler_exports = {};
+__export(PipelineAssembler_exports, {
+  PipelineAssembler: () => PipelineAssembler
+});
 var PipelineAssembler;
 var init_PipelineAssembler = __esm({
   "src/core/navigators/PipelineAssembler.ts"() {
     "use strict";
     init_navigators();
+    init_WeightedFilter();
     init_Pipeline();
     init_types_legacy();
     init_logger();
@@ -997,7 +2118,16 @@ var init_PipelineAssembler = __esm({
           try {
             const nav = await ContentNavigator.create(user, course, filterStrategy);
             if ("transform" in nav && typeof nav.transform === "function") {
-              filters.push(nav);
+              let filter = nav;
+              if (filterStrategy.learnable) {
+                filter = new WeightedFilter(
+                  filter,
+                  filterStrategy.learnable,
+                  filterStrategy.staticWeight,
+                  filterStrategy._id
+                );
+              }
+              filters.push(filter);
               logger.debug(`[PipelineAssembler] Added filter: ${filterStrategy.name}`);
             } else {
               warnings.push(
@@ -1008,252 +2138,43 @@ var init_PipelineAssembler = __esm({
             warnings.push(`Failed to instantiate filter '${filterStrategy.name}': ${e}`);
           }
         }
-        const pipeline = new Pipeline(generator, filters, user, course);
-        logger.debug(
-          `[PipelineAssembler] Assembled pipeline with ${generatorStrategies.length} generator(s) and ${filters.length} filter(s)`
-        );
-        return {
-          pipeline,
-          generatorStrategies,
-          filterStrategies: sortedFilterStrategies,
-          warnings
-        };
-      }
-      /**
-       * Creates a default ELO generator strategy.
-       * Used when filters are configured but no generator is specified.
-       */
-      makeDefaultEloStrategy(courseId) {
-        return {
-          _id: "NAVIGATION_STRATEGY-ELO-default",
-          course: courseId,
-          docType: "NAVIGATION_STRATEGY" /* NAVIGATION_STRATEGY */,
-          name: "ELO (default)",
-          description: "Default ELO-based generator",
-          implementingClass: "elo" /* ELO */,
-          serializedData: ""
-        };
-      }
-    };
-  }
-});
-
-// src/core/navigators/generators/elo.ts
-import { toCourseElo as toCourseElo3 } from "@vue-skuilder/common";
-var ELONavigator;
-var init_elo = __esm({
-  "src/core/navigators/generators/elo.ts"() {
-    "use strict";
-    init_navigators();
-    ELONavigator = class extends ContentNavigator {
-      /** Human-readable name for CardGenerator interface */
-      name;
-      constructor(user, course, strategyData) {
-        super(user, course, strategyData);
-        this.name = strategyData?.name || "ELO";
-      }
-      /**
-       * Get new cards with suitability scores based on ELO distance.
-       *
-       * Cards closer to user's ELO get higher scores.
-       * Score formula: max(0, 1 - distance / 500)
-       *
-       * NOTE: This generator only handles NEW cards. Reviews are handled by
-       * SRSNavigator. Use CompositeGenerator to combine both.
-       *
-       * This method supports both the legacy signature (limit only) and the
-       * CardGenerator interface signature (limit, context).
-       *
-       * @param limit - Maximum number of cards to return
-       * @param context - Optional GeneratorContext (used when called via Pipeline)
-       */
-      async getWeightedCards(limit, context) {
-        let userGlobalElo;
-        if (context?.userElo !== void 0) {
-          userGlobalElo = context.userElo;
-        } else {
-          const courseReg = await this.user.getCourseRegDoc(this.course.getCourseID());
-          const userElo = toCourseElo3(courseReg.elo);
-          userGlobalElo = userElo.global.score;
-        }
-        const activeCards = await this.user.getActiveCards();
-        const newCards = (await this.course.getCardsCenteredAtELO(
-          { limit, elo: "user" },
-          (c) => !activeCards.some((ac) => c.cardID === ac.cardID)
-        )).map((c) => ({ ...c, status: "new" }));
-        const cardIds = newCards.map((c) => c.cardID);
-        const cardEloData = await this.course.getCardEloData(cardIds);
-        const scored = newCards.map((c, i) => {
-          const cardElo = cardEloData[i]?.global?.score ?? 1e3;
-          const distance = Math.abs(cardElo - userGlobalElo);
-          const score = Math.max(0, 1 - distance / 500);
-          return {
-            cardId: c.cardID,
-            courseId: c.courseID,
-            score,
-            provenance: [
-              {
-                strategy: "elo",
-                strategyName: this.strategyName || this.name,
-                strategyId: this.strategyId || "NAVIGATION_STRATEGY-ELO-default",
-                action: "generated",
-                score,
-                reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userGlobalElo)}), new card`
-              }
-            ]
-          };
-        });
-        scored.sort((a, b) => b.score - a.score);
-        return scored.slice(0, limit);
-      }
-    };
-  }
-});
-
-// src/core/navigators/generators/srs.ts
-import moment3 from "moment";
-var SRSNavigator;
-var init_srs = __esm({
-  "src/core/navigators/generators/srs.ts"() {
-    "use strict";
-    init_navigators();
-    init_logger();
-    SRSNavigator = class extends ContentNavigator {
-      /** Human-readable name for CardGenerator interface */
-      name;
-      constructor(user, course, strategyData) {
-        super(user, course, strategyData);
-        this.name = strategyData?.name || "SRS";
-      }
-      /**
-       * Get review cards scored by urgency.
-       *
-       * Score formula combines:
-       * - Relative overdueness: hoursOverdue / intervalHours
-       * - Interval recency: exponential decay favoring shorter intervals
-       *
-       * Cards not yet due are excluded (not scored as 0).
-       *
-       * This method supports both the legacy signature (limit only) and the
-       * CardGenerator interface signature (limit, context).
-       *
-       * @param limit - Maximum number of cards to return
-       * @param _context - Optional GeneratorContext (currently unused, but required for interface)
-       */
-      async getWeightedCards(limit, _context) {
-        if (!this.user || !this.course) {
-          throw new Error("SRSNavigator requires user and course to be set");
-        }
-        const reviews = await this.user.getPendingReviews(this.course.getCourseID());
-        const now = moment3.utc();
-        const dueReviews = reviews.filter((r) => now.isAfter(moment3.utc(r.reviewTime)));
-        const scored = dueReviews.map((review) => {
-          const { score, reason } = this.computeUrgencyScore(review, now);
-          return {
-            cardId: review.cardId,
-            courseId: review.courseId,
-            score,
-            reviewID: review._id,
-            provenance: [
-              {
-                strategy: "srs",
-                strategyName: this.strategyName || this.name,
-                strategyId: this.strategyId || "NAVIGATION_STRATEGY-SRS-default",
-                action: "generated",
-                score,
-                reason
-              }
-            ]
-          };
-        });
-        logger.debug(`[srsNav] got ${scored.length} weighted cards`);
-        return scored.sort((a, b) => b.score - a.score).slice(0, limit);
-      }
-      /**
-       * Compute urgency score for a review card.
-       *
-       * Two factors:
-       * 1. Relative overdueness = hoursOverdue / intervalHours
-       *    - 2 days overdue on 3-day interval = 0.67 (urgent)
-       *    - 2 days overdue on 180-day interval = 0.01 (not urgent)
-       *
-       * 2. Interval recency factor = 0.3 + 0.7 * exp(-intervalHours / 720)
-       *    - 24h interval → ~1.0 (very recent learning)
-       *    - 30 days (720h) → ~0.56
-       *    - 180 days → ~0.30
-       *
-       * Combined: base 0.5 + weighted average of factors * 0.45
-       * Result range: approximately 0.5 to 0.95
-       */
-      computeUrgencyScore(review, now) {
-        const scheduledAt = moment3.utc(review.scheduledAt);
-        const due = moment3.utc(review.reviewTime);
-        const intervalHours = Math.max(1, due.diff(scheduledAt, "hours"));
-        const hoursOverdue = now.diff(due, "hours");
-        const relativeOverdue = hoursOverdue / intervalHours;
-        const recencyFactor = 0.3 + 0.7 * Math.exp(-intervalHours / 720);
-        const overdueContribution = Math.min(1, Math.max(0, relativeOverdue));
-        const urgency = overdueContribution * 0.5 + recencyFactor * 0.5;
-        const score = Math.min(0.95, 0.5 + urgency * 0.45);
-        const reason = `${Math.round(hoursOverdue)}h overdue (interval: ${Math.round(intervalHours)}h, relative: ${relativeOverdue.toFixed(2)}), recency: ${recencyFactor.toFixed(2)}, review`;
-        return { score, reason };
+        const pipeline = new Pipeline(generator, filters, user, course);
+        logger.debug(
+          `[PipelineAssembler] Assembled pipeline with ${generatorStrategies.length} generator(s) and ${filters.length} filter(s)`
+        );
+        return {
+          pipeline,
+          generatorStrategies,
+          filterStrategies: sortedFilterStrategies,
+          warnings
+        };
       }
-    };
-  }
-});
-
-// src/core/navigators/filters/eloDistance.ts
-function computeMultiplier(distance, halfLife, minMultiplier, maxMultiplier) {
-  const normalizedDistance = distance / halfLife;
-  const decay = Math.exp(-(normalizedDistance * normalizedDistance));
-  return minMultiplier + (maxMultiplier - minMultiplier) * decay;
-}
-function createEloDistanceFilter(config) {
-  const halfLife = config?.halfLife ?? DEFAULT_HALF_LIFE;
-  const minMultiplier = config?.minMultiplier ?? DEFAULT_MIN_MULTIPLIER;
-  const maxMultiplier = config?.maxMultiplier ?? DEFAULT_MAX_MULTIPLIER;
-  return {
-    name: "ELO Distance Filter",
-    async transform(cards, context) {
-      const { course, userElo } = context;
-      const cardIds = cards.map((c) => c.cardId);
-      const cardElos = await course.getCardEloData(cardIds);
-      return cards.map((card, i) => {
-        const cardElo = cardElos[i]?.global?.score ?? 1e3;
-        const distance = Math.abs(cardElo - userElo);
-        const multiplier = computeMultiplier(distance, halfLife, minMultiplier, maxMultiplier);
-        const newScore = card.score * multiplier;
-        const action = multiplier < maxMultiplier - 0.01 ? "penalized" : "passed";
+      /**
+       * Creates a default ELO generator strategy.
+       * Used when filters are configured but no generator is specified.
+       */
+      makeDefaultEloStrategy(courseId) {
         return {
-          ...card,
-          score: newScore,
-          provenance: [
-            ...card.provenance,
-            {
-              strategy: "eloDistance",
-              strategyName: "ELO Distance Filter",
-              strategyId: "ELO_DISTANCE_FILTER",
-              action,
-              score: newScore,
-              reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userElo)}) \u2192 ${multiplier.toFixed(2)}x`
-            }
-          ]
+          _id: "NAVIGATION_STRATEGY-ELO-default",
+          course: courseId,
+          docType: "NAVIGATION_STRATEGY" /* NAVIGATION_STRATEGY */,
+          name: "ELO (default)",
+          description: "Default ELO-based generator",
+          implementingClass: "elo" /* ELO */,
+          serializedData: ""
         };
-      });
-    }
-  };
-}
-var DEFAULT_HALF_LIFE, DEFAULT_MIN_MULTIPLIER, DEFAULT_MAX_MULTIPLIER;
-var init_eloDistance = __esm({
-  "src/core/navigators/filters/eloDistance.ts"() {
-    "use strict";
-    DEFAULT_HALF_LIFE = 200;
-    DEFAULT_MIN_MULTIPLIER = 0.3;
-    DEFAULT_MAX_MULTIPLIER = 1;
+      }
+    };
   }
 });
 
 // src/core/navigators/defaults.ts
+var defaults_exports = {};
+__export(defaults_exports, {
+  createDefaultEloStrategy: () => createDefaultEloStrategy,
+  createDefaultPipeline: () => createDefaultPipeline,
+  createDefaultSrsStrategy: () => createDefaultSrsStrategy
+});
 function createDefaultEloStrategy(courseId) {
   return {
     _id: "NAVIGATION_STRATEGY-ELO-default",
@@ -1297,12 +2218,310 @@ var init_defaults = __esm({
   }
 });
 
+// import("./**/*") in src/core/navigators/index.ts
+var globImport;
+var init_3 = __esm({
+  'import("./**/*") in src/core/navigators/index.ts'() {
+    globImport = __glob({
+      "./Pipeline.ts": () => Promise.resolve().then(() => (init_Pipeline(), Pipeline_exports)),
+      "./PipelineAssembler.ts": () => Promise.resolve().then(() => (init_PipelineAssembler(), PipelineAssembler_exports)),
+      "./defaults.ts": () => Promise.resolve().then(() => (init_defaults(), defaults_exports)),
+      "./filters/WeightedFilter.ts": () => Promise.resolve().then(() => (init_WeightedFilter(), WeightedFilter_exports)),
+      "./filters/eloDistance.ts": () => Promise.resolve().then(() => (init_eloDistance(), eloDistance_exports)),
+      "./filters/hierarchyDefinition.ts": () => Promise.resolve().then(() => (init_hierarchyDefinition(), hierarchyDefinition_exports)),
+      "./filters/index.ts": () => Promise.resolve().then(() => (init_filters(), filters_exports)),
+      "./filters/inferredPreferenceStub.ts": () => Promise.resolve().then(() => (init_inferredPreferenceStub(), inferredPreferenceStub_exports)),
+      "./filters/interferenceMitigator.ts": () => Promise.resolve().then(() => (init_interferenceMitigator(), interferenceMitigator_exports)),
+      "./filters/relativePriority.ts": () => Promise.resolve().then(() => (init_relativePriority(), relativePriority_exports)),
+      "./filters/types.ts": () => Promise.resolve().then(() => (init_types2(), types_exports2)),
+      "./filters/userGoalStub.ts": () => Promise.resolve().then(() => (init_userGoalStub(), userGoalStub_exports)),
+      "./filters/userTagPreference.ts": () => Promise.resolve().then(() => (init_userTagPreference(), userTagPreference_exports)),
+      "./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/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))
+    });
+  }
+});
+
+// src/core/navigators/index.ts
+var navigators_exports = {};
+__export(navigators_exports, {
+  ContentNavigator: () => ContentNavigator,
+  NavigatorRole: () => NavigatorRole,
+  NavigatorRoles: () => NavigatorRoles,
+  Navigators: () => Navigators,
+  getCardOrigin: () => getCardOrigin,
+  getRegisteredNavigator: () => getRegisteredNavigator,
+  getRegisteredNavigatorNames: () => getRegisteredNavigatorNames,
+  hasRegisteredNavigator: () => hasRegisteredNavigator,
+  initializeNavigatorRegistry: () => initializeNavigatorRegistry,
+  isFilter: () => isFilter,
+  isGenerator: () => isGenerator,
+  registerNavigator: () => registerNavigator
+});
+function registerNavigator(implementingClass, constructor) {
+  navigatorRegistry.set(implementingClass, constructor);
+  logger.debug(`[NavigatorRegistry] Registered: ${implementingClass}`);
+}
+function getRegisteredNavigator(implementingClass) {
+  return navigatorRegistry.get(implementingClass);
+}
+function hasRegisteredNavigator(implementingClass) {
+  return navigatorRegistry.has(implementingClass);
+}
+function getRegisteredNavigatorNames() {
+  return Array.from(navigatorRegistry.keys());
+}
+async function initializeNavigatorRegistry() {
+  logger.debug("[NavigatorRegistry] Initializing built-in navigators...");
+  const [eloModule, srsModule] = await Promise.all([
+    Promise.resolve().then(() => (init_elo(), elo_exports)),
+    Promise.resolve().then(() => (init_srs(), srs_exports))
+  ]);
+  registerNavigator("elo", eloModule.default);
+  registerNavigator("srs", srsModule.default);
+  const [
+    hierarchyModule,
+    interferenceModule,
+    relativePriorityModule,
+    userTagPreferenceModule
+  ] = await Promise.all([
+    Promise.resolve().then(() => (init_hierarchyDefinition(), hierarchyDefinition_exports)),
+    Promise.resolve().then(() => (init_interferenceMitigator(), interferenceMitigator_exports)),
+    Promise.resolve().then(() => (init_relativePriority(), relativePriority_exports)),
+    Promise.resolve().then(() => (init_userTagPreference(), userTagPreference_exports))
+  ]);
+  registerNavigator("hierarchyDefinition", hierarchyModule.default);
+  registerNavigator("interferenceMitigator", interferenceModule.default);
+  registerNavigator("relativePriority", relativePriorityModule.default);
+  registerNavigator("userTagPreference", userTagPreferenceModule.default);
+  logger.debug(
+    `[NavigatorRegistry] Initialized ${navigatorRegistry.size} navigators: ${getRegisteredNavigatorNames().join(", ")}`
+  );
+}
+function getCardOrigin(card) {
+  if (card.provenance.length === 0) {
+    throw new Error("Card has no provenance - cannot determine origin");
+  }
+  const firstEntry = card.provenance[0];
+  const reason = firstEntry.reason.toLowerCase();
+  if (reason.includes("failed")) {
+    return "failed";
+  }
+  if (reason.includes("review")) {
+    return "review";
+  }
+  return "new";
+}
+function isGenerator(impl) {
+  return NavigatorRoles[impl] === "generator" /* GENERATOR */;
+}
+function isFilter(impl) {
+  return NavigatorRoles[impl] === "filter" /* FILTER */;
+}
+var navigatorRegistry, Navigators, NavigatorRole, NavigatorRoles, ContentNavigator;
+var init_navigators = __esm({
+  "src/core/navigators/index.ts"() {
+    "use strict";
+    init_logger();
+    init_();
+    init_2();
+    init_3();
+    navigatorRegistry = /* @__PURE__ */ new Map();
+    Navigators = /* @__PURE__ */ ((Navigators2) => {
+      Navigators2["ELO"] = "elo";
+      Navigators2["SRS"] = "srs";
+      Navigators2["HIERARCHY"] = "hierarchyDefinition";
+      Navigators2["INTERFERENCE"] = "interferenceMitigator";
+      Navigators2["RELATIVE_PRIORITY"] = "relativePriority";
+      Navigators2["USER_TAG_PREFERENCE"] = "userTagPreference";
+      return Navigators2;
+    })(Navigators || {});
+    NavigatorRole = /* @__PURE__ */ ((NavigatorRole2) => {
+      NavigatorRole2["GENERATOR"] = "generator";
+      NavigatorRole2["FILTER"] = "filter";
+      return NavigatorRole2;
+    })(NavigatorRole || {});
+    NavigatorRoles = {
+      ["elo" /* ELO */]: "generator" /* GENERATOR */,
+      ["srs" /* SRS */]: "generator" /* GENERATOR */,
+      ["hierarchyDefinition" /* HIERARCHY */]: "filter" /* FILTER */,
+      ["interferenceMitigator" /* INTERFERENCE */]: "filter" /* FILTER */,
+      ["relativePriority" /* RELATIVE_PRIORITY */]: "filter" /* FILTER */,
+      ["userTagPreference" /* USER_TAG_PREFERENCE */]: "filter" /* FILTER */
+    };
+    ContentNavigator = class {
+      /** User interface for this navigation session */
+      user;
+      /** Course interface for this navigation session */
+      course;
+      /** Human-readable name for this strategy instance (from ContentNavigationStrategyData.name) */
+      strategyName;
+      /** Unique document ID for this strategy instance (from ContentNavigationStrategyData._id) */
+      strategyId;
+      /** Evolutionary weighting configuration */
+      learnable;
+      /** Whether to bypass deviation (manual/static weighting) */
+      staticWeight;
+      /**
+       * Constructor for standard navigators.
+       * Call this from subclass constructors to initialize common fields.
+       *
+       * Note: CompositeGenerator and Pipeline call super() without args, then set
+       * user/course fields directly if needed.
+       */
+      constructor(user, course, strategyData) {
+        this.user = user;
+        this.course = course;
+        if (strategyData) {
+          this.strategyName = strategyData.name;
+          this.strategyId = strategyData._id;
+          this.learnable = strategyData.learnable;
+          this.staticWeight = strategyData.staticWeight;
+        }
+      }
+      // ============================================================================
+      // 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.
+       *
+       * First checks the navigator registry for a pre-registered constructor.
+       * If not found, falls back to dynamic import (for custom navigators).
+       *
+       * For reliable operation in test environments, call initializeNavigatorRegistry()
+       * before using this method.
+       *
+       * @param user - User interface
+       * @param course - Course interface
+       * @param strategyData - Strategy configuration document
+       * @returns the runtime object used to steer a study session.
+       */
+      static async create(user, course, strategyData) {
+        const implementingClass = strategyData.implementingClass;
+        const RegisteredImpl = getRegisteredNavigator(implementingClass);
+        if (RegisteredImpl) {
+          logger.debug(`[ContentNavigator.create] Using registered navigator: ${implementingClass}`);
+          return new RegisteredImpl(user, course, strategyData);
+        }
+        logger.debug(
+          `[ContentNavigator.create] Navigator not in registry, attempting dynamic import: ${implementingClass}`
+        );
+        let NavigatorImpl;
+        const variations = [".ts", ".js", ""];
+        for (const ext of variations) {
+          try {
+            const module = await globImport_generators(`./generators/${implementingClass}${ext}`);
+            NavigatorImpl = module.default;
+            if (NavigatorImpl) break;
+          } catch (e) {
+            logger.debug(`Failed to load generator ${implementingClass}${ext}:`, e);
+          }
+          try {
+            const module = await globImport_filters(`./filters/${implementingClass}${ext}`);
+            NavigatorImpl = module.default;
+            if (NavigatorImpl) break;
+          } catch (e) {
+            logger.debug(`Failed to load filter ${implementingClass}${ext}:`, e);
+          }
+          try {
+            const module = await globImport(`./${implementingClass}${ext}`);
+            NavigatorImpl = module.default;
+            if (NavigatorImpl) break;
+          } catch (e) {
+            logger.debug(`Failed to load legacy ${implementingClass}${ext}:`, e);
+          }
+          if (NavigatorImpl) break;
+        }
+        if (!NavigatorImpl) {
+          throw new Error(`Could not load navigator implementation for: ${implementingClass}`);
+        }
+        return new NavigatorImpl(user, course, strategyData);
+      }
+      /**
+       * Get cards with suitability scores and provenance trails.
+       *
+       * **This is the PRIMARY API for navigation strategies.**
+       *
+       * Returns cards ranked by suitability score (0-1). Higher scores indicate
+       * better candidates for presentation. Each card includes a provenance trail
+       * documenting how strategies contributed to the final score.
+       *
+       * ## Implementation Required
+       * All navigation strategies MUST override this method. The base class does
+       * not provide a default implementation.
+       *
+       * ## For Generators
+       * Override this method to generate candidates and compute scores based on
+       * your strategy's logic (e.g., ELO proximity, review urgency). Create the
+       * initial provenance entry with action='generated'.
+       *
+       * ## For Filters
+       * Filters should implement the CardFilter interface instead and be composed
+       * via Pipeline. Filters do not directly implement getWeightedCards().
+       *
+       * @param limit - Maximum cards to return
+       * @returns Cards sorted by score descending, with provenance trails
+       */
+      async getWeightedCards(_limit) {
+        throw new Error(`${this.constructor.name} must implement getWeightedCards(). `);
+      }
+    };
+  }
+});
+
 // src/impl/couch/courseDB.ts
 import {
   EloToNumber,
   Status,
   blankCourseElo as blankCourseElo2,
-  toCourseElo as toCourseElo4
+  toCourseElo as toCourseElo6
 } from "@vue-skuilder/common";
 var init_courseDB = __esm({
   "src/impl/couch/courseDB.ts"() {
@@ -2445,6 +3664,19 @@ Currently logged-in as ${this._username}.`
         };
         await this.localDB.put(doc);
       }
+      async putUserOutcome(record) {
+        try {
+          await this.localDB.put(record);
+        } catch (err) {
+          if (err.status === 409) {
+            const existing = await this.localDB.get(record._id);
+            record._rev = existing._rev;
+            await this.localDB.put(record);
+          } else {
+            throw err;
+          }
+        }
+      }
       async deleteStrategyState(courseId, strategyKey) {
         const docId = buildStrategyStateId(courseId, strategyKey);
         try {
@@ -2481,6 +3713,7 @@ var init_factory = __esm({
     "use strict";
     init_common();
     init_logger();
+    init_navigators();
     NOT_SET = "NOT_SET";
     ENV = {
       COUCHDB_SERVER_PROTOCOL: NOT_SET,
@@ -2562,6 +3795,13 @@ var init_strategyState = __esm({
   }
 });
 
+// src/core/types/userOutcome.ts
+var init_userOutcome = __esm({
+  "src/core/types/userOutcome.ts"() {
+    "use strict";
+  }
+});
+
 // src/core/bulkImport/cardProcessor.ts
 import { Status as Status4 } from "@vue-skuilder/common";
 var init_cardProcessor = __esm({
@@ -2572,7 +3812,7 @@ var init_cardProcessor = __esm({
 });
 
 // src/core/bulkImport/types.ts
-var init_types = __esm({
+var init_types3 = __esm({
   "src/core/bulkImport/types.ts"() {
     "use strict";
   }
@@ -2583,7 +3823,7 @@ var init_bulkImport = __esm({
   "src/core/bulkImport/index.ts"() {
     "use strict";
     init_cardProcessor();
-    init_types();
+    init_types3();
   }
 });
 
@@ -2595,10 +3835,12 @@ var init_core = __esm({
     init_types_legacy();
     init_user();
     init_strategyState();
+    init_userOutcome();
     init_Loggable();
     init_util();
     init_navigators();
     init_bulkImport();
+    init_orchestration();
   }
 });