@vue-skuilder/db 0.1.38 → 0.1.40

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.38",
+  "version": "0.1.40",
   "description": "Database layer for vue-skuilder",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -48,7 +48,7 @@
   },
   "dependencies": {
     "@nilock2/pouchdb-authentication": "^1.0.2",
-    "@vue-skuilder/common": "0.1.38",
+    "@vue-skuilder/common": "0.1.40",
     "cross-fetch": "^4.1.0",
     "moment": "^2.29.4",
     "pouchdb": "^9.0.0",
@@ -62,5 +62,5 @@
     "vite": "^8.0.0",
     "vitest": "^4.1.0"
   },
-  "stableVersion": "0.1.38"
+  "stableVersion": "0.1.40"
 }

package/src/factory.ts

@@ -37,6 +37,18 @@ export interface DataLayerConfig {
     COUCHDB_PASSWORD?: string;
 
     COURSE_IDS?: string[];
+
+    /**
+     * Per-app tuning for the CouchDB→PouchDB course sync. Only applies when
+     * `type === 'couch'` and the course has `localSync.enabled === true`.
+     * See CourseSyncService.ReplicationOptions for defaults.
+     */
+    courseSync?: {
+      replication?: {
+        batchSize?: number;
+        batchesLimit?: number;
+      };
+    };
   };
 }
 
@@ -69,6 +81,11 @@ export async function initializeDataLayer(config: DataLayerConfig): Promise<Data
     ENV.COUCHDB_USERNAME = config.options.COUCHDB_USERNAME;
     ENV.COUCHDB_PASSWORD = config.options.COUCHDB_PASSWORD;
 
