@vue-skuilder/db 0.1.32-a → 0.1.32-c

package/src/core/navigators/index.ts

@@ -1,4 +1,5 @@
 import { StudyContentSource, UserDBInterface, CourseDBInterface } from '..';
+import type { ReplanHints } from '@db/study/SessionController';
 
 // Re-export filter types
 export type { CardFilter, FilterContext, CardFilterFactory } from './filters/types';
@@ -633,7 +634,7 @@ export abstract class ContentNavigator implements StudyContentSource {
    * Set ephemeral hints for the next pipeline run.
    * No-op for non-Pipeline navigators. Pipeline overrides this.
    */
-  setEphemeralHints(_hints: Record<string, unknown>): void {
+  setEphemeralHints(_hints: ReplanHints): void {
     // no-op — only Pipeline implements this
   }
 }

package/src/impl/couch/CourseSyncService.ts

@@ -137,9 +137,26 @@ export class CourseSyncService {
   async ensureSynced(courseId: string, forceEnabled?: boolean): Promise<void> {
     const existing = this.entries.get(courseId);
 
-    // Already synced
-    if (existing?.status.state === 'ready') {
-      return;
+    // Already synced — but check if the remote DB has been recreated
+    // (e.g., after a dev reseed). The seed script writes a `db-epoch`
+    // doc; if the remote epoch differs from our local copy, the local
+    // replica is stale and must be destroyed before re-syncing.
+    if (existing?.status.state === 'ready' && existing.localDB) {
+      const stale = await this.isLocalEpochStale(courseId, existing.localDB);
+      if (!stale) {
+        return;
+      }
+      logger.info(
+        `[CourseSyncService] Remote DB epoch changed for course ${courseId} — destroying stale local replica`
+      );
+      try {
+        await existing.localDB.destroy();
+      } catch {
+        // Ignore cleanup errors
+      }
+      existing.localDB = null;
+      existing.readyPromise = null;
+      // Fall through to start a fresh sync
     }
 
     // Already disabled
@@ -224,7 +241,23 @@ export class CourseSyncService {
       // Step 2: Create local PouchDB and replicate
       entry.status = { state: 'syncing' };
       const localDBName = this.localDBName(courseId);
-      const localDB = new pouch(localDBName);
+      let localDB = new pouch(localDBName);
+
+      // Check for stale local replica before replicating. If the remote DB
+      // was wiped and recreated (e.g., `yarn db:seed`), the local PouchDB
+      // has documents at rev 1-oldHash while the remote has 1-newHash for
+      // the same _ids. PouchDB replication treats this as a conflict rather
+      // than an update, and the stale revision can win — causing partial or
+      // incorrect data. Destroying the stale local DB avoids this entirely.
+      const stale = await this.isLocalEpochStale(courseId, localDB);
+      if (stale) {
+        logger.info(
+          `[CourseSyncService] Stale local DB detected for course ${courseId} — destroying before sync`
+        );
+        await localDB.destroy();
+        localDB = new pouch(localDBName);
+      }
+
       entry.localDB = localDB;
 
       const remoteDB = this.getRemoteDB(courseId);
@@ -340,6 +373,41 @@ export class CourseSyncService {
     }
   }
 
+  /**
+   * Check whether the local replica's `db-epoch` doc matches the remote.
+   *
+   * The seed script (and optionally upload-cards) writes a `db-epoch`
+   * document with a numeric timestamp. If the remote epoch differs from
+   * the local copy, the remote DB was recreated (e.g., `yarn db:seed`)
+   * and the local PouchDB is stale.
+   *
+   * Returns `true` if stale (epoch mismatch or remote has epoch but local
+   * doesn't). Returns `false` (not stale) if epochs match, or if the
+   * remote doesn't have an epoch doc at all (backwards compat).
+   */
+  private async isLocalEpochStale(
+    courseId: string,
+    localDB: PouchDB.Database
+  ): Promise<boolean> {
+    try {
+      const remoteDB = this.getRemoteDB(courseId);
+      const remoteEpoch = await remoteDB.get<{ epoch: number }>('db-epoch');
+
+      let localEpoch: { epoch: number } | null = null;
+      try {
+        localEpoch = await localDB.get<{ epoch: number }>('db-epoch');
+      } catch {
+        // Local doesn't have the epoch doc — stale
+        return true;
+      }
+
+      return remoteEpoch.epoch !== localEpoch.epoch;
+    } catch {
+      // Remote doesn't have db-epoch — no epoch tracking, not stale
+      return false;
+    }
+  }
+
   /**
    * Get a remote PouchDB handle for a course.
    */

package/src/impl/couch/courseDB.ts

@@ -1,4 +1,5 @@
 import { CourseDBInterface, CourseInfo, CoursesDBInterface, UserDBInterface } from '@db/core';
+import type { ReplanHints } from '@db/study/SessionController';
 import {
   CourseConfig,
   CourseElo,
@@ -650,11 +651,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: ReplanHints | null = null;
+
+  public setEphemeralHints(hints: ReplanHints): 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

@@ -6,6 +6,7 @@ import {
   CourseInfo,
   StudySessionItem,
 } from '../../core/interfaces';
+import type { ReplanHints } from '@db/study/SessionController';
 import { StaticDataUnpacker } from './StaticDataUnpacker';
 import { StaticCourseManifest } from '../../util/packer/types';
 import { CourseConfig, CourseElo, DataShape, Status } from '@vue-skuilder/common';
@@ -442,9 +443,21 @@ export class StaticCourseDB implements CourseDBInterface {
   }
 
   // Study Content Source implementation
+
+  private _pendingHints: ReplanHints | null = null;
+
+  setEphemeralHints(hints: ReplanHints): 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,69 @@ import { SourceMixer, QuotaRoundRobinMixer, SourceBatch } from './SourceMixer';
 import { captureMixerRun } from './MixerDebugger';
 import { startSessionTracking, recordCardPresentation, snapshotQueues, endSessionTracking } from './SessionDebugger';
 
+/**
+ * Typed ephemeral pipeline hints for a single run.
+ * All fields are optional. Tag/card patterns support `*` wildcards.
+ *
+ * Previously defined in Pipeline.ts; moved here so it's co-exported
+ * with ReplanOptions from the public `@vue-skuilder/db` surface.
+ */
+export interface ReplanHints {
+  /** Multiply scores for cards matching these tag patterns. */
+  boostTags?: Record<string, number>;
+  /** Multiply scores for these specific card IDs (glob patterns). */
+  boostCards?: Record<string, number>;
+  /** Cards matching these tag patterns MUST appear in results. */
+  requireTags?: string[];
+  /** These specific card IDs MUST appear in results. */
+  requireCards?: string[];
+  /** Remove cards matching these tag patterns from results. */
+  excludeTags?: string[];
+  /** Remove these specific card IDs from results. */
+  excludeCards?: string[];
+  /**
+   * Debugging label threaded from the replan requester.
+   * Prefixed with `_` to signal it's metadata, not a scoring hint.
+   */
+  _label?: string;
+}
+
+/**
+ * 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?: ReplanHints;
+  /**
+   * 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';
+  /**
+   * Guarantee that at least this many cards will be served after the
+   * replan, even if the session timer has expired. Prevents intro cards
+   * from surfacing at the end of a session with zero follow-up exercise.
+   * Decremented on each card draw while active.
+   */
+  minFollowUpCards?: number;
+  /**
+   * 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;
@@ -75,6 +138,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[] = [];
@@ -104,12 +174,38 @@ 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;
+
+  /**
+   * When > 0, the session timer cannot end the session. Decremented on
+   * each nextCard() draw. Set by replans that include `minFollowUpCards`.
+   */
+  private _minCardsGuarantee: number = 0;
+
   private startTime: Date;
   private endTime: Date;
   private _secondsRemaining: number;
   public get secondsRemaining(): number {
     return this._secondsRemaining;
   }
+  /** True when a card guarantee is active, preventing timer-based session end. */
+  public get hasCardGuarantee(): boolean {
+    return this._minCardsGuarantee > 0;
+  }
   public get report(): string {
     const reviewCount = this.reviewQ.dequeueCount;
     const newCount = this.newQ.dequeueCount;
@@ -129,13 +225,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();
 
@@ -159,9 +260,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() {
@@ -254,22 +360,58 @@ 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 | ReplanHints): 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) {
+    // Auto-exclude the currently-displayed card so the replan doesn't
+    // surface it again (avoids showing the same card twice in a row).
+    if (this._currentCard?.item.cardID) {
+      const currentId = this._currentCard.item.cardID;
+      if (!opts.hints) opts.hints = {};
+      const hints = opts.hints;
+      const excludeCards = hints.excludeCards ?? [];
+      if (!excludeCards.includes(currentId)) {
+        excludeCards.push(currentId);
+      }
+      hints.excludeCards = excludeCards;
+    }
+
+    // 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' : ''})`
+    );
+    // Update card guarantee if requested
+    if (opts.minFollowUpCards !== undefined && opts.minFollowUpCards > 0) {
+      this._minCardsGuarantee = Math.max(this._minCardsGuarantee, opts.minFollowUpCards);
+      this.log(`[Replan] Card guarantee set to ${this._minCardsGuarantee}`);
+    }
+
+    this._replanPromise = this._executeReplan(opts);
 
     try {
       await this._replanPromise;
@@ -278,6 +420,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 | ReplanHints
+  ): ReplanOptions {
+    if (!input) return {};
+
+    // If the input has any ReplanOptions-specific key, treat it as ReplanOptions
+    const replanKeys = ['hints', 'limit', 'mode', 'label', 'minFollowUpCards'];
+    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 ReplanHints };
+  }
+
   /** Minimum well-indicated cards before an additive retry is attempted */
   private static readonly MIN_WELL_INDICATED = 5;
 
@@ -298,18 +462,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);
@@ -381,6 +570,9 @@ export class SessionController<TView = unknown> extends Loggable {
       },
       replan: {
         inProgress: this._replanPromise !== null,
+        suppressQualityReplan: this._suppressQualityReplan,
+        defaultBatchLimit: this._defaultBatchLimit,
+        minCardsGuarantee: this._minCardsGuarantee,
       },
     };
   }
@@ -405,10 +597,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[] = [];
@@ -577,13 +773,13 @@ export class SessionController<TView = unknown> extends Loggable {
       return null;
     }
 
-    if (this._secondsRemaining < 2 && this.failedQ.length === 0) {
+    if (this._secondsRemaining < 2 && this.failedQ.length === 0 && this._minCardsGuarantee <= 0) {
       // session is over!
       return null;
     }
 
-    // If timer expired, only return failed cards
-    if (this._secondsRemaining <= 0) {
+    // If timer expired, only return failed cards (unless card guarantee active)
+    if (this._secondsRemaining <= 0 && this._minCardsGuarantee <= 0) {
       if (this.failedQ.length > 0) {
         return this.failedQ.peek(0);
       } else {
@@ -645,6 +841,12 @@ export class SessionController<TView = unknown> extends Loggable {
     // dismiss (or sort to failedQ) the current card
     this.dismissCurrentCard(action);
 
+    // Decrement card guarantee counter
+    if (this._minCardsGuarantee > 0) {
+      this._minCardsGuarantee--;
+      this.log(`[CardGuarantee] ${this._minCardsGuarantee} guaranteed cards remaining`);
+    }
+
     // If a replan is in flight, wait for it to complete before drawing.
     // This ensures the user sees cards scored against their latest state
     // (e.g. after a GPC intro unlocked new content).
@@ -653,25 +855,75 @@ 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();
     }
 
-    if (this._secondsRemaining <= 0 && this.failedQ.length === 0) {
+    if (this._secondsRemaining <= 0 && this.failedQ.length === 0 && this._minCardsGuarantee <= 0) {
       this._currentCard = null;
       endSessionTracking();
       return null;

package/src/study/services/EloService.ts

@@ -111,10 +111,29 @@ export class EloService {
     const userElo = toCourseElo(
       userCourseRegDoc.courses.find((c) => c.courseID === course_id)!.elo
     );
-    const cardElo = (await courseDB.getCardEloData([currentCard.card.card_id]))[0];
+
+    const [cardEloResults, cardTagsMap] = await Promise.all([
+      courseDB.getCardEloData([currentCard.card.card_id]),
+      courseDB.getAppliedTagsBatch([card_id]),
+    ]);
+    const cardElo = cardEloResults[0];
+
+    // Enrich TaggedPerformance with card-level tags not explicitly graded by
+    // the question's evaluate(). Category tags (concept:*, ui:*, etc.) are not
+    // emitted by individual question types; applying the global score as a proxy
+    // keeps hierarchy filter ELO thresholds functional without overriding any
+    // fine-grained per-GPC scores the question already provided.
+    const cardTags = cardTagsMap.get(card_id) ?? [];
+    const enriched: TaggedPerformance = { ...taggedPerformance };
+    const globalScore = taggedPerformance._global;
+    for (const tag of cardTags) {
+      if (!(tag in enriched)) {
+        enriched[tag] = globalScore;
+      }
+    }
 
     if (cardElo && userElo) {
-      const eloUpdate = adjustCourseScoresPerTag(userElo, cardElo, taggedPerformance);
+      const eloUpdate = adjustCourseScoresPerTag(userElo, cardElo, enriched);
       userCourseRegDoc.courses.find((c) => c.courseID === course_id)!.elo = eloUpdate.userElo;
 
       const results = await Promise.allSettled([
@@ -131,7 +150,7 @@ export class EloService {
         const card = (results[1] as PromiseFulfilledResult<any>).value;
 
         if (user.ok && card && card.ok) {
-          const tagCount = Object.keys(taggedPerformance).length - 1; // exclude _global
+          const tagCount = Object.keys(enriched).length - 1; // exclude _global
           logger.info(
             `[EloService] Updated ELOS (per-tag, ${tagCount} tags):
             \tUser: ${JSON.stringify(eloUpdate.userElo)})

package/src/study/services/ResponseProcessor.ts

@@ -181,6 +181,13 @@ export class ResponseProcessor {
       // Update ELO ratings
       if (taggedPerformance) {
         // Per-tag ELO update
+        const tagKeys = Object.keys(taggedPerformance).filter((k) => k !== '_global');
+        const nullTags = tagKeys.filter((k) => taggedPerformance[k] === null);
+        const scoredTags = tagKeys.filter((k) => taggedPerformance[k] !== null);
+        logger.info(
+          `[ResponseProcessor] per-tag ELO update for ${cardId}: scored=[${scoredTags.join(', ')}] count-only=[${nullTags.join(', ')}]`
+        );
+
         void this.eloService.updateUserAndCardEloPerTag(
           taggedPerformance,
           courseId,
@@ -188,9 +195,6 @@ export class ResponseProcessor {
           courseRegistrationDoc,
           currentCard
         );
-        logger.info(
-          `[ResponseProcessor] Processed correct response with per-tag ELO update (${Object.keys(taggedPerformance).length - 1} tags)`
-        );
       } else {
         // Standard single-score ELO update (backward compatible)
         const userScore = 0.5 + globalScore / 2;