@vue-skuilder/db 0.1.32-b → 0.1.32-e

package/src/core/navigators/generators/srs.ts

@@ -3,9 +3,8 @@ import type { ScheduledCard } from '../../types/user';
 import type { CourseDBInterface } from '../../interfaces/courseDB';
 import type { UserDBInterface } from '../../interfaces/userDB';
 import { ContentNavigator } from '../index';
-import type { WeightedCard } from '../index';
 import type { ContentNavigationStrategyData } from '../../types/contentNavigationStrategy';
-import type { CardGenerator, GeneratorContext } from './types';
+import type { CardGenerator, GeneratorContext, GeneratorResult } from './types';
 import { logger } from '@db/util/logger';
 
 // ============================================================================
@@ -122,7 +121,7 @@ export default class SRSNavigator extends ContentNavigator implements CardGenera
    * @param limit - Maximum number of cards to return
    * @param _context - Optional GeneratorContext (currently unused, but required for interface)
    */
-  async getWeightedCards(limit: number, _context?: GeneratorContext): Promise<WeightedCard[]> {
+  async getWeightedCards(limit: number, _context?: GeneratorContext): Promise<GeneratorResult> {
     if (!this.user || !this.course) {
       throw new Error('SRSNavigator requires user and course to be set');
     }
@@ -189,7 +188,7 @@ export default class SRSNavigator extends ContentNavigator implements CardGenera
     });
 
     // Sort by score descending and limit
-    return scored.sort((a, b) => b.score - a.score).slice(0, limit);
+    return { cards: scored.sort((a, b) => b.score - a.score).slice(0, limit) };
   }
 
   /**

package/src/core/navigators/generators/types.ts

@@ -3,6 +3,30 @@ import type { CourseDBInterface } from '../../interfaces/courseDB';
 import type { UserDBInterface } from '../../interfaces/userDB';
 import type { OrchestrationContext } from '../../orchestration';
 
+/**
+ * Typed ephemeral pipeline hints for a single run.
+ * All fields are optional. Tag/card patterns support `*` wildcards.
+ */
+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;
+}
+
 // ============================================================================
 // CARD GENERATOR INTERFACE
 // ============================================================================
@@ -44,6 +68,21 @@ export interface GeneratorContext {
   // - session state (cards already seen this session)
 }
 
+/**
+ * Structured generator result.
+ *
+ * Generators may optionally emit one-shot replan hints alongside their
+ * candidate cards. This allows a generator to shape the broader pipeline
+ * without having to enumerate every affected support card directly.
+ */
+export interface GeneratorResult {
+  /** Candidate cards produced by the generator */
+  cards: WeightedCard[];
+
+  /** Optional one-shot hints to apply after the filter chain */
+  hints?: ReplanHints;
+}
+
 /**
  * A generator that produces candidate cards with initial scores.
  *
@@ -65,6 +104,9 @@ export interface GeneratorContext {
  *
  * 4. **Sort before returning**: Return cards sorted by score descending.
  *
+ * 5. **Hints are optional**: Generators may return structured results with
+ *    `hints` when they need to apply pipeline-wide ephemeral pressure.
+ *
  * ## Example Implementation
  *
  * ```typescript
@@ -98,9 +140,13 @@ export interface CardGenerator {
    *
    * @param limit - Maximum number of cards to return
    * @param context - Shared context (user, course, userElo, etc.)
-   * @returns Cards sorted by score descending, with provenance
+   * @returns Cards sorted by score descending, with provenance, optionally
+   *          accompanied by one-shot replan hints
    */
-  getWeightedCards(limit: number, context: GeneratorContext): Promise<WeightedCard[]>;
+  getWeightedCards(
+    limit: number,
+    context: GeneratorContext
+  ): Promise<GeneratorResult>;
 }
 
 /**

package/src/core/navigators/index.ts

@@ -4,7 +4,8 @@ import { StudyContentSource, UserDBInterface, CourseDBInterface } from '..';
 export type { CardFilter, FilterContext, CardFilterFactory } from './filters/types';
 
 // Re-export generator types
-export type { CardGenerator, GeneratorContext, CardGeneratorFactory } from './generators/types';
+export type { CardGenerator, GeneratorContext, CardGeneratorFactory, GeneratorResult, ReplanHints } from './generators/types';
+import type { GeneratorResult, ReplanHints } from './generators/types';
 
 // Re-export pipeline debugger API
 export {
@@ -625,7 +626,7 @@ export abstract class ContentNavigator implements StudyContentSource {
    * @param limit - Maximum cards to return
    * @returns Cards sorted by score descending, with provenance trails
    */
