@vue-skuilder/db 0.2.3 → 0.2.5

package/package.json

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

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

@@ -7,6 +7,13 @@ import type { QualifiedCardID } from '../..';
 import type { CardGenerator, GeneratorContext, GeneratorResult } from './types';
 import { logger } from '@db/util/logger';
 
+/**
+ * Std-dev (in ELO points) of the Gaussian that converts card↔user ELO distance
+ * into a relevance weight. 300 reproduces the legacy linear ramp's half-weight
+ * point (distance 250 → ~0.5) while removing its hard zero beyond distance 500.
+ */
+const ELO_RELEVANCE_SIGMA = 300;
+
 // ============================================================================
 // ELO NAVIGATOR
 // ============================================================================
@@ -96,17 +103,31 @@ export default class ELONavigator extends ContentNavigator implements CardGenera
         // `[active=${activeCards.length} candidates=${newCards.length}]`
     // );
 
-    // Score new cards by ELO distance, then apply weighted sampling without
-    // replacement using the Efraimidis-Spirakis (A-Res) algorithm:
+    // Score new cards by ELO proximity, then apply bounded multiplicative
+    // jitter for session-to-session variety.
     //
-    //   key = U ^ (1 / rawScore)   where U ~ Uniform(0, 1)
+    //   relevance = exp(-(distance / SIGMA)^2)   // Gaussian: smooth, always > 0
+    //   score     = relevance * (0.5 + 0.5 * U)  // U ~ Uniform(0, 1)
     //
-    // Sorting by key descending produces a weighted random sample: high-score
-    // cards are still preferred, but cards with equal scores are shuffled
-    // uniformly rather than deterministically. This prevents the same failed
-    // cards from looping back every session when many cards share similar ELO.
+    // This replaces the legacy `rawScore = max(0, 1 - distance/500)` ramp +
+    // Efraimidis-Spirakis key `U^(1/rawScore)`, which introduced two
+    // discontinuities that defeated downstream replan boosts:
+    //   1. The ramp's clamp made every card ≥500 ELO from the user a HARD zero.
+    //      The pipeline DELETES zero-score cards (filter score>0) *before* boosts
+    //      are applied, so no boost could resurface an under-ELO'd target — e.g.
+    //      a freshly-introduced grapheme sitting ~475 below an inflated global
+    //      ELO. (See packages/db/docs/todo-intro-concept-emphasis-and-retrieval.md.)
+    //   2. The A-Res key `U^(1/rawScore)` ALSO manufactured effective zeros: as
+    //      rawScore→0 the exponent explodes and `U^huge` underflows to 0, with
+    //      wild variance just above it — so a downstream boost multiplied a
+    //      lottery ticket rather than a stable relevance.
     //
-    // Edge case: rawScore=0 → key=0, never selected (correct exclusion).
+    // Gaussian relevance never hits zero (no cliff, survives the score>0 filter,
+    // so a boost can always lift a low-ELO target), and the [0.5, 1] jitter keeps
+    // ELO ordering up to a 2× factor while still shuffling near-equal cards so the
+    // same cards don't loop every session. SIGMA=300 reproduces the old ramp's
+    // half-weight point (distance 250 → ~0.5), leaving center-of-range difficulty
+    // matching unchanged.
     //
     // Card ELO is read from the pooled `.elo` carried on each candidate by
     // getCardsCenteredAtELO — verified equal to a separate getCardEloData()
@@ -115,8 +136,8 @@ export default class ELONavigator extends ContentNavigator implements CardGenera
       const cardElo = c.elo ?? 1000;
 
       const distance = Math.abs(cardElo - userGlobalElo);
-      const rawScore = Math.max(0, 1 - distance / 500);
-      const samplingKey = rawScore > 0 ? Math.random() ** (1 / rawScore) : 0;
+      const relevance = Math.exp(-((distance / ELO_RELEVANCE_SIGMA) ** 2));
+      const samplingKey = relevance * (0.5 + 0.5 * Math.random());
 
       return {
         cardId: c.cardID,
@@ -129,7 +150,7 @@ export default class ELONavigator extends ContentNavigator implements CardGenera
             strategyId: this.strategyId || 'NAVIGATION_STRATEGY-ELO-default',
             action: 'generated',
             score: samplingKey,
-            reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userGlobalElo)}), raw ${rawScore.toFixed(3)}, key ${samplingKey.toFixed(3)}`,
+            reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userGlobalElo)}), relevance ${relevance.toFixed(3)}, key ${samplingKey.toFixed(3)}`,
           },
         ],
       };

