@vue-skuilder/db 0.2.8 → 0.2.9

package/dist/impl/static/index.d.cts

@@ -1,5 +1,5 @@
-import { U as UserDBInterface, C as CourseDBInterface, b as CoursesDBInterface, c as ClassroomDBInterface, A as AdminDBInterface, a as UserDBReader, d as CourseInfo, S as StudySessionItem, D as DataLayerResult, e as ContentNavigationStrategyData, f as ContentNavigator, R as ReplanHints, G as GeneratorResult } from '../../contentSource-kI9_jwTu.cjs';
-import { D as DataLayerProvider } from '../../dataLayerProvider-CiA2Rr0v.cjs';
+import { U as UserDBInterface, C as CourseDBInterface, b as CoursesDBInterface, c as ClassroomDBInterface, A as AdminDBInterface, a as UserDBReader, d as CourseInfo, S as StudySessionItem, D as DataLayerResult, e as ContentNavigationStrategyData, f as ContentNavigator, R as ReplanHints, G as GeneratorResult } from '../../contentSource-jSkcOt2s.cjs';
+import { D as DataLayerProvider } from '../../dataLayerProvider-BDClIrFC.cjs';
 import { S as StaticCourseManifest } from '../../types-BFUa1pa3.cjs';
 import { CourseConfig, CourseElo, DataShape } from '@vue-skuilder/common';
 import { S as SkuilderCourseData, Q as QualifiedCardID, T as TagStub, a as Tag } from '../../types-legacy-4tlwHnXo.cjs';

package/dist/impl/static/index.d.ts

@@ -1,5 +1,5 @@
-import { U as UserDBInterface, C as CourseDBInterface, b as CoursesDBInterface, c as ClassroomDBInterface, A as AdminDBInterface, a as UserDBReader, d as CourseInfo, S as StudySessionItem, D as DataLayerResult, e as ContentNavigationStrategyData, f as ContentNavigator, R as ReplanHints, G as GeneratorResult } from '../../contentSource-Cplhv3bJ.js';
-import { D as DataLayerProvider } from '../../dataLayerProvider-DrBqOUa3.js';
+import { U as UserDBInterface, C as CourseDBInterface, b as CoursesDBInterface, c as ClassroomDBInterface, A as AdminDBInterface, a as UserDBReader, d as CourseInfo, S as StudySessionItem, D as DataLayerResult, e as ContentNavigationStrategyData, f as ContentNavigator, R as ReplanHints, G as GeneratorResult } from '../../contentSource-C-0t0y0V.js';
+import { D as DataLayerProvider } from '../../dataLayerProvider-BB0oi9T0.js';
 import { S as StaticCourseManifest } from '../../types-CHgpWQAY.js';
 import { CourseConfig, CourseElo, DataShape } from '@vue-skuilder/common';
 import { S as SkuilderCourseData, Q as QualifiedCardID, T as TagStub, a as Tag } from '../../types-legacy-4tlwHnXo.js';

package/dist/impl/static/index.js

@@ -1443,6 +1443,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, {
@@ -1810,7 +1834,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";
@@ -1827,6 +1851,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";
@@ -1886,6 +1913,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,
@@ -1943,10 +1972,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,
@@ -2280,9 +2312,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.
@@ -2297,7 +2336,9 @@ var init_prescribed = __esm({
           userTagElo,
           userGlobalElo,
           activeIds,
-          seenIds
+          seenIds,
+          priorPracticeDebt,
+          nextPracticeDebt
         } = args;
         const patterns = group.practiceTagPatterns ?? [];
         if (patterns.length === 0) return [];
@@ -2307,6 +2348,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,
@@ -2322,18 +2377,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}`
               }
             ]
           });
@@ -2506,15 +2568,16 @@ var srs_exports = {};
 __export(srs_exports, {
   default: () => SRSNavigator
 });
-var import_moment3, DEFAULT_HEALTHY_BACKLOG, MAX_BACKLOG_PRESSURE, SRSNavigator;
+var import_moment3, DEFAULT_HEALTHY_BACKLOG, MAX_BACKLOG_MULTIPLIER, SRSNavigator;
 var init_srs = __esm({
   "src/core/navigators/generators/srs.ts"() {
     "use strict";
     import_moment3 = __toESM(require("moment"), 1);
     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;
@@ -2581,9 +2644,18 @@ var init_srs = __esm({
             }
           }
         }
-        const backlogPressure = this.computeBacklogPressure(dueReviews.length);
+        const backlogMultiplier = this.computeBacklogMultiplier(dueReviews.length);
+        const notDue = reviews.filter((r) => !now.isAfter(import_moment3.default.utc(r.reviewTime)));
+        let nextDueIn = null;
+        if (notDue.length > 0) {
+          const next = notDue.reduce(
+            (a, b) => import_moment3.default.utc(a.reviewTime).isBefore(import_moment3.default.utc(b.reviewTime)) ? a : b
+          );
+          const until = import_moment3.default.duration(import_moment3.default.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}`
           );
@@ -2602,7 +2674,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,
@@ -2620,30 +2692,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.
@@ -2658,19 +2742,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 = import_moment3.default.utc(review.scheduledAt);
         const due = import_moment3.default.utc(review.reviewTime);
         const intervalHours = Math.max(1, due.diff(scheduledAt, "hours"));
@@ -2680,15 +2765,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(", ");
@@ -4740,6 +4825,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)),
@@ -4772,12 +4858,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,
@@ -4859,6 +4947,7 @@ var init_navigators = __esm({
     "use strict";
     init_diversityRerank();
     init_PipelineDebugger();
+    init_SrsDebugger();
     init_logger();
     init_();
     init_2();