-  async getWeightedCards(_limit: number): Promise<WeightedCard[]> {
+  async getWeightedCards(_limit: number): Promise<GeneratorResult> {
     throw new Error(`${this.constructor.name} must implement getWeightedCards(). `);
   }
 
@@ -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/classroomDB.ts

@@ -1,5 +1,6 @@
 import { StudyContentSource } from '@db/core/interfaces/contentSource';
 import { WeightedCard } from '@db/core/navigators';
+import type { GeneratorResult } from '@db/core/navigators/generators/types';
 import { ClassroomConfig } from '@vue-skuilder/common';
 import { ENV } from '@db/factory';
 import { logger } from '@db/util/logger';
@@ -126,7 +127,7 @@ export class StudentClassroomDB
    * @param limit - Maximum number of cards to return
    * @returns Cards sorted by score descending (all scores = 1.0)
    */
-  public async getWeightedCards(limit: number): Promise<WeightedCard[]> {
+  public async getWeightedCards(limit: number): Promise<GeneratorResult> {
     const weighted: WeightedCard[] = [];
 
     // Get pending reviews for this classroom
@@ -167,7 +168,7 @@ export class StudentClassroomDB
       if (content.type === 'course') {
         // Get weighted cards from the course directly
         const db = new CourseDB(content.courseID, async () => this._user);
-        const courseCards = await db.getWeightedCards(limit);
+        const { cards: courseCards } = await db.getWeightedCards(limit);
         for (const card of courseCards) {
           if (!activeCardIds.has(card.cardId)) {
             weighted.push({
@@ -235,7 +236,7 @@ export class StudentClassroomDB
     );
 
     // Sort by score descending and limit
-    return weighted.sort((a, b) => b.score - a.score).slice(0, limit);
+    return { cards: weighted.sort((a, b) => b.score - a.score).slice(0, limit) };
   }
 }
 

package/src/impl/couch/courseDB.ts

@@ -1,4 +1,5 @@
 import { CourseDBInterface, CourseInfo, CoursesDBInterface, UserDBInterface } from '@db/core';
+import type { GeneratorResult, ReplanHints } from '@db/core/navigators/generators/types';
 import {
   CourseConfig,
   CourseElo,
@@ -28,7 +29,7 @@ import { DataLayerResult } from '@db/core/types/db';
 import { PouchError } from './types';
 import CourseLookup from './courseLookupDB';
 import { ContentNavigationStrategyData } from '@db/core/types/contentNavigationStrategy';
-import { ContentNavigator, Navigators, WeightedCard } from '@db/core/navigators';
+import { ContentNavigator, Navigators } from '@db/core/navigators';
 import { PipelineAssembler } from '@db/core/navigators/PipelineAssembler';
 import { createDefaultPipeline } from '@db/core/navigators/defaults';
 
@@ -650,13 +651,13 @@ 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;
+  private _pendingHints: ReplanHints | null = null;
 
-  public setEphemeralHints(hints: Record<string, unknown>): void {
+  public setEphemeralHints(hints: ReplanHints): void {
     this._pendingHints = hints;
   }
 
-  public async getWeightedCards(limit: number): Promise<WeightedCard[]> {
+  public async getWeightedCards(limit: number): Promise<GeneratorResult> {
     const u = await this._getCurrentUser();
 
     try {

package/src/impl/static/courseDB.ts

@@ -6,6 +6,7 @@ import {
   CourseInfo,
   StudySessionItem,
 } from '../../core/interfaces';
+import type { GeneratorResult, ReplanHints } from '../../core/navigators/generators/types';
 import { StaticDataUnpacker } from './StaticDataUnpacker';
 import { StaticCourseManifest } from '../../util/packer/types';
 import { CourseConfig, CourseElo, DataShape, Status } from '@vue-skuilder/common';
@@ -20,7 +21,7 @@ import {
 import { DataLayerResult } from '../../core/types/db';
 import { ContentNavigationStrategyData } from '../../core/types/contentNavigationStrategy';
 
-import { ContentNavigator, WeightedCard } from '../../core/navigators';
+import { ContentNavigator } from '../../core/navigators';
 import { logger } from '../../util/logger';
 import { createDefaultPipeline } from '@db/core/navigators/defaults';
 import { PipelineAssembler } from '@db/core/navigators/PipelineAssembler';
@@ -443,13 +444,13 @@ export class StaticCourseDB implements CourseDBInterface {
 
   // Study Content Source implementation
 
-  private _pendingHints: Record<string, unknown> | null = null;
+  private _pendingHints: ReplanHints | null = null;
 
-  setEphemeralHints(hints: Record<string, unknown>): void {
+  setEphemeralHints(hints: ReplanHints): void {
     this._pendingHints = hints;
   }
 
-  async getWeightedCards(limit: number): Promise<WeightedCard[]> {
+  async getWeightedCards(limit: number): Promise<GeneratorResult> {
     try {
       const navigator = await this.createNavigator(this.userDB);
       // Forward any pending hints to the Pipeline

package/src/study/SessionController.ts

@@ -16,10 +16,15 @@ import { CardRecord, CardHistory, CourseRegistrationDoc, QuestionRecord } from '
 import { recordUserOutcome } from '@db/core/orchestration/recording';
 import { Loggable } from '@db/util';
 import { getCardOrigin } from '@db/core/navigators';
+import { ReplanHints } from '@db/core/navigators/generators/types';
 import { SourceMixer, QuotaRoundRobinMixer, SourceBatch } from './SourceMixer';
 import { captureMixerRun } from './MixerDebugger';
 import { startSessionTracking, recordCardPresentation, snapshotQueues, endSessionTracking } from './SessionDebugger';
 
+// ReplanHints is defined in generators/types to avoid circular dependencies.
+// Re-exported here for backward compatibility.
+export type { ReplanHints } from '@db/core/navigators/generators/types';
+
 /**
  * Options for requesting a mid-session replan.
  *
@@ -29,7 +34,7 @@ import { startSessionTracking, recordCardPresentation, snapshotQueues, endSessio
  */
 export interface ReplanOptions {
   /** Scoring hints forwarded to the pipeline (boost/exclude/require). */
-  hints?: Record<string, unknown>;
+  hints?: ReplanHints;
   /**
    * Maximum number of new cards to return from the pipeline.
    * Default: 20 (the standard session batch size).
@@ -41,6 +46,13 @@ export interface ReplanOptions {
    * - `'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
@@ -156,12 +168,22 @@ export class SessionController<TView = unknown> extends Loggable {
    */
   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;
@@ -316,7 +338,7 @@ 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(options?: ReplanOptions | 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);
 
@@ -331,6 +353,19 @@ export class SessionController<TView = unknown> extends Loggable {
       return this._replanPromise;
     }
 
+    // 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
@@ -348,6 +383,12 @@ export class SessionController<TView = unknown> extends Loggable {
       ` (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 {
@@ -364,19 +405,19 @@ export class SessionController<TView = unknown> extends Loggable {
    * the presence of ReplanOptions-specific keys.
    */
   private normalizeReplanOptions(
-    input?: ReplanOptions | Record<string, unknown>
+    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'];
+    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 Record<string, unknown> };
+    return { hints: input as ReplanHints };
   }
 
   /** Minimum well-indicated cards before an additive retry is attempted */
@@ -509,6 +550,7 @@ export class SessionController<TView = unknown> extends Loggable {
         inProgress: this._replanPromise !== null,
         suppressQualityReplan: this._suppressQualityReplan,
         defaultBatchLimit: this._defaultBatchLimit,
+        minCardsGuarantee: this._minCardsGuarantee,
       },
     };
   }
@@ -549,7 +591,7 @@ export class SessionController<TView = unknown> extends Loggable {
       const source = this.sources[i];
       try {
         // Fetch weighted cards for mixing
-        const weighted = await source.getWeightedCards!(limit);
+        const weighted = (await source.getWeightedCards!(limit)).cards;
 
         batches.push({
           sourceIndex: i,
@@ -709,13 +751,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 {
@@ -777,6 +819,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).
@@ -853,7 +901,7 @@ export class SessionController<TView = unknown> extends Loggable {
       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/TagFilteredContentSource.ts

@@ -1,5 +1,6 @@
 import { StudyContentSource } from '@db/core/interfaces/contentSource';
 import { WeightedCard } from '@db/core/navigators';
+import type { GeneratorResult } from '@db/core/navigators/generators/types';
 import { UserDBInterface } from '@db/core';
 import { TagFilter, hasActiveFilter } from '@vue-skuilder/common';
 import { getTag } from '../impl/couch/courseDB';
@@ -117,10 +118,10 @@ export class TagFilteredContentSource implements StudyContentSource {
    * @param limit - Maximum number of cards to return
    * @returns Cards sorted by score descending (all scores = 1.0)
    */
-  public async getWeightedCards(limit: number): Promise<WeightedCard[]> {
+  public async getWeightedCards(limit: number): Promise<GeneratorResult> {
     if (!hasActiveFilter(this.filter)) {
       logger.warn('[TagFilteredContentSource] getWeightedCards called with no active filter');
-      return [];
+      return { cards: [] };
     }
 
     const eligibleCardIds = await this.resolveFilteredCardIds();
@@ -185,7 +186,7 @@ export class TagFilteredContentSource implements StudyContentSource {
     }));
 
     // Reviews first, then new cards; respect limit
-    return [...reviewWeighted, ...newCardWeighted].slice(0, limit);
+    return { cards: [...reviewWeighted, ...newCardWeighted].slice(0, limit) };
   }
 
   /**

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;