@vue-skuilder/db 0.1.32-b → 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,9 +651,9 @@ 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;
   }
 

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';
@@ -443,9 +444,9 @@ 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;
   }
 

package/src/study/SessionController.ts

@@ -20,6 +20,33 @@ 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.
  *
@@ -29,7 +56,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 +68,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 +190,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 +360,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 +375,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 +405,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 +427,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 +572,7 @@ export class SessionController<TView = unknown> extends Loggable {
         inProgress: this._replanPromise !== null,
         suppressQualityReplan: this._suppressQualityReplan,
         defaultBatchLimit: this._defaultBatchLimit,
+        minCardsGuarantee: this._minCardsGuarantee,
       },
     };
   }
@@ -709,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 {
@@ -777,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).
@@ -853,7 +923,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/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;

package/dist/dataLayerProvider-BKmVoyJR.d.ts

@@ -1,67 +0,0 @@
-import { U as UserDBInterface, a as UserDBReader, C as CourseDBInterface, b as CoursesDBInterface, c as ClassroomDBInterface, A as AdminDBInterface } from './contentSource-Bdwkvqa8.js';
-
-/**
- * Main factory interface for data access
- */
-interface DataLayerProvider {
-    /**
-     * Get the user database interface
-     */
-    getUserDB(): UserDBInterface;
-    /**
-     * Create a UserDBReader for a specific user (admin access required)
-     * Uses session authentication to verify requesting user is admin
-     * @param targetUsername - The username to create a reader for
-     * @throws Error if requesting user is not 'admin'
-     */
-    createUserReaderForUser(targetUsername: string): Promise<UserDBReader>;
-    /**
-     * Get a course database interface
-     */
-    getCourseDB(courseId: string): CourseDBInterface;
-    /**
-     * Get the courses-lookup interface
-     */
-    getCoursesDB(): CoursesDBInterface;
-    /**
-     * Get a classroom database interface
-     */
-    getClassroomDB(classId: string, type: 'student' | 'teacher'): Promise<ClassroomDBInterface>;
-    /**
-     * Get the admin database interface
-     */
-    getAdminDB(): AdminDBInterface;
-    /**
-     * Initialize the data layer
-     */
-    initialize(): Promise<void>;
-    /**
-     * Teardown the data layer
-     */
-    teardown(): Promise<void>;
-    /**
-     * Check if this data layer is read-only
-     */
-    isReadOnly(): boolean;
-    /**
-     * Trigger local replication of a course database.
-     *
-     * When a course opts in via `CourseConfig.localSync.enabled`, this method
-     * replicates the remote course DB to a local PouchDB instance. Subsequent
-     * `getCourseDB()` calls for that course will return a CourseDB that reads
-     * from the local replica (fast, no network) and writes to the remote
-     * (ELO updates, admin ops).
-     *
-     * Safe to call multiple times — concurrent calls coalesce. Returns when
-     * sync is complete (or immediately if already synced / disabled).
-     *
-     * Implementations that don't support local sync may no-op.
-     *
-     * @param courseId - The course to sync locally
-     * @param forceEnabled - Skip CourseConfig check and sync regardless.
-     *   Use when the caller already knows local sync is desired.
-     */
-    ensureCourseSynced?(courseId: string, forceEnabled?: boolean): Promise<void>;
-}
-
-export type { DataLayerProvider as D };

package/dist/dataLayerProvider-BQdfJuBN.d.cts

@@ -1,67 +0,0 @@
-import { U as UserDBInterface, a as UserDBReader, C as CourseDBInterface, b as CoursesDBInterface, c as ClassroomDBInterface, A as AdminDBInterface } from './contentSource-DF1nUbPQ.cjs';
-
-/**
- * Main factory interface for data access
- */
-interface DataLayerProvider {
-    /**
-     * Get the user database interface
-     */
-    getUserDB(): UserDBInterface;
-    /**
-     * Create a UserDBReader for a specific user (admin access required)
-     * Uses session authentication to verify requesting user is admin
-     * @param targetUsername - The username to create a reader for
-     * @throws Error if requesting user is not 'admin'
-     */
-    createUserReaderForUser(targetUsername: string): Promise<UserDBReader>;
-    /**
-     * Get a course database interface
-     */
-    getCourseDB(courseId: string): CourseDBInterface;
-    /**
-     * Get the courses-lookup interface
-     */
-    getCoursesDB(): CoursesDBInterface;
-    /**
-     * Get a classroom database interface
-     */
-    getClassroomDB(classId: string, type: 'student' | 'teacher'): Promise<ClassroomDBInterface>;
-    /**
-     * Get the admin database interface
-     */
-    getAdminDB(): AdminDBInterface;
-    /**
-     * Initialize the data layer
-     */
-    initialize(): Promise<void>;
-    /**
-     * Teardown the data layer
-     */
-    teardown(): Promise<void>;
-    /**
-     * Check if this data layer is read-only
-     */
-    isReadOnly(): boolean;
-    /**
-     * Trigger local replication of a course database.
-     *
-     * When a course opts in via `CourseConfig.localSync.enabled`, this method
-     * replicates the remote course DB to a local PouchDB instance. Subsequent
-     * `getCourseDB()` calls for that course will return a CourseDB that reads
-     * from the local replica (fast, no network) and writes to the remote
-     * (ELO updates, admin ops).
-     *
-     * Safe to call multiple times — concurrent calls coalesce. Returns when
-     * sync is complete (or immediately if already synced / disabled).
-     *
-     * Implementations that don't support local sync may no-op.
-     *
-     * @param courseId - The course to sync locally
-     * @param forceEnabled - Skip CourseConfig check and sync regardless.
-     *   Use when the caller already knows local sync is desired.
-     */
-    ensureCourseSynced?(courseId: string, forceEnabled?: boolean): Promise<void>;
-}
-
-export type { DataLayerProvider as D };