package/src/study/SessionController.ts

@@ -21,6 +21,12 @@ 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 {
+  registerActiveController,
+  type SessionDebugSnapshot,
+  type SessionDrawnCardDebug,
+  type SessionQueueDebug,
+} from './SessionOverlay';
 
 // ReplanHints is defined in generators/types to avoid circular dependencies.
 // Re-exported here for backward compatibility.
@@ -58,6 +64,21 @@ export interface ReplanOptions {
    * multiply, require/exclude lists concatenate).
    */
   sessionHints?: ReplanHints;
+  /**
+   * Like `sessionHints`, but *merged* into the existing session-durable hints
+   * (via `mergeHints`) instead of replacing them. Use when emphasis should
+   * *accumulate* across replans rather than clobber — e.g. introducing a second
+   * concept mid-session must not wipe the first concept's boost, nor any
+   * `difficultyBooster`/`conceptBackoff` state on other concepts.
+   *
+   * Merge semantics (see `mergeHints`): boosts MULTIPLY, require/exclude lists
+   * concat-dedup. Re-emphasising the *same* tag therefore compounds — callers
+   * boosting a tag they may have already boosted should clamp at the call site.
+   *
+   * If both `sessionHints` and `mergeSessionHints` are supplied, the replace is
+   * applied first, then the merge — but they are normally mutually exclusive.
+   */
+  mergeSessionHints?: ReplanHints;
   /**
    * Maximum number of new cards to return from the pipeline.
    * Default: 20 (the standard session batch size).
@@ -236,6 +257,14 @@ export class SessionController<TView = unknown> extends Loggable {
    */
   private _replanPromise: Promise<void> | null = null;
 
+  /**
+   * Reason for the replan currently executing in `_runReplan`, surfaced by the
+   * debug overlay's spinner. The caller's `opts.label` when present, else
+   * `'(auto)'`. Only meaningful while `_replanPromise` is non-null; cleared
+   * when the in-flight chain settles.
+   */
+  private _activeReplanLabel: string | null = null;
+
   /**
    * Number of well-indicated new cards remaining before the queue
    * degrades to poorly-indicated content. Decremented on each newQ
@@ -274,6 +303,22 @@ export class SessionController<TView = unknown> extends Loggable {
    */
   private _sessionHints: ReplanHints | null = null;
 
