@vue-skuilder/db 0.2.28 → 0.2.29

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 +587 -179
  6. package/dist/core/index.js.map +1 -1
  7. package/dist/core/index.mjs +586 -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 +585 -179
  20. package/dist/impl/couch/index.js.map +1 -1
  21. package/dist/impl/couch/index.mjs +585 -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 +582 -179
  26. package/dist/impl/static/index.js.map +1 -1
  27. package/dist/impl/static/index.mjs +582 -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 +635 -180
  32. package/dist/index.js.map +1 -1
  33. package/dist/index.mjs +622 -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 +261 -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
@@ -776,7 +776,7 @@ function parseCardElo(provenance) {
776
776
  const match = eloEntry.reason.match(/card:\s*(\d+)/);
777
777
  return match ? parseInt(match[1], 10) : void 0;
778
778
  }
779
- function buildRunReport(courseId, courseName, generatorName, generators, generatedCount, filters, allCards, selectedCards, userElo, hints, scoredCards) {
779
+ function buildRunReport(courseId, courseName, generatorName, generators, generatedCount, filters, allCards, selectedCards, userElo, hints, scoredCards, regulators) {
780
780
  const selectedIds = new Set(selectedCards.map((c) => c.cardId));
781
781
  const toReport = (card) => ({
782
782
  cardId: card.cardId,
@@ -784,7 +784,7 @@ function buildRunReport(courseId, courseName, generatorName, generators, generat
784
784
  origin: getOrigin(card),
785
785
  generator: card.provenance[0]?.strategyName || card.provenance[0]?.strategy,
786
786
  finalScore: card.score,
787
- cardElo: parseCardElo(card.provenance),
787
+ cardElo: card.cardElo ?? parseCardElo(card.provenance),
788
788
  provenance: card.provenance,
789
789
  tags: card.tags,
790
790
  selected: selectedIds.has(card.cardId)
@@ -862,7 +862,8 @@ function buildRunReport(courseId, courseName, generatorName, generators, generat
862
862
  newSelected,
863
863
  cards,
864
864
  unselectedNew,
865
- discardedTail
865
+ discardedTail,
866
+ ...regulators ? { regulators } : {}
866
867
  };
867
868
  }
868
869
  function formatProvenance(provenance) {
@@ -1586,11 +1587,23 @@ var SrsDebugger_exports = {};
1586
1587
  __export(SrsDebugger_exports, {
1587
1588
  captureSrsBacklog: () => captureSrsBacklog,
1588
1589
  clearSrsBacklogDebug: () => clearSrsBacklogDebug,
1589
- getSrsBacklogDebug: () => getSrsBacklogDebug
1590
+ getSrsBacklogDebug: () => getSrsBacklogDebug,
1591
+ noteReviewPressure: () => noteReviewPressure
1590
1592
  });
1591
1593
  function captureSrsBacklog(snapshot) {
1592
1594
  snapshots.set(snapshot.courseId, snapshot);
1593
1595
  }
1596
+ function noteReviewPressure(courseId, pressure) {
1597
+ const snapshot = snapshots.get(courseId);
1598
+ if (!snapshot) return;
1599
+ snapshots.set(courseId, {
1600
+ ...snapshot,
1601
+ reviewMass: pressure.mass,
1602
+ healthyBacklog: pressure.healthyMass,
1603
+ backlogGrowthRate: pressure.rate,
1604
+ backlogMultiplier: pressure.multiplier
1605
+ });
1606
+ }
1594
1607
  function getSrsBacklogDebug() {
1595
1608
  return [...snapshots.values()].sort((a, b) => b.timestamp - a.timestamp);
1596
1609
  }
@@ -1869,13 +1882,12 @@ __export(elo_exports, {
1869
1882
  default: () => ELONavigator
1870
1883
  });
1871
1884
  import { toCourseElo as toCourseElo2 } from "@vue-skuilder/common";
1872
- var ELO_RELEVANCE_SIGMA, ELONavigator;
1885
+ var ELONavigator;
1873
1886
  var init_elo = __esm({
1874
1887
  "src/core/navigators/generators/elo.ts"() {
1875
1888
  "use strict";
1876
1889
  init_navigators();
1877
1890
  init_logger();
1878
- ELO_RELEVANCE_SIGMA = 300;
1879
1891
  ELONavigator = class extends ContentNavigator {
1880
1892
  /** Human-readable name for CardGenerator interface */
1881
1893
  name;
@@ -1884,10 +1896,8 @@ var init_elo = __esm({
1884
1896
  this.name = strategyData?.name || "ELO";
1885
1897
  }
1886
1898
  /**
1887
- * Get new cards with suitability scores based on ELO distance.
1888
- *
1889
- * Cards closer to user's ELO get higher scores.
1890
- * Score formula: max(0, 1 - distance / 500)
1899
+ * Get the new cards nearest the learner's ELO, each scored with a flat
1900
+ * jitter in [0.5, 1]. Carries each card's ELO for the ELO distance filter.
1891
1901
  *
1892
1902
  * NOTE: This generator only handles NEW cards. Reviews are handled by
1893
1903
  * SRSNavigator. Use CompositeGenerator to combine both.
@@ -1915,20 +1925,20 @@ var init_elo = __esm({
1915
1925
  const scored = newCards.map((c) => {
1916
1926
  const cardElo = c.elo ?? 1e3;
1917
1927
  const distance = Math.abs(cardElo - userGlobalElo);
1918
- const relevance = Math.exp(-((distance / ELO_RELEVANCE_SIGMA) ** 2));
1919
- const samplingKey = relevance * (0.5 + 0.5 * Math.random());
1928
+ const jitter = 0.5 + 0.5 * Math.random();
1920
1929
  return {
1921
1930
  cardId: c.cardID,
1922
1931
  courseId: c.courseID,
1923
- score: samplingKey,
1932
+ score: jitter,
1933
+ cardElo,
1924
1934
  provenance: [
1925
1935
  {
1926
1936
  strategy: "elo",
1927
1937
  strategyName: this.strategyName || this.name,
1928
1938
  strategyId: this.strategyId || "NAVIGATION_STRATEGY-ELO-default",
1929
1939
  action: "generated",
1930
- score: samplingKey,
1931
- reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userGlobalElo)}), relevance ${relevance.toFixed(3)}, key ${samplingKey.toFixed(3)}`
1940
+ score: jitter,
1941
+ reason: `new card near learner ELO: distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userGlobalElo)}), jitter ${jitter.toFixed(3)}`
1932
1942
  }
1933
1943
  ]
1934
1944
  };
@@ -2804,43 +2814,132 @@ var init_prescribed = __esm({
2804
2814
  }
2805
2815
  });
2806
2816
 
2817
+ // src/core/navigators/regulators.ts
2818
+ var regulators_exports = {};
2819
+ __export(regulators_exports, {
2820
+ DEFAULT_REGULATOR_CONFIG: () => DEFAULT_REGULATOR_CONFIG,
2821
+ INTAKE_CLOCK_KEY: () => INTAKE_CLOCK_KEY,
2822
+ applyReading: () => applyReading,
2823
+ frozenMsAt: () => frozenMsAt,
2824
+ intakeHours: () => intakeHours,
2825
+ intakeReading: () => intakeReading,
2826
+ resetIntakeClock: () => resetIntakeClock,
2827
+ reviewMassReading: () => reviewMassReading,
2828
+ reviewWeight: () => reviewWeight,
2829
+ stepIntakeClock: () => stepIntakeClock
2830
+ });
2831
+ function clamp01(x) {
2832
+ return Math.min(1, Math.max(0, x));
2833
+ }
2834
+ function reviewWeight(card, generatedScore, referenceScore) {
2835
+ if (card.reviewUrgency !== void 0 && generatedScore !== void 0 && generatedScore > 0) {
2836
+ return clamp01(card.reviewUrgency * (card.score / generatedScore));
2837
+ }
2838
+ return clamp01(card.score / referenceScore);
2839
+ }
2840
+ function reviewMassReading(reviews, generatedScores, config = DEFAULT_REGULATOR_CONFIG.reviewMass) {
2841
+ const mass = reviews.reduce(
2842
+ (m, c) => m + reviewWeight(c, generatedScores.get(c.cardId), config.referenceScore),
2843
+ 0
2844
+ );
2845
+ const multiplier = mass > config.healthyMass ? Math.pow(config.rate, (mass - config.healthyMass) / config.healthyMass) : 1;
2846
+ return {
2847
+ name: "review-mass",
2848
+ class: "review",
2849
+ urgency: mass,
2850
+ multiplier,
2851
+ applied: reviews.length,
2852
+ inputs: { due: reviews.length, mass, healthyMass: config.healthyMass }
2853
+ };
2854
+ }
2855
+ function resetIntakeClock(nowMs) {
2856
+ return { lastNewAt: new Date(nowMs).toISOString(), frozenMs: 0, unservableSince: null };
2857
+ }
2858
+ function frozenMsAt(state, nowMs) {
2859
+ const open = state.unservableSince ? Math.max(0, nowMs - Date.parse(state.unservableSince)) : 0;
2860
+ return state.frozenMs + open;
2861
+ }
2862
+ function intakeHours(state, nowMs) {
2863
+ const elapsed = nowMs - Date.parse(state.lastNewAt);
2864
+ return Math.max(0, elapsed - frozenMsAt(state, nowMs)) / 36e5;
2865
+ }
2866
+ function stepIntakeClock(state, nowMs, eligibleNew) {
2867
+ if (eligibleNew === 0 && !state.unservableSince) {
2868
+ return { ...state, unservableSince: new Date(nowMs).toISOString() };
2869
+ }
2870
+ if (eligibleNew > 0 && state.unservableSince) {
2871
+ return { ...state, frozenMs: frozenMsAt(state, nowMs), unservableSince: null };
2872
+ }
2873
+ return state;
2874
+ }
2875
+ function intakeReading(state, nowMs, counts, config = DEFAULT_REGULATOR_CONFIG.intake) {
2876
+ const hours = intakeHours(state, nowMs);
2877
+ const multiplier = counts.eligibleNew > 0 ? Math.pow(config.rate, hours / config.scaleHours) : 1;
2878
+ return {
2879
+ name: "intake",
2880
+ class: "new",
2881
+ urgency: hours,
2882
+ multiplier,
2883
+ applied: counts.eligibleNew,
2884
+ inputs: {
2885
+ hoursSinceNew: hours,
2886
+ frozenHours: frozenMsAt(state, nowMs) / 36e5,
2887
+ eligibleNew: counts.eligibleNew,
2888
+ newCandidates: counts.newCandidates
2889
+ }
2890
+ };
2891
+ }
2892
+ function applyReading(cards, reading) {
2893
+ if (reading.multiplier === 1) return;
2894
+ 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)}`;
2895
+ for (const card of cards) {
2896
+ card.score *= reading.multiplier;
2897
+ card.provenance.push({
2898
+ strategy: "regulator",
2899
+ strategyName: `Regulator: ${REGULATOR_LABEL[reading.name]}`,
2900
+ strategyId: `regulator-${reading.name}`,
2901
+ action: reading.multiplier > 1 ? "boosted" : "penalized",
2902
+ score: card.score,
2903
+ reason
2904
+ });
2905
+ }
2906
+ }
2907
+ var DEFAULT_REGULATOR_CONFIG, INTAKE_CLOCK_KEY, REGULATOR_LABEL;
2908
+ var init_regulators = __esm({
2909
+ "src/core/navigators/regulators.ts"() {
2910
+ "use strict";
2911
+ DEFAULT_REGULATOR_CONFIG = {
2912
+ reviewMass: { referenceScore: 0.95, healthyMass: 20, rate: 2 },
2913
+ intake: { rate: 2, scaleHours: 24 }
2914
+ };
2915
+ INTAKE_CLOCK_KEY = "IntakeClock";
2916
+ REGULATOR_LABEL = {
2917
+ "review-mass": "Review mass",
2918
+ intake: "Intake"
2919
+ };
2920
+ }
2921
+ });
2922
+
2807
2923
  // src/core/navigators/generators/srs.ts
2808
2924
  var srs_exports = {};
2809
2925
  __export(srs_exports, {
2810
2926
  default: () => SRSNavigator
2811
2927
  });
2812
2928
  import moment from "moment";
2813
- var DEFAULT_HEALTHY_BACKLOG, BACKLOG_GROWTH_RATE, SRSNavigator;
2929
+ var SRSNavigator;
2814
2930
  var init_srs = __esm({
2815
2931
  "src/core/navigators/generators/srs.ts"() {
2816
2932
  "use strict";
2817
2933
  init_navigators();
2818
2934
  init_SrsDebugger();
2935
+ init_regulators();
2819
2936
  init_logger();
2820
- DEFAULT_HEALTHY_BACKLOG = 20;
2821
- BACKLOG_GROWTH_RATE = 2;
2822
2937
  SRSNavigator = class extends ContentNavigator {
2823
2938
  /** Human-readable name for CardGenerator interface */
2824
2939
  name;
2825
- /** Healthy backlog threshold - when exceeded, backlog pressure kicks in */
2826
- healthyBacklog;
2827
2940
  constructor(user, course, strategyData) {
2828
2941
  super(user, course, strategyData);
2829
2942
  this.name = strategyData?.name || "SRS";
2830
- const config = this.parseConfig(strategyData?.serializedData);
2831
- this.healthyBacklog = config.healthyBacklog ?? DEFAULT_HEALTHY_BACKLOG;
2832
- }
2833
- /**
2834
- * Parse configuration from serialized JSON.
2835
- */
2836
- parseConfig(serializedData) {
2837
- if (!serializedData) return {};
2838
- try {
2839
- return JSON.parse(serializedData);
2840
- } catch {
2841
- logger.warn("[SRS] Failed to parse strategy config, using defaults");
2842
- return {};
2843
- }
2844
2943
  }
2845
2944
  /**
2846
2945
  * Get review cards scored by urgency.
@@ -2848,7 +2947,6 @@ var init_srs = __esm({
2848
2947
  * Score formula combines:
2849
2948
  * - Relative overdueness: hoursOverdue / intervalHours
2850
2949
  * - Interval recency: exponential decay favoring shorter intervals
2851
- * - Backlog pressure: boost when due reviews exceed healthy threshold
2852
2950
  *
2853
2951
  * Cards not yet due are excluded (not scored as 0).
2854
2952
  *
@@ -2885,7 +2983,6 @@ var init_srs = __esm({
2885
2983
  }
2886
2984
  }
2887
2985
  }
2888
- const backlogMultiplier = this.computeBacklogMultiplier(dueReviews.length);
2889
2986
  const notDue = reviews.filter((r) => !now.isAfter(moment.utc(r.reviewTime)));
2890
2987
  let nextDueIn = null;
2891
2988
  if (notDue.length > 0) {
@@ -2896,9 +2993,8 @@ var init_srs = __esm({
2896
2993
  nextDueIn = until.asHours() < 1 ? `${Math.round(until.asMinutes())}m` : until.asHours() < 24 ? `${Math.round(until.asHours())}h` : `${Math.round(until.asDays())}d`;
2897
2994
  }
2898
2995
  if (dueReviews.length > 0) {
2899
- const pressureNote = backlogMultiplier > 1 ? ` [backlog pressure: \xD7${backlogMultiplier.toFixed(2)}]` : ` [healthy backlog]`;
2900
2996
  logger.info(
2901
- `[SRS] Course ${courseId}: ${dueReviews.length} reviews due now (of ${reviews.length} scheduled)${pressureNote}`
2997
+ `[SRS] Course ${courseId}: ${dueReviews.length} reviews due now (of ${reviews.length} scheduled)`
2902
2998
  );
2903
2999
  } else if (reviews.length > 0) {
2904
3000
  const sortedByDue = [...reviews].sort(
@@ -2915,11 +3011,12 @@ var init_srs = __esm({
2915
3011
  logger.info(`[SRS] Course ${courseId}: No reviews scheduled`);
2916
3012
  }
2917
3013
  const scored = dueReviews.map((review) => {
2918
- const { score, reason } = this.computeUrgencyScore(review, now, backlogMultiplier);
3014
+ const { score, urgency, reason } = this.computeUrgencyScore(review, now);
2919
3015
  return {
2920
3016
  cardId: review.cardId,
2921
3017
  courseId: review.courseId,
2922
3018
  score,
3019
+ reviewUrgency: urgency,
2923
3020
  reviewID: review._id,
2924
3021
  provenance: [
2925
3022
  {
@@ -2938,47 +3035,20 @@ var init_srs = __esm({
2938
3035
  courseId,
2939
3036
  scheduledTotal: reviews.length,
2940
3037
  dueNow: dueReviews.length,
2941
- healthyBacklog: this.healthyBacklog,
2942
- backlogMultiplier,
2943
- backlogGrowthRate: BACKLOG_GROWTH_RATE,
3038
+ healthyBacklog: DEFAULT_REGULATOR_CONFIG.reviewMass.healthyMass,
3039
+ reviewMass: null,
3040
+ backlogMultiplier: 1,
3041
+ backlogGrowthRate: DEFAULT_REGULATOR_CONFIG.reviewMass.rate,
2944
3042
  topReviewScore: sorted.length > 0 ? sorted[0].score : null,
2945
3043
  nextDueIn,
2946
3044
  timestamp: Date.now()
2947
3045
  });
2948
3046
  return { cards: sorted.slice(0, limit) };
2949
3047
  }
2950
- /**
2951
- * Compute the multiplicative backlog pressure based on number of due reviews.
2952
- *
2953
- * ×1.0 at or below the healthy threshold (no boost); above it, grows as
2954
- * BACKLOG_GROWTH_RATE raised to the excess expressed in multiples of the
2955
- * healthy threshold. Uncapped — self-regulating instead: reviews winning
2956
- * slots depletes dueCount, which drops the ratio and relaxes the multiplier
2957
- * next run.
2958
- *
2959
- * Examples (with default healthyBacklog=20, BACKLOG_GROWTH_RATE=1.5):
2960
- * - 10 due reviews → ×1.00 (healthy)
2961
- * - 20 due reviews → ×1.00 (at threshold, ratio 0)
2962
- * - 40 due reviews → ×1.50 (ratio 1, 2x threshold)
2963
- * - 60 due reviews → ×2.25 (ratio 2, 3x threshold — old hard cap was ×2.00 here)
2964
- * - 100 due reviews → ×5.06 (ratio 4, 5x threshold)
2965
- * - 160 due reviews → ×17.09 (ratio 7, 8x threshold)
2966
- *
2967
- * @param dueCount - Number of reviews currently due
2968
- * @returns Multiplier applied to review urgency (>= 1.0, unbounded)
2969
- */
2970
- computeBacklogMultiplier(dueCount) {
2971
- if (dueCount <= this.healthyBacklog) {
2972
- return 1;
2973
- }
2974
- const excess = dueCount - this.healthyBacklog;
2975
- const ratio = excess / this.healthyBacklog;
2976
- return Math.pow(BACKLOG_GROWTH_RATE, ratio);
2977
- }
2978
3048
  /**
2979
3049
  * Compute urgency score for a review card.
2980
3050
  *
2981
- * Three factors:
3051
+ * Two factors:
2982
3052
  * 1. Relative overdueness = hoursOverdue / intervalHours
2983
3053
  * - 2 days overdue on 3-day interval = 0.67 (urgent)
2984
3054
  * - 2 days overdue on 180-day interval = 0.01 (not urgent)
@@ -2988,20 +3058,14 @@ var init_srs = __esm({
2988
3058
  * - 30 days (720h) → ~0.56
2989
3059
  * - 180 days → ~0.30
2990
3060
  *
2991
- * 3. Backlog pressure = global *multiplier* when review backlog exceeds the
2992
- * healthy threshold (×1.0 healthy → exponential growth, uncapped, above it).
2993
- *
2994
- * Combined: (base 0.5 + urgency factors * 0.45) × backlog multiplier.
2995
- * Per-card range before pressure: ~0.57–0.95. NOT clamped to 1.0 — under a
2996
- * heavy backlog reviews scale onto the open scale to compete with (and exceed)
2997
- * new cards; there's no ceiling at all now, so a bad enough backlog always
2998
- * wins eventually — self-regulating because winning slots depletes dueCount.
3061
+ * Combined: base 0.5 + urgency factors * 0.45, so ~0.57–0.95 per card.
3062
+ * Backlog pressure is applied later, by the regulator stage, which can lift
3063
+ * reviews onto the open scale above new cards (see regulators.ts).
2999
3064
  *
3000
3065
  * @param review - The scheduled card to score
3001
3066
  * @param now - Current time
3002
- * @param backlogMultiplier - Pre-computed backlog multiplier (>= 1.0, unbounded)
3003
3067
  */
3004
- computeUrgencyScore(review, now, backlogMultiplier) {
3068
+ computeUrgencyScore(review, now) {
3005
3069
  const scheduledAt = moment.utc(review.scheduledAt);
3006
3070
  const due = moment.utc(review.reviewTime);
3007
3071
  const intervalHours = Math.max(1, due.diff(scheduledAt, "hours"));
@@ -3010,20 +3074,16 @@ var init_srs = __esm({
3010
3074
  const recencyFactor = 0.3 + 0.7 * Math.exp(-intervalHours / 720);
3011
3075
  const overdueContribution = Math.min(1, Math.max(0, relativeOverdue));
3012
3076
  const urgency = overdueContribution * 0.5 + recencyFactor * 0.5;
3013
- const baseScore = 0.5 + urgency * 0.45;
3014
- const score = baseScore * backlogMultiplier;
3077
+ const score = 0.5 + urgency * 0.45;
3015
3078
  const reasonParts = [
3016
3079
  `${Math.round(hoursOverdue)}h overdue`,
3017
3080
  `interval: ${Math.round(intervalHours)}h`,
3018
3081
  `relative: ${relativeOverdue.toFixed(2)}`,
3019
3082
  `recency: ${recencyFactor.toFixed(2)}`
3020
3083
  ];
3021
- if (backlogMultiplier > 1) {
3022
- reasonParts.push(`backlog: \xD7${backlogMultiplier.toFixed(2)}`);
3023
- }
3024
3084
  reasonParts.push("review");
3025
3085
  const reason = reasonParts.join(", ");
3026
- return { score, reason };
3086
+ return { score, urgency, reason };
3027
3087
  }
3028
3088
  };
3029
3089
  }
@@ -3078,6 +3138,8 @@ var init_WeightedFilter = __esm({
3078
3138
  init_contentNavigationStrategy();
3079
3139
  WeightedFilter = class {
3080
3140
  name;
3141
+ kind;
3142
+ liveOnly;
3081
3143
  inner;
3082
3144
  learnable;
3083
3145
  staticWeight;
@@ -3085,6 +3147,8 @@ var init_WeightedFilter = __esm({
3085
3147
  constructor(inner, learnable = DEFAULT_LEARNABLE_WEIGHT, staticWeight = false, strategyId) {
3086
3148
  this.inner = inner;
3087
3149
  this.name = inner.name;
3150
+ this.kind = inner.kind;
3151
+ this.liveOnly = inner.liveOnly;
3088
3152
  this.learnable = learnable;
3089
3153
  this.staticWeight = staticWeight;
3090
3154
  this.strategyId = strategyId;
@@ -3149,58 +3213,141 @@ var init_WeightedFilter = __esm({
3149
3213
  // src/core/navigators/filters/eloDistance.ts
3150
3214
  var eloDistance_exports = {};
3151
3215
  __export(eloDistance_exports, {
3152
- DEFAULT_HALF_LIFE: () => DEFAULT_HALF_LIFE,
3153
- DEFAULT_MAX_MULTIPLIER: () => DEFAULT_MAX_MULTIPLIER,
3154
- DEFAULT_MIN_MULTIPLIER: () => DEFAULT_MIN_MULTIPLIER,
3155
- createEloDistanceFilter: () => createEloDistanceFilter
3216
+ DEFAULT_ELO_DISTANCE_CONFIG: () => DEFAULT_ELO_DISTANCE_CONFIG,
3217
+ createEloDistanceFilter: () => createEloDistanceFilter,
3218
+ default: () => EloDistanceFilter,
3219
+ tagAwareGap: () => tagAwareGap
3156
3220
  });
3157
3221
  function computeMultiplier(distance, halfLife, minMultiplier, maxMultiplier) {
3158
3222
  const normalizedDistance = distance / halfLife;
3159
3223
  const decay = Math.exp(-(normalizedDistance * normalizedDistance));
3160
3224
  return minMultiplier + (maxMultiplier - minMultiplier) * decay;
3161
3225
  }
3226
+ function resolveConfig(config) {
3227
+ return { ...DEFAULT_ELO_DISTANCE_CONFIG, ...config };
3228
+ }
3229
+ function tagAwareGap(cardTags, cardElo, userElo, minTagCount) {
3230
+ const globalGap = cardElo.global.score - userElo.global.score;
3231
+ const tags = [];
3232
+ for (const tag of cardTags) {
3233
+ const user = userElo.tags[tag];
3234
+ if (!user || user.score === COUNT_ONLY_SENTINEL || user.count < minTagCount) continue;
3235
+ const card = cardElo.tags[tag]?.score ?? cardElo.global.score;
3236
+ tags.push({
3237
+ tag,
3238
+ gap: card - user.score,
3239
+ weight: user.count / (user.count + TAG_CONFIDENCE_HALF)
3240
+ });
3241
+ }
3242
+ if (tags.length === 0) return { gap: globalGap, globalGap, tags };
3243
+ const total = tags.reduce((w, t) => w + t.weight, 0);
3244
+ const tagGap = tags.reduce((g, t) => g + t.weight * t.gap, 0) / total;
3245
+ const lambda = total / (total + 1);
3246
+ return { gap: lambda * tagGap + (1 - lambda) * globalGap, globalGap, tags };
3247
+ }
3248
+ function tagReason(tags, globalGap) {
3249
+ 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(", ");
3250
+ const more = tags.length > 3 ? `, +${tags.length - 3} more` : "";
3251
+ return ` on ${tags.length} shared tag(s) [${shown}${more}] (global ${globalGap >= 0 ? "+" : ""}${Math.round(globalGap)})`;
3252
+ }
3253
+ async function applyEloDistance(cards, context, config, source) {
3254
+ const { course, userElo, userCourseElo } = context;
3255
+ const { halfLife, minMultiplier, maxMultiplier } = config;
3256
+ const tagAware = config.tagAware && userCourseElo !== void 0;
3257
+ const missing = cards.filter((c) => tagAware || c.cardElo === void 0).map((c) => c.cardId);
3258
+ const fetched = /* @__PURE__ */ new Map();
3259
+ if (missing.length > 0) {
3260
+ const elos = await course.getCardEloData(missing);
3261
+ missing.forEach((id, i) => {
3262
+ if (elos[i]) fetched.set(id, elos[i]);
3263
+ });
3264
+ }
3265
+ return cards.map((card) => {
3266
+ const full = fetched.get(card.cardId);
3267
+ const cardElo = full?.global?.score ?? card.cardElo ?? DEFAULT_CARD_ELO;
3268
+ let distance = Math.abs(cardElo - userElo);
3269
+ let how = "";
3270
+ if (tagAware && full) {
3271
+ const t = tagAwareGap(card.tags ?? [], full, userCourseElo, config.minTagCount);
3272
+ distance = Math.abs(t.gap);
3273
+ if (t.tags.length > 0) how = tagReason(t.tags, t.globalGap);
3274
+ }
3275
+ const multiplier = computeMultiplier(distance, halfLife, minMultiplier, maxMultiplier);
3276
+ const newScore = card.score * multiplier;
3277
+ const action = multiplier < maxMultiplier - 0.01 ? "penalized" : "passed";
3278
+ return {
3279
+ ...card,
3280
+ cardElo,
3281
+ score: newScore,
3282
+ provenance: [
3283
+ ...card.provenance,
3284
+ {
3285
+ strategy: "eloDistance",
3286
+ strategyName: source.name,
3287
+ strategyId: source.strategyId,
3288
+ action,
3289
+ score: newScore,
3290
+ reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userElo)})${how} \u2192 ${multiplier.toFixed(2)}x`
3291
+ }
3292
+ ]
3293
+ };
3294
+ });
3295
+ }
3162
3296
  function createEloDistanceFilter(config) {
3163
- const halfLife = config?.halfLife ?? DEFAULT_HALF_LIFE;
3164
- const minMultiplier = config?.minMultiplier ?? DEFAULT_MIN_MULTIPLIER;
3165
- const maxMultiplier = config?.maxMultiplier ?? DEFAULT_MAX_MULTIPLIER;
3297
+ const resolved = resolveConfig(config);
3298
+ const source = { name: "ELO Distance Filter", strategyId: "ELO_DISTANCE_FILTER" };
3166
3299
  return {
3167
- name: "ELO Distance Filter",
3168
- async transform(cards, context) {
3169
- const { course, userElo } = context;
3170
- const cardIds = cards.map((c) => c.cardId);
3171
- const cardElos = await course.getCardEloData(cardIds);
3172
- return cards.map((card, i) => {
3173
- const cardElo = cardElos[i]?.global?.score ?? 1e3;
3174
- const distance = Math.abs(cardElo - userElo);
3175
- const multiplier = computeMultiplier(distance, halfLife, minMultiplier, maxMultiplier);
3176
- const newScore = card.score * multiplier;
3177
- const action = multiplier < maxMultiplier - 0.01 ? "penalized" : "passed";
3178
- return {
3179
- ...card,
3180
- score: newScore,
3181
- provenance: [
3182
- ...card.provenance,
3183
- {
3184
- strategy: "eloDistance",
3185
- strategyName: "ELO Distance Filter",
3186
- strategyId: "ELO_DISTANCE_FILTER",
3187
- action,
3188
- score: newScore,
3189
- reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userElo)}) \u2192 ${multiplier.toFixed(2)}x`
3190
- }
3191
- ]
3192
- };
3193
- });
3194
- }
3300
+ name: source.name,
3301
+ kind: "signal",
3302
+ liveOnly: true,
3303
+ transform: (cards, context) => applyEloDistance(cards, context, resolved, source)
3195
3304
  };
3196
3305
  }
3197
- var DEFAULT_HALF_LIFE, DEFAULT_MIN_MULTIPLIER, DEFAULT_MAX_MULTIPLIER;
3306
+ var DEFAULT_ELO_DISTANCE_CONFIG, TAG_CONFIDENCE_HALF, COUNT_ONLY_SENTINEL, DEFAULT_CARD_ELO, EloDistanceFilter;
3198
3307
  var init_eloDistance = __esm({
3199
3308
  "src/core/navigators/filters/eloDistance.ts"() {
3200
3309
  "use strict";
3201
- DEFAULT_HALF_LIFE = 200;
3202
- DEFAULT_MIN_MULTIPLIER = 0.3;
3203
- DEFAULT_MAX_MULTIPLIER = 1;
3310
+ init_navigators();
3311
+ DEFAULT_ELO_DISTANCE_CONFIG = {
3312
+ halfLife: 300,
3313
+ minMultiplier: 0.05,
3314
+ maxMultiplier: 1,
3315
+ tagAware: true,
3316
+ minTagCount: 3
3317
+ };
3318
+ TAG_CONFIDENCE_HALF = 10;
3319
+ COUNT_ONLY_SENTINEL = -1;
3320
+ DEFAULT_CARD_ELO = 1e3;
3321
+ EloDistanceFilter = class _EloDistanceFilter extends ContentNavigator {
3322
+ name;
3323
+ /** See CardFilter.kind. Static, so the pipeline plan can read it without an instance. */
3324
+ static kind = "signal";
3325
+ kind = _EloDistanceFilter.kind;
3326
+ liveOnly = true;
3327
+ config;
3328
+ constructor(user, course, strategyData) {
3329
+ super(user, course, strategyData);
3330
+ this.name = strategyData.name || "ELO Distance";
3331
+ let parsed;
3332
+ try {
3333
+ parsed = strategyData.serializedData ? JSON.parse(strategyData.serializedData) : void 0;
3334
+ } catch {
3335
+ parsed = void 0;
3336
+ }
3337
+ this.config = resolveConfig(parsed);
3338
+ }
3339
+ transform(cards, context) {
3340
+ return applyEloDistance(cards, context, this.config, {
3341
+ name: this.name,
3342
+ strategyId: this.strategyId || "NAVIGATION_STRATEGY-eloDistance-default"
3343
+ });
3344
+ }
3345
+ async getWeightedCards(_limit) {
3346
+ throw new Error(
3347
+ "EloDistanceFilter is a filter and should not be used as a generator. Use Pipeline with a generator and this filter via transform()."
3348
+ );
3349
+ }
3350
+ };
3204
3351
  }
3205
3352
  });
3206
3353
 
@@ -3217,10 +3364,13 @@ var init_hierarchyDefinition = __esm({
3217
3364
  init_navigators();
3218
3365
  init_logger();
3219
3366
  DEFAULT_MIN_COUNT2 = 3;
3220
- HierarchyDefinitionNavigator = class extends ContentNavigator {
3367
+ HierarchyDefinitionNavigator = class _HierarchyDefinitionNavigator extends ContentNavigator {
3221
3368
  config;
3222
3369
  /** Human-readable name for CardFilter interface */
3223
3370
  name;
3371
+ /** See CardFilter.kind. Static, so the pipeline plan can read it without an instance. */
3372
+ static kind = "gate";
3373
+ kind = _HierarchyDefinitionNavigator.kind;
3224
3374
  constructor(user, course, strategyData) {
3225
3375
  super(user, course, strategyData);
3226
3376
  this.config = this.parseConfig(strategyData.serializedData);
@@ -3487,10 +3637,13 @@ var init_userTagPreference = __esm({
3487
3637
  "src/core/navigators/filters/userTagPreference.ts"() {
3488
3638
  "use strict";
3489
3639
  init_navigators();
3490
- UserTagPreferenceFilter = class extends ContentNavigator {
3640
+ UserTagPreferenceFilter = class _UserTagPreferenceFilter extends ContentNavigator {
3491
3641
  _strategyData;
3492
3642
  /** Human-readable name for CardFilter interface */
3493
3643
  name;
3644
+ /** See CardFilter.kind. Static, so the pipeline plan can read it without an instance. */
3645
+ static kind = "signal";
3646
+ kind = _UserTagPreferenceFilter.kind;
3494
3647
  constructor(user, course, strategyData) {
3495
3648
  super(user, course, strategyData);
3496
3649
  this._strategyData = strategyData;
@@ -3600,6 +3753,7 @@ var init_userTagPreference = __esm({
3600
3753
  // src/core/navigators/filters/index.ts
3601
3754
  var filters_exports = {};
3602
3755
  __export(filters_exports, {
3756
+ EloDistanceFilter: () => EloDistanceFilter,
3603
3757
  UserTagPreferenceFilter: () => UserTagPreferenceFilter,
3604
3758
  createEloDistanceFilter: () => createEloDistanceFilter
3605
3759
  });
@@ -3638,10 +3792,13 @@ var init_interferenceMitigator = __esm({
3638
3792
  DEFAULT_MIN_COUNT3 = 10;
3639
3793
  DEFAULT_MIN_ELAPSED_DAYS = 3;
3640
3794
  DEFAULT_INTERFERENCE_DECAY = 0.8;
3641
- InterferenceMitigatorNavigator = class extends ContentNavigator {
3795
+ InterferenceMitigatorNavigator = class _InterferenceMitigatorNavigator extends ContentNavigator {
3642
3796
  config;
3643
3797
  /** Human-readable name for CardFilter interface */
3644
3798
  name;
3799
+ /** See CardFilter.kind. Static, so the pipeline plan can read it without an instance. */
3800
+ static kind = "signal";
3801
+ kind = _InterferenceMitigatorNavigator.kind;
3645
3802
  /** Precomputed map: tag -> set of { partner, decay } it interferes with */
3646
3803
  interferenceMap;
3647
3804
  constructor(user, course, strategyData) {
@@ -3857,10 +4014,13 @@ var init_relativePriority = __esm({
3857
4014
  DEFAULT_PRIORITY = 0.5;
3858
4015
  DEFAULT_PRIORITY_INFLUENCE = 0.5;
3859
4016
  DEFAULT_COMBINE_MODE = "max";
3860
- RelativePriorityNavigator = class extends ContentNavigator {
4017
+ RelativePriorityNavigator = class _RelativePriorityNavigator extends ContentNavigator {
3861
4018
  config;
3862
4019
  /** Human-readable name for CardFilter interface */
3863
4020
  name;
4021
+ /** See CardFilter.kind. Static, so the pipeline plan can read it without an instance. */
4022
+ static kind = "signal";
4023
+ kind = _RelativePriorityNavigator.kind;
3864
4024
  constructor(user, course, strategyData) {
3865
4025
  super(user, course, strategyData);
3866
4026
  this.config = this.parseConfig(strategyData.serializedData);
@@ -4268,6 +4428,8 @@ var init_Pipeline = __esm({
4268
4428
  init_orchestration();
4269
4429
  init_PipelineDebugger();
4270
4430
  init_diversityRerank();
4431
+ init_regulators();
4432
+ init_SrsDebugger();
4271
4433
  VERBOSE_RESULTS = true;
4272
4434
  Pipeline = class extends ContentNavigator {
4273
4435
  generator;
@@ -4293,6 +4455,13 @@ var init_Pipeline = __esm({
4293
4455
  * getWeightedCards() call, then cleared.
4294
4456
  */
4295
4457
  _ephemeralHints = null;
4458
+ /**
4459
+ * The intake valve's clock (see regulators.ts), loaded from strategy state on
4460
+ * first use and kept in memory. Writes are chained so a presentation and a
4461
+ * run can't race each other's revision.
4462
+ */
4463
+ _intakeClock = null;
4464
+ _intakeClockWrite = Promise.resolve();
4296
4465
  /**
4297
4466
  * Create a new pipeline.
4298
4467
  *
@@ -4367,13 +4536,12 @@ var init_Pipeline = __esm({
4367
4536
  }
4368
4537
  }
4369
4538
  generatorSummaries = Array.from(genMap.entries()).map(([name, data]) => {
4370
- const newCards = data.cards.filter((c) => c.provenance[0]?.reason?.includes("new card"));
4371
- const reviewCards = data.cards.filter((c) => c.provenance[0]?.reason?.includes("review"));
4539
+ const reviewCount = data.cards.filter((c) => c.reviewID).length;
4372
4540
  return {
4373
4541
  name,
4374
4542
  cardCount: data.cards.length,
4375
- newCount: newCards.length,
4376
- reviewCount: reviewCards.length,
4543
+ newCount: data.cards.length - reviewCount,
4544
+ reviewCount,
4377
4545
  topScore: Math.max(...data.cards.map((c) => c.score), 0)
4378
4546
  };
4379
4547
  });
@@ -4409,19 +4577,24 @@ var init_Pipeline = __esm({
4409
4577
  cards.filter((c) => c.provenance.some((p) => p.strategy === "prescribed")).map((c) => c.cardId)
4410
4578
  );
4411
4579
  const filterImpacts = [];
4580
+ const generatedScores = new Map(cards.map((c) => [c.cardId, c.score]));
4581
+ const gated = /* @__PURE__ */ new Set();
4412
4582
  for (const filter of this.filters) {
4413
4583
  const beforeCount = cards.length;
4414
4584
  const beforeScores = new Map(cards.map((c) => [c.cardId, c.score]));
4415
4585
  cards = await filter.transform(cards, context);
4416
4586
  let boosted = 0, penalized = 0, passed = 0;
4417
4587
  const removed = beforeCount - cards.length;
4588
+ const kind = filter.kind ?? "gate";
4418
4589
  for (const card of cards) {
4419
4590
  const before = beforeScores.get(card.cardId) ?? 0;
4420
4591
  if (card.score > before) boosted++;
4421
- else if (card.score < before) penalized++;
4422
- else passed++;
4592
+ else if (card.score < before) {
4593
+ penalized++;
4594
+ if (kind === "gate") gated.add(card.cardId);
4595
+ } else passed++;
4423
4596
  }
4424
- filterImpacts.push({ name: filter.name, boosted, penalized, passed, removed });
4597
+ filterImpacts.push({ name: filter.name, kind, boosted, penalized, passed, removed });
4425
4598
  if (prescribedIds.size > 0) {
4426
4599
  const survivingIds = new Set(cards.map((c) => c.cardId));
4427
4600
  const killedPrescribed = [...prescribedIds].filter((id) => !survivingIds.has(id));
@@ -4437,6 +4610,7 @@ var init_Pipeline = __esm({
4437
4610
  }
4438
4611
  const scoredCards = cards;
4439
4612
  cards = cards.filter((c) => c.score > 0);
4613
+ const regulators = await this.regulate(cards, generatedScores, gated);
4440
4614
  const hints = this._ephemeralHints;
4441
4615
  if (hints) {
4442
4616
  this._ephemeralHints = null;
@@ -4473,7 +4647,8 @@ var init_Pipeline = __esm({
4473
4647
  result,
4474
4648
  context.userElo,
4475
4649
  hints ?? void 0,
4476
- scoredCards
4650
+ scoredCards,
4651
+ regulators
4477
4652
  );
4478
4653
  captureRun(report);
4479
4654
  } catch (e) {
@@ -4652,6 +4827,77 @@ var init_Pipeline = __esm({
4652
4827
  logger.info(`[Pipeline] Hints applied: ${beforeCount} \u2192 ${cards.length} cards`);
4653
4828
  return cards;
4654
4829
  }
4830
+ /**
4831
+ * The regulator stage: measure each class's pressure and scale it.
4832
+ *
4833
+ * - Review mass: every due review's SRS urgency times the filters' net
4834
+ * effect on it.
4835
+ * - Intake: servable hours since a new card was presented, applied only to
4836
+ * eligible new cards (no gate penalized them). With none eligible, the
4837
+ * clock freezes.
4838
+ *
4839
+ * Mutates `cards` in place; returns the readings for the run report.
4840
+ */
4841
+ async regulate(cards, generatedScores, gated) {
4842
+ const config = DEFAULT_REGULATOR_CONFIG;
4843
+ const reviews = cards.filter((c) => c.reviewID);
4844
+ const newCards = cards.filter((c) => !c.reviewID);
4845
+ const eligibleNew = newCards.filter((c) => !gated.has(c.cardId));
4846
+ const mass = reviewMassReading(reviews, generatedScores, config.reviewMass);
4847
+ applyReading(reviews, mass);
4848
+ noteReviewPressure(this.course.getCourseID(), {
4849
+ mass: mass.urgency,
4850
+ healthyMass: config.reviewMass.healthyMass,
4851
+ rate: config.reviewMass.rate,
4852
+ multiplier: mass.multiplier
4853
+ });
4854
+ const now = Date.now();
4855
+ const clock = await this.loadIntakeClock(now);
4856
+ const stepped = stepIntakeClock(clock, now, eligibleNew.length);
4857
+ if (stepped !== clock) this.saveIntakeClock(stepped);
4858
+ const intake = intakeReading(
4859
+ stepped,
4860
+ now,
4861
+ { eligibleNew: eligibleNew.length, newCandidates: newCards.length },
4862
+ config.intake
4863
+ );
4864
+ applyReading(eligibleNew, intake);
4865
+ logger.info(
4866
+ `[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)}`
4867
+ );
4868
+ return [mass, intake];
4869
+ }
4870
+ /**
4871
+ * A card was presented. A new card's first presentation discharges the
4872
+ * intake valve: its clock restarts. Called by the SessionController.
4873
+ */
4874
+ notePresented(card) {
4875
+ if (card.status !== "new" || card.courseId !== this.course?.getCourseID()) return;
4876
+ this.saveIntakeClock(resetIntakeClock(Date.now()));
4877
+ }
4878
+ async loadIntakeClock(nowMs) {
4879
+ if (this._intakeClock) return this._intakeClock;
4880
+ let stored = null;
4881
+ try {
4882
+ stored = await this.user.getStrategyState(
4883
+ this.course.getCourseID(),
4884
+ INTAKE_CLOCK_KEY
4885
+ );
4886
+ } catch (e) {
4887
+ logger.warn(`[Pipeline:regulators] Could not read the intake clock: ${e}`);
4888
+ }
4889
+ if (stored) {
4890
+ this._intakeClock = stored;
4891
+ } else {
4892
+ this.saveIntakeClock(resetIntakeClock(nowMs));
4893
+ }
4894
+ return this._intakeClock;
4895
+ }
4896
+ saveIntakeClock(state) {
4897
+ this._intakeClock = state;
4898
+ const courseId = this.course.getCourseID();
4899
+ 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}`));
4900
+ }
4655
4901
  /**
4656
4902
  * Build shared context for generator and filters.
4657
4903
  *
@@ -4662,10 +4908,11 @@ var init_Pipeline = __esm({
4662
4908
  */
4663
4909
  async buildContext() {
4664
4910
  let userElo = 1e3;
4911
+ let userCourseElo;
4665
4912
  try {
4666
4913
  const courseReg = await this.user.getCourseRegDoc(this.course.getCourseID());
4667
- const courseElo = toCourseElo5(courseReg.elo);
4668
- userElo = courseElo.global.score;
4914
+ userCourseElo = toCourseElo5(courseReg.elo);
4915
+ userElo = userCourseElo.global.score;
4669
4916
  } catch (e) {
4670
4917
  logger.debug(`[Pipeline] Could not get user ELO, using default: ${e}`);
4671
4918
  }
@@ -4677,6 +4924,7 @@ var init_Pipeline = __esm({
4677
4924
  user: this.user,
4678
4925
  course: this.course,
4679
4926
  userElo,
4927
+ ...userCourseElo ? { userCourseElo } : {},
4680
4928
  orchestration
4681
4929
  };
4682
4930
  }
@@ -4790,7 +5038,7 @@ var init_Pipeline = __esm({
4790
5038
  cards = await this.hydrateTags(cards);
4791
5039
  const fullPool = cards.slice();
4792
5040
  const context = await this.buildContext();
4793
- for (const filter of this.filters) {
5041
+ for (const filter of this.forecastFilters()) {
4794
5042
  cards = await filter.transform(cards, context);
4795
5043
  }
4796
5044
  if (opts?.hints) {
@@ -4809,6 +5057,14 @@ var init_Pipeline = __esm({
4809
5057
  cards.sort((a, b) => b.score - a.score);
4810
5058
  return opts?.limit ? cards.slice(0, opts.limit) : cards;
4811
5059
  }
5060
+ /**
5061
+ * The filters a forecast or card-space scan applies. Those start every card at
5062
+ * 1.0 without a generator, so they skip `liveOnly` filters (ELO distance),
5063
+ * which only make sense against generator scores.
5064
+ */
5065
+ forecastFilters() {
5066
+ return this.filters.filter((f) => !f.liveOnly);
5067
+ }
4812
5068
  /**
4813
5069
  * Scan every card in the course through the filter chain and report
4814
5070
  * how many are "well indicated" (score >= threshold) for the current user.
@@ -4830,7 +5086,7 @@ var init_Pipeline = __esm({
4830
5086
  cards = await this.hydrateTags(cards);
4831
5087
  const context = await this.buildContext();
4832
5088
  const filterBreakdown = [];
4833
- for (const filter of this.filters) {
5089
+ for (const filter of this.forecastFilters()) {
4834
5090
  cards = await filter.transform(cards, context);
4835
5091
  const wi = cards.filter((c) => c.score >= THRESHOLD).length;
4836
5092
  filterBreakdown.push({ name: filter.name, wellIndicated: wi });
@@ -4894,6 +5150,7 @@ var init_Pipeline = __esm({
4894
5150
  // src/core/navigators/defaults.ts
4895
5151
  var defaults_exports = {};
4896
5152
  __export(defaults_exports, {
5153
+ createDefaultEloDistanceStrategy: () => createDefaultEloDistanceStrategy,
4897
5154
  createDefaultEloStrategy: () => createDefaultEloStrategy,
4898
5155
  createDefaultPipeline: () => createDefaultPipeline,
4899
5156
  createDefaultSrsStrategy: () => createDefaultSrsStrategy
@@ -4920,12 +5177,28 @@ function createDefaultSrsStrategy(courseId) {
4920
5177
  serializedData: ""
4921
5178
  };
4922
5179
  }
5180
+ function createDefaultEloDistanceStrategy(courseId) {
5181
+ return {
5182
+ _id: "NAVIGATION_STRATEGY-eloDistance-default",
5183
+ docType: "NAVIGATION_STRATEGY" /* NAVIGATION_STRATEGY */,
5184
+ name: "ELO Distance (default)",
5185
+ description: "Scales every candidate, new or review, by its distance from the learner's ELO",
5186
+ implementingClass: "eloDistance" /* ELO_DISTANCE */,
5187
+ course: courseId,
5188
+ // Explicit, though the filter would default to it anyway: views show what runs.
5189
+ serializedData: JSON.stringify(DEFAULT_ELO_DISTANCE_CONFIG)
5190
+ };
5191
+ }
4923
5192
  function createDefaultPipeline(user, course) {
4924
5193
  const courseId = course.getCourseID();
4925
5194
  const eloNavigator = new ELONavigator(user, course, createDefaultEloStrategy(courseId));
4926
5195
  const srsNavigator = new SRSNavigator(user, course, createDefaultSrsStrategy(courseId));
4927
5196
  const compositeGenerator = new CompositeGenerator([eloNavigator, srsNavigator]);
4928
- const eloDistanceFilter = createEloDistanceFilter();
5197
+ const eloDistanceFilter = new EloDistanceFilter(
5198
+ user,
5199
+ course,
5200
+ createDefaultEloDistanceStrategy(courseId)
5201
+ );
4929
5202
  return new Pipeline(compositeGenerator, [eloDistanceFilter], user, course);
4930
5203
  }
4931
5204
  var init_defaults = __esm({
@@ -4941,6 +5214,131 @@ var init_defaults = __esm({
4941
5214
  }
4942
5215
  });
4943
5216
 
5217
+ // src/core/navigators/pipelinePlan.ts
5218
+ var pipelinePlan_exports = {};
5219
+ __export(pipelinePlan_exports, {
5220
+ PIPELINE_STAGES: () => PIPELINE_STAGES,
5221
+ planPipeline: () => planPipeline
5222
+ });
5223
+ function planned(strategy, role, origin) {
5224
+ const kind = role === "filter" /* FILTER */ ? getRegisteredFilterKind(strategy.implementingClass) : void 0;
5225
+ return {
5226
+ role,
5227
+ origin,
5228
+ name: strategy.name,
5229
+ implementingClass: strategy.implementingClass,
5230
+ strategy,
5231
+ ...kind ? { kind } : {}
5232
+ };
5233
+ }
5234
+ function planPipeline(strategies, courseId) {
5235
+ if (strategies.length === 0) {
5236
+ return {
5237
+ kind: "default",
5238
+ generators: [
5239
+ planned(createDefaultEloStrategy(courseId), "generator" /* GENERATOR */, "default-pipeline"),
5240
+ planned(createDefaultSrsStrategy(courseId), "generator" /* GENERATOR */, "default-pipeline")
5241
+ ],
5242
+ filters: [
5243
+ planned(
5244
+ createDefaultEloDistanceStrategy(courseId),
5245
+ "filter" /* FILTER */,
5246
+ "default-pipeline"
5247
+ )
5248
+ ],
5249
+ skipped: [],
5250
+ warnings: [],
5251
+ notes: [],
5252
+ regulators: DEFAULT_REGULATOR_CONFIG
5253
+ };
5254
+ }
5255
+ const generators = [];
5256
+ const filters = [];
5257
+ const skipped = [];
5258
+ const warnings = [];
5259
+ for (const s of strategies) {
5260
+ if (isGenerator(s.implementingClass)) {
5261
+ generators.push(planned(s, "generator" /* GENERATOR */, "strategy-doc"));
5262
+ } else if (isFilter(s.implementingClass)) {
5263
+ filters.push(planned(s, "filter" /* FILTER */, "strategy-doc"));
5264
+ } else {
5265
+ skipped.push({ strategy: s, reason: "not a registered generator or filter" });
5266
+ warnings.push(`Unknown strategy type '${s.implementingClass}', skipping: ${s.name}`);
5267
+ }
5268
+ }
5269
+ const declared = new Set(generators.map((g) => g.implementingClass));
5270
+ if (!declared.has(createDefaultEloStrategy(courseId).implementingClass)) {
5271
+ generators.push(
5272
+ planned(createDefaultEloStrategy(courseId), "generator" /* GENERATOR */, "assembler-default")
5273
+ );
5274
+ }
5275
+ if (!declared.has(createDefaultSrsStrategy(courseId).implementingClass)) {
5276
+ generators.push(
5277
+ planned(createDefaultSrsStrategy(courseId), "generator" /* GENERATOR */, "assembler-default")
5278
+ );
5279
+ }
5280
+ const eloDistance = createDefaultEloDistanceStrategy(courseId);
5281
+ if (!filters.some((f) => f.implementingClass === eloDistance.implementingClass)) {
5282
+ filters.push(planned(eloDistance, "filter" /* FILTER */, "assembler-default"));
5283
+ }
5284
+ filters.sort((a, b) => a.name.localeCompare(b.name));
5285
+ return {
5286
+ kind: "assembled",
5287
+ generators,
5288
+ filters,
5289
+ skipped,
5290
+ warnings,
5291
+ notes: [],
5292
+ regulators: DEFAULT_REGULATOR_CONFIG
5293
+ };
5294
+ }
5295
+ var PIPELINE_STAGES;
5296
+ var init_pipelinePlan = __esm({
5297
+ "src/core/navigators/pipelinePlan.ts"() {
5298
+ "use strict";
5299
+ init_navigators();
5300
+ init_regulators();
5301
+ init_defaults();
5302
+ PIPELINE_STAGES = [
5303
+ {
5304
+ key: "generate",
5305
+ title: "Generate",
5306
+ 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."
5307
+ },
5308
+ {
5309
+ key: "filter",
5310
+ title: "Filter",
5311
+ 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."
5312
+ },
5313
+ {
5314
+ key: "drop-zero",
5315
+ title: "Drop zero scores",
5316
+ summary: "Candidates whose score reached 0 leave the pool."
5317
+ },
5318
+ {
5319
+ key: "regulate",
5320
+ title: "Regulate",
5321
+ 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."
5322
+ },
5323
+ {
5324
+ key: "hints",
5325
+ title: "Apply hints",
5326
+ 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."
5327
+ },
5328
+ {
5329
+ key: "diversity",
5330
+ title: "Diversity re-rank",
5331
+ 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."
5332
+ },
5333
+ {
5334
+ key: "select",
5335
+ title: "Select",
5336
+ summary: "Highest scores first, up to the run's limit. The session mixes them into its supply queue."
5337
+ }
5338
+ ];
5339
+ }
5340
+ });
5341
+
4944
5342
  // src/core/navigators/PipelineAssembler.ts
4945
5343
  var PipelineAssembler_exports = {};
4946
5344
  __export(PipelineAssembler_exports, {
@@ -4955,16 +5353,16 @@ var init_PipelineAssembler = __esm({
4955
5353
  init_Pipeline();
4956
5354
  init_logger();
4957
5355
  init_CompositeGenerator();
4958
- init_defaults();
5356
+ init_pipelinePlan();
4959
5357
  PipelineAssembler = class {
4960
5358
  /**
4961
5359
  * Assembles a navigation pipeline from strategy documents.
4962
5360
  *
4963
- * 1. Separates into generators and filters by role
4964
- * 2. Validates at least one generator exists (or creates default ELO)
4965
- * 3. Instantiates generators - wraps multiple in CompositeGenerator
4966
- * 4. Instantiates filters
4967
- * 5. Returns Pipeline(generator, filters)
5361
+ * 1. Plans: classifies by role, adds default ELO/SRS and ELO distance, orders filters
5362
+ * (`planPipeline`)
5363
+ * 2. Instantiates generators - wraps multiple in CompositeGenerator
5364
+ * 3. Instantiates filters
5365
+ * 4. Returns Pipeline(generator, filters)
4968
5366
  *
4969
5367
  * @param input - Strategy documents plus user/course interfaces
4970
5368
  * @returns Assembled pipeline and any warnings
@@ -4980,28 +5378,17 @@ var init_PipelineAssembler = __esm({
4980
5378
  warnings
4981
5379
  };
4982
5380
  }
4983
- const generatorStrategies = [];
4984
- const filterStrategies = [];
4985
- for (const s of strategies) {
4986
- if (isGenerator(s.implementingClass)) {
4987
- generatorStrategies.push(s);
4988
- } else if (isFilter(s.implementingClass)) {
4989
- filterStrategies.push(s);
4990
- } else {
4991
- warnings.push(`Unknown strategy type '${s.implementingClass}', skipping: ${s.name}`);
5381
+ const plan = planPipeline(strategies, course.getCourseID());
5382
+ warnings.push(...plan.warnings);
5383
+ for (const n of [...plan.generators, ...plan.filters]) {
5384
+ if (n.origin === "assembler-default") {
5385
+ logger.debug(
5386
+ `[PipelineAssembler] No ${n.implementingClass} ${n.role} configured, adding default`
5387
+ );
4992
5388
  }
4993
5389
  }
4994
- const courseId = course.getCourseID();
4995
- const hasElo = generatorStrategies.some((s) => s.implementingClass === "elo" /* ELO */);
4996
- const hasSrs = generatorStrategies.some((s) => s.implementingClass === "srs" /* SRS */);
4997
- if (!hasElo) {
4998
- logger.debug("[PipelineAssembler] No ELO generator configured, adding default");
4999
- generatorStrategies.push(createDefaultEloStrategy(courseId));
5000
- }
5001
- if (!hasSrs) {
5002
- logger.debug("[PipelineAssembler] No SRS generator configured, adding default");
5003
- generatorStrategies.push(createDefaultSrsStrategy(courseId));
5004
- }
5390
+ const generatorStrategies = plan.generators.map((g) => g.strategy);
5391
+ const sortedFilterStrategies = plan.filters.map((f) => f.strategy);
5005
5392
  if (generatorStrategies.length === 0) {
5006
5393
  warnings.push("No generator strategy found");
5007
5394
  return {
@@ -5023,9 +5410,6 @@ var init_PipelineAssembler = __esm({
5023
5410
  generator = await CompositeGenerator.fromStrategies(user, course, generatorStrategies);
5024
5411
  }
5025
5412
  const filters = [];
5026
- const sortedFilterStrategies = [...filterStrategies].sort(
5027
- (a, b) => a.name.localeCompare(b.name)
5028
- );
5029
5413
  for (const filterStrategy of sortedFilterStrategies) {
5030
5414
  try {
5031
5415
  const nav = await ContentNavigator.create(user, course, filterStrategy);
@@ -5093,7 +5477,9 @@ var init_3 = __esm({
5093
5477
  "./generators/prescribed.ts": () => Promise.resolve().then(() => (init_prescribed(), prescribed_exports)),
5094
5478
  "./generators/srs.ts": () => Promise.resolve().then(() => (init_srs(), srs_exports)),
5095
5479
  "./generators/types.ts": () => Promise.resolve().then(() => (init_types(), types_exports)),
5096
- "./index.ts": () => Promise.resolve().then(() => (init_navigators(), navigators_exports))
5480
+ "./index.ts": () => Promise.resolve().then(() => (init_navigators(), navigators_exports)),
5481
+ "./pipelinePlan.ts": () => Promise.resolve().then(() => (init_pipelinePlan(), pipelinePlan_exports)),
5482
+ "./regulators.ts": () => Promise.resolve().then(() => (init_regulators(), regulators_exports))
5097
5483
  });
5098
5484
  }
5099
5485
  });
@@ -5114,6 +5500,7 @@ __export(navigators_exports, {
5114
5500
  drainCapturedRuns: () => drainCapturedRuns,
5115
5501
  getActivePipeline: () => getActivePipeline,
5116
5502
  getCardOrigin: () => getCardOrigin,
5503
+ getRegisteredFilterKind: () => getRegisteredFilterKind,
5117
5504
  getRegisteredNavigator: () => getRegisteredNavigator,
5118
5505
  getRegisteredNavigatorNames: () => getRegisteredNavigatorNames,
5119
5506
  getRegisteredNavigatorRole: () => getRegisteredNavigatorRole,
@@ -5142,6 +5529,10 @@ function hasRegisteredNavigator(implementingClass) {
5142
5529
  function getRegisteredNavigatorRole(implementingClass) {
5143
5530
  return navigatorRegistry.get(implementingClass)?.role;
5144
5531
  }
5532
+ function getRegisteredFilterKind(implementingClass) {
5533
+ const ctor = navigatorRegistry.get(implementingClass)?.constructor;
5534
+ return ctor?.kind;
5535
+ }
5145
5536
  function getRegisteredNavigatorNames() {
5146
5537
  return Array.from(navigatorRegistry.keys());
5147
5538
  }
@@ -5159,17 +5550,20 @@ async function initializeNavigatorRegistry() {
5159
5550
  hierarchyModule,
5160
5551
  interferenceModule,
5161
5552
  relativePriorityModule,
5162
- userTagPreferenceModule
5553
+ userTagPreferenceModule,
5554
+ eloDistanceModule
5163
5555
  ] = await Promise.all([
5164
5556
  Promise.resolve().then(() => (init_hierarchyDefinition(), hierarchyDefinition_exports)),
5165
5557
  Promise.resolve().then(() => (init_interferenceMitigator(), interferenceMitigator_exports)),
5166
5558
  Promise.resolve().then(() => (init_relativePriority(), relativePriority_exports)),
5167
- Promise.resolve().then(() => (init_userTagPreference(), userTagPreference_exports))
5559
+ Promise.resolve().then(() => (init_userTagPreference(), userTagPreference_exports)),
5560
+ Promise.resolve().then(() => (init_eloDistance(), eloDistance_exports))
5168
5561
  ]);
5169
5562
  registerNavigator("hierarchyDefinition", hierarchyModule.default);
5170
5563
  registerNavigator("interferenceMitigator", interferenceModule.default);
5171
5564
  registerNavigator("relativePriority", relativePriorityModule.default);
5172
5565
  registerNavigator("userTagPreference", userTagPreferenceModule.default);
5566
+ registerNavigator("eloDistance", eloDistanceModule.default);
5173
5567
  logger.debug(
5174
5568
  `[NavigatorRegistry] Initialized ${navigatorRegistry.size} navigators: ${getRegisteredNavigatorNames().join(", ")}`
5175
5569
  );
@@ -5217,6 +5611,7 @@ var init_navigators = __esm({
5217
5611
  Navigators2["INTERFERENCE"] = "interferenceMitigator";
5218
5612
  Navigators2["RELATIVE_PRIORITY"] = "relativePriority";
5219
5613
  Navigators2["USER_TAG_PREFERENCE"] = "userTagPreference";
5614
+ Navigators2["ELO_DISTANCE"] = "eloDistance";
5220
5615
  return Navigators2;
5221
5616
  })(Navigators || {});
5222
5617
  NavigatorRole = /* @__PURE__ */ ((NavigatorRole2) => {
@@ -5231,7 +5626,8 @@ var init_navigators = __esm({
5231
5626
  ["hierarchyDefinition" /* HIERARCHY */]: "filter" /* FILTER */,
5232
5627
  ["interferenceMitigator" /* INTERFERENCE */]: "filter" /* FILTER */,
5233
5628
  ["relativePriority" /* RELATIVE_PRIORITY */]: "filter" /* FILTER */,
5234
- ["userTagPreference" /* USER_TAG_PREFERENCE */]: "filter" /* FILTER */
5629
+ ["userTagPreference" /* USER_TAG_PREFERENCE */]: "filter" /* FILTER */,
5630
+ ["eloDistance" /* ELO_DISTANCE */]: "filter" /* FILTER */
5235
5631
  };
5236
5632
  ContentNavigator = class {
5237
5633
  /** User interface for this navigation session */
@@ -6057,6 +6453,14 @@ ${e.stack}` : JSON.stringify(e);
6057
6453
  setEphemeralHints(hints) {
6058
6454
  this._pendingHints = hints;
6059
6455
  }
6456
+ /**
6457
+ * Forward a presentation to the navigator (a new card restarts its intake
6458
+ * clock). Builds the navigator if the cached one has expired.
6459
+ */
6460
+ notePresented(card) {
6461
+ if (card.status !== "new") return;
6462
+ void this._getCurrentUser().then((u) => this._getCachedNavigator(u)).then(({ navigator: navigator2 }) => navigator2.notePresented?.(card)).catch((e) => logger.warn(`[courseDB] Could not note a presentation: ${e}`));
6463
+ }
6060
6464
  async getWeightedCards(limit) {
6061
6465
  const u = await this._getCurrentUser();
6062
6466
  try {
@@ -8823,10 +9227,11 @@ function backlogHtml(backlog) {
8823
9227
  const rows = backlog.map((b) => {
8824
9228
  const hot = b.backlogMultiplier >= 3;
8825
9229
  const multColor = b.backlogMultiplier <= 1 ? "#86efac" : hot ? "#fca5a5" : "#fcd34d";
8826
- const headroom = b.backlogMultiplier > 1 ? `climbing (\xD7${b.backlogGrowthRate.toFixed(2)} per ${b.healthyBacklog}-review excess, unbounded)` : "healthy \u2014 no pressure";
9230
+ const headroom = b.backlogMultiplier > 1 ? `climbing (\xD7${b.backlogGrowthRate.toFixed(2)} per ${b.healthyBacklog} of mass in excess, unbounded)` : "healthy \u2014 no pressure";
9231
+ const mass = b.reviewMass !== null ? ` \xB7 mass ${b.reviewMass.toFixed(1)}` : "";
8827
9232
  const top = b.topReviewScore !== null ? b.topReviewScore.toFixed(2) : "\u2014";
8828
9233
  const next = b.nextDueIn ? ` <span style="opacity:.6">\xB7 next due ${esc(b.nextDueIn)}</span>` : "";
8829
- 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>`;
9234
+ 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>`;
8830
9235
  }).join("");
8831
9236
  return `<div style="margin-bottom:6px"><div style="color:#93c5fd">review backpressure</div>${rows}</div>`;
8832
9237
  }
@@ -8965,8 +9370,9 @@ function snapshotToText(s) {
8965
9370
  const headroom = b.backlogMultiplier > 1 ? "climbing" : "healthy";
8966
9371
  const top = b.topReviewScore !== null ? b.topReviewScore.toFixed(2) : "\u2014";
8967
9372
  const next = b.nextDueIn ? `, next due ${b.nextDueIn}` : "";
9373
+ const mass = b.reviewMass !== null ? `, mass ${b.reviewMass.toFixed(1)}` : "";
8968
9374
  lines.push(
8969
- ` ${b.courseId.slice(0, 8)}: due ${b.dueNow}/${b.scheduledTotal} (healthy ${b.healthyBacklog})${next}; pressure \xD7${b.backlogMultiplier.toFixed(2)} ${headroom}; top review ${top}`
9375
+ ` ${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}`
8970
9376
  );
8971
9377
  }
8972
9378
  }