@vue-skuilder/db 0.2.7 → 0.2.9

package/dist/core/index.mjs

@@ -791,6 +791,7 @@ __export(PipelineDebugger_exports, {
   buildRunReport: () => buildRunReport,
   captureRun: () => captureRun,
   clearRunHistory: () => clearRunHistory,
+  getActivePipeline: () => getActivePipeline,
   mountPipelineDebugger: () => mountPipelineDebugger,
   pipelineDebugAPI: () => pipelineDebugAPI,
   registerPipelineForDebug: () => registerPipelineForDebug
@@ -798,6 +799,9 @@ __export(PipelineDebugger_exports, {
 function registerPipelineForDebug(pipeline) {
   _activePipeline = pipeline;
 }
+function getActivePipeline() {
+  return _activePipeline;
+}
 function clearRunHistory() {
   runHistory.length = 0;
 }
@@ -1613,6 +1617,30 @@ Example:
   }
 });
 
+// src/core/navigators/SrsDebugger.ts
+var SrsDebugger_exports = {};
+__export(SrsDebugger_exports, {
+  captureSrsBacklog: () => captureSrsBacklog,
+  clearSrsBacklogDebug: () => clearSrsBacklogDebug,
+  getSrsBacklogDebug: () => getSrsBacklogDebug
+});
+function captureSrsBacklog(snapshot) {
+  snapshots.set(snapshot.courseId, snapshot);
+}
+function getSrsBacklogDebug() {
+  return [...snapshots.values()].sort((a, b) => b.timestamp - a.timestamp);
+}
+function clearSrsBacklogDebug() {
+  snapshots.clear();
+}
+var snapshots;
+var init_SrsDebugger = __esm({
+  "src/core/navigators/SrsDebugger.ts"() {
+    "use strict";
+    snapshots = /* @__PURE__ */ new Map();
+  }
+});
+
 // src/core/navigators/generators/CompositeGenerator.ts
 var CompositeGenerator_exports = {};
 __export(CompositeGenerator_exports, {
@@ -1980,7 +2008,7 @@ function shuffleInPlace(arr) {
 function pickTopByScore(cards, limit) {
   return [...cards].sort((a, b) => b.score - a.score || a.cardId.localeCompare(b.cardId)).slice(0, limit);
 }
-var DEFAULT_FRESHNESS_WINDOW, DEFAULT_MAX_DIRECT_PER_RUN, DEFAULT_MAX_SUPPORT_PER_RUN, DEFAULT_HIERARCHY_DEPTH, DEFAULT_MIN_COUNT, DEFAULT_PRACTICE_MIN_COUNT, DEFAULT_MAX_PRACTICE_PER_RUN, BASE_TARGET_SCORE, BASE_SUPPORT_SCORE, DISCOVERED_SUPPORT_SCORE, BASE_PRACTICE_SCORE, MAX_TARGET_MULTIPLIER, MAX_SUPPORT_MULTIPLIER, PRESCRIBED_DEBUG_VERSION, PrescribedCardsGenerator;
+var DEFAULT_FRESHNESS_WINDOW, DEFAULT_MAX_DIRECT_PER_RUN, DEFAULT_MAX_SUPPORT_PER_RUN, DEFAULT_HIERARCHY_DEPTH, DEFAULT_MIN_COUNT, DEFAULT_PRACTICE_MIN_COUNT, DEFAULT_MAX_PRACTICE_PER_RUN, BASE_TARGET_SCORE, BASE_SUPPORT_SCORE, DISCOVERED_SUPPORT_SCORE, BASE_PRACTICE_SCORE, PRACTICE_BASE_MULT, MAX_PRACTICE_MULTIPLIER, PRACTICE_STALENESS_BUMP_PER_DAY, MAX_TARGET_MULTIPLIER, MAX_SUPPORT_MULTIPLIER, PRESCRIBED_DEBUG_VERSION, PrescribedCardsGenerator;
 var init_prescribed = __esm({
   "src/core/navigators/generators/prescribed.ts"() {
     "use strict";
@@ -1997,6 +2025,9 @@ var init_prescribed = __esm({
     BASE_SUPPORT_SCORE = 0.8;
     DISCOVERED_SUPPORT_SCORE = 12;
     BASE_PRACTICE_SCORE = 1;
+    PRACTICE_BASE_MULT = 2;
+    MAX_PRACTICE_MULTIPLIER = 4;
+    PRACTICE_STALENESS_BUMP_PER_DAY = 0.5;
     MAX_TARGET_MULTIPLIER = 8;
     MAX_SUPPORT_MULTIPLIER = 4;
     PRESCRIBED_DEBUG_VERSION = "testversion-prescribed-v3";
@@ -2056,6 +2087,8 @@ var init_prescribed = __esm({
         const emitted = [];
         const emittedIds = /* @__PURE__ */ new Set();
         const groupRuntimes = [];
+        const priorPracticeDebt = progress.practiceDebt ?? {};
+        const nextPracticeDebt = {};
         for (const group of this.config.groups) {
           const runtime = this.buildGroupRuntimeState({
             group,
@@ -2113,10 +2146,13 @@ var init_prescribed = __esm({
             userTagElo,
             userGlobalElo,
             activeIds,
-            seenIds
+            seenIds,
+            priorPracticeDebt,
+            nextPracticeDebt
           });
           emitted.push(...directCards, ...supportCards, ...discoveredSupportCards, ...practiceCards);
         }
+        nextState.practiceDebt = nextPracticeDebt;
         const hintSummary = this.buildSupportHintSummary(groupRuntimes);
         const hints = Object.keys(hintSummary.boostTags).length > 0 ? {
           boostTags: hintSummary.boostTags,
@@ -2450,9 +2486,16 @@ var init_prescribed = __esm({
        * `practiceMinCount`), this resolves cards carrying that tag and emits them
        * into the candidate pool. It exists because global-ELO retrieval
        * systematically fails to fetch the (low-ELO) drill cards for a
-       * freshly-introduced skill — putting them in the pool here lets the pipeline's
-       * scoring + the durable per-skill boost order them. Ordering/emphasis is NOT
-       * this method's job; it only guarantees presence.
+       * freshly-introduced skill — putting them in the pool here guarantees presence.
+       *
+       * Emphasis is a **practice-debt pressure** (parallel to SRS backlog pressure):
+       * cards score `base × multiplier`, where the multiplier starts at
+       * PRACTICE_BASE_MULT (so a few reps land promptly post-intro, competing with
+       * pressured reviews) and escalates by how long the debt has stayed open
+       * (per-tag, time-based via `priorPracticeDebt`/`nextPracticeDebt`), clamped at
+       * MAX_PRACTICE_MULTIPLIER. The debt is durable and self-discharges the instant
+       * the skill reaches `practiceMinCount` — so this no longer relies on the
+       * session-scoped intro boost to actually surface.
        *
        * Fully data-driven: the unlock relation comes from the hierarchy config and
        * practice-status from per-tag ELO. No card-id or tag-namespace hard-coding.
@@ -2467,7 +2510,9 @@ var init_prescribed = __esm({
           userTagElo,
           userGlobalElo,
           activeIds,
-          seenIds
+          seenIds,
+          priorPracticeDebt,
+          nextPracticeDebt
         } = args;
         const patterns = group.practiceTagPatterns ?? [];
         if (patterns.length === 0) return [];
@@ -2477,6 +2522,20 @@ var init_prescribed = __esm({
           (tag) => patterns.some((p) => matchesTagPattern(tag, p)) && this.isUnlockedGatedSkill(tag, hierarchyConfigs, userTagElo, userGlobalElo) && (userTagElo[tag]?.count ?? 0) < practiceMinCount
         );
         if (practiceTags.length === 0) return [];
+        const now = Date.now();
+        const DAY_MS = 24 * 60 * 60 * 1e3;
+        const tagMultiplier = /* @__PURE__ */ new Map();
+        for (const tag of practiceTags) {
+          const firstOwedAt = priorPracticeDebt[tag] ?? isoNow();
+          nextPracticeDebt[tag] = firstOwedAt;
+          const staleDays = Math.max(0, (now - new Date(firstOwedAt).getTime()) / DAY_MS);
+          const mult = clamp(
+            PRACTICE_BASE_MULT + staleDays * PRACTICE_STALENESS_BUMP_PER_DAY,
+            PRACTICE_BASE_MULT,
+            MAX_PRACTICE_MULTIPLIER
+          );
+          tagMultiplier.set(tag, mult);
+        }
         const practiceCardIds = this.findDiscoveredSupportCards({
           supportTags: practiceTags,
           cardsByTag,
@@ -2492,18 +2551,25 @@ var init_prescribed = __esm({
         const cards = [];
         for (const cardId of practiceCardIds) {
           emittedIds.add(cardId);
+          let mult = PRACTICE_BASE_MULT;
+          for (const tag of practiceTags) {
+            if (cardsByTag.get(tag)?.includes(cardId) ?? false) {
+              mult = Math.max(mult, tagMultiplier.get(tag) ?? PRACTICE_BASE_MULT);
+            }
+          }
+          const score = BASE_PRACTICE_SCORE * mult;
           cards.push({
             cardId,
             courseId,
-            score: BASE_PRACTICE_SCORE,
+            score,
             provenance: [
               {
                 strategy: "prescribed",
                 strategyName: this.strategyName || this.name,
                 strategyId: this.strategyId || "NAVIGATION_STRATEGY-prescribed",
                 action: "generated",
-                score: BASE_PRACTICE_SCORE,
-                reason: `mode=practice;group=${group.id};underPracticedSkills=${practiceTags.length};practiceTags=${practiceTags.slice(0, 8).join("|")}${practiceTags.length > 8 ? "|\u2026" : ""};testversion=${PRESCRIBED_DEBUG_VERSION}`
+                score,
+                reason: `mode=practice;group=${group.id};debtMult=\xD7${mult.toFixed(2)};underPracticedSkills=${practiceTags.length};practiceTags=${practiceTags.slice(0, 8).join("|")}${practiceTags.length > 8 ? "|\u2026" : ""};testversion=${PRESCRIBED_DEBUG_VERSION}`
               }
             ]
           });
@@ -2677,14 +2743,15 @@ __export(srs_exports, {
   default: () => SRSNavigator
 });
 import moment3 from "moment";
-var DEFAULT_HEALTHY_BACKLOG, MAX_BACKLOG_PRESSURE, SRSNavigator;
+var DEFAULT_HEALTHY_BACKLOG, MAX_BACKLOG_MULTIPLIER, SRSNavigator;
 var init_srs = __esm({
   "src/core/navigators/generators/srs.ts"() {
     "use strict";
     init_navigators();
+    init_SrsDebugger();
     init_logger();
     DEFAULT_HEALTHY_BACKLOG = 20;
-    MAX_BACKLOG_PRESSURE = 0.5;
+    MAX_BACKLOG_MULTIPLIER = 2;
     SRSNavigator = class extends ContentNavigator {
       /** Human-readable name for CardGenerator interface */
       name;
@@ -2751,9 +2818,18 @@ var init_srs = __esm({
             }
           }
         }
-        const backlogPressure = this.computeBacklogPressure(dueReviews.length);
+        const backlogMultiplier = this.computeBacklogMultiplier(dueReviews.length);
+        const notDue = reviews.filter((r) => !now.isAfter(moment3.utc(r.reviewTime)));
+        let nextDueIn = null;
+        if (notDue.length > 0) {
+          const next = notDue.reduce(
+            (a, b) => moment3.utc(a.reviewTime).isBefore(moment3.utc(b.reviewTime)) ? a : b
+          );
+          const until = moment3.duration(moment3.utc(next.reviewTime).diff(now));
+          nextDueIn = until.asHours() < 1 ? `${Math.round(until.asMinutes())}m` : until.asHours() < 24 ? `${Math.round(until.asHours())}h` : `${Math.round(until.asDays())}d`;
+        }
         if (dueReviews.length > 0) {
-          const pressureNote = backlogPressure > 0 ? ` [backlog pressure: +${backlogPressure.toFixed(2)}]` : ` [healthy backlog]`;
+          const pressureNote = backlogMultiplier > 1 ? ` [backlog pressure: \xD7${backlogMultiplier.toFixed(2)}]` : ` [healthy backlog]`;
           logger.info(
             `[SRS] Course ${courseId}: ${dueReviews.length} reviews due now (of ${reviews.length} scheduled)${pressureNote}`
           );
@@ -2772,7 +2848,7 @@ var init_srs = __esm({
           logger.info(`[SRS] Course ${courseId}: No reviews scheduled`);
         }
         const scored = dueReviews.map((review) => {
-          const { score, reason } = this.computeUrgencyScore(review, now, backlogPressure);
+          const { score, reason } = this.computeUrgencyScore(review, now, backlogMultiplier);
           return {
             cardId: review.cardId,
             courseId: review.courseId,
@@ -2790,30 +2866,42 @@ var init_srs = __esm({
             ]
           };
         });
-        return { cards: scored.sort((a, b) => b.score - a.score).slice(0, limit) };
+        const sorted = scored.sort((a, b) => b.score - a.score);
+        captureSrsBacklog({
+          courseId,
+          scheduledTotal: reviews.length,
+          dueNow: dueReviews.length,
+          healthyBacklog: this.healthyBacklog,
+          backlogMultiplier,
+          maxBacklogMultiplier: MAX_BACKLOG_MULTIPLIER,
+          topReviewScore: sorted.length > 0 ? sorted[0].score : null,
+          nextDueIn,
+          timestamp: Date.now()
+        });
+        return { cards: sorted.slice(0, limit) };
       }
       /**
-       * Compute backlog pressure based on number of due reviews.
+       * Compute the multiplicative backlog pressure based on number of due reviews.
        *
-       * Backlog pressure is 0 when at or below healthy threshold,
-       * and increases linearly above it, maxing out at MAX_BACKLOG_PRESSURE.
+       * ×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.
        *
-       * Examples (with default healthyBacklog=20):
-       * - 10 due reviews → 0.00 (healthy)
-       * - 20 due reviews → 0.00 (at threshold)
-       * - 40 due reviews → 0.25 (2x threshold)
-       * - 60 due reviews → 0.50 (3x threshold, maxed)
+       * 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)
        *
        * @param dueCount - Number of reviews currently due
-       * @returns Backlog pressure score to add to urgency (0 to MAX_BACKLOG_PRESSURE)
+       * @returns Multiplier applied to review urgency (1.0 to MAX_BACKLOG_MULTIPLIER)
        */
-      computeBacklogPressure(dueCount) {
+      computeBacklogMultiplier(dueCount) {
         if (dueCount <= this.healthyBacklog) {
-          return 0;
+          return 1;
         }
         const excess = dueCount - this.healthyBacklog;
-        const pressure = excess / this.healthyBacklog * (MAX_BACKLOG_PRESSURE / 2);
-        return Math.min(MAX_BACKLOG_PRESSURE, pressure);
+        const multiplier = 1 + excess / this.healthyBacklog * ((MAX_BACKLOG_MULTIPLIER - 1) / 2);
+        return Math.min(MAX_BACKLOG_MULTIPLIER, multiplier);
       }
       /**
        * Compute urgency score for a review card.
@@ -2828,19 +2916,20 @@ var init_srs = __esm({
        *    - 30 days (720h) → ~0.56
        *    - 180 days → ~0.30
        *
-       * 3. Backlog pressure = global boost when review backlog exceeds healthy threshold
-       *    - At healthy backlog: 0
-       *    - At 2x healthy: +0.25
-       *    - At 3x+ healthy: +0.50 (max)
+       * 3. Backlog pressure = global *multiplier* when review backlog exceeds the
+       *    healthy threshold (×1.0 healthy → up to MAX_BACKLOG_MULTIPLIER at 3×).
        *
-       * Combined: base 0.5 + (urgency factors * 0.45) + backlog pressure
-       * Result range: 0.5 to 1.0 (uncapped to allow high-urgency reviews to compete with new cards)
+       * 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.
        *
        * @param review - The scheduled card to score
        * @param now - Current time
-       * @param backlogPressure - Pre-computed backlog pressure (0 to 0.5)
+       * @param backlogMultiplier - Pre-computed backlog multiplier (1.0 to MAX_BACKLOG_MULTIPLIER)
        */
-      computeUrgencyScore(review, now, backlogPressure) {
+      computeUrgencyScore(review, now, backlogMultiplier) {
         const scheduledAt = moment3.utc(review.scheduledAt);
         const due = moment3.utc(review.reviewTime);
         const intervalHours = Math.max(1, due.diff(scheduledAt, "hours"));
@@ -2850,15 +2939,15 @@ var init_srs = __esm({
         const overdueContribution = Math.min(1, Math.max(0, relativeOverdue));
         const urgency = overdueContribution * 0.5 + recencyFactor * 0.5;
         const baseScore = 0.5 + urgency * 0.45;
-        const score = Math.min(1, baseScore + backlogPressure);
+        const score = baseScore * backlogMultiplier;
         const reasonParts = [
           `${Math.round(hoursOverdue)}h overdue`,
           `interval: ${Math.round(intervalHours)}h`,
           `relative: ${relativeOverdue.toFixed(2)}`,
           `recency: ${recencyFactor.toFixed(2)}`
         ];
-        if (backlogPressure > 0) {
-          reasonParts.push(`backlog: +${backlogPressure.toFixed(2)}`);
+        if (backlogMultiplier > 1) {
+          reasonParts.push(`backlog: \xD7${backlogMultiplier.toFixed(2)}`);
         }
         reasonParts.push("review");
         const reason = reasonParts.join(", ");
@@ -4830,6 +4919,68 @@ var init_Pipeline = __esm({
       // ---------------------------------------------------------------------------
       // Card-space diagnostic
       // ---------------------------------------------------------------------------
+      /**
+       * Commit-free forecast: score the user's full card space through the filter
+       * chain and return the cards that are currently *reachable* (score >=
+       * threshold), optionally nudged by caller-supplied hints and/or restricted
+       * to cards the user hasn't seen yet.
+       *
+       * This is a GENERIC primitive — it returns scored, tag-hydrated cards and
+       * stops there. It has no knowledge of any particular tag convention; callers
+       * decide what the surviving cards mean (e.g. filter to their own "intro"
+       * tag family). Nothing is written and no session is started.
+       *
+       * The optional `hints` are the "out-of-band kick": they run through the same
+       * {@link applyHints} path a live replan uses, so the two semantics carry over —
+       *   - `boostTags`/`boostCards` reweight *within* gating (a gated score-0 card
+       *     stays out), and
+       *   - `requireTags`/`requireCards` inject from the full pre-filter pool,
+       *     *bypassing* gating (use when you want a card regardless of reachability).
+       * Note `unseenOnly` is applied LAST, so it can drop a `require`d card that the
+       * user has already seen — pass `unseenOnly: false` if that matters.
+       *
+       * Cost note: like {@link diagnoseCardSpace}, this scans every card through the
+       * filters, so it's heavier than a normal replan. Intended for one-shot
+       * out-of-band use (e.g. a session-end "what's next" snapshot), not the hot path.
+       *
+       * @param opts.hints       Optional ephemeral hints to apply after the filter chain.
+       * @param opts.unseenOnly  Only return cards the user hasn't encountered (default true).
+       * @param opts.threshold   Min score to count as reachable (default 0.10).
+       * @param opts.limit       Optional cap on results (already sorted desc).
+       */
+      async forecast(opts) {
+        const threshold = opts?.threshold ?? 0.1;
+        const unseenOnly = opts?.unseenOnly ?? true;
+        const courseId = this.course.getCourseID();
+        const allCardIds = await this.course.getAllCardIds();
+        let cards = allCardIds.map((cardId) => ({
+          cardId,
+          courseId,
+          score: 1,
+          provenance: []
+        }));
+        cards = await this.hydrateTags(cards);
+        const fullPool = cards.slice();
+        const context = await this.buildContext();
+        for (const filter of this.filters) {
+          cards = await filter.transform(cards, context);
+        }
+        if (opts?.hints) {
+          cards = this.applyHints(cards, opts.hints, fullPool);
+        }
+        cards = cards.filter((c) => c.score >= threshold);
+        if (unseenOnly) {
+          let encountered;
+          try {
+            encountered = new Set(await this.user.getSeenCards(courseId));
+          } catch {
+            encountered = /* @__PURE__ */ new Set();
+          }
+          cards = cards.filter((c) => !encountered.has(c.cardId));
+        }
+        cards.sort((a, b) => b.score - a.score);
+        return opts?.limit ? cards.slice(0, opts.limit) : cards;
+      }
       /**
        * Scan every card in the course through the filter chain and report
        * how many are "well indicated" (score >= threshold) for the current user.
@@ -5094,6 +5245,7 @@ var init_3 = __esm({
       "./Pipeline.ts": () => Promise.resolve().then(() => (init_Pipeline(), Pipeline_exports)),
       "./PipelineAssembler.ts": () => Promise.resolve().then(() => (init_PipelineAssembler(), PipelineAssembler_exports)),
       "./PipelineDebugger.ts": () => Promise.resolve().then(() => (init_PipelineDebugger(), PipelineDebugger_exports)),
+      "./SrsDebugger.ts": () => Promise.resolve().then(() => (init_SrsDebugger(), SrsDebugger_exports)),
       "./defaults.ts": () => Promise.resolve().then(() => (init_defaults(), defaults_exports)),
       "./diversityRerank.ts": () => Promise.resolve().then(() => (init_diversityRerank(), diversityRerank_exports)),
       "./filters/WeightedFilter.ts": () => Promise.resolve().then(() => (init_WeightedFilter(), WeightedFilter_exports)),
@@ -5126,11 +5278,14 @@ __export(navigators_exports, {
   NavigatorRole: () => NavigatorRole,
   NavigatorRoles: () => NavigatorRoles,
   Navigators: () => Navigators,
+  clearSrsBacklogDebug: () => clearSrsBacklogDebug,
   diversityRerank: () => diversityRerank,
+  getActivePipeline: () => getActivePipeline,
   getCardOrigin: () => getCardOrigin,
   getRegisteredNavigator: () => getRegisteredNavigator,
   getRegisteredNavigatorNames: () => getRegisteredNavigatorNames,
   getRegisteredNavigatorRole: () => getRegisteredNavigatorRole,
+  getSrsBacklogDebug: () => getSrsBacklogDebug,
   hasRegisteredNavigator: () => hasRegisteredNavigator,
   initializeNavigatorRegistry: () => initializeNavigatorRegistry,
   isFilter: () => isFilter,
@@ -5212,6 +5367,7 @@ var init_navigators = __esm({
     "use strict";
     init_diversityRerank();
     init_PipelineDebugger();
+    init_SrsDebugger();
     init_logger();
     init_();
     init_2();
@@ -8246,6 +8402,7 @@ export {
   aggregateOutcomesForGradient,
   areQuestionRecords,
   buildStrategyStateId,
+  clearSrsBacklogDebug,
   computeDeviation,
   computeEffectiveWeight,
   computeOutcomeSignal,
@@ -8254,12 +8411,14 @@ export {
   createOrchestrationContext,
   diversityRerank,
   docIsDeleted,
+  getActivePipeline,
   getCardHistoryID,
   getCardOrigin,
   getDefaultLearnableWeight,
   getRegisteredNavigator,
   getRegisteredNavigatorNames,
   getRegisteredNavigatorRole,
+  getSrsBacklogDebug,
   getStudySource,
   hasRegisteredNavigator,
   importParsedCards,