@vue-skuilder/db 0.2.0 → 0.2.2

package/src/impl/couch/courseDB.ts

@@ -302,11 +302,19 @@ export class CourseDB implements CourseDBInterface {
     elo = parseInt(elo as any);
     const limit = cardLimit ? cardLimit : 25;
 
+    // const tQ0 = performance.now();
+    // NOTE: `stale: 'update_after'` was tried here and removed — it gave no
+    // measurable speedup (PouchDB 9 effectively ignores it for the reindex
+    // cost) AND it can return an empty result on the first query after a cold
+    // DB open (index not yet loaded), which then poisons the pool cache. The
+    // session pool cache (see getCardsCenteredAtELO) is what removes the
+    // per-run cost, so we read the view normally (always-fresh) here.
     const below: PouchDB.Query.Response<object> = await this.db.query('elo', {
       limit: Math.ceil(limit / 2),
       startkey: elo,
       descending: true,
     });
+    // const tBelowQ = performance.now();
 
     const aboveLimit = limit - below.rows.length;
 
@@ -314,7 +322,13 @@ export class CourseDB implements CourseDBInterface {
       limit: aboveLimit,
       startkey: elo + 1,
     });
-    // logger.log(JSON.stringify(below));
+    // const tAbove = performance.now();
+    // [perf] parked: getCardsByELO view-query timing (below/above split)
+    // logger.info(
+      // `[perf][getCardsByELO] reqLimit=${limit} ` +
+        // `below=${(tBelowQ - tQ0).toFixed(0)}ms(${below.rows.length}r) ` +
+        // `above=${(tAbove - tBelowQ).toFixed(0)}ms(${above.rows.length}r)`
+    // );
 
     let cards = below.rows;
     cards = cards.concat(above.rows);
@@ -573,6 +587,8 @@ above:\n${above.rows.map((r) => `\t${r.id}-${r.key}\n`)}`;
 
   async addNavigationStrategy(data: ContentNavigationStrategyData): Promise<void> {
     logger.debug(`[courseDB] Adding navigation strategy: ${data._id}`);
+    // Strategy set changed — drop the cached navigator so it rebuilds.
+    this.invalidateNavigatorCache();
     // Admin write operation — use remote DB.
     return this.remoteDB.put(data).then(() => {});
   }
@@ -654,6 +670,35 @@ above:\n${above.rows.map((r) => `\t${r.id}-${r.key}\n`)}`;
    */
   private _pendingHints: ReplanHints | null = 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.
+   */
+  private _eloPoolCache: {
+    rows: (QualifiedCardID & { elo?: number })[];
+    fetchedAt: number;
+  } | null = null;
+  private readonly _eloPoolTtlMs = 5 * 60 * 1000;
+
+  /**
+   * 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.
+   */
+  private _cachedNavigator: {
+    navigator: ContentNavigator;
+    userId: string;
+    builtAt: number;
+  } | null = null;
+  private readonly _navigatorTtlMs = 5 * 60 * 1000;
+
   public setEphemeralHints(hints: ReplanHints): void {
     this._pendingHints = hints;
   }
