@vue-skuilder/db 0.2.0 → 0.2.2

package/dist/index.d.cts

@@ -544,6 +544,19 @@ declare class SessionController<TView = unknown> extends Loggable {
      * know or care which strategy assigned the score.
      */
     private static readonly WELL_INDICATED_SCORE;
+    /**
+     * newQ length at or below which the opportunistic depletion-prefetch
+     * fires. Sets the lead time available for the background replan to land
+     * before the user actually empties the queue and falls into the
+     * (synchronous) wedge-breaker path.
+     *
+     * Set to a small absolute value (not a fraction of batch limit) because
+     * pipeline latency is roughly fixed regardless of batch size — what
+     * matters is "how many cards of user-pace do we have left." 3 cards
+     * × ~3-5s/card = ~10-15s of lead time, comfortably exceeding typical
+     * pipeline latency.
+     */
+    private static readonly DEPLETION_PREFETCH_THRESHOLD;
     /**
      * Internal replan execution. Runs the pipeline, builds a new newQ,
      * atomically swaps it in, and triggers hydration for the new contents.

package/dist/index.d.ts

@@ -544,6 +544,19 @@ declare class SessionController<TView = unknown> extends Loggable {
      * know or care which strategy assigned the score.
      */
     private static readonly WELL_INDICATED_SCORE;
+    /**
+     * newQ length at or below which the opportunistic depletion-prefetch
+     * fires. Sets the lead time available for the background replan to land
+     * before the user actually empties the queue and falls into the
+     * (synchronous) wedge-breaker path.
+     *
+     * Set to a small absolute value (not a fraction of batch limit) because
+     * pipeline latency is roughly fixed regardless of batch size — what
+     * matters is "how many cards of user-pace do we have left." 3 cards
+     * × ~3-5s/card = ~10-15s of lead time, comfortably exceeding typical
+     * pipeline latency.
+     */
+    private static readonly DEPLETION_PREFETCH_THRESHOLD;
     /**
      * Internal replan execution. Runs the pipeline, builds a new newQ,
      * atomically swaps it in, and triggers hydration for the new contents.

package/dist/index.js

@@ -1982,10 +1982,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;
@@ -5901,6 +5899,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(() => {
         });
       }
@@ -5967,23 +5966,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"
@@ -6006,20 +6049,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) {
@@ -9835,9 +9889,14 @@ var init_UserDBDebugger = __esm({
        */
       async showScheduledReviews(courseId) {
         const userDB = getUserDB();
-        if (!userDB) return;
+        if (!userDB) {
+          logger.info("[UserDB Debug] Data layer not available");
+          return;
+        }
+        logger.info(`[UserDB Debug] Fetching pending reviews${courseId ? ` for course: ${courseId}` : ""}...`);
         try {
           const reviews = await userDB.getPendingReviews(courseId);
+          logger.info(`[UserDB Debug] Got ${reviews.length} reviews`);
           console.group(`\u{1F4C5} Scheduled Reviews${courseId ? ` (${courseId})` : ""}`);
           logger.info(`Total: ${reviews.length}`);
           if (reviews.length > 0) {
@@ -13696,6 +13755,19 @@ var SessionController = class _SessionController extends Loggable {
    * know or care which strategy assigned the score.
    */
   static WELL_INDICATED_SCORE = 0.1;
+  /**
+   * newQ length at or below which the opportunistic depletion-prefetch
+   * fires. Sets the lead time available for the background replan to land
+   * before the user actually empties the queue and falls into the
+   * (synchronous) wedge-breaker path.
+   *
+   * Set to a small absolute value (not a fraction of batch limit) because
+   * pipeline latency is roughly fixed regardless of batch size — what
+   * matters is "how many cards of user-pace do we have left." 3 cards
+   * × ~3-5s/card = ~10-15s of lead time, comfortably exceeding typical
+   * pipeline latency.
+   */
+  static DEPLETION_PREFETCH_THRESHOLD = 3;
   /**
    * Internal replan execution. Runs the pipeline, builds a new newQ,
    * atomically swaps it in, and triggers hydration for the new contents.
@@ -14002,7 +14074,7 @@ var SessionController = class _SessionController extends Loggable {
       this.log("nextCard: queues empty, awaiting in-flight replan before drawing");
       await this._replanPromise;
     }
-    if (this.newQ.length <= 1 && this._secondsRemaining > 0 && !this._replanPromise) {
+    if (this.newQ.length <= _SessionController.DEPLETION_PREFETCH_THRESHOLD && this._secondsRemaining > 0 && !this._replanPromise) {
       this._suppressQualityReplan = false;
       const otherContent = this.reviewQ.length + this.failedQ.length;
       this.log(