@vue-skuilder/db 0.2.11 → 0.2.13

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.2.11",
+  "version": "0.2.13",
   "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.2.11",
+    "@vue-skuilder/common": "0.2.13",
     "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.2.11"
+  "stableVersion": "0.2.13"
 }

package/src/core/navigators/SrsDebugger.ts

@@ -3,10 +3,11 @@
 // ============================================================================
 //
 // A tiny module-level capture of the SRS generator's per-run backlog state,
-// so the live session overlay can show whether reviews being out-competed by
-// (boosted) new cards is *temporary* (the backlog multiplier still has headroom
-// to climb and lift reviews) or *boost-driven* (the multiplier is maxed and the
-// new-card boosts simply sit higher — only a hint relaxation reorders them).
+// so the live session overlay can show how much runway remains before reviews
+// out-compete the current (boosted) new/prescribed cards: the backlog
+// multiplier is exponential and uncapped, so it always has headroom to climb
+// further — the question is just how large the backlog needs to get before it
+// crosses whatever the competing boosts currently sit at.
 //
 // Mirrors MixerDebugger/PipelineDebugger: the generator pushes a snapshot each
 // run (keyed by course, latest wins); the overlay reads it via the controller's
@@ -23,10 +24,10 @@ export interface SrsBacklogDebug {
   dueNow: number;
   /** Healthy backlog threshold; multiplier is ×1.0 at or below this. */
   healthyBacklog: number;
-  /** Global multiplier applied to every due review's urgency this run (1.0 → max). */
+  /** Global multiplier applied to every due review's urgency this run (>= 1.0, unbounded). */
   backlogMultiplier: number;
-  /** Max achievable backlog multiplier (the cap), for headroom context. */
-  maxBacklogMultiplier: number;
+  /** Exponential growth-rate base the multiplier climbs by per multiple of healthyBacklog excess. */
+  backlogGrowthRate: number;
   /** Highest review score produced this run (post-multiplier; can exceed 1.0); null if none due. */
   topReviewScore: number | null;
   /** Human-readable time until the next review comes due, or null if some are due now. */

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

@@ -42,19 +42,27 @@ import { logger } from '@db/util/logger';
 const DEFAULT_HEALTHY_BACKLOG = 20;
 
 /**
- * Maximum backlog pressure as a *multiplier* on review urgency.
+ * Growth-rate base for backlog pressure as a *multiplier* on review urgency.
  *
- * Backlog pressure is multiplicative (×1.0 at/below healthy, scaling up as the
- * due pile grows, maxing here at 3× healthy backlog). It replaces an older
- * additive +0..+0.5 term that was a [0,1]-era modifier — once review scores
- * stopped being clamped to 1.0 and new cards could be boosted well past it
- * (e.g. an intro ×5 → 7+), a flat +0.5 was both too small to compete and mostly
- * eaten by the old 1.0 clamp. A multiplier scales review priority onto the same
- * open scale the boosted new cards live on, so a heavy backlog can genuinely
- * lift reviews into competition. Tunable — verify review vs new ordering in the
- * dbg overlay's "review backpressure" panel.
+ * Backlog pressure is multiplicative (×1.0 at/below healthy) and exponential
+ * in the backlog's excess over healthy, expressed in multiples of
+ * `healthyBacklog` (see computeBacklogMultiplier) — deliberately uncapped. It
+ * replaces an older additive +0..+0.5 term that was a [0,1]-era modifier —
+ * once review scores stopped being clamped to 1.0 and new cards could be
+ * boosted well past it (e.g. an intro ×5 → 7+), a flat +0.5 was both too small
+ * to compete and mostly eaten by the old 1.0 clamp. A linear-then-capped
+ * multiplier came next, but that just moved the problem: other generators
+ * (e.g. Prescribed Intro Backpressure) score on a much larger open scale with
+ * their own, independently-tuned caps, so a hard review-side ceiling meant
+ * reviews could never win out no matter how backlogged they got. Exponential
+ * growth has no such ceiling — a sufficiently neglected backlog keeps
+ * climbing until it outcompetes anything, which is the intended long-term
+ * fallback: other generators can dominate short-term, but SRS is the
+ * framework-invariant backstop and should always win eventually. Tunable —
+ * verify review vs new ordering in the dbg overlay's "review backpressure"
+ * panel.
  */
-const MAX_BACKLOG_MULTIPLIER = 2.0;
+const BACKLOG_GROWTH_RATE = 2;
 
 /**
  * Configuration for the SRS strategy.
@@ -249,7 +257,7 @@ export default class SRSNavigator extends ContentNavigator implements CardGenera
       dueNow: dueReviews.length,
       healthyBacklog: this.healthyBacklog,
       backlogMultiplier,
-      maxBacklogMultiplier: MAX_BACKLOG_MULTIPLIER,
+      backlogGrowthRate: BACKLOG_GROWTH_RATE,
       topReviewScore: sorted.length > 0 ? sorted[0].score : null,
       nextDueIn,
       timestamp: Date.now(),
@@ -268,28 +276,32 @@ export default class SRSNavigator extends ContentNavigator implements CardGenera
   /**
    * Compute the multiplicative backlog pressure based on number of due reviews.
    *
-   * ×1.0 at or below the healthy threshold (no boost), increasing linearly above
-   * it and maxing out at MAX_BACKLOG_MULTIPLIER at 3× the healthy backlog.
+   * ×1.0 at or below the healthy threshold (no boost); above it, grows as
+   * BACKLOG_GROWTH_RATE raised to the excess expressed in multiples of the
+   * healthy threshold. Uncapped — self-regulating instead: reviews winning
+   * slots depletes dueCount, which drops the ratio and relaxes the multiplier
+   * next run.
    *
-   * Examples (with default healthyBacklog=20, MAX_BACKLOG_MULTIPLIER=2.0):
-   * - 10 due reviews → ×1.00 (healthy)
-   * - 20 due reviews → ×1.00 (at threshold)
-   * - 40 due reviews → ×1.50 (2x threshold)
-   * - 60 due reviews → ×2.00 (3x threshold, maxed)
+   * Examples (with default healthyBacklog=20, BACKLOG_GROWTH_RATE=1.5):
+   * - 10 due reviews → ×1.00  (healthy)
+   * - 20 due reviews → ×1.00  (at threshold, ratio 0)
+   * - 40 due reviews → ×1.50  (ratio 1, 2x threshold)
+   * - 60 due reviews → ×2.25  (ratio 2, 3x threshold — old hard cap was ×2.00 here)
+   * - 100 due reviews → ×5.06 (ratio 4, 5x threshold)
+   * - 160 due reviews → ×17.09 (ratio 7, 8x threshold)
    *
    * @param dueCount - Number of reviews currently due
-   * @returns Multiplier applied to review urgency (1.0 to MAX_BACKLOG_MULTIPLIER)
+   * @returns Multiplier applied to review urgency (>= 1.0, unbounded)
    */
   private computeBacklogMultiplier(dueCount: number): number {
     if (dueCount <= this.healthyBacklog) {
       return 1.0;
     }
 
-    // Linear in excess: ×1 at healthy, reaching MAX at 3× healthy (excess = 2×healthy).
     const excess = dueCount - this.healthyBacklog;
-    const multiplier = 1 + (excess / this.healthyBacklog) * ((MAX_BACKLOG_MULTIPLIER - 1) / 2);
+    const ratio = excess / this.healthyBacklog;
 
-    return Math.min(MAX_BACKLOG_MULTIPLIER, multiplier);
+    return Math.pow(BACKLOG_GROWTH_RATE, ratio);
   }
 
   /**
@@ -306,17 +318,17 @@ export default class SRSNavigator extends ContentNavigator implements CardGenera
    *    - 180 days → ~0.30
    *
    * 3. Backlog pressure = global *multiplier* when review backlog exceeds the
-   *    healthy threshold (×1.0 healthy → up to MAX_BACKLOG_MULTIPLIER at 3×).
+   *    healthy threshold (×1.0 healthy → exponential growth, uncapped, above it).
    *
    * Combined: (base 0.5 + urgency factors * 0.45) × backlog multiplier.
    * Per-card range before pressure: ~0.57–0.95. NOT clamped to 1.0 — under a
    * heavy backlog reviews scale onto the open scale to compete with (and exceed)
-   * new cards; what keeps them from running away is the bounded multiplier, not
-   * a hard ceiling.
+   * new cards; there's no ceiling at all now, so a bad enough backlog always
+   * wins eventually — self-regulating because winning slots depletes dueCount.
    *
    * @param review - The scheduled card to score
    * @param now - Current time
-   * @param backlogMultiplier - Pre-computed backlog multiplier (1.0 to MAX_BACKLOG_MULTIPLIER)
+   * @param backlogMultiplier - Pre-computed backlog multiplier (>= 1.0, unbounded)
    */
   private computeUrgencyScore(
     review: ScheduledCard,
@@ -366,4 +378,4 @@ export default class SRSNavigator extends ContentNavigator implements CardGenera
 
     return { score, reason };
   }
-}
+}

