@vue-skuilder/db 0.1.31 → 0.1.32-b

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.31",
+  "version": "0.1.32-b",
   "description": "Database layer for vue-skuilder",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -48,7 +48,7 @@
   },
   "dependencies": {
     "@nilock2/pouchdb-authentication": "^1.0.2",
-    "@vue-skuilder/common": "0.1.31",
+    "@vue-skuilder/common": "0.1.32-b",
     "cross-fetch": "^4.1.0",
     "moment": "^2.29.4",
     "pouchdb": "^9.0.0",

package/src/core/navigators/Pipeline.ts

@@ -39,6 +39,13 @@ export interface ReplanHints {
   excludeTags?: string[];
   /** Remove these specific card IDs from results. */
   excludeCards?: string[];
+  /**
+   * Debugging label threaded from the replan requester.
+   * Attached to provenance entries so card scoring history
+   * can be traced back to the originating event.
+   * Prefixed with `_` to signal it's metadata, not a scoring hint.
+   */
+  _label?: string;
 }
 
 /**
@@ -544,7 +551,7 @@ export class Pipeline extends ContentNavigator {
             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} ×${factor}`,
@@ -561,7 +568,7 @@ export class Pipeline extends ContentNavigator {
             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} ×${factor}`,
@@ -573,6 +580,7 @@ export class Pipeline extends ContentNavigator {
 
     // 3. Require — inject from the full pool if not already present
     const cardIds = new Set(cards.map((c) => c.cardId));
+    const hintLabel = hints._label ? `Replan Hint (${hints._label})` : 'Replan Hint';
     const inject = (card: WeightedCard, reason: string) => {
       if (!cardIds.has(card.cardId)) {
         // Give required cards a floor score so they sort above zero-score filler
@@ -585,7 +593,7 @@ export class Pipeline extends ContentNavigator {
             {
               strategy: 'ephemeralHint',
               strategyId: 'ephemeral-hint',
-              strategyName: 'Replan Hint',
+              strategyName: hintLabel,
               action: 'boosted',
               score: floorScore,
               reason,

package/src/core/navigators/filters/hierarchyDefinition.ts

@@ -5,6 +5,7 @@ import type { WeightedCard } from '../index';
 import type { ContentNavigationStrategyData } from '../../types/contentNavigationStrategy';
 import type { CardFilter, FilterContext } from './types';
 import { toCourseElo } from '@vue-skuilder/common';
+import { logger } from '../../../util/logger';
 
 /**
  * A single prerequisite requirement for a tag.
@@ -286,6 +287,9 @@ export default class HierarchyDefinitionNavigator extends ContentNavigator imple
           finalScore *= maxBoost;
           action = 'boosted';
           finalReason = `${reason} | preReqBoost ×${maxBoost.toFixed(2)} for ${boostedPrereqs.join(', ')}`;
+          logger.info(
+            `[HierarchyDefinition] preReqBoost ×${maxBoost.toFixed(2)} applied to card ${card.cardId} via tags [${boostedPrereqs.join(', ')}] (score: ${card.score.toFixed(3)} → ${finalScore.toFixed(3)})`
+          );
         }
       }
 

package/src/core/navigators/filters/relativePriority.ts

@@ -198,7 +198,13 @@ export default class RelativePriorityNavigator extends ContentNavigator implemen
         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));
+        // No upper clamp — scores may exceed 1.0 intentionally.
+        // Scores are only used for relative ordering within a pipeline run,
+        // so absolute magnitude doesn't matter. Clamping to 1.0 here collapsed
+        // differentiation when GPC preReqBoosts and priority boosts compounded
+        // (e.g. 0.96 × 2.5 × 1.24 → 2.98, previously crushed back to 1.0).
+        // Floor of 0 is kept: negative scores have no meaning.
+        const finalScore = Math.max(0, card.score * boostFactor);
 
         // Determine action based on boost factor
         const action = boostFactor > 1.0 ? 'boosted' : boostFactor < 1.0 ? 'penalized' : 'passed';

package/src/impl/couch/courseDB.ts

@@ -650,11 +650,21 @@ above:\n${above.rows.map((r) => `\t${r.id}-${r.key}\n`)}`;
    * @param limit - Maximum number of cards to return
    * @returns Cards sorted by score descending
    */
+  private _pendingHints: Record<string, unknown> | null = null;
+
+  public setEphemeralHints(hints: Record<string, unknown>): void {
+    this._pendingHints = hints;
+  }
+
   public async getWeightedCards(limit: number): Promise<WeightedCard[]> {
     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}`);

package/src/impl/static/courseDB.ts

@@ -442,9 +442,21 @@ export class StaticCourseDB implements CourseDBInterface {
   }
 
   // Study Content Source implementation
+
+  private _pendingHints: Record<string, unknown> | null = null;
+
+  setEphemeralHints(hints: Record<string, unknown>): void {
+    this._pendingHints = hints;
+  }
+
   async getWeightedCards(limit: number): Promise<WeightedCard[]> {
     try {
       const navigator = await this.createNavigator(this.userDB);
+      // Forward any pending hints to the Pipeline
+      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}`);