+  /**
+   * Card IDs that have been *served* (drawn/consumed) this session. Populated
+   * at the single consumption choke-point (removeItemFromQueue), so it reflects
+   * a draw the instant it happens — earlier than `_sessionRecord`, which only
+   * lands once the card is *responded to*.
+   *
+   * Used to keep already-served cards out of newQ on every (re)plan: a `new`
+   * card shown once must never re-enter newQ this session. This is the general
+   * guard against re-presentation — including the case where a replan in flight
+   * captured a now-drawn card (e.g. a +INF require-injected follow-up the
+   * depletion prefetch grabbed just before it was drawn). Reviews/failed cards
+   * legitimately recur and are tracked by their own queues, so this only gates
+   * `new`-origin candidates.
+   */
+  private _servedCardIds: Set<string> = new Set();
+
   /**
    * Consumer-supplied hooks invoked after each question response is processed.
    * Seeded from constructor options (threaded from
@@ -372,6 +417,11 @@ export class SessionController<TView = unknown> extends Loggable {
     endTime: ${this.endTime}
     defaultBatchLimit: ${this._defaultBatchLimit}
     initialReviewCap: ${this._initialReviewCap}`);
+
+    // Expose this (now the most-recently-constructed) controller to the debug
+    // overlay (window.skuilder.session.dbgOverlay()). A new session overwrites
+    // the prior handle; no-op overhead when the overlay is never opened.
+    registerActiveController(this);
   }
 
   private tick() {
@@ -500,17 +550,33 @@ export class SessionController<TView = unknown> extends Loggable {
         .catch(() => undefined)
         .then(() => this._runReplan(opts));
 
-      this._replanPromise = queued.finally(() => {
-        if (this._replanPromise === queued) this._replanPromise = null;
+      // Compare against the promise we actually store. `.finally()` returns a
+      // NEW promise, so guarding on `=== queued` (the pre-finally promise) never
+      // matches and would leak _replanPromise. `tracked` is read only inside the
+      // async callback (after init), so the self-reference is safe.
+      const tracked: Promise<void> = queued.finally(() => {
+        if (this._replanPromise === tracked) {
+          this._replanPromise = null;
+          this._activeReplanLabel = null;
+        }
       });
+      this._replanPromise = tracked;
 
       return queued;
     }
 
     const run = this._runReplan(opts);
-    this._replanPromise = run.finally(() => {
-      if (this._replanPromise === run) this._replanPromise = null;
+    // Compare against the wrapped promise we store, not `run` — `.finally()`
+    // returns a new promise, so `=== run` never matches and _replanPromise
+    // would never clear (perpetual "replan in progress"). Safe self-reference:
+    // `tracked` is read only in the async callback, after initialization.
+    const tracked: Promise<void> = run.finally(() => {
+      if (this._replanPromise === tracked) {
+        this._replanPromise = null;
+        this._activeReplanLabel = null;
+      }
     });
+    this._replanPromise = tracked;
 
     await run;
   }
@@ -521,12 +587,18 @@ export class SessionController<TView = unknown> extends Loggable {
    * triggers in nextCard) return false and may coalesce.
    */
   private _replanHasIntent(opts: ReplanOptions): boolean {
-    if (opts.label) return true;
+    // NOTE: `label` is intentionally NOT an intent signal. It is observability-
+    // only metadata (debug overlay spinner, log tags, Pipeline strategy names),
+    // so labelling a replan must never change scheduling. Intent is strictly
+    // "does this replan carry scheduling-relevant options". This lets the
+    // unlabeled-but-named auto-replans (auto:depletion / auto:quality) keep
+    // coalescing while still showing a reason in the overlay.
     if (opts.limit !== undefined) return true;
     if (opts.minFollowUpCards !== undefined) return true;
     if (opts.mode && opts.mode !== 'replace') return true;
     if (opts.hints && Object.keys(opts.hints).length > 0) return true;
     if (opts.sessionHints !== undefined) return true;
+    if (opts.mergeSessionHints !== undefined) return true;
     return false;
   }
 