package/src/impl/common/BaseUserDB.ts

@@ -214,6 +214,19 @@ Currently logged-in as ${this._username}.`
     }
 
     const ret = await this.syncStrategy.logout!();
+
+    // Mint a FRESH guest identity on logout rather than re-adopting whatever
+    // sk-guest-uuid happens to survive in localStorage. A stale UUID can point
+    // at an already-consumed guest DB (one previously migrated into a real
+    // account); re-adopting it would resurface that account's progress and, on
+    // the next signup, migrate it into the new account. Clearing the pointer
+    // forces accomodateGuest() to generate a new UUID + empty guest DB.
+    try {
+      localStorage.removeItem('sk-guest-uuid');
+    } catch (e) {
+      logger.warn('localStorage not available (Node.js environment):', e);
+    }
+
     // return to 'guest' mode
     this._username = await this.syncStrategy.getCurrentUsername();
     await this.init();

package/src/impl/couch/CouchDBSyncStrategy.ts

@@ -228,6 +228,23 @@ export class CouchDBSyncStrategy implements SyncStrategy {
         logger.info('No documents to migrate from funnel account');
       }
 
+      // Destroy the consumed guest DB so it can never be re-migrated into a
+      // future account. Without this, an orphaned userdb-sk-guest-<uuid> lingers
+      // in IndexedDB indefinitely; if its stale identity is later re-adopted
+      // (e.g. on logout via a surviving sk-guest-uuid), its progress bleeds into
+      // the next new account. Best-effort: migration has already succeeded, so a
+      // teardown failure must not fail account creation.
+      try {
+        await oldLocalDB.destroy();
+        logger.info(`Destroyed consumed guest DB for ${oldUsername}`);
+      } catch (destroyErr) {
+        logger.warn(
+          `Failed to destroy consumed guest DB for ${oldUsername} (non-fatal): ${
+            destroyErr instanceof Error ? destroyErr.message : String(destroyErr)
+          }`
+        );
+      }
+
       return { success: true };
     } catch (error) {
       logger.error('Migration failed:', error);

package/src/study/SessionController.ts

@@ -20,7 +20,7 @@ import { ReplanHints } from '@db/core/navigators/generators/types';
 import { mergeHints } from '@db/core/navigators/Pipeline';
 import { SourceMixer, QuotaRoundRobinMixer, SourceBatch } from './SourceMixer';
 import { captureMixerRun } from './MixerDebugger';
-import { startSessionTracking, recordCardPresentation, snapshotQueues, endSessionTracking } from './SessionDebugger';
+import { startSessionTracking, recordCardPresentation, snapshotQueues, endSessionTracking, clearStaleSessionDebugState } from './SessionDebugger';
 import {
   registerActiveController,
   type SessionDebugSnapshot,
@@ -475,6 +475,10 @@ export class SessionController<TView = unknown> extends Loggable {
       );
     }
 
+    // Clear the previous session's debug state before this session's
+    // bootstrap pipeline run fires, so that run's own report isn't wiped out.
+    clearStaleSessionDebugState();
+
     const wellIndicated = await this.getWeightedContent();
     this._wellIndicatedRemaining = wellIndicated;
     if (wellIndicated >= 0 && wellIndicated < SessionController.MIN_WELL_INDICATED) {

package/src/study/SessionDebugger.ts

@@ -68,6 +68,22 @@ let activeSession: SessionRunReport | null = null;
 const sessionHistory: SessionRunReport[] = [];
 const MAX_HISTORY = 5;
 
+/**
+ * Release pipeline run-history / SRS backlog debug memory from the previous
+ * session before this session begins piling new runs on top of it. Must be
+ * called before the first pipeline run of the new session (including the
+ * bootstrap run in prepareSession) — clearing on session START rather than
+ * END keeps post-session inspection, the dominant debugging workflow, fully
+ * functional: a finished session's run history sits intact until the user
+ * actually begins another one. It's a separate call from startSessionTracking
+ * because that function can't run until supplyQ/failedQ are populated by the
+ * bootstrap pipeline run, which would otherwise be cleared out from under it.
+ */
+export function clearStaleSessionDebugState(): void {
+  clearPipelineRunHistory();
+  clearSrsBacklogDebug();
+}
+
 /**
  * Start tracking a new session.
  */
@@ -75,14 +91,6 @@ export function startSessionTracking(
   supplyQLength: number,
   failedQLength: number
 ): void {
-  // Release pipeline run-history memory before this session begins piling
-  // new runs on top of the previous session's retained reports. Clearing on
-  // session START (rather than END) keeps post-session inspection — the
-  // dominant debugging workflow — fully functional: a finished session's
-  // run history sits intact until the user actually begins another one.
-  clearPipelineRunHistory();
-  clearSrsBacklogDebug();
-
   const sessionId = `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 
   activeSession = {

package/src/study/SessionOverlay.ts

@@ -365,25 +365,24 @@ function hintsHtml(h: ReplanHints | null): string {
 
 /**
  * SRS backlog panel — answers "is review starvation permanent?". Backlog
- * pressure is a multiplier (×1.0 healthy → max) on review urgency; reviews are
- * no longer clamped to 1.0, so under a heavy backlog they scale up to compete
- * with (and exceed) new cards. So:
- *  - multiplier climbing, below max → reviews will rise as the backlog grows
- *    (temporary — they'll start winning slots);
- *  - multiplier maxed but still out-competed → the boosts in `sessionHints`
- *    simply sit higher; reviews only resurface once those relax (backoff), not
- *    from more backlog. Compare `top review` here against the supplyQ head score.
+ * pressure is a multiplier (×1.0 healthy → exponential, uncapped) on review
+ * urgency; reviews are no longer clamped to 1.0, so under a heavy backlog they
+ * scale up to compete with (and exceed) new cards. There's no ceiling, so
+ * reviews always win eventually — the panel shows how far the current
+ * multiplier is from that crossover, not whether it's "maxed": compare
+ * `top review` here against the supplyQ head score to see how much further
+ * the backlog needs to grow (or the boosts need to relax) before reviews win
+ * slots.
  */
 function backlogHtml(backlog: SrsBacklogDebug[]): string {
   if (!backlog.length) return '';
   const rows = backlog
     .map((b) => {
-      const maxed = b.backlogMultiplier >= b.maxBacklogMultiplier - 1e-9;
-      const multColor = b.backlogMultiplier <= 1 ? '#86efac' : maxed ? '#fca5a5' : '#fcd34d';
-      const headroom = maxed
-        ? 'maxed — boosts decide order until they relax'
-        : b.backlogMultiplier > 1
-          ? 'climbing as backlog grows'
+      const hot = b.backlogMultiplier >= 3;
+      const multColor = b.backlogMultiplier <= 1 ? '#86efac' : hot ? '#fca5a5' : '#fcd34d';
+      const headroom =
+        b.backlogMultiplier > 1
+          ? `climbing (×${b.backlogGrowthRate.toFixed(2)} per ${b.healthyBacklog}-review excess, unbounded)`
           : 'healthy — no pressure';
       const top = b.topReviewScore !== null ? b.topReviewScore.toFixed(2) : '—';
       const next = b.nextDueIn ? ` <span style="opacity:.6">· next due ${esc(b.nextDueIn)}</span>` : '';
@@ -392,7 +391,7 @@ function backlogHtml(backlog: SrsBacklogDebug[]): string {
         `<span style="opacity:.7">${esc(b.courseId.slice(0, 8))}</span> ` +
         `due ${b.dueNow}/${b.scheduledTotal} <span style="opacity:.6">(healthy ${b.healthyBacklog})</span>${next}` +
         `<div style="margin-left:6px">` +
-        `pressure <span style="color:${multColor}">×${b.backlogMultiplier.toFixed(2)}/${b.maxBacklogMultiplier.toFixed(2)}</span> ` +
+        `pressure <span style="color:${multColor}">×${b.backlogMultiplier.toFixed(2)}</span> ` +
         `<span style="opacity:.6">${headroom} · top review ${top}</span></div>` +
         `</div>`
       );
@@ -541,18 +540,13 @@ function snapshotToText(s: SessionDebugSnapshot | null): string {
     lines.push('');
     lines.push('review backpressure:');
     for (const b of s.reviewBacklog) {
-      const maxed = b.backlogMultiplier >= b.maxBacklogMultiplier - 1e-9;
-      const headroom = maxed
-        ? 'maxed (boosts decide order)'
-        : b.backlogMultiplier > 1
-          ? 'climbing'
-          : 'healthy';
+      const headroom = b.backlogMultiplier > 1 ? 'climbing' : 'healthy';
       const top = b.topReviewScore !== null ? b.topReviewScore.toFixed(2) : '—';
       const next = b.nextDueIn ? `, next due ${b.nextDueIn}` : '';
       lines.push(
         `  ${b.courseId.slice(0, 8)}: due ${b.dueNow}/${b.scheduledTotal} ` +
-          `(healthy ${b.healthyBacklog})${next}; pressure ×${b.backlogMultiplier.toFixed(2)}/` +
-          `${b.maxBacklogMultiplier.toFixed(2)} ${headroom}; top review ${top}`
+          `(healthy ${b.healthyBacklog})${next}; pressure ×${b.backlogMultiplier.toFixed(2)} ` +
+          `${headroom}; top review ${top}`
       );
     }
   }