+    if (config.options.courseSync) {
+      const { CourseSyncService } = await import('./impl/couch/CourseSyncService');
+      CourseSyncService.getInstance().configure(config.options.courseSync);
+    }
+
     if (
       config.options.COUCHDB_PASSWORD &&
       config.options.COUCHDB_USERNAME &&

package/src/impl/couch/CourseSyncService.ts

@@ -82,10 +82,33 @@ interface SyncEntry {
  *
  * The service is a singleton — course sync state is shared across the app.
  */
+/**
+ * Tuning knobs for one-shot remote→local replication.
+ * Defaults are chosen for one-shot snapshot replication of bounded course
+ * corpora (text/JSON docs, no large attachments). PouchDB's built-in
+ * defaults (100/10) target live continuous sync — too conservative for
+ * cold-load UX on a course of a few thousand docs.
+ *
+ * Apps with smaller/larger corpora can override via
+ * `initializeDataLayer({ options: { courseSync: { replication: {...} } } })`.
+ */
+export interface ReplicationOptions {
+  /** Docs per `_bulk_get` HTTP request. Higher = fewer roundtrips. */
+  batchSize?: number;
+  /** Concurrent batches in flight. */
+  batchesLimit?: number;
+}
+
+const DEFAULT_REPLICATION: Required<ReplicationOptions> = {
+  batchSize: 1000,
+  batchesLimit: 5,
+};
+
 export class CourseSyncService {
   private static instance: CourseSyncService | null = null;
 
   private entries: Map<string, SyncEntry> = new Map();
+  private replicationOptions: Required<ReplicationOptions> = DEFAULT_REPLICATION;
 
   private constructor() {}
 
@@ -96,6 +119,24 @@ export class CourseSyncService {
     return CourseSyncService.instance;
   }
 
+  /**
+   * Apply replication tuning. Typically called once from `initializeDataLayer`.
+   * Partial overrides merge with defaults.
+   */
+  configure(opts: { replication?: ReplicationOptions }): void {
+    if (opts.replication) {
+      this.replicationOptions = {
+        ...DEFAULT_REPLICATION,
+        ...opts.replication,
+      };
+      logger.info(
+        `[CourseSyncService] Replication configured: ` +
+          `batch_size=${this.replicationOptions.batchSize}, ` +
+          `batches_limit=${this.replicationOptions.batchesLimit}`
+      );
+    }
+  }
+
   /**
    * Reset the singleton (for testing).
    */
@@ -264,7 +305,9 @@ export class CourseSyncService {
       const syncStart = Date.now();
 
       logger.info(
-        `[CourseSyncService] Starting one-shot replication for course ${courseId}`
+        `[CourseSyncService] Starting one-shot replication for course ${courseId} ` +
+          `(batch_size=${this.replicationOptions.batchSize}, ` +
+          `batches_limit=${this.replicationOptions.batchesLimit})`
       );
 
       const result = await this.replicate(remoteDB, localDB);
@@ -339,6 +382,8 @@ export class CourseSyncService {
     return new Promise((resolve, reject) => {
       void pouch.replicate(source, target, {
         // One-shot, not live. Local is a read-only snapshot.
+        batch_size: this.replicationOptions.batchSize,
+        batches_limit: this.replicationOptions.batchesLimit,
       })
         .on('complete', (info) => {
           resolve(info);

package/src/study/SessionController.ts

@@ -171,14 +171,6 @@ export class SessionController<TView = unknown> extends Loggable {
    */
   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`.
@@ -370,12 +362,6 @@ export class SessionController<TView = unknown> extends Loggable {
     // 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;
-    }
-
     const hasIntent = this._replanHasIntent(opts);
 
     if (this._replanPromise) {
@@ -495,6 +481,26 @@ export class SessionController<TView = unknown> extends Loggable {
     await this._executeReplan(opts);
   }
 
+  /**
+   * Run a replan, bypassing requestReplan()'s coalesce logic.
+   *
+   * Use this when correctness depends on a *fresh* pipeline run, not on
+   * the existence of *some* in-flight replan. Specifically: the
+   * wedge-breaker path in nextCard(), where coalescing into a previous
+   * run that we now know produced insufficient content would re-create
+   * the bug we're trying to prevent.
+   *
+   * Still tracks _replanPromise like requestReplan() does so concurrent
+   * observers (auto-trigger guards in nextCard()) see consistent state.
+   */
+  private async _replanUncoalesced(opts: ReplanOptions): Promise<void> {
+    const run = this._runReplan(opts);
+    this._replanPromise = run.finally(() => {
+      if (this._replanPromise === run) this._replanPromise = null;
+    });
+    await run;
+  }
+
   /**
    * Normalise the requestReplan argument. Accepts either a ReplanOptions
    * object (new API) or a plain Record<string, unknown> (legacy callers
@@ -565,12 +571,6 @@ export class SessionController<TView = unknown> extends Loggable {
       );
     }
 
-    // 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();
     const labelTag = opts.label ? ` [${opts.label}]` : '';
     this.log(`Replan complete${labelTag}: newQ now has ${this.newQ.length} cards (mode=${mode})`);
@@ -933,68 +933,60 @@ export class SessionController<TView = unknown> extends Loggable {
       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).
-    if (this._replanPromise) {
-      this.log('nextCard: awaiting in-flight replan before drawing');
+    // If a replan is in flight AND we have nothing queued to serve, wait for
+    // it. When queues still have cards, draw from them immediately and let
+    // the replan land asynchronously — blocking here adds visible lag
+    // between cards for a marginal scoring-freshness benefit. The
+    // wedge-breaker below handles the genuinely-empty case.
+    if (
+      this._replanPromise &&
+      this.newQ.length === 0 &&
+      this.reviewQ.length === 0 &&
+      this.failedQ.length === 0
+    ) {
+      this.log('nextCard: queues empty, awaiting in-flight replan before drawing');
       await this._replanPromise;
     }
 
-    // --- Auto-replan triggers ---
-    // Two automatic replan triggers maintain queue freshness:
+    // --- Replan triggers ---
+    //
+    // Two flavors:
     //
-    // 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.
+    //  (a) OPPORTUNISTIC PREFETCH (best-effort, may coalesce, may no-op):
+    //      `depletion` and `quality` triggers below. Their job is to make
+    //      replans happen *early*, so the user doesn't wait. They are
+    //      *not* responsible for making replans happen *at all* — if every
+    //      one of them gets eaten by coalescing or suppression, that's
+    //      fine. They are perf optimizations.
     //
-    // 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.
+    //  (b) LOAD-BEARING WEDGE-BREAKER (correctness):
+    //      Below, right before the draw loop. Invariant: if the clock is
+    //      ticking and we'd otherwise serve null, the pipeline runs. No
+    //      coalesce, no latch, no flag. This is the *only* guarantee.
+    //
+    // Rule of thumb: a redundant pipeline run is a perf bug, a missing
+    // pipeline run is a correctness bug. Bias toward the cheaper failure.
 
-    // 1. Depletion trigger
-    //    Guarded by _depletionReplanAttempted to avoid infinite loops when
-    //    the pipeline consistently returns no new content.
+    // Opportunistic depletion: newQ running dry → background prefetch.
+    // No latch — if this fires repeatedly when the pipeline keeps coming
+    // back empty, the wedge-breaker's local backoff handles spin protection.
     if (
       this.newQ.length <= 1 &&
       this._secondsRemaining > 0 &&
-      !this._replanPromise &&
-      !this._depletionReplanAttempted
+      !this._replanPromise
     ) {
-      this._suppressQualityReplan = false; // burst is (nearly) consumed, clear suppression
-      this._depletionReplanAttempted = true;
-
+      this._suppressQualityReplan = false; // burst is (nearly) consumed
       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();
-      }
+      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.
+    // Opportunistic quality: few well-indicated cards remain.
+    // Suppressed after a burst replan to avoid clobbering burst cards.
     const REPLAN_BUFFER = 3;
     if (
       !this._suppressQualityReplan &&
@@ -1015,6 +1007,49 @@ export class SessionController<TView = unknown> extends Loggable {
       return null;
     }
 
+    // Wedge-breaker (correctness path).
+    //
+    // If we'd otherwise be about to draw from empty queues with time on
+    // the clock, run the pipeline. Bypasses requestReplan() coalesce
+    // because coalescing into a previous run that we now know produced
+    // insufficient content is the exact failure mode this defends against.
+    //
+    // Bounded by an empty-streak counter: if the pipeline consistently
+    // returns nothing, we eventually give up and let the session end
+    // gracefully rather than spin forever.
+    const WEDGE_MAX_EMPTY_STREAK = 3;
+    const WEDGE_BACKOFF_MS = 250;
+    let wedgeEmptyStreak = 0;
+    while (
+      this._secondsRemaining > 0 &&
+      this.newQ.length === 0 &&
+      this.reviewQ.length === 0 &&
+      this.failedQ.length === 0
+    ) {
+      this.log(
+        `[WedgeBreaker] All queues empty with ${this._secondsRemaining}s remaining. ` +
+        `Running pipeline (attempt ${wedgeEmptyStreak + 1}/${WEDGE_MAX_EMPTY_STREAK}).`
+      );
+      await this._replanUncoalesced({ label: 'wedge-breaker' });
+      if (
+        this.newQ.length === 0 &&
+        this.reviewQ.length === 0 &&
+        this.failedQ.length === 0
+      ) {
+        wedgeEmptyStreak++;
+        if (wedgeEmptyStreak >= WEDGE_MAX_EMPTY_STREAK) {
+          this.log(
+            `[WedgeBreaker] Pipeline returned no content ${WEDGE_MAX_EMPTY_STREAK} consecutive ` +
+            `times. Giving up; session will end.`
+          );
+          break;
+        }
+        await new Promise((resolve) => setTimeout(resolve, WEDGE_BACKOFF_MS));
+      } else {
+        wedgeEmptyStreak = 0;
+      }
+    }
+
     // Try multiple cards in case some fail hydration (e.g., deleted from DB)
     const MAX_SKIP = 20;
     for (let attempt = 0; attempt < MAX_SKIP; attempt++) {