package/src/study/SessionController.ts

@@ -20,6 +20,35 @@ import { SourceMixer, QuotaRoundRobinMixer, SourceBatch } from './SourceMixer';
 import { captureMixerRun } from './MixerDebugger';
 import { startSessionTracking, recordCardPresentation, snapshotQueues, endSessionTracking } from './SessionDebugger';
 
+/**
+ * Options for requesting a mid-session replan.
+ *
+ * All fields are optional — callers can pass just the fields they need.
+ * When omitted, defaults match the existing behaviour (full 20-card
+ * replace with no hints).
+ */
+export interface ReplanOptions {
+  /** Scoring hints forwarded to the pipeline (boost/exclude/require). */
+  hints?: Record<string, unknown>;
+  /**
+   * Maximum number of new cards to return from the pipeline.
+   * Default: 20 (the standard session batch size).
+   */
+  limit?: number;
+  /**
+   * How to integrate the new cards into the existing newQ.
+   * - `'replace'` (default): atomically swap the entire newQ.
+   * - `'merge'`: insert new cards at the front, keeping existing cards.
+   */
+  mode?: 'replace' | 'merge';
+  /**
+   * Human-readable label for debugging / provenance.
+   * Appears in console logs and in card provenance entries created
+   * by ephemeral hint application.
+   */
+  label?: string;
+}
+
 export interface StudySessionRecord {
   card: {
     course_id: string;
@@ -44,6 +73,14 @@ export interface ResponseResult {
   nextCardAction: Exclude<SessionAction, 'dismiss-error'> | 'none';
   shouldLoadNextCard: boolean;
 
+  /**
+   * When true, the card requested deferred advancement via `deferAdvance`.
+   * The record was logged and ELO updated, but navigation was suppressed.
+   * StudySession should stash `nextCardAction` and wait for a
+   * `ready-to-advance` event from the card before calling `nextCard()`.
+   */
+  deferred?: boolean;
+
   // UI Data (let view decide how to render)
   isCorrect: boolean;
   performanceScore?: number; // for shadow color calculation
@@ -67,6 +104,13 @@ export class SessionController<TView = unknown> extends Loggable {
   private dataLayer: DataLayerProvider;
   private courseNameCache: Map<string, string> = 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`.
+   */
+  private _defaultBatchLimit: number = 20;
+
   private sources: StudyContentSource[];
   // dataLayer and getViewComponent now injected into CardHydrationService
   private _sessionRecord: StudySessionRecord[] = [];
@@ -96,6 +140,22 @@ export class SessionController<TView = unknown> extends Loggable {
    */
   private _wellIndicatedRemaining: number = 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).
+   */
+  private _suppressQualityReplan: boolean = 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.
+   */
+  private _depletionReplanAttempted: boolean = false;
+
   private startTime: Date;
   private endTime: Date;
   private _secondsRemaining: number;
@@ -121,13 +181,18 @@ export class SessionController<TView = unknown> 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: StudyContentSource[],
     time: number,
     dataLayer: DataLayerProvider,
     getViewComponent: (viewId: string) => TView,
-    mixer?: SourceMixer
+    mixer?: SourceMixer,
+    options?: { defaultBatchLimit?: number }
   ) {
     super();
 
@@ -151,9 +216,14 @@ export class SessionController<TView = unknown> extends Loggable {
     this._secondsRemaining = time;
     this.endTime = new Date(this.startTime.valueOf() + 1000 * this._secondsRemaining);
 
+    if (options?.defaultBatchLimit !== undefined) {
+      this._defaultBatchLimit = options.defaultBatchLimit;
+    }
+
     this.log(`Session constructed:
     startTime: ${this.startTime}
-    endTime: ${this.endTime}`);
+    endTime: ${this.endTime}
+    defaultBatchLimit: ${this._defaultBatchLimit}`);
   }
 
   private tick() {
@@ -246,22 +316,39 @@ export class SessionController<TView = unknown> 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.
    */
-  public async requestReplan(hints?: Record<string, unknown>): Promise<void> {
+  public async requestReplan(options?: ReplanOptions | Record<string, unknown>): Promise<void> {
+    // Normalise: bare hints object (legacy callers) → ReplanOptions wrapper
+    const opts = this.normalizeReplanOptions(options);
+
+    // Explicit (non-auto) replans clear the depletion guard — the caller
+    // is providing fresh intent that may change pipeline results.
+    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;
     }
 
-    // Forward hints to all sources that support them (Pipeline)
-    if (hints) {
+    // Forward hints to all sources (CourseDB stashes them, Pipeline consumes them)
+    if (opts.hints) {
+      // Thread label into hints so Pipeline can attach it to provenance
+      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;
@@ -270,6 +357,28 @@ export class SessionController<TView = unknown> extends Loggable {
     }
   }
 
+  /**
+   * 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.
+   */
+  private normalizeReplanOptions(
+    input?: ReplanOptions | Record<string, unknown>
+  ): ReplanOptions {
+    if (!input) return {};
+
+    // If the input has any ReplanOptions-specific key, treat it as ReplanOptions
+    const replanKeys = ['hints', 'limit', 'mode', 'label'];
+    const inputKeys = Object.keys(input);
+    if (inputKeys.some((k) => replanKeys.includes(k))) {
+      return input as ReplanOptions;
+    }
+
+    // Otherwise treat as legacy bare-hints object
+    return { hints: input as Record<string, unknown> };
+  }
+
   /** Minimum well-indicated cards before an additive retry is attempted */
   private static readonly MIN_WELL_INDICATED = 5;
 
@@ -290,18 +399,43 @@ export class SessionController<TView = unknown> extends Loggable {
    * pass all hierarchy filters, one additive retry is attempted — merging
    * any new high-quality candidates into the front of the queue.
    */
-  private async _executeReplan(): Promise<void> {
-    const wellIndicated = await this.getWeightedContent({ replan: true });
+  private async _executeReplan(opts: ReplanOptions = {}): Promise<void> {
+    const limit = opts.limit;
+    const mode = opts.mode ?? 'replace';
+
+    const wellIndicated = await this.getWeightedContent({
+      replan: true,
+      additive: mode === 'merge',
+      limit,
+    });
     this._wellIndicatedRemaining = wellIndicated;
 
+    // Burst replan: suppress quality-based auto-replan so the background
+    // replan doesn't clobber the small hinted queue before it's consumed.
+    // The depletion trigger (newQ empty) takes over instead.
+    if (limit !== undefined && limit < this._defaultBatchLimit) {
+      this._suppressQualityReplan = true;
+      this.log(`[Replan] Burst mode (limit=${limit}): suppressing quality-based auto-replan`);
+    } else {
+      // Normal or auto-replan — clear the burst suppression flag
+      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 the replan produced content, clear the depletion guard so future
+    // depletions can trigger fresh replans.
+    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})`);
 
     // Snapshot queue state for debugging
     snapshotQueues(this.reviewQ.length, this.newQ.length, this.failedQ.length);
@@ -373,6 +507,8 @@ export class SessionController<TView = unknown> extends Loggable {
       },
       replan: {
         inProgress: this._replanPromise !== null,
+        suppressQualityReplan: this._suppressQualityReplan,
+        defaultBatchLimit: this._defaultBatchLimit,
       },
     };
   }
@@ -397,10 +533,14 @@ export class SessionController<TView = unknown> extends Loggable {
    * @returns Number of "well-indicated" cards (passed all hierarchy filters)
    *   in the new content. Returns -1 if no content was loaded.
    */
-  private async getWeightedContent(options?: { replan?: boolean; additive?: boolean }): Promise<number> {
+  private async getWeightedContent(options?: {
+    replan?: boolean;
+    additive?: boolean;
+    limit?: number;
+  }): Promise<number> {
     const replan = options?.replan ?? false;
     const additive = options?.additive ?? false;
-    const limit = 20; // Initial batch size per source
+    const limit = options?.limit ?? this._defaultBatchLimit;
 
     // Collect batches from each source
     const batches: SourceBatch[] = [];
@@ -645,19 +785,69 @@ export class SessionController<TView = unknown> extends Loggable {
       await this._replanPromise;
     }
 
-    // Quality-based auto-replan: when few well-indicated cards remain,
-    // trigger a background replan. The buffer of remaining good cards
-    // covers the replan latency — by the time they're consumed, the
-    // refreshed queue is ready. Strategy-agnostic: relies only on the
-    // score-based well-indicated count, not any specific filter's output.
+    // --- Auto-replan triggers ---
+    // Two automatic replan triggers maintain queue freshness:
+    //
+    // 1. Depletion: newQ is running dry → fire a replan so fresh content
+    //    is ready by the time the last card is consumed.
+    //    - newQ === 1: background replan — overlaps pipeline latency with
+    //      the user's interaction on the last card. On the *next*
+    //      nextCard(), the _replanPromise await at the top ensures the
+    //      replan has landed before we try to draw.
+    //    - newQ === 0 && all queues empty: blocking await — nothing else
+    //      to serve, so we must wait for the pipeline before proceeding.
+    //    - newQ === 0 && other queues have content: background — the user
+    //      draws from reviewQ/failedQ while the pipeline runs.
+    //
+    // 2. Quality: few well-indicated cards remain → background replan so
+    //    the refreshed queue is ready by the time the buffer is consumed.
+    //    Suppressed after a burst replan to avoid clobbering burst cards.
+
+    // 1. Depletion trigger
+    //    Guarded by _depletionReplanAttempted to avoid infinite loops when
+    //    the pipeline consistently returns no new content.
+    if (
+      this.newQ.length <= 1 &&
+      this._secondsRemaining > 0 &&
+      !this._replanPromise &&
+      !this._depletionReplanAttempted
+    ) {
+      this._suppressQualityReplan = false; // burst is (nearly) consumed, clear suppression
+      this._depletionReplanAttempted = true;
+
+      const otherContent = this.reviewQ.length + this.failedQ.length;
+
+      if (this.newQ.length === 0 && otherContent === 0) {
+        // Truly empty — nothing to serve. Must block until the pipeline delivers.
+        this.log(
+          `[AutoReplan:depletion] All queues empty with ${this._secondsRemaining}s remaining. ` +
+          `Awaiting replan.`
+        );
+        await this.requestReplan();
+      } else {
+        // Either 1 card remains (look-ahead) or other queues can cover.
+        // Fire in background — pipeline runs while the user works.
+        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();
+      }
+    }
+
+    // 2. Quality trigger: few well-indicated cards remain. The buffer of
+    //    remaining good cards covers replan latency.
+    //    Suppressed after a burst replan to avoid clobbering burst cards.
     const REPLAN_BUFFER = 3;
     if (
+      !this._suppressQualityReplan &&
       this._wellIndicatedRemaining <= REPLAN_BUFFER &&
       this.newQ.length > 0 &&
       !this._replanPromise
     ) {
       this.log(
-        `[AutoReplan] ${this._wellIndicatedRemaining} well-indicated cards remaining ` +
+        `[AutoReplan:quality] ${this._wellIndicatedRemaining} well-indicated cards remaining ` +
         `(newQ: ${this.newQ.length}). Triggering background replan.`
       );
       void this.requestReplan();

package/src/study/services/ResponseProcessor.ts

@@ -107,9 +107,11 @@ export class ResponseProcessor {
     try {
       const history = await cardHistory;
 
+      let result: ResponseResult;
+
       // Handle correct responses
       if (cardRecord.isCorrect) {
-        return this.processCorrectResponse(
+        result = this.processCorrectResponse(
           cardRecord,
           history,
           studySessionItem,
@@ -120,7 +122,7 @@ export class ResponseProcessor {
         );
       } else {
         // Handle incorrect responses
-        return this.processIncorrectResponse(
+        result = this.processIncorrectResponse(
           cardRecord,
           history,
           courseRegistrationDoc,
@@ -132,6 +134,24 @@ export class ResponseProcessor {
           sessionViews
         );
       }
+
+      // Apply deferred advancement: record is logged and ELO updated above,
+      // but we suppress navigation so the view retains control of the UI
+      // timeline. StudySession will stash the nextCardAction and wait for
+      // a `ready-to-advance` event from the view.
+      if (cardRecord.deferAdvance && result.shouldLoadNextCard) {
+        logger.info(
+          '[ResponseProcessor] deferAdvance requested — suppressing navigation, action stashed:',
+          { nextCardAction: result.nextCardAction }
+        );
+        result = {
+          ...result,
+          shouldLoadNextCard: false,
+          deferred: true,
+        };
+      }
+
+      return result;
     } catch (e: unknown) {
       logger.error('[ResponseProcessor] Failed to load card history', { e, cardId });
       throw e;