@@ -662,18 +707,60 @@ above:\n${above.rows.map((r) => `\t${r.id}-${r.key}\n`)}`;
     const u = await this._getCurrentUser();
 
     try {
-      const navigator = await this.createNavigator(u);
+      // const tNav0 = performance.now(); // [perf] parked
+      const { navigator } = await this._getCachedNavigator(u);
+      // const tNav1 = performance.now(); // [perf] parked
       if (this._pendingHints) {
         navigator.setEphemeralHints(this._pendingHints);
         this._pendingHints = null;
       }
-      return navigator.getWeightedCards(limit);
+      const result = await navigator.getWeightedCards(limit);
+      // const tRun = performance.now(); // [perf] parked
+      // [perf] parked 2026-05 (pipeline-docs-workup) — uncomment to re-measure
+      // logger.info(
+        // `[perf][courseDB] getWeightedCards(limit=${limit}): ` +
+          // `navigator=${(tNav1 - tNav0).toFixed(0)}ms(${navCache}) ` +
+          // `pipelineRun=${(tRun - tNav1).toFixed(0)}ms ` +
+          // `total=${(tRun - tNav0).toFixed(0)}ms`
+      // );
+      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.
+   */
+  private async _getCachedNavigator(
+    user: UserDBInterface
+  ): Promise<{ navigator: ContentNavigator; cacheStatus: 'hit' | 'miss' }> {
+    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 navigator = await this.createNavigator(user);
+    this._cachedNavigator = { navigator, userId, builtAt: now };
+    return { navigator, cacheStatus: 'miss' };
+  }
+
+  /**
+   * Drop the cached navigator so the next getWeightedCards() rebuilds it.
+   * Call after mutating this course's navigation strategy documents.
+   */
+  public invalidateNavigatorCache(): void {
+    this._cachedNavigator = null;
+  }
+
   public async getCardsCenteredAtELO(
     options: {
       limit: number;
@@ -684,6 +771,9 @@ above:\n${above.rows.map((r) => `\t${r.id}-${r.key}\n`)}`;
     },
     filter?: (a: QualifiedCardID) => boolean
   ): Promise<StudySessionItem[]> {
+    // [perf] parked: getCardsCenteredAtELO rewrite banner
+    // logger.info('[perf][run] getCardsCenteredAtELO rewrite (session pool cache + in-memory recenter)');
+    // const tCelo0 = performance.now();
     let targetElo: number;
 
     if (options.elo === 'user') {
@@ -706,26 +796,65 @@ above:\n${above.rows.map((r) => `\t${r.id}-${r.key}\n`)}`;
       targetElo = options.elo;
     }
 
-    let cards: (QualifiedCardID & { elo?: number })[] = [];
-    let mult: number = 4;
-    let previousCount: number = -1;
-    let newCount: number = 0;
+    // const tReg = performance.now();
+
+    // Broad neighbor pool fetched once per session and re-used. We over-fetch
+    // (POOL_SIZE >> limit) so that the in-memory active-card filter and the
+    // slowly-roaming ELO both have ample headroom before a refetch is needed.
+    const POOL_SIZE = Math.max(2000, options.limit * 4);
+    const nowMs = Date.now();
+    let cacheStatus: 'hit' | 'miss' | 'refresh' = 'hit';
+
+    if (!this._eloPoolCache || nowMs - this._eloPoolCache.fetchedAt > this._eloPoolTtlMs) {
+      // MISS: pay the (reindexing) view query once, then cache the raw pool.
+      // Guard: never cache an EMPTY pool. A cold-DB-open or sync-race fetch can
+      // transiently return [], and caching it would starve the session for the
+      // whole TTL. Leaving the cache untouched lets the next call retry.
+      const fetched = await this.getCardsByELO(targetElo, POOL_SIZE);
+      if (fetched.length > 0) {
+        this._eloPoolCache = { rows: fetched, fetchedAt: nowMs };
+      }
+      cacheStatus = 'miss';
+    }
 
-    while (cards.length < options.limit && newCount !== previousCount) {
-      cards = await this.getCardsByELO(targetElo, mult * options.limit);
-      previousCount = newCount;
-      newCount = cards.length;
+    // Apply the (fresh) caller filter, then re-center against the *current* ELO.
+    // Returns a new array each call — the cached pool is never mutated, and the
+    // ranking reflects the live ELO even as it drifts within a session.
+    const rankAgainstCurrentElo = (): (QualifiedCardID & { elo?: number })[] => {
+      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)
+        );
+    };
 
-      logger.debug(`Found ${cards.length} elo neighbor cards...`);
+    let cards = rankAgainstCurrentElo();
 
-      if (filter) {
-        cards = cards.filter(filter);
-        logger.debug(`Filtered to ${cards.length} cards...`);
+    // Refetch once if the pool can't satisfy the limit — either the active-card
+    // filter has grown past pool coverage (hit), or the pool is missing because
+    // a prior fetch came back empty (cold open / sync race). A miss that cached
+    // a non-empty-but-small pool (genuinely small course) is left alone.
+    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 };
       }
-
-      mult *= 2;
+      cards = rankAgainstCurrentElo();
+      cacheStatus = 'refresh';
     }
 
+    // [perf] parked: centeredAtELO regDoc / pool-cache timing
+    // logger.info(
+      // `[perf][centeredAtELO] regDoc=${(tReg - tCelo0).toFixed(0)}ms ` +
+        // `cache=${cacheStatus} build=${(performance.now() - tReg).toFixed(0)}ms ` +
+        // `poolRaw=${this._eloPoolCache?.rows.length ?? 0} postFilter=${cards.length} ` +
+        // `limit=${options.limit} targetElo=${targetElo}`
+    // );
+
     const selectedCards: {
       courseID: string;
       cardID: string;

package/src/study/SessionController.ts

@@ -478,7 +478,13 @@ export class SessionController<TView = unknown> extends Loggable {
       this.log(`[Replan] Card guarantee set to ${this._minCardsGuarantee}`);
     }
 
+    // [perf] parked 2026-05 (pipeline-docs-workup) — uncomment to re-measure
+    // const tReplan0 = performance.now();
     await this._executeReplan(opts);
+    // logger.info(
+    //   `[perf][SessionController] replan${labelTag} (limit=${opts.limit ?? 'default'}, ` +
+    //     `mode=${opts.mode ?? 'replace'}) took ${(performance.now() - tReplan0).toFixed(0)}ms`
+    // );
   }
 
   /**
@@ -535,6 +541,20 @@ export class SessionController<TView = unknown> extends Loggable {
    */
   private static readonly WELL_INDICATED_SCORE = 0.10;
 
+  /**
+   * 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 = 3;
+
   /**
    * Internal replan execution. Runs the pipeline, builds a new newQ,
    * atomically swaps it in, and triggers hydration for the new contents.
@@ -677,6 +697,7 @@ export class SessionController<TView = unknown> extends Loggable {
     additive?: boolean;
     limit?: number;
   }): Promise<number> {
+    // const tGwc0 = performance.now(); // [perf] parked
     const replan = options?.replan ?? false;
     const additive = options?.additive ?? false;
     const newLimit = options?.limit ?? this._defaultBatchLimit;
@@ -707,6 +728,8 @@ export class SessionController<TView = unknown> extends Loggable {
       }
     }
 
+    // const tSources = performance.now(); // [perf] parked
+
     // Verify we got content from at least one source
     if (batches.length === 0) {
       if (replan) {
@@ -722,6 +745,7 @@ export class SessionController<TView = unknown> extends Loggable {
 
     // Mix weighted cards across sources using configured strategy
     const mixedWeighted = this.mixer.mix(batches, fetchLimit * this.sources.length);
+    // const tMixed = performance.now(); // [perf] parked
 
     // Capture mixer run for debugging - fetch course names
     const sourceIds = batches.map((b) => {
@@ -820,6 +844,18 @@ export class SessionController<TView = unknown> extends Loggable {
     }
 
     this.log(report);
+
+    // [perf] parked: getWeightedContent stage timing
+    // const tEnd = performance.now();
+    // logger.info(
+    //   `[perf][SessionController] getWeightedContent(replan=${replan}): ` +
+    //     `sources=${(tSources - tGwc0).toFixed(0)}ms ` +
+    //     `mix=${(tMixed - tSources).toFixed(0)}ms ` +
+    //     `post=${(tEnd - tMixed).toFixed(0)}ms ` +
+    //     `total=${(tEnd - tGwc0).toFixed(0)}ms ` +
+    //     `[sources=${this.sources.length} fetchLimit=${fetchLimit} newLimit=${newLimit}]`
+    // );
+
     return wellIndicated;
   }
 
@@ -924,6 +960,10 @@ export class SessionController<TView = unknown> extends Loggable {
   public async nextCard(
     action: SessionAction = 'dismiss-success'
   ): Promise<HydratedCard<TView> | null> {
+    // [perf] parked: nextCard provenance/timing (awaitedReplan, wedgeRuns)
+    // const tNext0 = performance.now();
+    // let awaitedInFlightReplan = false;
+    // let wedgeRuns = 0;
     // dismiss (or sort to failedQ) the current card
     this.dismissCurrentCard(action);
 
@@ -945,6 +985,7 @@ export class SessionController<TView = unknown> extends Loggable {
       this.failedQ.length === 0
     ) {
       this.log('nextCard: queues empty, awaiting in-flight replan before drawing');
+      // awaitedInFlightReplan = true; // [perf] parked
       await this._replanPromise;
     }
 
@@ -970,8 +1011,16 @@ export class SessionController<TView = unknown> extends Loggable {
     // Opportunistic depletion: newQ running dry → background prefetch.
     // No latch — if this fires repeatedly when the pipeline keeps coming
     // back empty, the wedge-breaker's local backoff handles spin protection.
+    //
+    // Threshold sized to give the pipeline enough lead time to land the
+    // replan before the user empties the queue. Previously hardcoded to 1,
+    // which raced user pace against pipeline latency — fast users would hit
+    // an empty queue mid-session and feel the wedge-breaker's synchronous
+    // pipeline call as a "hang". DEPLETION_PREFETCH_THRESHOLD trades a
+    // slightly earlier prefetch (which is anyway desirable for content
+    // freshness) for a much more reliable lead time.
     if (
-      this.newQ.length <= 1 &&
+      this.newQ.length <= SessionController.DEPLETION_PREFETCH_THRESHOLD &&
       this._secondsRemaining > 0 &&
       !this._replanPromise
     ) {
@@ -1031,6 +1080,7 @@ export class SessionController<TView = unknown> extends Loggable {
         `Running pipeline (attempt ${wedgeEmptyStreak + 1}/${WEDGE_MAX_EMPTY_STREAK}).`
       );
       await this._replanUncoalesced({ label: 'wedge-breaker' });
+      // wedgeRuns++; // [perf] parked
       if (
         this.newQ.length === 0 &&
         this.reviewQ.length === 0 &&
@@ -1093,6 +1143,11 @@ export class SessionController<TView = unknown> extends Loggable {
         // Snapshot queue state
         snapshotQueues(this.reviewQ.length, this.newQ.length, this.failedQ.length);
 
+        // [perf] parked: per-draw nextCard timing
+        // logger.info(
+        //   `[perf][nextCard] -> ${card.item.cardID} in ${(performance.now() - tNext0).toFixed(0)}ms ` +
+        //     `(awaitedReplan=${awaitedInFlightReplan} wedgeRuns=${wedgeRuns})`
+        // );
         return card;
       }
 

package/src/study/services/CardHydrationService.ts

@@ -163,6 +163,9 @@ export class CardHydrationService<TView = unknown> {
     }
 
     this.hydrationInProgress = true;
+    // [perf] parked 2026-05 (pipeline-docs-workup) — batch hydration timing
+    // const tFill0 = performance.now();
+    // let hydratedThisBatch = 0;
 
     try {
       const itemsToHydrate = this.getItemsToHydrate();
@@ -175,12 +178,20 @@ export class CardHydrationService<TView = unknown> {
 
         try {
           await this.hydrateCard(item);
+          // hydratedThisBatch++; // [perf] parked
         } catch (e) {
           logger.error(`[CardHydrationService] Error hydrating card ${item.cardID}:`, e);
         }
       }
     } finally {
       this.hydrationInProgress = false;
+      // [perf] parked: batch hydration timing
+      // if (hydratedThisBatch > 0) {
+      //   logger.info(
+      //     `[perf][Hydrate] batch: hydrated ${hydratedThisBatch} card(s) in ` +
+      //       `${(performance.now() - tFill0).toFixed(0)}ms`
+      //   );
+      // }
     }
   }
 
@@ -195,11 +206,13 @@ export class CardHydrationService<TView = unknown> {
     this.hydrationInFlight.add(item.cardID);
 
     try {
+      // const tH0 = performance.now(); // [perf] parked
       const courseDB = this.getCourseDB(item.courseID);
       const [cardData, tagsByCard] = await Promise.all([
         courseDB.getCourseDoc<CardData>(item.cardID),
         courseDB.getAppliedTagsBatch([item.cardID]),
       ]);
+      // const tFetch = performance.now(); // [perf] parked
 
       if (!isCourseElo(cardData.elo)) {
         cardData.elo = toCourseElo(cardData.elo);
@@ -214,6 +227,7 @@ export class CardHydrationService<TView = unknown> {
           })
         )
       );
+      // const tDocs = performance.now(); // [perf] parked
 
       // Extract audio URLs from all data fields and prefetch them
       const audioToPrefetch: string[] = [];
@@ -224,6 +238,7 @@ export class CardHydrationService<TView = unknown> {
       });
 
       // Dedupe and prefetch, waiting for browser cache to be ready
+      // const tAudioStart = performance.now(); // [perf] parked
       const uniqueAudioUrls = [...new Set(audioToPrefetch)];
       if (uniqueAudioUrls.length > 0) {
         logger.debug(
@@ -231,6 +246,7 @@ export class CardHydrationService<TView = unknown> {
         );
         await Promise.allSettled(uniqueAudioUrls.map(prefetchAudio));
       }
+      // const tAudio = performance.now(); // [perf] parked
 
       const data = dataDocs.map(displayableDataToViewData).reverse();
 
@@ -241,6 +257,14 @@ export class CardHydrationService<TView = unknown> {
         tags: tagsByCard.get(item.cardID) ?? [],
       });
 
+      // [perf] parked: per-card hydration timing (cardDoc+tags / dataDocs / audio)
+      // logger.info(
+      //   `[perf][Hydrate] ${item.cardID}: ` +
+      //     `cardDoc+tags=${(tFetch - tH0).toFixed(0)}ms ` +
+      //     `dataDocs=${(tDocs - tFetch).toFixed(0)}ms ` +
+      //     `audioPrefetch=${(tAudio - tAudioStart).toFixed(0)}ms(${uniqueAudioUrls.length} files) ` +
+      //     `total=${(tAudio - tH0).toFixed(0)}ms`
+      // );
       logger.debug(`[CardHydrationService] Hydrated card ${item.cardID}`);
     } finally {
       this.hydrationInFlight.delete(item.cardID);