@vue-skuilder/db 0.1.31-b → 0.1.31

package/src/impl/couch/CourseSyncService.ts

@@ -0,0 +1,356 @@
+import pouch from './pouchdb-setup';
+import { getCourseDB } from '.';
+import { logger } from '../../util/logger';
+import type { CourseConfig } from '@vue-skuilder/common';
+
+// ============================================================================
+// COURSE SYNC SERVICE
+// ============================================================================
+//
+// Manages client-side PouchDB replicas of course databases.
+//
+// Courses opt in to local sync via CourseConfig.localSync.enabled. When
+// enabled, the service performs a one-shot replication from remote CouchDB
+// to a local PouchDB on first visit, then incremental sync on subsequent
+// visits. Pipeline scoring, tag hydration, and card lookup then run against
+// the local replica — eliminating network round trips from the study-session
+// hot path.
+//
+// Read/write split:
+//   Local DB  = read-only snapshot (pipeline, filters, card lookup)
+//   Remote DB = all writes (ELO updates, tag mutations, admin ops)
+//
+// This avoids propagating per-interaction ELO write noise to every syncing
+// client. Each client's local snapshot refreshes on the next page load.
+//
+// Live replication is intentionally NOT supported. The remote course DB
+// receives high-frequency ELO updates from all concurrent users — live
+// sync would cause constant re-indexing of local PouchDB views.
+//
+// ============================================================================
+
+/**
+ * Sync state for a single course database.
+ */
+export type CourseSyncState =
+  | 'not-started'
+  | 'checking-config'
+  | 'syncing'
+  | 'warming-views'
+  | 'ready'
+  | 'disabled'
+  | 'error';
+
+/**
+ * Detailed sync status for observability.
+ */
+export interface CourseSyncStatus {
+  state: CourseSyncState;
+  /** Number of documents replicated (set after sync completes) */
+  docsReplicated?: number;
+  /** Total replication time in ms */
+  syncTimeMs?: number;
+  /** View warming time in ms */
+  viewWarmTimeMs?: number;
+  /** Error message if state is 'error' */
+  error?: string;
+}
+
+/**
+ * Internal tracking entry per course.
+ */
+interface SyncEntry {
+  localDB: PouchDB.Database | null;
+  status: CourseSyncStatus;
+  /** Promise that resolves when sync is complete (or rejects on failure) */
+  readyPromise: Promise<void> | null;
+}
+
+/**
+ * Service that manages local PouchDB replicas of course databases.
+ *
+ * Usage:
+ * ```typescript
+ * const syncService = CourseSyncService.getInstance();
+ *
+ * // Trigger sync (typically on app load / pre-session)
+ * await syncService.ensureSynced(courseId);
+ *
+ * // Get local DB for reads (returns null if sync not ready/enabled)
+ * const localDB = syncService.getLocalDB(courseId);
+ * ```
+ *
+ * The service is a singleton — course sync state is shared across the app.
+ */
+export class CourseSyncService {
+  private static instance: CourseSyncService | null = null;
+
+  private entries: Map<string, SyncEntry> = new Map();
+
+  private constructor() {}
+
+  static getInstance(): CourseSyncService {
+    if (!CourseSyncService.instance) {
+      CourseSyncService.instance = new CourseSyncService();
+    }
+    return CourseSyncService.instance;
+  }
+
+  /**
+   * Reset the singleton (for testing).
+   */
+  static resetInstance(): void {
+    if (CourseSyncService.instance) {
+      // Close all local DBs
+      for (const [, entry] of CourseSyncService.instance.entries) {
+        if (entry.localDB) {
+          entry.localDB.close().catch(() => {});
+        }
+      }
+      CourseSyncService.instance.entries.clear();
+    }
+    CourseSyncService.instance = null;
+  }
+
+  // --------------------------------------------------------------------------
+  // Public API
+  // --------------------------------------------------------------------------
+
+  /**
+   * Ensure a course's local replica is synced.
+   *
+   * On first call for a course:
+   *   1. Fetches CourseConfig from remote to check localSync.enabled
+   *   2. If enabled, performs one-shot replication remote → local
+   *   3. Pre-warms PouchDB view indices (elo, getTags)
+   *
+   * On subsequent calls: returns immediately if already synced, or awaits
+   * the in-flight sync if one is in progress.
+   *
+   * Safe to call multiple times — concurrent calls coalesce to one sync.
+   *
+   * @param courseId - The course to sync
+   * @param forceEnabled - Skip the CourseConfig check and sync regardless.
+   *   Useful when the caller already knows local sync is desired (e.g.,
+   *   LettersPractice hardcodes this).
+   */
+  async ensureSynced(courseId: string, forceEnabled?: boolean): Promise<void> {
+    const existing = this.entries.get(courseId);
+
+    // Already synced
+    if (existing?.status.state === 'ready') {
+      return;
+    }
+
+    // Already disabled
+    if (existing?.status.state === 'disabled') {
+      return;
+    }
+
+    // Sync in flight — coalesce
+    if (existing?.readyPromise) {
+      return existing.readyPromise;
+    }
+
+    // Start a new sync
+    const entry: SyncEntry = {
+      localDB: null,
+      status: { state: 'not-started' },
+      readyPromise: null,
+    };
+    this.entries.set(courseId, entry);
+
+    entry.readyPromise = this.performSync(courseId, entry, forceEnabled);
+    return entry.readyPromise;
+  }
+
+  /**
+   * Get the local PouchDB for a course, or null if not available.
+   *
+   * Returns null when:
+   *   - Local sync is not enabled for this course
+   *   - Sync has not been triggered yet
+   *   - Sync is still in progress
+   *   - Sync failed
+   */
+  getLocalDB(courseId: string): PouchDB.Database | null {
+    const entry = this.entries.get(courseId);
+    if (entry?.status.state === 'ready' && entry.localDB) {
+      return entry.localDB;
+    }
+    return null;
+  }
+
+  /**
+   * Check whether a course has a ready local replica.
+   */
+  isReady(courseId: string): boolean {
+    return this.entries.get(courseId)?.status.state === 'ready';
+  }
+
+  /**
+   * Get detailed sync status for a course.
+   */
+  getStatus(courseId: string): CourseSyncStatus {
+    return (
+      this.entries.get(courseId)?.status ?? { state: 'not-started' }
+    );
+  }
+
+  // --------------------------------------------------------------------------
+  // Internal
+  // --------------------------------------------------------------------------
+
+  private async performSync(
+    courseId: string,
+    entry: SyncEntry,
+    forceEnabled?: boolean
+  ): Promise<void> {
+    try {
+      // Step 1: Check if local sync is enabled for this course
+      if (!forceEnabled) {
+        entry.status = { state: 'checking-config' };
+        const enabled = await this.checkLocalSyncEnabled(courseId);
+        if (!enabled) {
+          entry.status = { state: 'disabled' };
+          entry.readyPromise = null;
+          logger.debug(
+            `[CourseSyncService] Local sync disabled for course ${courseId}`
+          );
+          return;
+        }
+      }
+
+      // Step 2: Create local PouchDB and replicate
+      entry.status = { state: 'syncing' };
+      const localDBName = this.localDBName(courseId);
+      const localDB = new pouch(localDBName);
+      entry.localDB = localDB;
+
+      const remoteDB = this.getRemoteDB(courseId);
+      const syncStart = Date.now();
+
+      logger.info(
+        `[CourseSyncService] Starting one-shot replication for course ${courseId}`
+      );
+
+      const result = await this.replicate(remoteDB, localDB);
+      const syncTimeMs = Date.now() - syncStart;
+
+      logger.info(
+        `[CourseSyncService] Replication complete for course ${courseId}: ` +
+          `${result.docs_written} docs in ${syncTimeMs}ms`
+      );
+
+      // Step 3: Pre-warm view indices
+      entry.status = { state: 'warming-views' };
+      const warmStart = Date.now();
+      await this.warmViewIndices(localDB);
+      const viewWarmTimeMs = Date.now() - warmStart;
+
+      logger.info(
+        `[CourseSyncService] View indices warmed for course ${courseId} in ${viewWarmTimeMs}ms`
+      );
+
+      // Done
+      entry.status = {
+        state: 'ready',
+        docsReplicated: result.docs_written,
+        syncTimeMs,
+        viewWarmTimeMs,
+      };
+    } catch (e) {
+      const errorMsg = e instanceof Error ? e.message : String(e);
+      logger.error(
+        `[CourseSyncService] Sync failed for course ${courseId}: ${errorMsg}`
+      );
+      entry.status = { state: 'error', error: errorMsg };
+      entry.readyPromise = null;
+
+      // Clean up the local DB on failure — don't leave a partial replica
+      if (entry.localDB) {
+        try {
+          await entry.localDB.destroy();
+        } catch {
+          // Ignore cleanup errors
+        }
+        entry.localDB = null;
+      }
+    }
+  }
+
+  /**
+   * Check CourseConfig.localSync.enabled on the remote DB.
+   */
+  private async checkLocalSyncEnabled(courseId: string): Promise<boolean> {
+    try {
+      const remoteDB = this.getRemoteDB(courseId);
+      const config = await remoteDB.get<CourseConfig>('CourseConfig');
+      return config.localSync?.enabled === true;
+    } catch (e) {
+      logger.warn(
+        `[CourseSyncService] Could not read CourseConfig for ${courseId}, ` +
+          `assuming local sync disabled: ${e}`
+      );
+      return false;
+    }
+  }
+
+  /**
+   * One-shot replication from remote to local.
+   */
+  private replicate(
+    source: PouchDB.Database,
+    target: PouchDB.Database
+  ): Promise<PouchDB.Replication.ReplicationResultComplete<object>> {
+    return new Promise((resolve, reject) => {
+      void pouch.replicate(source, target, {
+        // One-shot, not live. Local is a read-only snapshot.
+      })
+        .on('complete', (info) => {
+          resolve(info);
+        })
+        .on('error', (err) => {
+          reject(err);
+        });
+    });
+  }
+
+  /**
+   * Pre-warm PouchDB view indices by running a minimal query against each
+   * design doc. This forces PouchDB to build the MapReduce index now
+   * (during a loading phase) rather than on first pipeline query.
+   */
+  private async warmViewIndices(localDB: PouchDB.Database): Promise<void> {
+    const viewsToWarm = ['elo', 'getTags'];
+
+    for (const viewName of viewsToWarm) {
+      try {
+        await localDB.query(viewName, { limit: 1 });
+        logger.debug(
+          `[CourseSyncService] Warmed view index: ${viewName}`
+        );
+      } catch (e) {
+        // View might not exist in this course DB — that's OK.
+        // Not all courses have all design docs.
+        logger.debug(
+          `[CourseSyncService] Could not warm view ${viewName}: ${e}`
+        );
+      }
+    }
+  }
+
+  /**
+   * Get a remote PouchDB handle for a course.
+   */
+  private getRemoteDB(courseId: string): PouchDB.Database {
+    return getCourseDB(courseId);
+  }
+
+  /**
+   * Local DB naming convention.
+   */
+  private localDBName(courseId: string): string {
+    return `coursedb-local-${courseId}`;
+  }
+}

