@vue-skuilder/db 0.2.28 → 0.2.30

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. package/dist/{contentSource-DpQqTG3m.d.cts → contentSource-B6FrSihy.d.cts} +218 -2
  2. package/dist/{contentSource-BoFBwvYa.d.ts → contentSource-CqJmbOZN.d.ts} +218 -2
  3. package/dist/core/index.d.cts +13 -90
  4. package/dist/core/index.d.ts +13 -90
  5. package/dist/core/index.js +621 -179
  6. package/dist/core/index.js.map +1 -1
  7. package/dist/core/index.mjs +620 -179
  8. package/dist/core/index.mjs.map +1 -1
  9. package/dist/{dataLayerProvider-D_LJT3F4.d.ts → dataLayerProvider-B9_UCvkR.d.ts} +1 -1
  10. package/dist/{dataLayerProvider-Dl3cAAvQ.d.cts → dataLayerProvider-DUxDqMtZ.d.cts} +1 -1
  11. package/dist/diagnostics/index.d.cts +79 -6
  12. package/dist/diagnostics/index.d.ts +79 -6
  13. package/dist/diagnostics/index.js +158 -4
  14. package/dist/diagnostics/index.js.map +1 -1
  15. package/dist/diagnostics/index.mjs +156 -4
  16. package/dist/diagnostics/index.mjs.map +1 -1
  17. package/dist/impl/couch/index.d.cts +11 -2
  18. package/dist/impl/couch/index.d.ts +11 -2
  19. package/dist/impl/couch/index.js +619 -179
  20. package/dist/impl/couch/index.js.map +1 -1
  21. package/dist/impl/couch/index.mjs +619 -179
  22. package/dist/impl/couch/index.mjs.map +1 -1
  23. package/dist/impl/static/index.d.cts +8 -2
  24. package/dist/impl/static/index.d.ts +8 -2
  25. package/dist/impl/static/index.js +616 -179
  26. package/dist/impl/static/index.js.map +1 -1
  27. package/dist/impl/static/index.mjs +616 -179
  28. package/dist/impl/static/index.mjs.map +1 -1
  29. package/dist/index.d.cts +66 -5
  30. package/dist/index.d.ts +66 -5
  31. package/dist/index.js +669 -180
  32. package/dist/index.js.map +1 -1
  33. package/dist/index.mjs +656 -180
  34. package/dist/index.mjs.map +1 -1
  35. package/package.json +3 -3
  36. package/src/core/interfaces/contentSource.ts +7 -0
  37. package/src/core/navigators/Pipeline.ts +145 -13
  38. package/src/core/navigators/PipelineAssembler.ts +19 -40
  39. package/src/core/navigators/PipelineDebugger.ts +11 -2
  40. package/src/core/navigators/SrsDebugger.ts +37 -12
  41. package/src/core/navigators/defaults.ts +29 -5
  42. package/src/core/navigators/filters/WeightedFilter.ts +5 -1
  43. package/src/core/navigators/filters/eloDistance.ts +320 -76
  44. package/src/core/navigators/filters/hierarchyDefinition.ts +5 -1
  45. package/src/core/navigators/filters/index.ts +2 -2
  46. package/src/core/navigators/filters/interferenceMitigator.ts +5 -1
  47. package/src/core/navigators/filters/relativePriority.ts +5 -1
  48. package/src/core/navigators/filters/types.ts +24 -1
  49. package/src/core/navigators/filters/userTagPreference.ts +5 -1
  50. package/src/core/navigators/generators/elo.ts +23 -53
  51. package/src/core/navigators/generators/srs.ts +27 -124
  52. package/src/core/navigators/index.ts +31 -5
  53. package/src/core/navigators/pipelinePlan.ts +245 -0
  54. package/src/core/navigators/regulators.ts +230 -0
  55. package/src/core/types/studySession.ts +3 -0
  56. package/src/diagnostics/dataset.ts +13 -2
  57. package/src/diagnostics/index.ts +3 -0
  58. package/src/diagnostics/loader.ts +5 -2
  59. package/src/diagnostics/pipeline.ts +236 -0
  60. package/src/diagnostics/text.ts +26 -3
  61. package/src/impl/couch/courseDB.ts +13 -0
  62. package/src/impl/static/courseDB.ts +9 -0
  63. package/src/index.ts +4 -0
  64. package/src/study/SessionController.ts +20 -0
  65. package/src/study/SessionOverlay.ts +7 -4
  66. package/tests/core/navigators/PipelineAssembler.test.ts +20 -5
  67. package/tests/core/navigators/eloDistanceFilter.test.ts +9 -9
@@ -509,7 +509,7 @@ function parseCardElo(provenance) {
509
509
  const match = eloEntry.reason.match(/card:\s*(\d+)/);
510
510
  return match ? parseInt(match[1], 10) : void 0;
511
511
  }
