@vue-skuilder/db 0.2.10 → 0.2.12

package/package.json

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

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/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}`
       );
     }
   }

package/src/study/services/ResponseProcessor.ts

@@ -189,7 +189,9 @@ export class ResponseProcessor {
         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(', ')}]`
+          `[FirstContactElo] correct first-attempt per-tag ELO update for ${cardId} ` +
+            `(historyLen=${history.records.length}, priorAttemps=${cardRecord.priorAttemps}): ` +
+            `scored=[${scoredTags.join(', ')}] count-only=[${nullTags.join(', ')}]`
         );
 
         void this.eloService.updateUserAndCardEloPerTag(
@@ -225,7 +227,8 @@ export class ResponseProcessor {
           );
         }
         logger.info(
-          '[ResponseProcessor] Processed correct response with SRS scheduling and ELO update'
+          `[FirstContactElo] correct first-attempt ELO update (score=${userScore.toFixed(3)}) ` +
+            `for ${cardId} (historyLen=${history.records.length}, priorAttemps=${cardRecord.priorAttemps})`
         );
       }
 
@@ -270,8 +273,17 @@ export class ResponseProcessor {
     // Parse performance (may be numeric or structured)
     const { taggedPerformance } = this.parsePerformance(cardRecord.performance);
 
-    // Update ELO for first-time failures (not subsequent attempts on same card)
-    if (history.records.length !== 1 && cardRecord.priorAttemps === 0) {
+    // Tracks whether this response already produced an ELO update, so the
+    // dismiss-failed branch below doesn't double-penalize the same record (the
+    // two coincide when maxAttemptsPerView === 1: first contact and final
+    // failure land on one response).
+    let eloUpdated = false;
+
+    // Update ELO on the first attempt of a presentation — symmetric with the
+    // correct path. Previously this was gated on `history.records.length !== 1`,
+    // so first-EVER failures were skipped while first-ever successes updated,
+    // biasing cold-start ELO upward. See WORKING-first-contact-elo-asymmetry.md.
+    if (cardRecord.priorAttemps === 0) {
       if (taggedPerformance) {
         // Per-tag ELO update for incorrect response
         void this.eloService.updateUserAndCardEloPerTag(
@@ -282,7 +294,9 @@ export class ResponseProcessor {
           currentCard
         );
         logger.info(
-          `[ResponseProcessor] Processed incorrect response with per-tag ELO update (${Object.keys(taggedPerformance).length - 1} tags)`
+          `[FirstContactElo] incorrect first-attempt per-tag ELO update for ${cardId} ` +
+            `(historyLen=${history.records.length}, priorAttemps=${cardRecord.priorAttemps}, ` +
+            `tags=${Object.keys(taggedPerformance).length - 1})`
         );
       } else {
         // Standard single-score ELO update
@@ -293,32 +307,52 @@ export class ResponseProcessor {
           courseRegistrationDoc,
           currentCard
         );
-        logger.info('[ResponseProcessor] Processed incorrect response with ELO update');
+        logger.info(
+          `[FirstContactElo] incorrect first-attempt ELO update (score=0) for ${cardId} ` +
+            `(historyLen=${history.records.length}, priorAttemps=${cardRecord.priorAttemps})`
+        );
       }
+      eloUpdated = true;
     } else {
-      logger.info('[ResponseProcessor] Processed incorrect response (no ELO update needed)');
+      logger.info(
+        `[FirstContactElo] incorrect retry — no ELO update for ${cardId} ` +
+          `(historyLen=${history.records.length}, priorAttemps=${cardRecord.priorAttemps})`
+      );
     }
 
     // Determine navigation based on attempt limits
     if (currentCard.records.length >= maxAttemptsPerView) {
       if (sessionViews >= maxSessionViews) {
-        // Too many session views - dismiss completely with ELO penalty
-        if (taggedPerformance) {
-          // Use tagged performance for final failure
-          void this.eloService.updateUserAndCardEloPerTag(
-            taggedPerformance,
-            courseId,
-            cardId,
-            courseRegistrationDoc,
-            currentCard
+        // Too many session views - dismiss completely with ELO penalty.
+        // Skip if this response already updated ELO above, to avoid a double
+        // penalty on the same record (happens when maxAttemptsPerView === 1).
+        if (!eloUpdated) {
+          if (taggedPerformance) {
+            // Use tagged performance for final failure
+            void this.eloService.updateUserAndCardEloPerTag(
+              taggedPerformance,
+              courseId,
+              cardId,
+              courseRegistrationDoc,
+              currentCard
+            );
+          } else {
+            void this.eloService.updateUserAndCardElo(
+              0,
+              courseId,
+              cardId,
+              courseRegistrationDoc,
+              currentCard
+            );
+          }
+          logger.info(
+            `[FirstContactElo] dismiss-failed final ELO penalty for ${cardId} ` +
+              `(historyLen=${history.records.length}, sessionViews=${sessionViews})`
           );
         } else {
-          void this.eloService.updateUserAndCardElo(
-            0,
-            courseId,
-            cardId,
-            courseRegistrationDoc,
-            currentCard
+          logger.info(
+            `[FirstContactElo] dismiss-failed — ELO already updated this response, ` +
+              `skipping double penalty for ${cardId}`
           );
         }
         return {