package/src/impl/couch/PouchDataLayerProvider.ts

@@ -17,6 +17,7 @@ import { getLoggedInUsername } from './auth';
 import { AdminDB } from './adminDB';
 import { StudentClassroomDB, TeacherClassroomDB } from './classroomDB';
 import { CourseDB, CoursesDB } from './courseDB';
+import { CourseSyncService } from './CourseSyncService';
 
 import { BaseUser } from '../common';
 import { CouchDBSyncStrategy } from './CouchDBSyncStrategy';
@@ -73,7 +74,26 @@ export class CouchDataLayerProvider implements DataLayerProvider {
   }
 
   getCourseDB(courseId: string): CourseDBInterface {
-    return new CourseDB(courseId, async () => this.getUserDB());
+    // If the CourseSyncService has a ready local replica for this course,
+    // pass it to CourseDB so reads (pipeline, card hydration) run locally.
+    // Writes always go to the remote DB (handled inside CourseDB).
+    const localDB = CourseSyncService.getInstance().getLocalDB(courseId);
+    return new CourseDB(courseId, async () => this.getUserDB(), localDB ?? undefined);
+  }
+
+  /**
+   * Trigger local sync for a course. Call during app initialization or
+   * pre-session loading for courses that opt in via CourseConfig.localSync.
+   *
+   * Safe to call multiple times — concurrent calls coalesce. Returns when
+   * sync is complete (or immediately if already synced / disabled).
+   *
+   * @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.
+   */
+  async ensureCourseSynced(courseId: string, forceEnabled?: boolean): Promise<void> {
+    return CourseSyncService.getInstance().ensureSynced(courseId, forceEnabled);
   }
 
   getCoursesDB(): CoursesDBInterface {

package/src/impl/couch/courseDB.ts

@@ -9,7 +9,7 @@ import {
   toCourseElo,
 } from '@vue-skuilder/common';
 
-import { filterAllDocsByPrefix, getCourseDB, getCourseDoc, getCourseDocs } from '.';
+import { filterAllDocsByPrefix, getCourseDB } from '.';
 import UpdateQueue from './updateQueue';
 import { StudySessionItem } from '../../core/interfaces/contentSource';
 import {
@@ -94,16 +94,48 @@ export class CourseDB implements CourseDBInterface {
   //   log(`CourseLog: ${this.id}\n  ${msg}`);
   // }
 
+  /**
+   * Primary database handle used for all **read** operations (queries, gets).
+   *
+   * When local sync is active, this points to the local PouchDB replica for
+   * fast, network-free reads. Otherwise it points to the remote CouchDB.
+   */
   private db: PouchDB.Database;
+
+  /**
+   * Remote database handle used for all **write** operations.
+   *
+   * Always points to the remote CouchDB so that writes (ELO updates, tag
+   * mutations, admin operations) aggregate on the server. The local replica
+   * is a read-only snapshot that refreshes on the next page load.
+   *
+   * When local sync is NOT active, this is the same instance as `this.db`.
+   */
+  private remoteDB: PouchDB.Database;
+
   private id: string;
   private _getCurrentUser: () => Promise<UserDBInterface>;
   private updateQueue: UpdateQueue;
 
-  constructor(id: string, userLookup: () => Promise<UserDBInterface>) {
+  /**
+   * @param id - Course ID
+   * @param userLookup - Async function returning the current user DB
+   * @param localDB - Optional local PouchDB replica for reads. When provided,
+   *   `this.db` uses the local replica and `this.remoteDB` stays remote.
+   *   The UpdateQueue reads from remote and writes to remote (local `_rev`
+   *   values may be stale, so read-modify-write cycles must go through
+   *   the remote DB to avoid conflicts).
+   */
+  constructor(id: string, userLookup: () => Promise<UserDBInterface>, localDB?: PouchDB.Database) {
     this.id = id;
-    this.db = getCourseDB(this.id);
+    const remote = getCourseDB(this.id);
+    this.remoteDB = remote;
+    this.db = localDB ?? remote;
     this._getCurrentUser = userLookup;
-    this.updateQueue = new UpdateQueue(this.db);
+    // UpdateQueue always operates against the remote DB for its
+    // read-modify-write cycle. Local _rev values may be stale (the local
+    // replica is a snapshot), so conflict retries must read from remote.
+    this.updateQueue = new UpdateQueue(this.remoteDB, this.remoteDB);
   }
 
   public getCourseID(): string {
@@ -217,7 +249,9 @@ export class CourseDB implements CourseDBInterface {
   }
 
   public async removeCard(id: string) {
-    const doc = await this.db.get<CardData>(id);
+    // Admin operation — read and write both go through remote DB to ensure
+    // we have the current _rev for the delete.
+    const doc = await this.remoteDB.get<CardData>(id);
     if (!doc.docType || !(doc.docType === DocType.CARD)) {
       throw new Error(`failed to remove ${id} from course ${this.id}. id does not point to a card`);
     }
@@ -244,7 +278,7 @@ export class CourseDB implements CourseDBInterface {
       // Continue with card deletion even if tag cleanup fails
     }
 
-    return this.db.remove(doc);
+    return this.remoteDB.remove(doc);
   }
 
   public async getCardDisplayableDataIDs(id: string[]) {
@@ -364,8 +398,7 @@ above:\n${above.rows.map((r) => `\t${r.id}-${r.key}\n`)}`;
       return new Map();
     }
 
-    const db = getCourseDB(this.id);
-    const result = await db.query<TagStub>('getTags', {
+    const result = await this.db.query<TagStub>('getTags', {
       keys: cardIds,
       include_docs: false,
     });
@@ -389,6 +422,15 @@ above:\n${above.rows.map((r) => `\t${r.id}-${r.key}\n`)}`;
     return tagsByCard;
   }
 
+  async getAllCardIds(): Promise<string[]> {
+    const result = await this.db.allDocs({
+      startkey: 'CARD-',
+      endkey: 'CARD-\ufff0',
+      include_docs: false,
+    });
+    return result.rows.map((row) => row.id);
+  }
+
   async addTagToCard(
     cardId: string,
     tagId: string,
@@ -479,14 +521,20 @@ above:\n${above.rows.map((r) => `\t${r.id}-${r.key}\n`)}`;
     id: string,
     options?: PouchDB.Core.GetOptions
   ): Promise<PouchDB.Core.GetMeta & PouchDB.Core.Document<T>> {
-    return await getCourseDoc(this.id, id, options);
+    // Use this.db (local when available) for read operations.
+    // Falls back to the standalone helper (always remote) only if needed.
+    return await this.db.get<T>(id, options) as PouchDB.Core.GetMeta & PouchDB.Core.Document<T>;
   }
 
   async getCourseDocs<T extends SkuilderCourseData>(
     ids: string[],
     options: PouchDB.Core.AllDocsOptions = {}
   ): Promise<PouchDB.Core.AllDocsWithKeysResponse<{} & T>> {
-    return await getCourseDocs(this.id, ids, options);
+    // Use this.db (local when available) for read operations.
+    return await this.db.allDocs<T>({
+      ...options,
+      keys: ids,
+    }) as PouchDB.Core.AllDocsWithKeysResponse<{} & T>;
   }
 
   ////////////////////////////////////
@@ -524,9 +572,8 @@ above:\n${above.rows.map((r) => `\t${r.id}-${r.key}\n`)}`;
 
   async addNavigationStrategy(data: ContentNavigationStrategyData): Promise<void> {
     logger.debug(`[courseDB] Adding navigation strategy: ${data._id}`);
-    // // For now, just log the data and return success
-    // logger.debug(JSON.stringify(data));
-    return this.db.put(data).then(() => {});
+    // Admin write operation — use remote DB.
+    return this.remoteDB.put(data).then(() => {});
   }
   updateNavigationStrategy(id: string, data: ContentNavigationStrategyData): Promise<void> {
     logger.debug(`[courseDB] Updating navigation strategy: ${id}`);

package/src/impl/couch/index.ts

@@ -288,4 +288,5 @@ export * from './adminDB';
 export * from './classroomDB';
 export * from './courseAPI';
 export * from './courseDB';
+export * from './CourseSyncService';
 export * from './CouchDBSyncStrategy';

package/src/impl/static/courseDB.ts

@@ -244,6 +244,11 @@ export class StaticCourseDB implements CourseDBInterface {
     return tagsByCard;
   }
 
+  async getAllCardIds(): Promise<string[]> {
+    const tagsIndex = await this.unpacker.getTagsIndex();
+    return Object.keys(tagsIndex.byCard);
+  }
+
   async addTagToCard(_cardId: string, _tagId: string): Promise<PouchDB.Core.Response> {
     throw new Error('Cannot modify tags in static mode');
   }

package/src/study/ItemQueue.ts

@@ -47,6 +47,48 @@ export class ItemQueue<T> {
     }
   }
 
+  /**
+   * Atomically replace all queue contents with new items.
+   *
+   * Used by mid-session replanning to swap the queue without a window where
+   * it's empty (avoiding dead-air if nextCard() is called concurrently).
+   *
+   * Preserves dequeueCount (cumulative across the session).
+   * Resets seenCardIds to match the new contents — cards from the old queue
+   * that don't appear in the new set can be re-added in future replans.
+   */
+  public replaceAll(items: T[], cardIdExtractor: (item: T) => string): void {
+    this.q = [];
+    this.seenCardIds = [];
+    for (const item of items) {
+      const cardId = cardIdExtractor(item);
+      if (!this.seenCardIds.includes(cardId)) {
+        this.seenCardIds.push(cardId);
+        this.q.push(item);
+      }
+    }
+  }
+
+  /**
+   * Merge new items into the front of the queue, skipping duplicates.
+   * Used by additive replans to inject high-quality candidates without
+   * discarding the existing queue contents.
+   */
+  public mergeToFront(items: T[], cardIdExtractor: (item: T) => string): number {
+    let added = 0;
+    const toInsert: T[] = [];
+    for (const item of items) {
+      const cardId = cardIdExtractor(item);
+      if (!this.seenCardIds.includes(cardId)) {
+        this.seenCardIds.push(cardId);
+        toInsert.push(item);
+        added++;
+      }
+    }
+    this.q.unshift(...toInsert);
+    return added;
+  }
+
   public get toString(): string {
     return (
       `${typeof this.q[0]}:\n` +