512
- function buildRunReport(courseId, courseName, generatorName, generators, generatedCount, filters, allCards, selectedCards, userElo, hints, scoredCards) {
512
+ function buildRunReport(courseId, courseName, generatorName, generators, generatedCount, filters, allCards, selectedCards, userElo, hints, scoredCards, regulators) {
513
513
  const selectedIds = new Set(selectedCards.map((c) => c.cardId));
514
514
  const toReport = (card) => ({
515
515
  cardId: card.cardId,
@@ -517,7 +517,7 @@ function buildRunReport(courseId, courseName, generatorName, generators, generat
517
517
  origin: getOrigin(card),
518
518
  generator: card.provenance[0]?.strategyName || card.provenance[0]?.strategy,
519
519
  finalScore: card.score,
520
- cardElo: parseCardElo(card.provenance),
520
+ cardElo: card.cardElo ?? parseCardElo(card.provenance),
521
521
  provenance: card.provenance,
522
522
  tags: card.tags,
523
523
  selected: selectedIds.has(card.cardId)
@@ -595,7 +595,8 @@ function buildRunReport(courseId, courseName, generatorName, generators, generat
595
595
  newSelected,
596
596
  cards,
597
597
  unselectedNew,
598
- discardedTail
598
+ discardedTail,
599
+ ...regulators ? { regulators } : {}
599
600
  };
600
601
  }
601
602
  function formatProvenance(provenance) {
@@ -1319,11 +1320,23 @@ var SrsDebugger_exports = {};
1319
1320
  __export(SrsDebugger_exports, {
1320
1321
  captureSrsBacklog: () => captureSrsBacklog,
1321
1322
  clearSrsBacklogDebug: () => clearSrsBacklogDebug,
1322
- getSrsBacklogDebug: () => getSrsBacklogDebug
1323
+ getSrsBacklogDebug: () => getSrsBacklogDebug,
1324
+ noteReviewPressure: () => noteReviewPressure
1323
1325
  });
1324
1326
  function captureSrsBacklog(snapshot) {
1325
1327
  snapshots.set(snapshot.courseId, snapshot);
1326
1328
  }
1329
+ function noteReviewPressure(courseId, pressure) {
1330
+ const snapshot = snapshots.get(courseId);
1331
+ if (!snapshot) return;
1332
+ snapshots.set(courseId, {
1333
+ ...snapshot,
1334
+ reviewMass: pressure.mass,
1335
+ healthyBacklog: pressure.healthyMass,
1336
+ backlogGrowthRate: pressure.rate,
1337
+ backlogMultiplier: pressure.multiplier
1338
+ });
1339
+ }
1327
1340
  function getSrsBacklogDebug() {
1328
1341
  return [...snapshots.values()].sort((a, b) => b.timestamp - a.timestamp);
1329
1342
  }
@@ -1602,13 +1615,12 @@ __export(elo_exports, {
1602
1615
  default: () => ELONavigator
1603
1616
  });
1604
1617
  import { toCourseElo as toCourseElo2 } from "@vue-skuilder/common";
1605
- var ELO_RELEVANCE_SIGMA, ELONavigator;
1618
+ var ELONavigator;
1606
1619
  var init_elo = __esm({
1607
1620
  "src/core/navigators/generators/elo.ts"() {
1608
1621
  "use strict";
1609
1622
  init_navigators();
1610
1623
  init_logger();
1611
- ELO_RELEVANCE_SIGMA = 300;
1612
1624
  ELONavigator = class extends ContentNavigator {
1613
1625
  /** Human-readable name for CardGenerator interface */
1614
1626
  name;
@@ -1617,10 +1629,8 @@ var init_elo = __esm({
1617
1629
  this.name = strategyData?.name || "ELO";
1618
1630
  }
1619
1631
  /**
1620
- * Get new cards with suitability scores based on ELO distance.
1621
- *
1622
- * Cards closer to user's ELO get higher scores.
1623
- * Score formula: max(0, 1 - distance / 500)
1632
+ * Get the new cards nearest the learner's ELO, each scored with a flat
1633
+ * jitter in [0.5, 1]. Carries each card's ELO for the ELO distance filter.
1624
1634
  *
1625
1635
  * NOTE: This generator only handles NEW cards. Reviews are handled by
1626
1636
  * SRSNavigator. Use CompositeGenerator to combine both.
@@ -1648,20 +1658,20 @@ var init_elo = __esm({
1648
1658
  const scored = newCards.map((c) => {
1649
1659
  const cardElo = c.elo ?? 1e3;
1650
1660
  const distance = Math.abs(cardElo - userGlobalElo);
1651
- const relevance = Math.exp(-((distance / ELO_RELEVANCE_SIGMA) ** 2));
1652
- const samplingKey = relevance * (0.5 + 0.5 * Math.random());
1661
+ const jitter = 0.5 + 0.5 * Math.random();
1653
1662
  return {
1654
1663
  cardId: c.cardID,
1655
1664
  courseId: c.courseID,
1656
- score: samplingKey,
1665
+ score: jitter,
1666
+ cardElo,
1657
1667
  provenance: [
1658
1668
  {
1659
1669
  strategy: "elo",
1660
1670
  strategyName: this.strategyName || this.name,
1661
1671
  strategyId: this.strategyId || "NAVIGATION_STRATEGY-ELO-default",
1662
1672
  action: "generated",
1663
- score: samplingKey,
1664
- reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userGlobalElo)}), relevance ${relevance.toFixed(3)}, key ${samplingKey.toFixed(3)}`
1673
+ score: jitter,
1674
+ reason: `new card near learner ELO: distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userGlobalElo)}), jitter ${jitter.toFixed(3)}`
1665
1675
  }
1666
1676
  ]
1667
1677
  };
@@ -2537,43 +2547,132 @@ var init_prescribed = __esm({
2537
2547
  }
2538
2548
  });
2539
2549
 
2550
+ // src/core/navigators/regulators.ts
2551
+ var regulators_exports = {};
2552
+ __export(regulators_exports, {
2553
+ DEFAULT_REGULATOR_CONFIG: () => DEFAULT_REGULATOR_CONFIG,
2554
+ INTAKE_CLOCK_KEY: () => INTAKE_CLOCK_KEY,
2555
+ applyReading: () => applyReading,
2556
+ frozenMsAt: () => frozenMsAt,
2557
+ intakeHours: () => intakeHours,
2558
+ intakeReading: () => intakeReading,
2559
+ resetIntakeClock: () => resetIntakeClock,
2560
+ reviewMassReading: () => reviewMassReading,
2561
+ reviewWeight: () => reviewWeight,
2562
+ stepIntakeClock: () => stepIntakeClock
2563
+ });
2564
+ function clamp01(x) {
2565
+ return Math.min(1, Math.max(0, x));
2566
+ }
2567
+ function reviewWeight(card, generatedScore, referenceScore) {
2568
+ if (card.reviewUrgency !== void 0 && generatedScore !== void 0 && generatedScore > 0) {
2569
+ return clamp01(card.reviewUrgency * (card.score / generatedScore));
2570
+ }
2571
+ return clamp01(card.score / referenceScore);
2572
+ }
2573
+ function reviewMassReading(reviews, generatedScores, config = DEFAULT_REGULATOR_CONFIG.reviewMass) {
2574
+ const mass = reviews.reduce(
2575
+ (m, c) => m + reviewWeight(c, generatedScores.get(c.cardId), config.referenceScore),
2576
+ 0
2577
+ );
2578
+ const multiplier = mass > config.healthyMass ? Math.pow(config.rate, (mass - config.healthyMass) / config.healthyMass) : 1;
2579
+ return {
2580
+ name: "review-mass",
2581
+ class: "review",
2582
+ urgency: mass,
2583
+ multiplier,
2584
+ applied: reviews.length,
2585
+ inputs: { due: reviews.length, mass, healthyMass: config.healthyMass }
2586
+ };
2587
+ }
2588
+ function resetIntakeClock(nowMs) {
2589
+ return { lastNewAt: new Date(nowMs).toISOString(), frozenMs: 0, unservableSince: null };
2590
+ }
2591
+ function frozenMsAt(state, nowMs) {
2592
+ const open = state.unservableSince ? Math.max(0, nowMs - Date.parse(state.unservableSince)) : 0;
2593
+ return state.frozenMs + open;
2594
+ }
2595
+ function intakeHours(state, nowMs) {
2596
+ const elapsed = nowMs - Date.parse(state.lastNewAt);
2597
+ return Math.max(0, elapsed - frozenMsAt(state, nowMs)) / 36e5;
2598
+ }
2599
+ function stepIntakeClock(state, nowMs, eligibleNew) {
2600
+ if (eligibleNew === 0 && !state.unservableSince) {
2601
+ return { ...state, unservableSince: new Date(nowMs).toISOString() };
2602
+ }
2603
+ if (eligibleNew > 0 && state.unservableSince) {
2604
+ return { ...state, frozenMs: frozenMsAt(state, nowMs), unservableSince: null };
2605
+ }
2606
+ return state;
2607
+ }
2608
+ function intakeReading(state, nowMs, counts, config = DEFAULT_REGULATOR_CONFIG.intake) {
2609
+ const hours = intakeHours(state, nowMs);
2610
+ const multiplier = counts.eligibleNew > 0 ? Math.pow(config.rate, hours / config.scaleHours) : 1;
2611
+ return {
2612
+ name: "intake",
2613
+ class: "new",
2614
+ urgency: hours,
2615
+ multiplier,
2616
+ applied: counts.eligibleNew,
2617
+ inputs: {
2618
+ hoursSinceNew: hours,
2619
+ frozenHours: frozenMsAt(state, nowMs) / 36e5,
2620
+ eligibleNew: counts.eligibleNew,
2621
+ newCandidates: counts.newCandidates
2622
+ }
2623
+ };
2624
+ }
2625
+ function applyReading(cards, reading) {
2626
+ if (reading.multiplier === 1) return;
2627
+ const reason = reading.name === "review-mass" ? `review mass ${reading.urgency.toFixed(1)} (healthy ${reading.inputs.healthyMass}) \u2192 \xD7${reading.multiplier.toFixed(2)}` : `${reading.urgency.toFixed(1)}h since a new card \u2192 \xD7${reading.multiplier.toFixed(2)}`;
2628
+ for (const card of cards) {
2629
+ card.score *= reading.multiplier;
2630
+ card.provenance.push({
2631
+ strategy: "regulator",
2632
+ strategyName: `Regulator: ${REGULATOR_LABEL[reading.name]}`,
2633
+ strategyId: `regulator-${reading.name}`,
2634
+ action: reading.multiplier > 1 ? "boosted" : "penalized",
2635
+ score: card.score,
2636
+ reason
2637
+ });
2638
+ }
2639
+ }
2640
+ var DEFAULT_REGULATOR_CONFIG, INTAKE_CLOCK_KEY, REGULATOR_LABEL;
2641
+ var init_regulators = __esm({
2642
+ "src/core/navigators/regulators.ts"() {
2643
+ "use strict";
2644
+ DEFAULT_REGULATOR_CONFIG = {
2645
+ reviewMass: { referenceScore: 0.95, healthyMass: 20, rate: 2 },
2646
+ intake: { rate: 2, scaleHours: 24 }
2647
+ };
2648
+ INTAKE_CLOCK_KEY = "IntakeClock";
2649
+ REGULATOR_LABEL = {
2650
+ "review-mass": "Review mass",
2651
+ intake: "Intake"
2652
+ };
2653
+ }
2654
+ });
2655
+
2540
2656
  // src/core/navigators/generators/srs.ts
2541
2657
  var srs_exports = {};
2542
2658
  __export(srs_exports, {
2543
2659
  default: () => SRSNavigator
2544
2660
  });
2545
2661
  import moment from "moment";
2546
- var DEFAULT_HEALTHY_BACKLOG, BACKLOG_GROWTH_RATE, SRSNavigator;
2662
+ var SRSNavigator;
2547
2663
  var init_srs = __esm({
2548
2664
  "src/core/navigators/generators/srs.ts"() {
2549
2665
  "use strict";
2550
2666
  init_navigators();
2551
2667
  init_SrsDebugger();
2668
+ init_regulators();
2552
2669
  init_logger();
2553
- DEFAULT_HEALTHY_BACKLOG = 20;
2554
- BACKLOG_GROWTH_RATE = 2;
2555
2670
  SRSNavigator = class extends ContentNavigator {
2556
2671
  /** Human-readable name for CardGenerator interface */
2557
2672
  name;
2558
- /** Healthy backlog threshold - when exceeded, backlog pressure kicks in */
2559
- healthyBacklog;
2560
2673
  constructor(user, course, strategyData) {
2561
2674
  super(user, course, strategyData);
2562
2675
  this.name = strategyData?.name || "SRS";
2563
- const config = this.parseConfig(strategyData?.serializedData);
2564
- this.healthyBacklog = config.healthyBacklog ?? DEFAULT_HEALTHY_BACKLOG;
2565
- }
2566
- /**
2567
- * Parse configuration from serialized JSON.
2568
- */
2569
- parseConfig(serializedData) {
2570
- if (!serializedData) return {};
2571
- try {
2572
- return JSON.parse(serializedData);
2573
- } catch {
2574
- logger.warn("[SRS] Failed to parse strategy config, using defaults");
2575
- return {};
2576
- }
2577
2676
  }
2578
2677
  /**
2579
2678
  * Get review cards scored by urgency.
@@ -2581,7 +2680,6 @@ var init_srs = __esm({
2581
2680
  * Score formula combines:
2582
2681
  * - Relative overdueness: hoursOverdue / intervalHours
2583
2682
  * - Interval recency: exponential decay favoring shorter intervals
2584
- * - Backlog pressure: boost when due reviews exceed healthy threshold
2585
2683
  *
2586
2684
  * Cards not yet due are excluded (not scored as 0).
2587
2685
  *
@@ -2618,7 +2716,6 @@ var init_srs = __esm({
2618
2716
  }
2619
2717
  }
2620
2718
  }
2621
- const backlogMultiplier = this.computeBacklogMultiplier(dueReviews.length);
2622
2719
  const notDue = reviews.filter((r) => !now.isAfter(moment.utc(r.reviewTime)));
2623
2720
  let nextDueIn = null;
2624
2721
  if (notDue.length > 0) {
@@ -2629,9 +2726,8 @@ var init_srs = __esm({
2629
2726
  nextDueIn = until.asHours() < 1 ? `${Math.round(until.asMinutes())}m` : until.asHours() < 24 ? `${Math.round(until.asHours())}h` : `${Math.round(until.asDays())}d`;
2630
2727
  }
2631
2728
  if (dueReviews.length > 0) {
2632
- const pressureNote = backlogMultiplier > 1 ? ` [backlog pressure: \xD7${backlogMultiplier.toFixed(2)}]` : ` [healthy backlog]`;
2633
2729
  logger.info(
2634
- `[SRS] Course ${courseId}: ${dueReviews.length} reviews due now (of ${reviews.length} scheduled)${pressureNote}`
2730
+ `[SRS] Course ${courseId}: ${dueReviews.length} reviews due now (of ${reviews.length} scheduled)`
2635
2731
  );
2636
2732
  } else if (reviews.length > 0) {
2637
2733
  const sortedByDue = [...reviews].sort(
@@ -2648,11 +2744,12 @@ var init_srs = __esm({
2648
2744
  logger.info(`[SRS] Course ${courseId}: No reviews scheduled`);
2649
2745
  }
2650
2746
  const scored = dueReviews.map((review) => {
2651
- const { score, reason } = this.computeUrgencyScore(review, now, backlogMultiplier);
2747
+ const { score, urgency, reason } = this.computeUrgencyScore(review, now);
2652
2748
  return {
2653
2749
  cardId: review.cardId,
2654
2750
  courseId: review.courseId,
2655
2751
  score,
2752
+ reviewUrgency: urgency,
2656
2753
  reviewID: review._id,
2657
2754
  provenance: [
2658
2755
  {
@@ -2671,47 +2768,20 @@ var init_srs = __esm({
2671
2768
  courseId,
2672
2769
  scheduledTotal: reviews.length,
2673
2770
  dueNow: dueReviews.length,
2674
- healthyBacklog: this.healthyBacklog,
2675
- backlogMultiplier,
2676
- backlogGrowthRate: BACKLOG_GROWTH_RATE,
2771
+ healthyBacklog: DEFAULT_REGULATOR_CONFIG.reviewMass.healthyMass,
2772
+ reviewMass: null,
2773
+ backlogMultiplier: 1,
2774
+ backlogGrowthRate: DEFAULT_REGULATOR_CONFIG.reviewMass.rate,
2677
2775
  topReviewScore: sorted.length > 0 ? sorted[0].score : null,
2678
2776
  nextDueIn,
2679
2777
  timestamp: Date.now()
2680
2778
  });
2681
2779
  return { cards: sorted.slice(0, limit) };
2682
2780
  }
2683
- /**
2684
- * Compute the multiplicative backlog pressure based on number of due reviews.
2685
- *
2686
- * ×1.0 at or below the healthy threshold (no boost); above it, grows as
2687
- * BACKLOG_GROWTH_RATE raised to the excess expressed in multiples of the
2688
- * healthy threshold. Uncapped — self-regulating instead: reviews winning
2689
- * slots depletes dueCount, which drops the ratio and relaxes the multiplier
2690
- * next run.
2691
- *
2692
- * Examples (with default healthyBacklog=20, BACKLOG_GROWTH_RATE=1.5):
2693
- * - 10 due reviews → ×1.00 (healthy)
2694
- * - 20 due reviews → ×1.00 (at threshold, ratio 0)
2695
- * - 40 due reviews → ×1.50 (ratio 1, 2x threshold)
2696
- * - 60 due reviews → ×2.25 (ratio 2, 3x threshold — old hard cap was ×2.00 here)
2697
- * - 100 due reviews → ×5.06 (ratio 4, 5x threshold)
2698
- * - 160 due reviews → ×17.09 (ratio 7, 8x threshold)
2699
- *
2700
- * @param dueCount - Number of reviews currently due
2701
- * @returns Multiplier applied to review urgency (>= 1.0, unbounded)
2702
- */
2703
- computeBacklogMultiplier(dueCount) {
2704
- if (dueCount <= this.healthyBacklog) {
2705
- return 1;
2706
- }
2707
- const excess = dueCount - this.healthyBacklog;
2708
- const ratio = excess / this.healthyBacklog;
2709
- return Math.pow(BACKLOG_GROWTH_RATE, ratio);
2710
- }
2711
2781
  /**
2712
2782
  * Compute urgency score for a review card.
2713
2783
  *
2714
- * Three factors:
2784
+ * Two factors:
2715
2785
  * 1. Relative overdueness = hoursOverdue / intervalHours
2716
2786
  * - 2 days overdue on 3-day interval = 0.67 (urgent)
2717
2787
  * - 2 days overdue on 180-day interval = 0.01 (not urgent)
@@ -2721,20 +2791,14 @@ var init_srs = __esm({
2721
2791
  * - 30 days (720h) → ~0.56
2722
2792
  * - 180 days → ~0.30
2723
2793
  *
2724
- * 3. Backlog pressure = global *multiplier* when review backlog exceeds the
2725
- * healthy threshold (×1.0 healthy → exponential growth, uncapped, above it).
2726
- *
2727
- * Combined: (base 0.5 + urgency factors * 0.45) × backlog multiplier.
2728
- * Per-card range before pressure: ~0.57–0.95. NOT clamped to 1.0 — under a
2729
- * heavy backlog reviews scale onto the open scale to compete with (and exceed)
2730
- * new cards; there's no ceiling at all now, so a bad enough backlog always
2731
- * wins eventually — self-regulating because winning slots depletes dueCount.
2794
+ * Combined: base 0.5 + urgency factors * 0.45, so ~0.57–0.95 per card.
2795
+ * Backlog pressure is applied later, by the regulator stage, which can lift
2796
+ * reviews onto the open scale above new cards (see regulators.ts).
2732
2797
  *
2733
2798
  * @param review - The scheduled card to score
2734
2799
  * @param now - Current time
2735
- * @param backlogMultiplier - Pre-computed backlog multiplier (>= 1.0, unbounded)
2736
2800
  */
2737
- computeUrgencyScore(review, now, backlogMultiplier) {
2801
+ computeUrgencyScore(review, now) {
2738
2802
  const scheduledAt = moment.utc(review.scheduledAt);
2739
2803
  const due = moment.utc(review.reviewTime);
2740
2804
  const intervalHours = Math.max(1, due.diff(scheduledAt, "hours"));
@@ -2743,20 +2807,16 @@ var init_srs = __esm({
2743
2807
  const recencyFactor = 0.3 + 0.7 * Math.exp(-intervalHours / 720);
2744
2808
  const overdueContribution = Math.min(1, Math.max(0, relativeOverdue));
2745
2809
  const urgency = overdueContribution * 0.5 + recencyFactor * 0.5;
2746
- const baseScore = 0.5 + urgency * 0.45;
2747
- const score = baseScore * backlogMultiplier;
2810
+ const score = 0.5 + urgency * 0.45;
2748
2811
  const reasonParts = [
2749
2812
  `${Math.round(hoursOverdue)}h overdue`,
2750
2813
  `interval: ${Math.round(intervalHours)}h`,
2751
2814
  `relative: ${relativeOverdue.toFixed(2)}`,
2752
2815
  `recency: ${recencyFactor.toFixed(2)}`
2753
2816
  ];
2754
- if (backlogMultiplier > 1) {
2755
- reasonParts.push(`backlog: \xD7${backlogMultiplier.toFixed(2)}`);
2756
- }
2757
2817
  reasonParts.push("review");
2758
2818
  const reason = reasonParts.join(", ");
2759
- return { score, reason };
2819
+ return { score, urgency, reason };
2760
2820
  }
2761
2821
  };
2762
2822
  }
@@ -2811,6 +2871,8 @@ var init_WeightedFilter = __esm({
2811
2871
  init_contentNavigationStrategy();
2812
2872
  WeightedFilter = class {
2813
2873
  name;
2874
+ kind;
2875
+ liveOnly;
2814
2876
  inner;
2815
2877
  learnable;
2816
2878
  staticWeight;
@@ -2818,6 +2880,8 @@ var init_WeightedFilter = __esm({
2818
2880
  constructor(inner, learnable = DEFAULT_LEARNABLE_WEIGHT, staticWeight = false, strategyId) {
2819
2881
  this.inner = inner;
2820
2882
  this.name = inner.name;
2883
+ this.kind = inner.kind;
2884
+ this.liveOnly = inner.liveOnly;
2821
2885
  this.learnable = learnable;
2822
2886
  this.staticWeight = staticWeight;
2823
2887
  this.strategyId = strategyId;
@@ -2882,58 +2946,175 @@ var init_WeightedFilter = __esm({
2882
2946
  // src/core/navigators/filters/eloDistance.ts
2883
2947
  var eloDistance_exports = {};
2884
2948
  __export(eloDistance_exports, {
2885
- DEFAULT_HALF_LIFE: () => DEFAULT_HALF_LIFE,
2886
- DEFAULT_MAX_MULTIPLIER: () => DEFAULT_MAX_MULTIPLIER,
2887
- DEFAULT_MIN_MULTIPLIER: () => DEFAULT_MIN_MULTIPLIER,
2888
- createEloDistanceFilter: () => createEloDistanceFilter
2949
+ DEFAULT_ELO_DISTANCE_CONFIG: () => DEFAULT_ELO_DISTANCE_CONFIG,
2950
+ createEloDistanceFilter: () => createEloDistanceFilter,
2951
+ default: () => EloDistanceFilter,
2952
+ mountMultiDimEloToggle: () => mountMultiDimEloToggle,
2953
+ tagAwareGap: () => tagAwareGap
2889
2954
  });
2890
2955
  function computeMultiplier(distance, halfLife, minMultiplier, maxMultiplier) {
2891
2956
  const normalizedDistance = distance / halfLife;
2892
2957
  const decay = Math.exp(-(normalizedDistance * normalizedDistance));
2893
2958
  return minMultiplier + (maxMultiplier - minMultiplier) * decay;
2894
2959
  }
2960
+ function resolveConfig(config) {
2961
+ return { ...DEFAULT_ELO_DISTANCE_CONFIG, ...config };
2962
+ }
2963
+ function readMultiDimElo() {
2964
+ try {
2965
+ return typeof localStorage !== "undefined" && localStorage.getItem(MULTI_DIM_ELO_KEY) === "true";
2966
+ } catch {
2967
+ return false;
2968
+ }
2969
+ }
2970
+ function mountMultiDimEloToggle() {
2971
+ if (typeof window === "undefined") return;
2972
+ const win = window;
2973
+ win.skuilder = win.skuilder || {};
2974
+ Object.defineProperty(win.skuilder, "multiDimElo", {
2975
+ configurable: true,
2976
+ enumerable: true,
2977
+ get: () => multiDimElo,
2978
+ set: (on) => {
2979
+ multiDimElo = on === true;
2980
+ try {
2981
+ if (multiDimElo) localStorage.setItem(MULTI_DIM_ELO_KEY, "true");
2982
+ else localStorage.removeItem(MULTI_DIM_ELO_KEY);
2983
+ } catch (e) {
2984
+ logger.warn(`[EloDistance] multiDimElo not persisted (localStorage unavailable): ${e}`);
2985
+ }
2986
+ logger.info(
2987
+ `[EloDistance] multiDimElo ${multiDimElo ? "on: tag-aware" : "off: per strategy config"} ELO distance from the next replan`
2988
+ );
2989
+ }
2990
+ });
2991
+ }
2992
+ function tagAwareGap(cardTags, cardElo, userElo, minTagCount) {
2993
+ const globalGap = cardElo.global.score - userElo.global.score;
2994
+ const tags = [];
2995
+ for (const tag of cardTags) {
2996
+ const user = userElo.tags[tag];
2997
+ if (!user || user.score === COUNT_ONLY_SENTINEL || user.count < minTagCount) continue;
2998
+ const card = cardElo.tags[tag]?.score ?? cardElo.global.score;
2999
+ tags.push({
3000
+ tag,
3001
+ gap: card - user.score,
3002
+ weight: user.count / (user.count + TAG_CONFIDENCE_HALF)
3003
+ });
3004
+ }
3005
+ if (tags.length === 0) return { gap: globalGap, globalGap, tags };
3006
+ const total = tags.reduce((w, t) => w + t.weight, 0);
3007
+ const tagGap = tags.reduce((g, t) => g + t.weight * t.gap, 0) / total;
3008
+ const lambda = total / (total + 1);
3009
+ return { gap: lambda * tagGap + (1 - lambda) * globalGap, globalGap, tags };
3010
+ }
3011
+ function tagReason(tags, globalGap) {
3012
+ const shown = [...tags].sort((a, b) => Math.abs(b.gap) * b.weight - Math.abs(a.gap) * a.weight).slice(0, 3).map((t) => `${t.tag} ${t.gap >= 0 ? "+" : ""}${Math.round(t.gap)}`).join(", ");
3013
+ const more = tags.length > 3 ? `, +${tags.length - 3} more` : "";
3014
+ return ` on ${tags.length} shared tag(s) [${shown}${more}] (global ${globalGap >= 0 ? "+" : ""}${Math.round(globalGap)})`;
3015
+ }
3016
+ async function applyEloDistance(cards, context, config, source) {
3017
+ const { course, userElo, userCourseElo } = context;
3018
+ const { halfLife, minMultiplier, maxMultiplier } = config;
3019
+ const tagAware = (config.tagAware || multiDimElo) && userCourseElo !== void 0;
3020
+ const missing = cards.filter((c) => tagAware || c.cardElo === void 0).map((c) => c.cardId);
3021
+ const fetched = /* @__PURE__ */ new Map();
3022
+ if (missing.length > 0) {
3023
+ const elos = await course.getCardEloData(missing);
3024
+ missing.forEach((id, i) => {
3025
+ if (elos[i]) fetched.set(id, elos[i]);
3026
+ });
3027
+ }
3028
+ return cards.map((card) => {
3029
+ const full = fetched.get(card.cardId);
3030
+ const cardElo = full?.global?.score ?? card.cardElo ?? DEFAULT_CARD_ELO;
3031
+ let distance = Math.abs(cardElo - userElo);
3032
+ let how = "";
3033
+ if (tagAware) {
3034
+ const t = full ? tagAwareGap(card.tags ?? [], full, userCourseElo, config.minTagCount) : void 0;
3035
+ if (t) distance = Math.abs(t.gap);
3036
+ how = t?.tags.length ? `, tag-aware${tagReason(t.tags, t.globalGap)}` : ", tag-aware: global (no shared tags)";
3037
+ }
3038
+ const multiplier = computeMultiplier(distance, halfLife, minMultiplier, maxMultiplier);
3039
+ const newScore = card.score * multiplier;
3040
+ const action = multiplier < maxMultiplier - 0.01 ? "penalized" : "passed";
3041
+ return {
3042
+ ...card,
3043
+ cardElo,
3044
+ score: newScore,
3045
+ provenance: [
3046
+ ...card.provenance,
3047
+ {
3048
+ strategy: "eloDistance",
3049
+ strategyName: source.name,
3050
+ strategyId: source.strategyId,
3051
+ action,
3052
+ score: newScore,
3053
+ reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userElo)})${how} \u2192 ${multiplier.toFixed(2)}x`
3054
+ }
3055
+ ]
3056
+ };
3057
+ });
3058
+ }
2895
3059
  function createEloDistanceFilter(config) {
2896
- const halfLife = config?.halfLife ?? DEFAULT_HALF_LIFE;
2897
- const minMultiplier = config?.minMultiplier ?? DEFAULT_MIN_MULTIPLIER;
2898
- const maxMultiplier = config?.maxMultiplier ?? DEFAULT_MAX_MULTIPLIER;
3060
+ const resolved = resolveConfig(config);
3061
+ const source = { name: "ELO Distance Filter", strategyId: "ELO_DISTANCE_FILTER" };
2899
3062
  return {
2900
- name: "ELO Distance Filter",
2901
- async transform(cards, context) {
2902
- const { course, userElo } = context;
2903
- const cardIds = cards.map((c) => c.cardId);
2904
- const cardElos = await course.getCardEloData(cardIds);
2905
- return cards.map((card, i) => {
2906
- const cardElo = cardElos[i]?.global?.score ?? 1e3;
2907
- const distance = Math.abs(cardElo - userElo);
2908
- const multiplier = computeMultiplier(distance, halfLife, minMultiplier, maxMultiplier);
2909
- const newScore = card.score * multiplier;
2910
- const action = multiplier < maxMultiplier - 0.01 ? "penalized" : "passed";
2911
- return {
2912
- ...card,
2913
- score: newScore,
2914
- provenance: [
2915
- ...card.provenance,
2916
- {
2917
- strategy: "eloDistance",
2918
- strategyName: "ELO Distance Filter",
2919
- strategyId: "ELO_DISTANCE_FILTER",
2920
- action,
2921
- score: newScore,
2922
- reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userElo)}) \u2192 ${multiplier.toFixed(2)}x`
2923
- }
2924
- ]
2925
- };
2926
- });
2927
- }
3063
+ name: source.name,
3064
+ kind: "signal",
3065
+ liveOnly: true,
3066
+ transform: (cards, context) => applyEloDistance(cards, context, resolved, source)
2928
3067
  };
2929
3068
  }
2930
- var DEFAULT_HALF_LIFE, DEFAULT_MIN_MULTIPLIER, DEFAULT_MAX_MULTIPLIER;
3069
+ var DEFAULT_ELO_DISTANCE_CONFIG, TAG_CONFIDENCE_HALF, COUNT_ONLY_SENTINEL, DEFAULT_CARD_ELO, MULTI_DIM_ELO_KEY, multiDimElo, EloDistanceFilter;
2931
3070
  var init_eloDistance = __esm({
2932
3071
  "src/core/navigators/filters/eloDistance.ts"() {
2933
3072
  "use strict";
2934
- DEFAULT_HALF_LIFE = 200;
2935
- DEFAULT_MIN_MULTIPLIER = 0.3;
2936
- DEFAULT_MAX_MULTIPLIER = 1;
3073
+ init_navigators();
3074
+ init_logger();
3075
+ DEFAULT_ELO_DISTANCE_CONFIG = {
3076
+ halfLife: 300,
3077
+ minMultiplier: 0.05,
3078
+ maxMultiplier: 1,
3079
+ tagAware: false,
3080
+ minTagCount: 3
3081
+ };
3082
+ TAG_CONFIDENCE_HALF = 10;
3083
+ COUNT_ONLY_SENTINEL = -1;
3084
+ DEFAULT_CARD_ELO = 1e3;
3085
+ MULTI_DIM_ELO_KEY = "skuilder:multiDimElo";
3086
+ multiDimElo = readMultiDimElo();
3087
+ mountMultiDimEloToggle();
3088
+ EloDistanceFilter = class _EloDistanceFilter extends ContentNavigator {
3089
+ name;
3090
+ /** See CardFilter.kind. Static, so the pipeline plan can read it without an instance. */
3091
+ static kind = "signal";
3092
+ kind = _EloDistanceFilter.kind;
3093
+ liveOnly = true;
3094
+ config;
3095
+ constructor(user, course, strategyData) {
3096
+ super(user, course, strategyData);
3097
+ this.name = strategyData.name || "ELO Distance";
3098
+ let parsed;
3099
+ try {
3100
+ parsed = strategyData.serializedData ? JSON.parse(strategyData.serializedData) : void 0;
3101
+ } catch {
3102
+ parsed = void 0;
3103
+ }
3104
+ this.config = resolveConfig(parsed);
3105
+ }
3106
+ transform(cards, context) {
3107
+ return applyEloDistance(cards, context, this.config, {
3108
+ name: this.name,
3109
+ strategyId: this.strategyId || "NAVIGATION_STRATEGY-eloDistance-default"
3110
+ });
3111
+ }
3112
+ async getWeightedCards(_limit) {
3113
+ throw new Error(
3114
+ "EloDistanceFilter is a filter and should not be used as a generator. Use Pipeline with a generator and this filter via transform()."
3115
+ );
3116
+ }
3117
+ };
2937
3118
  }
2938
3119
  });
2939
3120
 
@@ -2950,10 +3131,13 @@ var init_hierarchyDefinition = __esm({
2950
3131
  init_navigators();
2951
3132
  init_logger();
2952
3133
  DEFAULT_MIN_COUNT2 = 3;
2953
- HierarchyDefinitionNavigator = class extends ContentNavigator {
3134
+ HierarchyDefinitionNavigator = class _HierarchyDefinitionNavigator extends ContentNavigator {
2954
3135
  config;
2955
3136
  /** Human-readable name for CardFilter interface */
2956
3137
  name;
3138
+ /** See CardFilter.kind. Static, so the pipeline plan can read it without an instance. */
3139
+ static kind = "gate";
3140
+ kind = _HierarchyDefinitionNavigator.kind;
2957
3141
  constructor(user, course, strategyData) {
2958
3142
  super(user, course, strategyData);
2959
3143
  this.config = this.parseConfig(strategyData.serializedData);
@@ -3220,10 +3404,13 @@ var init_userTagPreference = __esm({
3220
3404
  "src/core/navigators/filters/userTagPreference.ts"() {
3221
3405
  "use strict";
3222
3406
  init_navigators();
3223
- UserTagPreferenceFilter = class extends ContentNavigator {
3407
+ UserTagPreferenceFilter = class _UserTagPreferenceFilter extends ContentNavigator {
3224
3408
  _strategyData;
3225
3409
  /** Human-readable name for CardFilter interface */
3226
3410
  name;
3411
+ /** See CardFilter.kind. Static, so the pipeline plan can read it without an instance. */
3412
+ static kind = "signal";
3413
+ kind = _UserTagPreferenceFilter.kind;
3227
3414
  constructor(user, course, strategyData) {
3228
3415
  super(user, course, strategyData);
3229
3416
  this._strategyData = strategyData;
@@ -3333,6 +3520,7 @@ var init_userTagPreference = __esm({
3333
3520
  // src/core/navigators/filters/index.ts
3334
3521
  var filters_exports = {};
3335
3522
  __export(filters_exports, {
3523
+ EloDistanceFilter: () => EloDistanceFilter,
3336
3524
  UserTagPreferenceFilter: () => UserTagPreferenceFilter,
3337
3525
  createEloDistanceFilter: () => createEloDistanceFilter
3338
3526
  });
@@ -3371,10 +3559,13 @@ var init_interferenceMitigator = __esm({
3371
3559
  DEFAULT_MIN_COUNT3 = 10;
3372
3560
  DEFAULT_MIN_ELAPSED_DAYS = 3;
3373
3561
  DEFAULT_INTERFERENCE_DECAY = 0.8;
3374
- InterferenceMitigatorNavigator = class extends ContentNavigator {
3562
+ InterferenceMitigatorNavigator = class _InterferenceMitigatorNavigator extends ContentNavigator {
3375
3563
  config;
3376
3564
  /** Human-readable name for CardFilter interface */
3377
3565
  name;
3566
+ /** See CardFilter.kind. Static, so the pipeline plan can read it without an instance. */
3567
+ static kind = "signal";
3568
+ kind = _InterferenceMitigatorNavigator.kind;
3378
3569
  /** Precomputed map: tag -> set of { partner, decay } it interferes with */
3379
3570
  interferenceMap;
3380
3571
  constructor(user, course, strategyData) {
@@ -3590,10 +3781,13 @@ var init_relativePriority = __esm({
3590
3781
  DEFAULT_PRIORITY = 0.5;
3591
3782
  DEFAULT_PRIORITY_INFLUENCE = 0.5;
3592
3783
  DEFAULT_COMBINE_MODE = "max";
3593
- RelativePriorityNavigator = class extends ContentNavigator {
3784
+ RelativePriorityNavigator = class _RelativePriorityNavigator extends ContentNavigator {
3594
3785
  config;
3595
3786
  /** Human-readable name for CardFilter interface */
3596
3787
  name;
3788
+ /** See CardFilter.kind. Static, so the pipeline plan can read it without an instance. */
3789
+ static kind = "signal";
3790
+ kind = _RelativePriorityNavigator.kind;
3597
3791
  constructor(user, course, strategyData) {
3598
3792
  super(user, course, strategyData);
3599
3793
  this.config = this.parseConfig(strategyData.serializedData);
@@ -4001,6 +4195,8 @@ var init_Pipeline = __esm({
4001
4195
  init_orchestration();
4002
4196
  init_PipelineDebugger();
4003
4197
  init_diversityRerank();
4198
+ init_regulators();
4199
+ init_SrsDebugger();
4004
4200
  VERBOSE_RESULTS = true;
4005
4201
  Pipeline = class extends ContentNavigator {
4006
4202
  generator;
@@ -4026,6 +4222,13 @@ var init_Pipeline = __esm({
4026
4222
  * getWeightedCards() call, then cleared.
4027
4223
  */
4028
4224
  _ephemeralHints = null;
4225
+ /**
4226
+ * The intake valve's clock (see regulators.ts), loaded from strategy state on
4227
+ * first use and kept in memory. Writes are chained so a presentation and a
4228
+ * run can't race each other's revision.
4229
+ */
4230
+ _intakeClock = null;
4231
+ _intakeClockWrite = Promise.resolve();
4029
4232
  /**
4030
4233
  * Create a new pipeline.
4031
4234
  *
@@ -4100,13 +4303,12 @@ var init_Pipeline = __esm({
4100
4303
  }
4101
4304
  }
4102
4305
  generatorSummaries = Array.from(genMap.entries()).map(([name, data]) => {
4103
- const newCards = data.cards.filter((c) => c.provenance[0]?.reason?.includes("new card"));
4104
- const reviewCards = data.cards.filter((c) => c.provenance[0]?.reason?.includes("review"));
4306
+ const reviewCount = data.cards.filter((c) => c.reviewID).length;
4105
4307
  return {
4106
4308
  name,
4107
4309
  cardCount: data.cards.length,
4108
- newCount: newCards.length,
4109
- reviewCount: reviewCards.length,
4310
+ newCount: data.cards.length - reviewCount,
4311
+ reviewCount,
4110
4312
  topScore: Math.max(...data.cards.map((c) => c.score), 0)
4111
4313
  };
4112
4314
  });
@@ -4142,19 +4344,24 @@ var init_Pipeline = __esm({
4142
4344
  cards.filter((c) => c.provenance.some((p) => p.strategy === "prescribed")).map((c) => c.cardId)
4143
4345
  );
4144
4346
  const filterImpacts = [];
4347
+ const generatedScores = new Map(cards.map((c) => [c.cardId, c.score]));
4348
+ const gated = /* @__PURE__ */ new Set();
4145
4349
  for (const filter of this.filters) {
4146
4350
  const beforeCount = cards.length;
4147
4351
  const beforeScores = new Map(cards.map((c) => [c.cardId, c.score]));
4148
4352
  cards = await filter.transform(cards, context);
4149
4353
  let boosted = 0, penalized = 0, passed = 0;
4150
4354
  const removed = beforeCount - cards.length;
4355
+ const kind = filter.kind ?? "gate";
4151
4356
  for (const card of cards) {
4152
4357
  const before = beforeScores.get(card.cardId) ?? 0;
4153
4358
  if (card.score > before) boosted++;
4154
- else if (card.score < before) penalized++;
4155
- else passed++;
4359
+ else if (card.score < before) {
4360
+ penalized++;
4361
+ if (kind === "gate") gated.add(card.cardId);
4362
+ } else passed++;
4156
4363
  }
4157
- filterImpacts.push({ name: filter.name, boosted, penalized, passed, removed });
4364
+ filterImpacts.push({ name: filter.name, kind, boosted, penalized, passed, removed });
4158
4365
  if (prescribedIds.size > 0) {
4159
4366
  const survivingIds = new Set(cards.map((c) => c.cardId));
4160
4367
  const killedPrescribed = [...prescribedIds].filter((id) => !survivingIds.has(id));
@@ -4170,6 +4377,7 @@ var init_Pipeline = __esm({
4170
4377
  }
4171
4378
  const scoredCards = cards;
4172
4379
  cards = cards.filter((c) => c.score > 0);
4380
+ const regulators = await this.regulate(cards, generatedScores, gated);
4173
4381
  const hints = this._ephemeralHints;
4174
4382
  if (hints) {
4175
4383
  this._ephemeralHints = null;
@@ -4206,7 +4414,8 @@ var init_Pipeline = __esm({
4206
4414
  result,
4207
4415
  context.userElo,
4208
4416
  hints ?? void 0,
4209
- scoredCards
4417
+ scoredCards,
4418
+ regulators
4210
4419
  );
4211
4420
  captureRun(report);
4212
4421
  } catch (e) {
@@ -4385,6 +4594,77 @@ var init_Pipeline = __esm({
4385
4594
  logger.info(`[Pipeline] Hints applied: ${beforeCount} \u2192 ${cards.length} cards`);
4386
4595
  return cards;
4387
4596
  }
4597
+ /**
4598
+ * The regulator stage: measure each class's pressure and scale it.
4599
+ *
4600
+ * - Review mass: every due review's SRS urgency times the filters' net
4601
+ * effect on it.
4602
+ * - Intake: servable hours since a new card was presented, applied only to
4603
+ * eligible new cards (no gate penalized them). With none eligible, the
4604
+ * clock freezes.
4605
+ *
4606
+ * Mutates `cards` in place; returns the readings for the run report.
4607
+ */
4608
+ async regulate(cards, generatedScores, gated) {
4609
+ const config = DEFAULT_REGULATOR_CONFIG;
4610
+ const reviews = cards.filter((c) => c.reviewID);
4611
+ const newCards = cards.filter((c) => !c.reviewID);
4612
+ const eligibleNew = newCards.filter((c) => !gated.has(c.cardId));
4613
+ const mass = reviewMassReading(reviews, generatedScores, config.reviewMass);
4614
+ applyReading(reviews, mass);
4615
+ noteReviewPressure(this.course.getCourseID(), {
4616
+ mass: mass.urgency,
4617
+ healthyMass: config.reviewMass.healthyMass,
4618
+ rate: config.reviewMass.rate,
4619
+ multiplier: mass.multiplier
4620
+ });
4621
+ const now = Date.now();
4622
+ const clock = await this.loadIntakeClock(now);
4623
+ const stepped = stepIntakeClock(clock, now, eligibleNew.length);
4624
+ if (stepped !== clock) this.saveIntakeClock(stepped);
4625
+ const intake = intakeReading(
4626
+ stepped,
4627
+ now,
4628
+ { eligibleNew: eligibleNew.length, newCandidates: newCards.length },
4629
+ config.intake
4630
+ );
4631
+ applyReading(eligibleNew, intake);
4632
+ logger.info(
4633
+ `[Pipeline:regulators] review mass ${mass.urgency.toFixed(1)} over ${reviews.length} due \u2192 \xD7${mass.multiplier.toFixed(2)}; intake ${intake.urgency.toFixed(1)}h, ${eligibleNew.length}/${newCards.length} new eligible \u2192 \xD7${intake.multiplier.toFixed(2)}`
4634
+ );
4635
+ return [mass, intake];
4636
+ }
4637
+ /**
4638
+ * A card was presented. A new card's first presentation discharges the
4639
+ * intake valve: its clock restarts. Called by the SessionController.
4640
+ */
4641
+ notePresented(card) {
4642
+ if (card.status !== "new" || card.courseId !== this.course?.getCourseID()) return;
4643
+ this.saveIntakeClock(resetIntakeClock(Date.now()));
4644
+ }
4645
+ async loadIntakeClock(nowMs) {
4646
+ if (this._intakeClock) return this._intakeClock;
4647
+ let stored = null;
4648
+ try {
4649
+ stored = await this.user.getStrategyState(
4650
+ this.course.getCourseID(),
4651
+ INTAKE_CLOCK_KEY
4652
+ );
4653
+ } catch (e) {
4654
+ logger.warn(`[Pipeline:regulators] Could not read the intake clock: ${e}`);
4655
+ }
4656
+ if (stored) {
4657
+ this._intakeClock = stored;
4658
+ } else {
4659
+ this.saveIntakeClock(resetIntakeClock(nowMs));
4660
+ }
4661
+ return this._intakeClock;
4662
+ }
4663
+ saveIntakeClock(state) {
4664
+ this._intakeClock = state;
4665
+ const courseId = this.course.getCourseID();
4666
+ this._intakeClockWrite = this._intakeClockWrite.then(() => this.user.putStrategyState(courseId, INTAKE_CLOCK_KEY, state)).catch((e) => logger.warn(`[Pipeline:regulators] Could not save the intake clock: ${e}`));
4667
+ }
4388
4668
  /**
4389
4669
  * Build shared context for generator and filters.
4390
4670
  *
@@ -4395,10 +4675,11 @@ var init_Pipeline = __esm({
4395
4675
  */
4396
4676
  async buildContext() {
4397
4677
  let userElo = 1e3;
4678
+ let userCourseElo;
4398
4679
  try {
4399
4680
  const courseReg = await this.user.getCourseRegDoc(this.course.getCourseID());
4400
- const courseElo = toCourseElo5(courseReg.elo);
4401
- userElo = courseElo.global.score;
4681
+ userCourseElo = toCourseElo5(courseReg.elo);
4682
+ userElo = userCourseElo.global.score;
4402
4683
  } catch (e) {
4403
4684
  logger.debug(`[Pipeline] Could not get user ELO, using default: ${e}`);
4404
4685
  }
@@ -4410,6 +4691,7 @@ var init_Pipeline = __esm({
4410
4691
  user: this.user,
4411
4692
  course: this.course,
4412
4693
  userElo,
4694
+ ...userCourseElo ? { userCourseElo } : {},
4413
4695
  orchestration
4414
4696
  };
4415
4697
  }
@@ -4523,7 +4805,7 @@ var init_Pipeline = __esm({
4523
4805
  cards = await this.hydrateTags(cards);
4524
4806
  const fullPool = cards.slice();
4525
4807
  const context = await this.buildContext();
4526
- for (const filter of this.filters) {
4808
+ for (const filter of this.forecastFilters()) {
4527
4809
  cards = await filter.transform(cards, context);
4528
4810
  }
4529
4811
  if (opts?.hints) {
@@ -4542,6 +4824,14 @@ var init_Pipeline = __esm({
4542
4824
  cards.sort((a, b) => b.score - a.score);
4543
4825
  return opts?.limit ? cards.slice(0, opts.limit) : cards;
4544
4826
  }
4827
+ /**
4828
+ * The filters a forecast or card-space scan applies. Those start every card at
4829
+ * 1.0 without a generator, so they skip `liveOnly` filters (ELO distance),
4830
+ * which only make sense against generator scores.
4831
+ */
4832
+ forecastFilters() {
4833
+ return this.filters.filter((f) => !f.liveOnly);
4834
+ }
4545
4835
  /**
4546
4836
  * Scan every card in the course through the filter chain and report
4547
4837
  * how many are "well indicated" (score >= threshold) for the current user.
@@ -4563,7 +4853,7 @@ var init_Pipeline = __esm({
4563
4853
  cards = await this.hydrateTags(cards);
4564
4854
  const context = await this.buildContext();
4565
4855
  const filterBreakdown = [];
4566
- for (const filter of this.filters) {
4856
+ for (const filter of this.forecastFilters()) {
4567
4857
  cards = await filter.transform(cards, context);
4568
4858
  const wi = cards.filter((c) => c.score >= THRESHOLD).length;
4569
4859
  filterBreakdown.push({ name: filter.name, wellIndicated: wi });
@@ -4627,6 +4917,7 @@ var init_Pipeline = __esm({
4627
4917
  // src/core/navigators/defaults.ts
4628
4918
  var defaults_exports = {};
4629
4919
  __export(defaults_exports, {
4920
+ createDefaultEloDistanceStrategy: () => createDefaultEloDistanceStrategy,
4630
4921
  createDefaultEloStrategy: () => createDefaultEloStrategy,
4631
4922
  createDefaultPipeline: () => createDefaultPipeline,
4632
4923
  createDefaultSrsStrategy: () => createDefaultSrsStrategy
@@ -4653,12 +4944,28 @@ function createDefaultSrsStrategy(courseId) {
4653
4944
  serializedData: ""
4654
4945
  };
4655
4946
  }
4947
+ function createDefaultEloDistanceStrategy(courseId) {
4948
+ return {
4949
+ _id: "NAVIGATION_STRATEGY-eloDistance-default",
4950
+ docType: "NAVIGATION_STRATEGY" /* NAVIGATION_STRATEGY */,
4951
+ name: "ELO Distance (default)",
4952
+ description: "Scales every candidate, new or review, by its distance from the learner's ELO",
4953
+ implementingClass: "eloDistance" /* ELO_DISTANCE */,
4954
+ course: courseId,
4955
+ // Explicit, though the filter would default to it anyway: views show what runs.
4956
+ serializedData: JSON.stringify(DEFAULT_ELO_DISTANCE_CONFIG)
4957
+ };
4958
+ }
4656
4959
  function createDefaultPipeline(user, course) {
4657
4960
  const courseId = course.getCourseID();
4658
4961
  const eloNavigator = new ELONavigator(user, course, createDefaultEloStrategy(courseId));
4659
4962
  const srsNavigator = new SRSNavigator(user, course, createDefaultSrsStrategy(courseId));
4660
4963
  const compositeGenerator = new CompositeGenerator([eloNavigator, srsNavigator]);
4661
- const eloDistanceFilter = createEloDistanceFilter();
4964
+ const eloDistanceFilter = new EloDistanceFilter(
4965
+ user,
4966
+ course,
4967
+ createDefaultEloDistanceStrategy(courseId)
4968
+ );
4662
4969
  return new Pipeline(compositeGenerator, [eloDistanceFilter], user, course);
4663
4970
  }
4664
4971
  var init_defaults = __esm({
@@ -4674,6 +4981,131 @@ var init_defaults = __esm({
4674
4981
  }
4675
4982
  });
4676
4983
 
4984
+ // src/core/navigators/pipelinePlan.ts
4985
+ var pipelinePlan_exports = {};
4986
+ __export(pipelinePlan_exports, {
4987
+ PIPELINE_STAGES: () => PIPELINE_STAGES,
4988
+ planPipeline: () => planPipeline
4989
+ });
4990
+ function planned(strategy, role, origin) {
4991
+ const kind = role === "filter" /* FILTER */ ? getRegisteredFilterKind(strategy.implementingClass) : void 0;
4992
+ return {
4993
+ role,
4994
+ origin,
4995
+ name: strategy.name,
4996
+ implementingClass: strategy.implementingClass,
4997
+ strategy,
4998
+ ...kind ? { kind } : {}
4999
+ };
5000
+ }
5001
+ function planPipeline(strategies, courseId) {
5002
+ if (strategies.length === 0) {
5003
+ return {
5004
+ kind: "default",
5005
+ generators: [
5006
+ planned(createDefaultEloStrategy(courseId), "generator" /* GENERATOR */, "default-pipeline"),
5007
+ planned(createDefaultSrsStrategy(courseId), "generator" /* GENERATOR */, "default-pipeline")
5008
+ ],
5009
+ filters: [
5010
+ planned(
5011
+ createDefaultEloDistanceStrategy(courseId),
5012
+ "filter" /* FILTER */,
5013
+ "default-pipeline"
5014
+ )
5015
+ ],
5016
+ skipped: [],
5017
+ warnings: [],
5018
+ notes: [],
5019
+ regulators: DEFAULT_REGULATOR_CONFIG
5020
+ };
5021
+ }
5022
+ const generators = [];
5023
+ const filters = [];
5024
+ const skipped = [];
5025
+ const warnings = [];
5026
+ for (const s of strategies) {
5027
+ if (isGenerator(s.implementingClass)) {
5028
+ generators.push(planned(s, "generator" /* GENERATOR */, "strategy-doc"));
5029
+ } else if (isFilter(s.implementingClass)) {
5030
+ filters.push(planned(s, "filter" /* FILTER */, "strategy-doc"));
5031
+ } else {
5032
+ skipped.push({ strategy: s, reason: "not a registered generator or filter" });
5033
+ warnings.push(`Unknown strategy type '${s.implementingClass}', skipping: ${s.name}`);
5034
+ }
5035
+ }
5036
+ const declared = new Set(generators.map((g) => g.implementingClass));
5037
+ if (!declared.has(createDefaultEloStrategy(courseId).implementingClass)) {
5038
+ generators.push(
5039
+ planned(createDefaultEloStrategy(courseId), "generator" /* GENERATOR */, "assembler-default")
5040
+ );
5041
+ }
5042
+ if (!declared.has(createDefaultSrsStrategy(courseId).implementingClass)) {
5043
+ generators.push(
5044
+ planned(createDefaultSrsStrategy(courseId), "generator" /* GENERATOR */, "assembler-default")
5045
+ );
5046
+ }
5047
+ const eloDistance = createDefaultEloDistanceStrategy(courseId);
5048
+ if (!filters.some((f) => f.implementingClass === eloDistance.implementingClass)) {
5049
+ filters.push(planned(eloDistance, "filter" /* FILTER */, "assembler-default"));
5050
+ }
5051
+ filters.sort((a, b) => a.name.localeCompare(b.name));
5052
+ return {
5053
+ kind: "assembled",
5054
+ generators,
5055
+ filters,
5056
+ skipped,
5057
+ warnings,
5058
+ notes: [],
5059
+ regulators: DEFAULT_REGULATOR_CONFIG
5060
+ };
5061
+ }
5062
+ var PIPELINE_STAGES;
5063
+ var init_pipelinePlan = __esm({
5064
+ "src/core/navigators/pipelinePlan.ts"() {
5065
+ "use strict";
5066
+ init_navigators();
5067
+ init_regulators();
5068
+ init_defaults();
5069
+ PIPELINE_STAGES = [
5070
+ {
5071
+ key: "generate",
5072
+ title: "Generate",
5073
+ summary: "Each generator proposes candidates (up to 500 in all), scored on what is specific to its source. A card proposed by several generators keeps their mean score, raised 10% per extra generator."
5074
+ },
5075
+ {
5076
+ key: "filter",
5077
+ title: "Filter",
5078
+ summary: "Each filter multiplies candidate scores, in the order shown. A gate says a card is not ready yet; a signal expresses preference. Gates usually penalize rather than remove, so a gated card stays in the pool at a low score."
5079
+ },
5080
+ {
5081
+ key: "drop-zero",
5082
+ title: "Drop zero scores",
5083
+ summary: "Candidates whose score reached 0 leave the pool."
5084
+ },
5085
+ {
5086
+ key: "regulate",
5087
+ title: "Regulate",
5088
+ summary: "Balances reviews against new cards. Review mass: the due reviews weighed by their filtered scores; above a healthy level, every review is lifted. Intake: hours since a new card was last presented; new cards no gate penalized are lifted, and the clock stops while there are none."
5089
+ },
5090
+ {
5091
+ key: "hints",
5092
+ title: "Apply hints",
5093
+ summary: "The session's hints (from the app: an intro's follow-up, a difficulty boost) exclude, boost, or require cards. Required cards skip the filters entirely."
5094
+ },
5095
+ {
5096
+ key: "diversity",
5097
+ title: "Diversity re-rank",
5098
+ summary: "Demotes candidates that repeat a distinctive tag already ranked above them, so one concept or answer cannot take the whole head of the queue. Sees this run only, not what the session already served."
5099
+ },
5100
+ {
5101
+ key: "select",
5102
+ title: "Select",
5103
+ summary: "Highest scores first, up to the run's limit. The session mixes them into its supply queue."
5104
+ }
5105
+ ];
5106
+ }
5107
+ });
5108
+
4677
5109
  // src/core/navigators/PipelineAssembler.ts
4678
5110
  var PipelineAssembler_exports = {};
4679
5111
  __export(PipelineAssembler_exports, {
@@ -4688,16 +5120,16 @@ var init_PipelineAssembler = __esm({
4688
5120
  init_Pipeline();
4689
5121
  init_logger();
4690
5122
  init_CompositeGenerator();
4691
- init_defaults();
5123
+ init_pipelinePlan();
4692
5124
  PipelineAssembler = class {
4693
5125
  /**
4694
5126
  * Assembles a navigation pipeline from strategy documents.
4695
5127
  *
4696
- * 1. Separates into generators and filters by role
4697
- * 2. Validates at least one generator exists (or creates default ELO)
4698
- * 3. Instantiates generators - wraps multiple in CompositeGenerator
4699
- * 4. Instantiates filters
4700
- * 5. Returns Pipeline(generator, filters)
5128
+ * 1. Plans: classifies by role, adds default ELO/SRS and ELO distance, orders filters
5129
+ * (`planPipeline`)
5130
+ * 2. Instantiates generators - wraps multiple in CompositeGenerator
5131
+ * 3. Instantiates filters
5132
+ * 4. Returns Pipeline(generator, filters)
4701
5133
  *
4702
5134
  * @param input - Strategy documents plus user/course interfaces
4703
5135
  * @returns Assembled pipeline and any warnings
@@ -4713,28 +5145,17 @@ var init_PipelineAssembler = __esm({
4713
5145
  warnings
4714
5146
  };
4715
5147
  }
4716
- const generatorStrategies = [];
4717
- const filterStrategies = [];
4718
- for (const s of strategies) {
4719
- if (isGenerator(s.implementingClass)) {
4720
- generatorStrategies.push(s);
4721
- } else if (isFilter(s.implementingClass)) {
4722
- filterStrategies.push(s);
4723
- } else {
4724
- warnings.push(`Unknown strategy type '${s.implementingClass}', skipping: ${s.name}`);
5148
+ const plan = planPipeline(strategies, course.getCourseID());
5149
+ warnings.push(...plan.warnings);
5150
+ for (const n of [...plan.generators, ...plan.filters]) {
5151
+ if (n.origin === "assembler-default") {
5152
+ logger.debug(
5153
+ `[PipelineAssembler] No ${n.implementingClass} ${n.role} configured, adding default`
5154
+ );
4725
5155
  }
4726
5156
  }
4727
- const courseId = course.getCourseID();
4728
- const hasElo = generatorStrategies.some((s) => s.implementingClass === "elo" /* ELO */);
4729
- const hasSrs = generatorStrategies.some((s) => s.implementingClass === "srs" /* SRS */);
4730
- if (!hasElo) {
4731
- logger.debug("[PipelineAssembler] No ELO generator configured, adding default");
4732
- generatorStrategies.push(createDefaultEloStrategy(courseId));
4733
- }
4734
- if (!hasSrs) {
4735
- logger.debug("[PipelineAssembler] No SRS generator configured, adding default");
4736
- generatorStrategies.push(createDefaultSrsStrategy(courseId));
4737
- }
5157
+ const generatorStrategies = plan.generators.map((g) => g.strategy);
5158
+ const sortedFilterStrategies = plan.filters.map((f) => f.strategy);
4738
5159
  if (generatorStrategies.length === 0) {
4739
5160
  warnings.push("No generator strategy found");
4740
5161
  return {
@@ -4756,9 +5177,6 @@ var init_PipelineAssembler = __esm({
4756
5177
  generator = await CompositeGenerator.fromStrategies(user, course, generatorStrategies);
4757
5178
  }
4758
5179
  const filters = [];
4759
- const sortedFilterStrategies = [...filterStrategies].sort(
4760
- (a, b) => a.name.localeCompare(b.name)
4761
- );
4762
5180
  for (const filterStrategy of sortedFilterStrategies) {
4763
5181
  try {
4764
5182
  const nav = await ContentNavigator.create(user, course, filterStrategy);
@@ -4826,7 +5244,9 @@ var init_3 = __esm({
4826
5244
  "./generators/prescribed.ts": () => Promise.resolve().then(() => (init_prescribed(), prescribed_exports)),
4827
5245
  "./generators/srs.ts": () => Promise.resolve().then(() => (init_srs(), srs_exports)),
4828
5246
  "./generators/types.ts": () => Promise.resolve().then(() => (init_types(), types_exports)),
4829
- "./index.ts": () => Promise.resolve().then(() => (init_navigators(), navigators_exports))
5247
+ "./index.ts": () => Promise.resolve().then(() => (init_navigators(), navigators_exports)),
5248
+ "./pipelinePlan.ts": () => Promise.resolve().then(() => (init_pipelinePlan(), pipelinePlan_exports)),
5249
+ "./regulators.ts": () => Promise.resolve().then(() => (init_regulators(), regulators_exports))
4830
5250
  });
4831
5251
  }
4832
5252
  });
@@ -4847,6 +5267,7 @@ __export(navigators_exports, {
4847
5267
  drainCapturedRuns: () => drainCapturedRuns,
4848
5268
  getActivePipeline: () => getActivePipeline,
4849
5269
  getCardOrigin: () => getCardOrigin,
5270
+ getRegisteredFilterKind: () => getRegisteredFilterKind,
4850
5271
  getRegisteredNavigator: () => getRegisteredNavigator,
4851
5272
  getRegisteredNavigatorNames: () => getRegisteredNavigatorNames,
4852
5273
  getRegisteredNavigatorRole: () => getRegisteredNavigatorRole,
@@ -4875,6 +5296,10 @@ function hasRegisteredNavigator(implementingClass) {
4875
5296
  function getRegisteredNavigatorRole(implementingClass) {
4876
5297
  return navigatorRegistry.get(implementingClass)?.role;
4877
5298
  }
5299
+ function getRegisteredFilterKind(implementingClass) {
5300
+ const ctor = navigatorRegistry.get(implementingClass)?.constructor;
5301
+ return ctor?.kind;
5302
+ }
4878
5303
  function getRegisteredNavigatorNames() {
4879
5304
  return Array.from(navigatorRegistry.keys());
4880
5305
  }
@@ -4892,17 +5317,20 @@ async function initializeNavigatorRegistry() {
4892
5317
  hierarchyModule,
4893
5318
  interferenceModule,
4894
5319
  relativePriorityModule,
4895
- userTagPreferenceModule
5320
+ userTagPreferenceModule,
5321
+ eloDistanceModule
4896
5322
  ] = await Promise.all([
4897
5323
  Promise.resolve().then(() => (init_hierarchyDefinition(), hierarchyDefinition_exports)),
4898
5324
  Promise.resolve().then(() => (init_interferenceMitigator(), interferenceMitigator_exports)),
4899
5325
  Promise.resolve().then(() => (init_relativePriority(), relativePriority_exports)),
4900
- Promise.resolve().then(() => (init_userTagPreference(), userTagPreference_exports))
5326
+ Promise.resolve().then(() => (init_userTagPreference(), userTagPreference_exports)),
5327
+ Promise.resolve().then(() => (init_eloDistance(), eloDistance_exports))
4901
5328
  ]);
4902
5329
  registerNavigator("hierarchyDefinition", hierarchyModule.default);
4903
5330
  registerNavigator("interferenceMitigator", interferenceModule.default);
4904
5331
  registerNavigator("relativePriority", relativePriorityModule.default);
4905
5332
  registerNavigator("userTagPreference", userTagPreferenceModule.default);
5333
+ registerNavigator("eloDistance", eloDistanceModule.default);
4906
5334
  logger.debug(
4907
5335
  `[NavigatorRegistry] Initialized ${navigatorRegistry.size} navigators: ${getRegisteredNavigatorNames().join(", ")}`
4908
5336
  );
@@ -4950,6 +5378,7 @@ var init_navigators = __esm({
4950
5378
  Navigators2["INTERFERENCE"] = "interferenceMitigator";
4951
5379
  Navigators2["RELATIVE_PRIORITY"] = "relativePriority";
4952
5380
  Navigators2["USER_TAG_PREFERENCE"] = "userTagPreference";
5381
+ Navigators2["ELO_DISTANCE"] = "eloDistance";
4953
5382
  return Navigators2;
4954
5383
  })(Navigators || {});
4955
5384
  NavigatorRole = /* @__PURE__ */ ((NavigatorRole2) => {
@@ -4964,7 +5393,8 @@ var init_navigators = __esm({
4964
5393
  ["hierarchyDefinition" /* HIERARCHY */]: "filter" /* FILTER */,
4965
5394
  ["interferenceMitigator" /* INTERFERENCE */]: "filter" /* FILTER */,
4966
5395
  ["relativePriority" /* RELATIVE_PRIORITY */]: "filter" /* FILTER */,
4967
- ["userTagPreference" /* USER_TAG_PREFERENCE */]: "filter" /* FILTER */
5396
+ ["userTagPreference" /* USER_TAG_PREFERENCE */]: "filter" /* FILTER */,
5397
+ ["eloDistance" /* ELO_DISTANCE */]: "filter" /* FILTER */
4968
5398
  };
4969
5399
  ContentNavigator = class {
4970
5400
  /** User interface for this navigation session */
@@ -6813,10 +7243,11 @@ function backlogHtml(backlog) {
6813
7243
  const rows = backlog.map((b) => {
6814
7244
  const hot = b.backlogMultiplier >= 3;
6815
7245
  const multColor = b.backlogMultiplier <= 1 ? "#86efac" : hot ? "#fca5a5" : "#fcd34d";
6816
- const headroom = b.backlogMultiplier > 1 ? `climbing (\xD7${b.backlogGrowthRate.toFixed(2)} per ${b.healthyBacklog}-review excess, unbounded)` : "healthy \u2014 no pressure";
7246
+ const headroom = b.backlogMultiplier > 1 ? `climbing (\xD7${b.backlogGrowthRate.toFixed(2)} per ${b.healthyBacklog} of mass in excess, unbounded)` : "healthy \u2014 no pressure";
7247
+ const mass = b.reviewMass !== null ? ` \xB7 mass ${b.reviewMass.toFixed(1)}` : "";
6817
7248
  const top = b.topReviewScore !== null ? b.topReviewScore.toFixed(2) : "\u2014";
6818
7249
  const next = b.nextDueIn ? ` <span style="opacity:.6">\xB7 next due ${esc(b.nextDueIn)}</span>` : "";
6819
- return `<div style="margin-left:6px"><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}">\xD7${b.backlogMultiplier.toFixed(2)}</span> <span style="opacity:.6">${headroom} \xB7 top review ${top}</span></div></div>`;
7250
+ return `<div style="margin-left:6px"><span style="opacity:.7">${esc(b.courseId.slice(0, 8))}</span> due ${b.dueNow}/${b.scheduledTotal}${mass} <span style="opacity:.6">(healthy mass ${b.healthyBacklog})</span>${next}<div style="margin-left:6px">pressure <span style="color:${multColor}">\xD7${b.backlogMultiplier.toFixed(2)}</span> <span style="opacity:.6">${headroom} \xB7 top review ${top}</span></div></div>`;
6820
7251
  }).join("");
6821
7252
  return `<div style="margin-bottom:6px"><div style="color:#93c5fd">review backpressure</div>${rows}</div>`;
6822
7253
  }
@@ -6955,8 +7386,9 @@ function snapshotToText(s) {
6955
7386
  const headroom = b.backlogMultiplier > 1 ? "climbing" : "healthy";
6956
7387
  const top = b.topReviewScore !== null ? b.topReviewScore.toFixed(2) : "\u2014";
6957
7388
  const next = b.nextDueIn ? `, next due ${b.nextDueIn}` : "";
7389
+ const mass = b.reviewMass !== null ? `, mass ${b.reviewMass.toFixed(1)}` : "";
6958
7390
  lines.push(
6959
- ` ${b.courseId.slice(0, 8)}: due ${b.dueNow}/${b.scheduledTotal} (healthy ${b.healthyBacklog})${next}; pressure \xD7${b.backlogMultiplier.toFixed(2)} ${headroom}; top review ${top}`
7391
+ ` ${b.courseId.slice(0, 8)}: due ${b.dueNow}/${b.scheduledTotal}${mass} (healthy mass ${b.healthyBacklog})${next}; pressure \xD7${b.backlogMultiplier.toFixed(2)} ${headroom}; top review ${top}`
6960
7392
  );
6961
7393
  }
6962
7394
  }
@@ -9978,6 +10410,11 @@ var init_courseDB3 = __esm({
9978
10410
  setEphemeralHints(hints) {
9979
10411
  this._pendingHints = hints;
9980
10412
  }
10413
+ /** Forward a presentation to the navigator (a new card restarts its intake clock). */
10414
+ notePresented(card) {
10415
+ if (card.status !== "new") return;
10416
+ void this.createNavigator(this.userDB).then((navigator2) => navigator2.notePresented?.(card)).catch((e) => logger.warn(`[static/courseDB] Could not note a presentation: ${e}`));
10417
+ }
9981
10418
  async getWeightedCards(limit) {
9982
10419
  try {
9983
10420
  const navigator2 = await this.createNavigator(this.userDB);