@vue-skuilder/db 0.1.31 → 0.1.32-b

package/dist/index.mjs

@@ -1913,6 +1913,7 @@ var init_hierarchyDefinition = __esm({
   "src/core/navigators/filters/hierarchyDefinition.ts"() {
     "use strict";
     init_navigators();
+    init_logger();
     DEFAULT_MIN_COUNT = 3;
     HierarchyDefinitionNavigator = class extends ContentNavigator {
       config;
@@ -2080,6 +2081,9 @@ var init_hierarchyDefinition = __esm({
               finalScore *= maxBoost;
               action = "boosted";
               finalReason = `${reason} | preReqBoost \xD7${maxBoost.toFixed(2)} for ${boostedPrereqs.join(", ")}`;
+              logger.info(
+                `[HierarchyDefinition] preReqBoost \xD7${maxBoost.toFixed(2)} applied to card ${card.cardId} via tags [${boostedPrereqs.join(", ")}] (score: ${card.score.toFixed(3)} \u2192 ${finalScore.toFixed(3)})`
+              );
             }
           }
           gated.push({
@@ -2589,7 +2593,7 @@ var init_relativePriority = __esm({
             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 finalScore = Math.max(0, card.score * boostFactor);
             const action = boostFactor > 1 ? "boosted" : boostFactor < 1 ? "penalized" : "passed";
             const reason = this.buildPriorityReason(cardTags, priority, boostFactor, finalScore);
             return {
@@ -3354,7 +3358,7 @@ var init_Pipeline = __esm({
                 card.provenance.push({
                   strategy: "ephemeralHint",
                   strategyId: "ephemeral-hint",
-                  strategyName: "Replan Hint",
+                  strategyName: hints._label ? `Replan Hint (${hints._label})` : "Replan Hint",
                   action: "boosted",
                   score: card.score,
                   reason: `boostTag ${pattern} \xD7${factor}`
@@ -3371,7 +3375,7 @@ var init_Pipeline = __esm({
                 card.provenance.push({
                   strategy: "ephemeralHint",
                   strategyId: "ephemeral-hint",
-                  strategyName: "Replan Hint",
+                  strategyName: hints._label ? `Replan Hint (${hints._label})` : "Replan Hint",
                   action: "boosted",
                   score: card.score,
                   reason: `boostCard ${pattern} \xD7${factor}`
@@ -3381,6 +3385,7 @@ var init_Pipeline = __esm({
           }
         }
         const cardIds = new Set(cards.map((c) => c.cardId));
+        const hintLabel = hints._label ? `Replan Hint (${hints._label})` : "Replan Hint";
         const inject = (card, reason) => {
           if (!cardIds.has(card.cardId)) {
             const floorScore = Math.max(card.score, 1);
@@ -3392,7 +3397,7 @@ var init_Pipeline = __esm({
                 {
                   strategy: "ephemeralHint",
                   strategyId: "ephemeral-hint",
-                  strategyName: "Replan Hint",
+                  strategyName: hintLabel,
                   action: "boosted",
                   score: floorScore,
                   reason
@@ -4646,10 +4651,18 @@ ${above.rows.map((r) => `	${r.id}-${r.key}
        * @param limit - Maximum number of cards to return
        * @returns Cards sorted by score descending
        */
+      _pendingHints = null;
+      setEphemeralHints(hints) {
+        this._pendingHints = hints;
+      }
       async getWeightedCards(limit) {
         const u = await this._getCurrentUser();
         try {
           const navigator = await this.createNavigator(u);
+          if (this._pendingHints) {
+            navigator.setEphemeralHints(this._pendingHints);
+            this._pendingHints = null;
+          }
           return navigator.getWeightedCards(limit);
         } catch (e) {
           logger.error(`[courseDB] Error getting weighted cards: ${e}`);
@@ -7640,9 +7653,17 @@ var init_courseDB2 = __esm({
         }
       }
       // Study Content Source implementation
+      _pendingHints = null;
+      setEphemeralHints(hints) {
+        this._pendingHints = hints;
+      }
       async getWeightedCards(limit) {
         try {
           const navigator = await this.createNavigator(this.userDB);
+          if (this._pendingHints) {
+            navigator.setEphemeralHints(this._pendingHints);
+            this._pendingHints = null;
+          }
           return navigator.getWeightedCards(limit);
         } catch (e) {
           logger.error(`[static/courseDB] Error getting weighted cards: ${e}`);
@@ -9319,8 +9340,9 @@ var ResponseProcessor = class {
     }
     try {
       const history = await cardHistory;
+      let result;
       if (cardRecord.isCorrect) {
-        return this.processCorrectResponse(
+        result = this.processCorrectResponse(
           cardRecord,
           history,
           studySessionItem,
@@ -9330,7 +9352,7 @@ var ResponseProcessor = class {
           cardId
         );
       } else {
-        return this.processIncorrectResponse(
+        result = this.processIncorrectResponse(
           cardRecord,
           history,
           courseRegistrationDoc,
@@ -9342,6 +9364,18 @@ var ResponseProcessor = class {
           sessionViews
         );
       }
+      if (cardRecord.deferAdvance && result.shouldLoadNextCard) {
+        logger.info(
+          "[ResponseProcessor] deferAdvance requested \u2014 suppressing navigation, action stashed:",
+          { nextCardAction: result.nextCardAction }
+        );
+        result = {
+          ...result,
+          shouldLoadNextCard: false,
+          deferred: true
+        };
+      }
+      return result;
     } catch (e) {
       logger.error("[ResponseProcessor] Failed to load card history", { e, cardId });
       throw e;
@@ -11836,6 +11870,12 @@ var SessionController = class _SessionController extends Loggable {
   mixer;
   dataLayer;
   courseNameCache = /* @__PURE__ */ new Map();
+  /**
+   * Default pipeline batch size for new-card planning.
+   * Set via constructor options; falls back to 20 when not specified.
+   * Individual replans can override via `ReplanOptions.limit`.
+   */
+  _defaultBatchLimit = 20;
   sources;
   // dataLayer and getViewComponent now injected into CardHydrationService
   _sessionRecord = [];
@@ -11860,6 +11900,20 @@ var SessionController = class _SessionController extends Loggable {
    * (user state has changed from completing good cards).
    */
   _wellIndicatedRemaining = 0;
+  /**
+   * When true, suppresses the quality-based auto-replan trigger in
+   * nextCard(). Set after a burst replan (small limit) to prevent the
+   * auto-replan from clobbering the burst cards before they're consumed.
+   * Cleared when the depletion-triggered replan fires (newQ exhausted).
+   */
+  _suppressQualityReplan = false;
+  /**
+   * Guards against infinite depletion-triggered replans. Set to true
+   * when a depletion replan fires; cleared when a replan produces
+   * content (newQ.length > 0 after replan) or when an explicit
+   * (non-auto) replan is requested.
+   */
+  _depletionReplanAttempted = false;
   startTime;
   endTime;
   _secondsRemaining;
@@ -11884,8 +11938,12 @@ var SessionController = class _SessionController extends Loggable {
    * @param dataLayer - Data layer provider
    * @param getViewComponent - Function to resolve view components
    * @param mixer - Optional source mixer strategy (defaults to QuotaRoundRobinMixer)
+   * @param options - Optional session-level configuration
+   * @param options.defaultBatchLimit - Default pipeline batch size (default: 20).
+   *   Smaller values for newer users cause more frequent replans, keeping plans
+   *   aligned with rapidly-changing user state.
    */
-  constructor(sources, time, dataLayer, getViewComponent, mixer) {
+  constructor(sources, time, dataLayer, getViewComponent, mixer, options) {
     super();
     this.dataLayer = dataLayer;
     this.mixer = mixer || new QuotaRoundRobinMixer();
@@ -11903,9 +11961,13 @@ var SessionController = class _SessionController extends Loggable {
     this.startTime = /* @__PURE__ */ new Date();
     this._secondsRemaining = time;
     this.endTime = new Date(this.startTime.valueOf() + 1e3 * this._secondsRemaining);
+    if (options?.defaultBatchLimit !== void 0) {
+      this._defaultBatchLimit = options.defaultBatchLimit;
+    }
     this.log(`Session constructed:
     startTime: ${this.startTime}
-    endTime: ${this.endTime}`);
+    endTime: ${this.endTime}
+    defaultBatchLimit: ${this._defaultBatchLimit}`);
   }
   tick() {
     this._secondsRemaining = Math.floor((this.endTime.valueOf() - Date.now()) / 1e3);
@@ -11981,25 +12043,47 @@ var SessionController = class _SessionController extends Loggable {
    * Typical trigger: application-level code (e.g. after a GPC intro completion)
    * calls this to ensure newly-unlocked content appears in the session.
    */
-  async requestReplan(hints) {
+  async requestReplan(options) {
+    const opts = this.normalizeReplanOptions(options);
+    if (opts.hints || opts.label || opts.limit) {
+      this._depletionReplanAttempted = false;
+    }
     if (this._replanPromise) {
       this.log("Replan already in progress, awaiting existing replan");
       return this._replanPromise;
     }
-    if (hints) {
+    if (opts.hints) {
+      const hintsWithLabel = opts.label ? { ...opts.hints, _label: opts.label } : opts.hints;
       for (const source of this.sources) {
-        this.log(`[Hints] source type=${source.constructor.name}, hasMethod=${typeof source.setEphemeralHints}`);
-        source.setEphemeralHints?.(hints);
+        source.setEphemeralHints?.(hintsWithLabel);
       }
     }
-    this.log(`Mid-session replan requested${hints ? ` (hints: ${JSON.stringify(hints)})` : ""}`);
-    this._replanPromise = this._executeReplan();
+    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" : ""})`
+    );
+    this._replanPromise = this._executeReplan(opts);
     try {
       await this._replanPromise;
     } finally {
       this._replanPromise = null;
     }
   }
+  /**
+   * Normalise the requestReplan argument. Accepts either a ReplanOptions
+   * object (new API) or a plain Record<string, unknown> (legacy callers
+   * that passed hints directly). Distinguishes the two by checking for
+   * the presence of ReplanOptions-specific keys.
+   */
+  normalizeReplanOptions(input) {
+    if (!input) return {};
+    const replanKeys = ["hints", "limit", "mode", "label"];
+    const inputKeys = Object.keys(input);
+    if (inputKeys.some((k) => replanKeys.includes(k))) {
+      return input;
+    }
+    return { hints: input };
+  }
   /** Minimum well-indicated cards before an additive retry is attempted */
   static MIN_WELL_INDICATED = 5;
   /**
@@ -12018,16 +12102,32 @@ var SessionController = class _SessionController extends Loggable {
    * pass all hierarchy filters, one additive retry is attempted — merging
    * any new high-quality candidates into the front of the queue.
    */
-  async _executeReplan() {
-    const wellIndicated = await this.getWeightedContent({ replan: true });
+  async _executeReplan(opts = {}) {
+    const limit = opts.limit;
+    const mode = opts.mode ?? "replace";
+    const wellIndicated = await this.getWeightedContent({
+      replan: true,
+      additive: mode === "merge",
+      limit
+    });
     this._wellIndicatedRemaining = wellIndicated;
+    if (limit !== void 0 && limit < this._defaultBatchLimit) {
+      this._suppressQualityReplan = true;
+      this.log(`[Replan] Burst mode (limit=${limit}): suppressing quality-based auto-replan`);
+    } else {
+      this._suppressQualityReplan = false;
+    }
     if (wellIndicated >= 0 && wellIndicated < _SessionController.MIN_WELL_INDICATED) {
       this.log(
         `[Replan] Only ${wellIndicated}/${_SessionController.MIN_WELL_INDICATED} well-indicated cards after replan`
       );
     }
+    if (this.newQ.length > 0) {
+      this._depletionReplanAttempted = false;
+    }
     await this.hydrationService.ensureHydratedCards();
-    this.log(`Replan complete: newQ now has ${this.newQ.length} cards`);
+    const labelTag = opts.label ? ` [${opts.label}]` : "";
+    this.log(`Replan complete${labelTag}: newQ now has ${this.newQ.length} cards (mode=${mode})`);
     snapshotQueues(this.reviewQ.length, this.newQ.length, this.failedQ.length);
   }
   addTime(seconds) {
@@ -12087,7 +12187,9 @@ var SessionController = class _SessionController extends Loggable {
         cardIds: this.hydrationService.getHydratedCardIds()
       },
       replan: {
-        inProgress: this._replanPromise !== null
+        inProgress: this._replanPromise !== null,
+        suppressQualityReplan: this._suppressQualityReplan,
+        defaultBatchLimit: this._defaultBatchLimit
       }
     };
   }
@@ -12114,7 +12216,7 @@ var SessionController = class _SessionController extends Loggable {
   async getWeightedContent(options) {
     const replan = options?.replan ?? false;
     const additive = options?.additive ?? false;
-    const limit = 20;
+    const limit = options?.limit ?? this._defaultBatchLimit;
     const batches = [];
     for (let i = 0; i < this.sources.length; i++) {
       const source = this.sources[i];
@@ -12295,10 +12397,26 @@ var SessionController = class _SessionController extends Loggable {
       this.log("nextCard: awaiting in-flight replan before drawing");
       await this._replanPromise;
     }
+    if (this.newQ.length <= 1 && this._secondsRemaining > 0 && !this._replanPromise && !this._depletionReplanAttempted) {
+      this._suppressQualityReplan = false;
+      this._depletionReplanAttempted = true;
+      const otherContent = this.reviewQ.length + this.failedQ.length;
+      if (this.newQ.length === 0 && otherContent === 0) {
+        this.log(
+          `[AutoReplan:depletion] All queues empty with ${this._secondsRemaining}s remaining. Awaiting replan.`
+        );
+        await this.requestReplan();
+      } else {
+        this.log(
+          `[AutoReplan:depletion] newQ has ${this.newQ.length} card(s) (${otherContent} in other queues) with ${this._secondsRemaining}s remaining. Triggering background replan.`
+        );
+        void this.requestReplan();
+      }
+    }
     const REPLAN_BUFFER = 3;
-    if (this._wellIndicatedRemaining <= REPLAN_BUFFER && this.newQ.length > 0 && !this._replanPromise) {
+    if (!this._suppressQualityReplan && this._wellIndicatedRemaining <= REPLAN_BUFFER && this.newQ.length > 0 && !this._replanPromise) {
       this.log(
-        `[AutoReplan] ${this._wellIndicatedRemaining} well-indicated cards remaining (newQ: ${this.newQ.length}). Triggering background replan.`
+        `[AutoReplan:quality] ${this._wellIndicatedRemaining} well-indicated cards remaining (newQ: ${this.newQ.length}). Triggering background replan.`
       );
       void this.requestReplan();
     }