@@ -543,6 +615,11 @@ export class SessionController<TView = unknown> extends Loggable {
    * newQ.peek(0) is the imminent draw we need to exclude.
    */
   private async _runReplan(opts: ReplanOptions): Promise<void> {
+    // Surface the executing replan's reason to the debug overlay spinner.
+    // `label` is observability-only (see _replanHasIntent); '(auto)' covers any
+    // unlabeled path.
+    this._activeReplanLabel = opts.label ?? '(auto)';
+
     // Exclude all cards already presented this session. The pipeline may
     // not yet see their encounter records (async writes), so without this
     // they can re-enter newQ via replaceAll and cause duplicates.
@@ -583,6 +660,14 @@ export class SessionController<TView = unknown> extends Loggable {
       );
     }
 
+    // Additive emphasis: merge (don't clobber) into durable hints. Lets a new
+    // concept's boost accumulate on top of prior concepts' boosts and any
+    // observer-managed boost/decay state. Boosts multiply, lists concat-dedup.
+    if (opts.mergeSessionHints !== undefined) {
+      this._sessionHints = mergeHints([this._sessionHints, opts.mergeSessionHints]) ?? null;
+      this.log(`[Replan] Session hints merged: ${JSON.stringify(this._sessionHints)}`);
+    }
+
     // Forward hints to all sources (CourseDB stashes them, Pipeline consumes
     // them). The one-shot `opts.hints` are merged with the durable
     // `_sessionHints` so session emphasis survives this and every later run.
@@ -638,6 +723,46 @@ export class SessionController<TView = unknown> extends Loggable {
     return this._sessionHints;
   }
 
+  /**
+   * Live state snapshot for the debug overlay (window.skuilder.session
+   * .dbgOverlay()). Reads directly from the private queues and hints, so it
+   * always reflects the current moment — unlike the passive SessionDebugger
+   * snapshots, which only capture what was explicitly pushed to them.
+   */
+  public getDebugSnapshot(): SessionDebugSnapshot {
+    const describe = <T extends { cardID: string }>(q: ItemQueue<T>): SessionQueueDebug => {
+      const cards: string[] = [];
+      for (let i = 0; i < q.length; i++) {
+        cards.push(q.peek(i).cardID);
+      }
+      return { length: q.length, dequeueCount: q.dequeueCount, cards };
+    };
+    const drawnCards: SessionDrawnCardDebug[] = this._sessionRecord.map((r) => {
+      const last = r.records[r.records.length - 1];
+      return {
+        cardID: r.item.cardID,
+        status: r.item.status,
+        attempts: r.records.length,
+        correct: last && isQuestionRecord(last) ? last.isCorrect : null,
+        timeSpentMs: r.records.reduce((sum, rec) => sum + rec.timeSpent, 0),
+      };
+    });
+    return {
+      secondsRemaining: this.secondsRemaining,
+      hasCardGuarantee: this.hasCardGuarantee,
+      minCardsGuarantee: this._minCardsGuarantee,
+      wellIndicatedRemaining: this._wellIndicatedRemaining,
+      currentCard: this._currentCard?.item.cardID ?? null,
+      sessionHints: this._sessionHints,
+      replanActive: this._replanPromise !== null,
+      replanLabel: this._activeReplanLabel,
+      reviewQ: describe(this.reviewQ),
+      newQ: describe(this.newQ),
+      failedQ: describe(this.failedQ),
+      drawnCards,
+    };
+  }
+
   /**
    * Merge `hints` into the durable session hints via the pipeline's
    * `mergeHints` (boosts multiply, require/exclude lists concat-dedup).
@@ -734,9 +859,14 @@ export class SessionController<TView = unknown> extends Loggable {
    */
   private async _replanUncoalesced(opts: ReplanOptions): Promise<void> {
     const run = this._runReplan(opts);
-    this._replanPromise = run.finally(() => {
-      if (this._replanPromise === run) this._replanPromise = null;
+    // See requestReplan: guard against the wrapped promise we store, not `run`.
+    const tracked: Promise<void> = run.finally(() => {
+      if (this._replanPromise === tracked) {
+        this._replanPromise = null;
+        this._activeReplanLabel = null;
+      }
     });
+    this._replanPromise = tracked;
     await run;
   }
 
@@ -1026,8 +1156,13 @@ export class SessionController<TView = unknown> extends Loggable {
     const reviewWeighted = mixedWeighted
       .filter((w) => getCardOrigin(w) === 'review')
       .slice(0, this._initialReviewCap);
+    // Proactive de-dup: a `new` card served earlier this session must never
+    // re-enter newQ — whether it slipped back via a +INF require-injection, an
+    // additive merge, or a stale generator candidate. This is the general guard
+    // (see _servedCardIds); it makes re-presentation structurally impossible
+    // rather than relying on each upstream path to exclude correctly.
     const newWeighted = mixedWeighted
-      .filter((w) => getCardOrigin(w) === 'new')
+      .filter((w) => getCardOrigin(w) === 'new' && !this._servedCardIds.has(w.cardId))
       .slice(0, newLimit);
 
     logger.debug(`[reviews] got ${reviewWeighted.length} reviews from mixer`);
@@ -1272,7 +1407,11 @@ export class SessionController<TView = unknown> extends Loggable {
         `(${otherContent} in other queues) with ${this._secondsRemaining}s remaining. ` +
         `Triggering background replan.`
       );
-      void this.requestReplan();
+      // label is observability-only (overlay/logs); does not affect coalescing.
+      // mode:'merge' preserves any already-queued cards (e.g. an undrawn
+      // prescribed WST whose one-shot requireCards won't be re-asserted by this
+      // bare replan) instead of replaceAll() wiping them. See mergeToFront.
+      void this.requestReplan({ label: 'auto:depletion', mode: 'merge' });
     }
 
     // Opportunistic quality: few well-indicated cards remain.
@@ -1288,7 +1427,8 @@ export class SessionController<TView = unknown> extends Loggable {
         `[AutoReplan:quality] ${this._wellIndicatedRemaining} well-indicated cards remaining ` +
         `(newQ: ${this.newQ.length}). Triggering background replan.`
       );
-      void this.requestReplan();
+      // label is observability-only (overlay/logs); does not affect coalescing.
+      void this.requestReplan({ label: 'auto:quality' });
     }
 
     if (this._secondsRemaining <= 0 && this.failedQ.length === 0 && this._minCardsGuarantee <= 0) {
@@ -1510,6 +1650,21 @@ export class SessionController<TView = unknown> extends Loggable {
    * Remove an item from its source queue after consumption by nextCard().
    */
   private removeItemFromQueue(item: StudySessionItem): void {
+    // Durable-until-drawn requirements: a caller may place a card ID in the
+    // session-durable `requireCards` (via mergeSessionHints) so every later
+    // replan re-asserts it at +INF until it actually surfaces — e.g. a
+    // prescribed intro follow-up that must survive the replace-mode burst/auto
+    // replans that would otherwise clobber a one-shot requirement. The
+    // requirement is satisfied the instant the card is drawn, so clear it here
+    // (the single consumption choke-point) to stop it being re-injected forever
+    // and to bound accumulation. Generic: card-ID only, no domain vocabulary.
+    this._clearDurableRequirement(item.cardID);
+
+    // Record the draw immediately (earlier than _sessionRecord, which waits for
+    // a response) so getWeightedContent can keep this card out of newQ on any
+    // replan that lands after this draw.
+    this._servedCardIds.add(item.cardID);
+
     // Check each queue - item should be at the front of one of them
     if (this.reviewQ.peek(0)?.cardID === item.cardID) {
       this.reviewQ.dequeue((queueItem) => queueItem.cardID);
@@ -1523,6 +1678,28 @@ export class SessionController<TView = unknown> extends Loggable {
     }
   }
 
+  /**
+   * Remove a satisfied card ID from the durable session-hint `requireCards`
+   * list. Called when a card is consumed (see removeItemFromQueue). No-op if
+   * the card was not a durable requirement.
+   *
+   * Matches literal IDs only: a glob/pattern requirement (which may stand for
+   * several cards) is NOT considered satisfied by a single draw and is left in
+   * place — durable patterns are the caller's responsibility, one-shot `hints`
+   * remain the right tool for them.
+   */
+  private _clearDurableRequirement(cardID: string): void {
+    const req = this._sessionHints?.requireCards;
+    if (!req || req.length === 0) return;
+    const next = req.filter((id) => id !== cardID);
+    if (next.length === req.length) return; // not a durable requirement
+    this._sessionHints = {
+      ...this._sessionHints!,
+      requireCards: next.length > 0 ? next : undefined,
+    };
+    this.log(`[Replan] Durable requirement satisfied & cleared on draw: ${cardID}`);
+  }
+
   /**
    * End the session and record learning outcomes.
    *

package/src/study/SessionDebugger.ts

@@ -1,5 +1,6 @@
 import { logger } from '../util/logger';
 import { clearRunHistory as clearPipelineRunHistory } from '../core/navigators/PipelineDebugger';
+import { toggleSessionOverlay } from './SessionOverlay';
 
 // ============================================================================
 // SESSION DEBUGGER
@@ -344,6 +345,14 @@ export const sessionDebugAPI = {
     showCurrentQueue();
   },
 
+  /**
+   * Toggle the pinned, live-updating DOM overlay for the active controller
+   * (queues, session hints, timer). No-ops in non-browser hosts.
+   */
+  dbgOverlay(): void {
+    toggleSessionOverlay();
+  },
+
   /**
    * Show presentation history for current or past session.
    */
@@ -413,6 +422,7 @@ export const sessionDebugAPI = {
 🎯 Session Debug API
 
 Commands:
+  .dbgOverlay()             Toggle the pinned live overlay (queues, hints, timer)
   .showQueue()              Show current queue state (active session only)
   .showHistory(index?)      Show presentation history (0=current/last, 1=previous, etc)
   .showInterleaving(index?) Analyze course interleaving pattern