@vue-skuilder/db 0.1.38 → 0.1.40

package/dist/index.d.cts

@@ -422,13 +422,6 @@ declare class SessionController<TView = unknown> extends Loggable {
      * Cleared when the depletion-triggered replan fires (newQ exhausted).
      */
     private _suppressQualityReplan;
-    /**
-     * 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;
     /**
      * When > 0, the session timer cannot end the session. Decremented on
      * each nextCard() draw. Set by replans that include `minFollowUpCards`.
@@ -521,6 +514,19 @@ declare class SessionController<TView = unknown> extends Loggable {
      * newQ.peek(0) is the imminent draw we need to exclude.
      */
     private _runReplan;
+    /**
+     * 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 _replanUncoalesced;
     /**
      * Normalise the requestReplan argument. Accepts either a ReplanOptions
      * object (new API) or a plain Record<string, unknown> (legacy callers
@@ -1111,6 +1117,17 @@ interface DataLayerConfig {
         COUCHDB_USERNAME?: string;
         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;
+            };
+        };
     };
 }
 /**

package/dist/index.d.ts

@@ -422,13 +422,6 @@ declare class SessionController<TView = unknown> extends Loggable {
      * Cleared when the depletion-triggered replan fires (newQ exhausted).
      */
     private _suppressQualityReplan;
-    /**
-     * 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;
     /**
      * When > 0, the session timer cannot end the session. Decremented on
      * each nextCard() draw. Set by replans that include `minFollowUpCards`.
@@ -521,6 +514,19 @@ declare class SessionController<TView = unknown> extends Loggable {
      * newQ.peek(0) is the imminent draw we need to exclude.
      */
     private _runReplan;
+    /**
+     * 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 _replanUncoalesced;
     /**
      * Normalise the requestReplan argument. Accepts either a ReplanOptions
      * object (new API) or a plain Record<string, unknown> (legacy callers
@@ -1111,6 +1117,17 @@ interface DataLayerConfig {
         COUCHDB_USERNAME?: string;
         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;
+            };
+        };
     };
 }
 /**

package/dist/index.js

@@ -6469,16 +6469,25 @@ var init_adminDB2 = __esm({
 });
 
 // src/impl/couch/CourseSyncService.ts
-var CourseSyncService;
+var CourseSyncService_exports = {};
+__export(CourseSyncService_exports, {
+  CourseSyncService: () => CourseSyncService
+});
+var DEFAULT_REPLICATION, CourseSyncService;
 var init_CourseSyncService = __esm({
   "src/impl/couch/CourseSyncService.ts"() {
     "use strict";
     init_pouchdb_setup();
     init_couch();
     init_logger();
+    DEFAULT_REPLICATION = {
+      batchSize: 1e3,
+      batchesLimit: 5
+    };
     CourseSyncService = class _CourseSyncService {
       static instance = null;
       entries = /* @__PURE__ */ new Map();
+      replicationOptions = DEFAULT_REPLICATION;
       constructor() {
       }
       static getInstance() {
@@ -6487,6 +6496,21 @@ var init_CourseSyncService = __esm({
         }
         return _CourseSyncService.instance;
       }
+      /**
+       * Apply replication tuning. Typically called once from `initializeDataLayer`.
+       * Partial overrides merge with defaults.
+       */
+      configure(opts) {
+        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).
        */
@@ -6615,7 +6639,7 @@ var init_CourseSyncService = __esm({
           const remoteDB = this.getRemoteDB(courseId);
           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);
           const syncTimeMs = Date.now() - syncStart;
@@ -6673,6 +6697,8 @@ var init_CourseSyncService = __esm({
         return new Promise((resolve, reject) => {
           void pouchdb_setup_default.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);
           }).on("error", (err) => {
@@ -9298,6 +9324,10 @@ async function initializeDataLayer(config) {
     ENV.COUCHDB_SERVER_URL = config.options.COUCHDB_SERVER_URL;
     ENV.COUCHDB_USERNAME = config.options.COUCHDB_USERNAME;
     ENV.COUCHDB_PASSWORD = config.options.COUCHDB_PASSWORD;
+    if (config.options.courseSync) {
+      const { CourseSyncService: CourseSyncService2 } = await Promise.resolve().then(() => (init_CourseSyncService(), CourseSyncService_exports));
+      CourseSyncService2.getInstance().configure(config.options.courseSync);
+    }
     if (config.options.COUCHDB_PASSWORD && config.options.COUCHDB_USERNAME && typeof window !== "undefined") {
       const { CouchDBSyncStrategy: CouchDBSyncStrategy2 } = await Promise.resolve().then(() => (init_CouchDBSyncStrategy(), CouchDBSyncStrategy_exports));
       const syncStrategy = new CouchDBSyncStrategy2();
@@ -13387,13 +13417,6 @@ var SessionController = class _SessionController extends Loggable {
    * Cleared when the depletion-triggered replan fires (newQ exhausted).
    */
   _suppressQualityReplan = 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.
-   */
-  _depletionReplanAttempted = false;
   /**
    * When > 0, the session timer cannot end the session. Decremented on
    * each nextCard() draw. Set by replans that include `minFollowUpCards`.
@@ -13551,9 +13574,6 @@ var SessionController = class _SessionController extends Loggable {
    */
   async requestReplan(options) {
     const opts = this.normalizeReplanOptions(options);
-    if (opts.hints || opts.label || opts.limit) {
-      this._depletionReplanAttempted = false;
-    }
     const hasIntent = this._replanHasIntent(opts);
     if (this._replanPromise) {
       if (!hasIntent) {
@@ -13632,6 +13652,25 @@ var SessionController = class _SessionController 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.
+   */
+  async _replanUncoalesced(opts) {
+    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
@@ -13685,9 +13724,6 @@ var SessionController = class _SessionController extends Loggable {
         `[Replan] Only ${wellIndicated}/${_SessionController.MIN_WELL_INDICATED} well-indicated cards after replan`
       );
     }
-    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})`);
@@ -13962,25 +13998,17 @@ var SessionController = class _SessionController extends Loggable {
       this._minCardsGuarantee--;
       this.log(`[CardGuarantee] ${this._minCardsGuarantee} guaranteed cards remaining`);
     }
-    if (this._replanPromise) {
-      this.log("nextCard: awaiting in-flight replan before drawing");
+    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;
     }
-    if (this.newQ.length <= 1 && this._secondsRemaining > 0 && !this._replanPromise && !this._depletionReplanAttempted) {
+    if (this.newQ.length <= 1 && this._secondsRemaining > 0 && !this._replanPromise) {
       this._suppressQualityReplan = false;
-      this._depletionReplanAttempted = true;
       const otherContent = this.reviewQ.length + this.failedQ.length;
-      if (this.newQ.length === 0 && otherContent === 0) {
-        this.log(
-          `[AutoReplan:depletion] All queues empty with ${this._secondsRemaining}s remaining. Awaiting replan.`
-        );
-        await this.requestReplan();
-      } else {
-        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();
     }
     const REPLAN_BUFFER = 3;
     if (!this._suppressQualityReplan && this._wellIndicatedRemaining <= REPLAN_BUFFER && this.newQ.length > 0 && !this._replanPromise) {
@@ -13994,6 +14022,27 @@ var SessionController = class _SessionController extends Loggable {
       endSessionTracking();
       return null;
     }
+    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;
+      }
+    }
     const MAX_SKIP = 20;
     for (let attempt = 0; attempt < MAX_SKIP; attempt++) {
       const nextItem = this._selectNextItemToHydrate();