@vue-skuilder/db 0.2.1 → 0.2.3

package/dist/index.mjs

@@ -1959,10 +1959,8 @@ var init_elo = __esm({
           { 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 scored = newCards.map((c) => {
+          const cardElo = c.elo ?? 1e3;
           const distance = Math.abs(cardElo - userGlobalElo);
           const rawScore = Math.max(0, 1 - distance / 500);
           const samplingKey = rawScore > 0 ? Math.random() ** (1 / rawScore) : 0;
@@ -4186,7 +4184,8 @@ var init_orchestration = __esm({
 // src/core/navigators/Pipeline.ts
 var Pipeline_exports = {};
 __export(Pipeline_exports, {
-  Pipeline: () => Pipeline
+  Pipeline: () => Pipeline,
+  mergeHints: () => mergeHints2
 });
 import { toCourseElo as toCourseElo5 } from "@vue-skuilder/common";
 function globToRegex(pattern) {
@@ -5883,6 +5882,7 @@ ${above.rows.map((r) => `	${r.id}-${r.key}
       }
       async addNavigationStrategy(data) {
         logger.debug(`[courseDB] Adding navigation strategy: ${data._id}`);
+        this.invalidateNavigatorCache();
         return this.remoteDB.put(data).then(() => {
         });
       }
@@ -5949,23 +5949,67 @@ ${e.stack}` : JSON.stringify(e);
        * @returns Cards sorted by score descending
        */
       _pendingHints = null;
+      /**
+       * Session-scoped cache of the broad ELO-neighbor pool used by
+       * getCardsCenteredAtELO. The `elo` view query re-indexes on first touch per
+       * call (PouchDB 9 ignores `stale`), so without this each plan/replan pays
+       * ~1.5-2s. The pool is fetched once and re-ranked against the live (roaming)
+       * ELO in memory on subsequent calls.
+       */
+      _eloPoolCache = null;
+      _eloPoolTtlMs = 5 * 60 * 1e3;
+      /**
+       * Cached assembled navigator (Pipeline). createNavigator() reads strategy
+       * docs and builds a fresh Pipeline every call — whose internal `_tagCache`
+       * and `_cachedOrchestration` are designed to make replans cheap but never
+       * survive, because the instance is discarded each run. Caching it lets those
+       * caches persist across plan/replan within a session (SessionController holds
+       * one CourseDB instance for the session's lifetime). Rebuilt on user change,
+       * TTL expiry, or explicit invalidation after a strategy-doc write.
+       */
+      _cachedNavigator = null;
+      _navigatorTtlMs = 5 * 60 * 1e3;
       setEphemeralHints(hints) {
         this._pendingHints = hints;
       }
       async getWeightedCards(limit) {
         const u = await this._getCurrentUser();
         try {
-          const navigator2 = await this.createNavigator(u);
+          const { navigator: navigator2 } = await this._getCachedNavigator(u);
           if (this._pendingHints) {
             navigator2.setEphemeralHints(this._pendingHints);
             this._pendingHints = null;
           }
-          return navigator2.getWeightedCards(limit);
+          const result = await navigator2.getWeightedCards(limit);
+          return result;
         } catch (e) {
           logger.error(`[courseDB] Error getting weighted cards: ${e}`);
           throw e;
         }
       }
+      /**
+       * Return the assembled navigator, reusing the cached instance when possible.
+       * Reuse preserves the Pipeline's per-session caches (tags, orchestration
+       * context) across replans, which is the dominant per-replan cost once the
+       * ELO-pool cost is removed. Rebuilds on user change or TTL expiry.
+       */
+      async _getCachedNavigator(user) {
+        const userId = user.getUsername();
+        const now = Date.now();
+        if (this._cachedNavigator && this._cachedNavigator.userId === userId && now - this._cachedNavigator.builtAt < this._navigatorTtlMs) {
+          return { navigator: this._cachedNavigator.navigator, cacheStatus: "hit" };
+        }
+        const navigator2 = await this.createNavigator(user);
+        this._cachedNavigator = { navigator: navigator2, userId, builtAt: now };
+        return { navigator: navigator2, cacheStatus: "miss" };
+      }
+      /**
+       * Drop the cached navigator so the next getWeightedCards() rebuilds it.
+       * Call after mutating this course's navigation strategy documents.
+       */
+      invalidateNavigatorCache() {
+        this._cachedNavigator = null;
+      }
       async getCardsCenteredAtELO(options = {
         limit: 99,
         elo: "user"
@@ -5988,20 +6032,31 @@ ${e.stack}` : JSON.stringify(e);
         } else {
           targetElo = options.elo;
         }
-        let cards = [];
-        let mult = 4;
-        let previousCount = -1;
-        let newCount = 0;
-        while (cards.length < options.limit && newCount !== previousCount) {
-          cards = await this.getCardsByELO(targetElo, mult * options.limit);
-          previousCount = newCount;
-          newCount = cards.length;
-          logger.debug(`Found ${cards.length} elo neighbor cards...`);
-          if (filter) {
-            cards = cards.filter(filter);
-            logger.debug(`Filtered to ${cards.length} cards...`);
-          }
-          mult *= 2;
+        const POOL_SIZE = Math.max(2e3, options.limit * 4);
+        const nowMs = Date.now();
+        let cacheStatus = "hit";
+        if (!this._eloPoolCache || nowMs - this._eloPoolCache.fetchedAt > this._eloPoolTtlMs) {
+          const fetched = await this.getCardsByELO(targetElo, POOL_SIZE);
+          if (fetched.length > 0) {
+            this._eloPoolCache = { rows: fetched, fetchedAt: nowMs };
+          }
+          cacheStatus = "miss";
+        }
+        const rankAgainstCurrentElo = () => {
+          const raw = this._eloPoolCache?.rows ?? [];
+          const survivors = filter ? raw.filter((c) => filter(c)) : raw;
+          return survivors.map((c) => ({ ...c })).sort(
+            (a, b) => Math.abs((a.elo ?? targetElo) - targetElo) - Math.abs((b.elo ?? targetElo) - targetElo)
+          );
+        };
+        let cards = rankAgainstCurrentElo();
+        if (cards.length < options.limit && (cacheStatus === "hit" || !this._eloPoolCache)) {
+          const fetched = await this.getCardsByELO(targetElo, POOL_SIZE);
+          if (fetched.length > 0) {
+            this._eloPoolCache = { rows: fetched, fetchedAt: nowMs };
+          }
+          cards = rankAgainstCurrentElo();
+          cacheStatus = "refresh";
         }
         const selectedCards = [];
         while (selectedCards.length < options.limit && cards.length > 0) {
@@ -11188,6 +11243,7 @@ var ItemQueue = class {
 
 // src/study/SessionController.ts
 init_couch();
+init_core();
 init_recording();
 
 // src/util/index.ts
@@ -12614,6 +12670,7 @@ init_dataDirectory();
 
 // src/study/SessionController.ts
 init_navigators();
+init_Pipeline();
 
 // src/study/SourceMixer.ts
 var QuotaRoundRobinMixer = class {
@@ -13325,6 +13382,32 @@ var SessionController = class _SessionController extends Loggable {
    * each nextCard() draw. Set by replans that include `minFollowUpCards`.
    */
   _minCardsGuarantee = 0;
+  /**
+   * Session-durable scoring hints. Re-merged into every pipeline run for
+   * the rest of the session (initial plan + every replan, including bare
+   * auto-replans and the wedge-breaker), via `_applyHintsToSources`.
+   *
+   * Set by `setSessionHints()` (e.g. session-start post-lesson boost) or by
+   * any replan carrying `ReplanOptions.sessionHints` (e.g. a just-failed
+   * concept boost). Replace semantics, no decay — lives until overwritten
+   * or session end. See `ReplanOptions.sessionHints` for rationale.
+   *
+   * Note: the controller-managed auto-excludes (current card, session
+   * record, imminent draw) are intentionally NOT folded in here — those are
+   * recomputed per-run in `_runReplan` and would otherwise go stale.
+   */
+  _sessionHints = null;
+  /**
+   * Consumer-supplied hooks invoked after each question response is processed.
+   * Seeded from constructor options (threaded from
+   * `StudySessionConfig.outcomeObservers`). See {@link OutcomeObserver}.
+   */
+  _outcomeObservers = [];
+  /**
+   * Lazily-built, stable capability object handed to observers. Bound to
+   * `this`; constructed once so observers can rely on referential identity.
+   */
+  _sessionControls = null;
   startTime;
   endTime;
   _secondsRemaining;
@@ -13384,6 +13467,9 @@ var SessionController = class _SessionController extends Loggable {
     if (options?.initialReviewCap !== void 0) {
       this._initialReviewCap = options.initialReviewCap;
     }
+    if (options?.outcomeObservers?.length) {
+      this._outcomeObservers = [...options.outcomeObservers];
+    }
     this.log(`Session constructed:
     startTime: ${this.startTime}
     endTime: ${this.endTime}
@@ -13511,6 +13597,7 @@ var SessionController = class _SessionController extends Loggable {
     if (opts.minFollowUpCards !== void 0) return true;
     if (opts.mode && opts.mode !== "replace") return true;
     if (opts.hints && Object.keys(opts.hints).length > 0) return true;
+    if (opts.sessionHints !== void 0) return true;
     return false;
   }
   /**
@@ -13539,12 +13626,13 @@ var SessionController = class _SessionController extends Loggable {
       excludeSet.add(this.newQ.peek(0).cardID);
     }
     hints.excludeCards = [...excludeSet];
-    if (opts.hints) {
-      const hintsWithLabel = opts.label ? { ...opts.hints, _label: opts.label } : opts.hints;
-      for (const source of this.sources) {
-        source.setEphemeralHints?.(hintsWithLabel);
-      }
+    if (opts.sessionHints !== void 0) {
+      this._sessionHints = opts.sessionHints;
+      this.log(
+        `[Replan] Session hints ${opts.sessionHints ? "set" : "cleared"}: ${JSON.stringify(opts.sessionHints)}`
+      );
     }
+    this._applyHintsToSources(opts.hints, opts.label);
     const labelTag = opts.label ? ` [${opts.label}]` : "";
     this.log(
       `Mid-session replan requested${labelTag} (limit: ${opts.limit ?? "default"}, mode: ${opts.mode ?? "replace"}${opts.hints ? ", with hints" : ""})`
@@ -13555,6 +13643,100 @@ var SessionController = class _SessionController extends Loggable {
     }
     await this._executeReplan(opts);
   }
+  /**
+   * Set the session-durable scoring hints (replace semantics, no decay).
+   *
+   * Unlike a one-shot replan hint, these are re-merged into every pipeline
+   * run for the rest of the session — including the initial plan when set
+   * before `prepareSession()`, every replan, the bare auto-replans, and the
+   * wedge-breaker. Pass `null` to clear.
+   *
+   * Typical callers:
+   * - `StudySession` at session start, threading `StudySessionConfig.initHints`
+   *   (e.g. a post-lesson concept boost) — so the boost outlives the first
+   *   queue rebuild instead of being clobbered by the first auto-replan.
+   * - A consumer view on a failure, boosting the just-failed concept tag.
+   *
+   * Does not itself trigger a replan; the next plan/replan picks it up.
+   */
+  setSessionHints(hints) {
+    this._sessionHints = hints;
+    this.log(`Session hints ${hints ? "set" : "cleared"}: ${JSON.stringify(hints)}`);
+  }
+  /**
+   * Read the current session-durable hints (for read-modify-write callers,
+   * e.g. an outcome observer that clamps a compounding boost).
+   */
+  getSessionHints() {
+    return this._sessionHints;
+  }
+  /**
+   * Merge `hints` into the durable session hints via the pipeline's
+   * `mergeHints` (boosts multiply, require/exclude lists concat-dedup).
+   * Convenience over get-then-set for the common additive case. Note the
+   * multiplicative, no-decay semantics — clamp boost factors at the call
+   * site if a repeatedly-emphasised tag could compound unboundedly.
+   */
+  mergeSessionHints(hints) {
+    this._sessionHints = mergeHints2([this._sessionHints, hints]) ?? null;
+    this.log(`Session hints merged: ${JSON.stringify(this._sessionHints)}`);
+  }
+  /**
+   * Merge the durable `_sessionHints` with this run's one-shot hints and
+   * push the result to every source for consumption on the next pipeline
+   * run. Centralised so the initial plan and all replan paths apply session
+   * emphasis identically. No-op when there are no hints of either kind.
+   */
+  _applyHintsToSources(oneShot, label) {
+    const oneShotWithLabel = oneShot && label ? { ...oneShot, _label: label } : oneShot;
+    const merged = mergeHints2([this._sessionHints, oneShotWithLabel]);
+    if (!merged) return;
+    for (const source of this.sources) {
+      source.setEphemeralHints?.(merged);
+    }
+  }
+  /**
+   * Build (once) the stable capability object handed to outcome observers.
+   * Methods are bound to `this`; the object identity is stable across calls
+   * so observers may key off it.
+   */
+  _getSessionControls() {
+    if (!this._sessionControls) {
+      this._sessionControls = {
+        getSessionHints: () => this.getSessionHints(),
+        setSessionHints: (h) => this.setSessionHints(h),
+        mergeSessionHints: (h) => this.mergeSessionHints(h),
+        requestReplan: (opts) => this.requestReplan(opts)
+      };
+    }
+    return this._sessionControls;
+  }
+  /**
+   * Notify registered outcome observers about a processed response.
+   *
+   * Only question records are surfaced (non-question dismisses are skipped).
+   * Observers run after ELO/SRS are recorded and before navigation. Each is
+   * awaited but isolated in try/catch — a throwing observer is logged and
+   * skipped, never wedging the session. Keep observers cheap and `void` any
+   * long work (e.g. a triggered replan) to avoid stalling the draw.
+   */
+  async _notifyOutcomeObservers(record, currentCard, result) {
+    if (this._outcomeObservers.length === 0) return;
+    if (!isQuestionRecord(record)) return;
+    const outcome = {
+      record,
+      card: currentCard.card,
+      result
+    };
+    const controls = this._getSessionControls();
+    for (const observer of this._outcomeObservers) {
+      try {
+        await observer(outcome, controls);
+      } catch (e) {
+        this.error("[OutcomeObserver] observer threw; ignoring", e);
+      }
+    }
+  }
   /**
    * Run a replan, bypassing requestReplan()'s coalesce logic.
    *
@@ -13582,7 +13764,7 @@ var SessionController = class _SessionController extends Loggable {
    */
   normalizeReplanOptions(input) {
     if (!input) return {};
-    const replanKeys = ["hints", "limit", "mode", "label", "minFollowUpCards"];
+    const replanKeys = ["hints", "sessionHints", "limit", "mode", "label", "minFollowUpCards"];
     const inputKeys = Object.keys(input);
     if (inputKeys.some((k) => replanKeys.includes(k))) {
       return input;
@@ -13734,6 +13916,9 @@ var SessionController = class _SessionController extends Loggable {
     const additive = options?.additive ?? false;
     const newLimit = options?.limit ?? this._defaultBatchLimit;
     const fetchLimit = replan ? newLimit : newLimit + this._initialReviewCap;
+    if (!replan) {
+      this._applyHintsToSources();
+    }
     const batches = [];
     for (let i = 0; i < this.sources.length; i++) {
       const source = this.sources[i];
@@ -14014,7 +14199,7 @@ var SessionController = class _SessionController extends Loggable {
     const studySessionItem = {
       ...currentCard.item
     };
-    return await this.services.response.processResponse(
+    const result = await this.services.response.processResponse(
       cardRecord,
       cardHistory,
       studySessionItem,
@@ -14026,6 +14211,8 @@ var SessionController = class _SessionController extends Loggable {
       maxSessionViews,
       sessionViews
     );
+    await this._notifyOutcomeObservers(cardRecord, currentCard, result);
+    return result;
   }
   dismissCurrentCard(action = "dismiss-success") {
     if (this._currentCard) {