@vue-skuilder/db 0.2.27 → 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 (82) hide show
  1. package/dist/classroomDB-DLTtLZct.d.cts +86 -0
  2. package/dist/classroomDB-DLTtLZct.d.ts +86 -0
  3. package/dist/{contentSource-LPf044hY.d.ts → contentSource-B6FrSihy.d.cts} +282 -99
  4. package/dist/{contentSource-D3c1fMAk.d.cts → contentSource-CqJmbOZN.d.ts} +282 -99
  5. package/dist/core/index.d.cts +16 -92
  6. package/dist/core/index.d.ts +16 -92
  7. package/dist/core/index.js +607 -179
  8. package/dist/core/index.js.map +1 -1
  9. package/dist/core/index.mjs +606 -179
  10. package/dist/core/index.mjs.map +1 -1
  11. package/dist/{dataLayerProvider-DaAootVV.d.ts → dataLayerProvider-B9_UCvkR.d.ts} +2 -8
  12. package/dist/{dataLayerProvider-CeLiFbHv.d.cts → dataLayerProvider-DUxDqMtZ.d.cts} +2 -8
  13. package/dist/diagnostics/index.d.cts +443 -0
  14. package/dist/diagnostics/index.d.ts +443 -0
  15. package/dist/diagnostics/index.js +932 -0
  16. package/dist/diagnostics/index.js.map +1 -0
  17. package/dist/diagnostics/index.mjs +881 -0
  18. package/dist/diagnostics/index.mjs.map +1 -0
  19. package/dist/impl/couch/index.d.cts +13 -3
  20. package/dist/impl/couch/index.d.ts +13 -3
  21. package/dist/impl/couch/index.js +605 -179
  22. package/dist/impl/couch/index.js.map +1 -1
  23. package/dist/impl/couch/index.mjs +605 -179
  24. package/dist/impl/couch/index.mjs.map +1 -1
  25. package/dist/impl/static/index.d.cts +11 -5
  26. package/dist/impl/static/index.d.ts +11 -5
  27. package/dist/impl/static/index.js +602 -185
  28. package/dist/impl/static/index.js.map +1 -1
  29. package/dist/impl/static/index.mjs +602 -185
  30. package/dist/impl/static/index.mjs.map +1 -1
  31. package/dist/{index-BkBJlGDX.d.ts → index-CVGehe_t.d.ts} +1 -1
  32. package/dist/{index-D7WdMDAs.d.cts → index-Ktg72jKb.d.cts} +1 -1
  33. package/dist/index.d.cts +73 -11
  34. package/dist/index.d.ts +73 -11
  35. package/dist/index.js +696 -200
  36. package/dist/index.js.map +1 -1
  37. package/dist/index.mjs +683 -200
  38. package/dist/index.mjs.map +1 -1
  39. package/dist/{types-DjiFOZxJ.d.cts → types-D0oQeJAi.d.cts} +1 -1
  40. package/dist/{types-uJ2Xn3_X.d.ts → types-dXWfyz9B.d.ts} +1 -1
  41. package/dist/{types-legacy-CrwyZIvI.d.cts → types-legacy-BkOYOR6U.d.cts} +1 -1
  42. package/dist/{types-legacy-CrwyZIvI.d.ts → types-legacy-BkOYOR6U.d.ts} +1 -1
  43. package/dist/util/packer/index.d.cts +3 -3
  44. package/dist/util/packer/index.d.ts +3 -3
  45. package/package.json +15 -3
  46. package/src/core/interfaces/contentSource.ts +7 -0
  47. package/src/core/interfaces/dataLayerProvider.ts +3 -8
  48. package/src/core/navigators/Pipeline.ts +149 -14
  49. package/src/core/navigators/PipelineAssembler.ts +19 -40
  50. package/src/core/navigators/PipelineDebugger.ts +74 -17
  51. package/src/core/navigators/SrsDebugger.ts +37 -12
  52. package/src/core/navigators/defaults.ts +29 -5
  53. package/src/core/navigators/filters/WeightedFilter.ts +5 -1
  54. package/src/core/navigators/filters/eloDistance.ts +261 -76
  55. package/src/core/navigators/filters/hierarchyDefinition.ts +5 -1
  56. package/src/core/navigators/filters/index.ts +2 -2
  57. package/src/core/navigators/filters/interferenceMitigator.ts +5 -1
  58. package/src/core/navigators/filters/relativePriority.ts +5 -1
  59. package/src/core/navigators/filters/types.ts +24 -1
  60. package/src/core/navigators/filters/userTagPreference.ts +5 -1
  61. package/src/core/navigators/generators/elo.ts +23 -53
  62. package/src/core/navigators/generators/srs.ts +27 -124
  63. package/src/core/navigators/index.ts +32 -5
  64. package/src/core/navigators/pipelinePlan.ts +245 -0
  65. package/src/core/navigators/regulators.ts +230 -0
  66. package/src/core/types/studySession.ts +40 -0
  67. package/src/diagnostics/dataset.ts +242 -0
  68. package/src/diagnostics/derive.ts +555 -0
  69. package/src/diagnostics/index.ts +27 -0
  70. package/src/diagnostics/loader.ts +194 -0
  71. package/src/diagnostics/pipeline.ts +236 -0
  72. package/src/diagnostics/text.ts +265 -0
  73. package/src/impl/couch/PouchDataLayerProvider.ts +0 -23
  74. package/src/impl/couch/courseDB.ts +13 -0
  75. package/src/impl/static/StaticDataLayerProvider.ts +0 -11
  76. package/src/impl/static/courseDB.ts +9 -0
  77. package/src/index.ts +4 -0
  78. package/src/study/SessionController.ts +76 -2
  79. package/src/study/SessionOverlay.ts +7 -4
  80. package/tests/core/navigators/PipelineAssembler.test.ts +20 -5
  81. package/tests/core/navigators/eloDistanceFilter.test.ts +9 -9
  82. package/tsup.config.ts +1 -0
@@ -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) {
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)
@@ -829,6 +829,23 @@ function buildRunReport(courseId, courseName, generatorName, generators, generat
829
829
  note: `${discardedTailCards.length} additional candidate(s) scored below the top ${DISCARDED_KEEP_TOP} near-misses and were not retained (score ${scoreMin.toExponential(2)}\u2013${scoreMax.toExponential(2)}${eloFragment}). Likely ELO-window pull remnants filtered out by hierarchy/lesson/priority gates.`
830
830
  };
831
831
  }
832
+ const isUnselectedNew = (c) => !c.reviewID && !selectedIds.has(c.cardId);
833
+ const generatorScore = (c) => c.provenance[0]?.score ?? 0;
834
+ const keptIds = new Set(allCards.map((c) => c.cardId));
835
+ const hintExcluded = (c) => c.score > 0 && !keptIds.has(c.cardId);
836
+ let nextInLine;
837
+ for (const c of allCards) {
838
+ if (isUnselectedNew(c) && (!nextInLine || c.score > nextInLine.score)) nextInLine = c;
839
+ }
840
+ let topGenerated;
841
+ for (const c of scoredCards ?? allCards) {
842
+ if (!isUnselectedNew(c) || hintExcluded(c)) continue;
843
+ if (!topGenerated || generatorScore(c) > generatorScore(topGenerated)) topGenerated = c;
844
+ }
845
+ const unselectedNew = nextInLine || topGenerated ? {
846
+ ...nextInLine ? { nextInLine: toReport(nextInLine) } : {},
847
+ ...topGenerated && topGenerated.cardId !== nextInLine?.cardId ? { topGenerated: toReport(topGenerated) } : {}
848
+ } : void 0;
832
849
  const reviewsSelected = selectedCards.filter((c) => getOrigin(c) === "review").length;
833
850
  const newSelected = selectedCards.filter((c) => getOrigin(c) === "new").length;
834
851
  return {
@@ -844,7 +861,9 @@ function buildRunReport(courseId, courseName, generatorName, generators, generat
844
861
  reviewsSelected,
845
862
  newSelected,
846
863
  cards,
847
- discardedTail
864
+ unselectedNew,
865
+ discardedTail,
866
+ ...regulators ? { regulators } : {}
848
867
  };
849
868
  }
850
869
  function formatProvenance(provenance) {
@@ -1568,11 +1587,23 @@ var SrsDebugger_exports = {};
1568
1587
  __export(SrsDebugger_exports, {
1569
1588
  captureSrsBacklog: () => captureSrsBacklog,
1570
1589
  clearSrsBacklogDebug: () => clearSrsBacklogDebug,
1571
- getSrsBacklogDebug: () => getSrsBacklogDebug
1590
+ getSrsBacklogDebug: () => getSrsBacklogDebug,
1591
+ noteReviewPressure: () => noteReviewPressure
1572
1592
  });
1573
1593
  function captureSrsBacklog(snapshot) {
1574
1594
  snapshots.set(snapshot.courseId, snapshot);
1575
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
+ }
1576
1607
  function getSrsBacklogDebug() {
1577
1608
  return [...snapshots.values()].sort((a, b) => b.timestamp - a.timestamp);
1578
1609
  }
@@ -1851,13 +1882,12 @@ __export(elo_exports, {
1851
1882
  default: () => ELONavigator
1852
1883
  });
1853
1884
  import { toCourseElo as toCourseElo2 } from "@vue-skuilder/common";
1854
- var ELO_RELEVANCE_SIGMA, ELONavigator;
1885
+ var ELONavigator;
1855
1886
  var init_elo = __esm({
1856
1887
  "src/core/navigators/generators/elo.ts"() {
1857
1888
  "use strict";
1858
1889
  init_navigators();
1859
1890
  init_logger();
1860
- ELO_RELEVANCE_SIGMA = 300;
1861
1891
  ELONavigator = class extends ContentNavigator {
1862
1892
  /** Human-readable name for CardGenerator interface */
1863
1893
  name;
@@ -1866,10 +1896,8 @@ var init_elo = __esm({
1866
1896
  this.name = strategyData?.name || "ELO";
1867
1897
  }
1868
1898
  /**
1869
- * Get new cards with suitability scores based on ELO distance.
1870
- *
1871
- * Cards closer to user's ELO get higher scores.
1872
- * 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.
1873
1901
  *
1874
1902
  * NOTE: This generator only handles NEW cards. Reviews are handled by
1875
1903
  * SRSNavigator. Use CompositeGenerator to combine both.
@@ -1897,20 +1925,20 @@ var init_elo = __esm({
1897
1925
  const scored = newCards.map((c) => {
1898
1926
  const cardElo = c.elo ?? 1e3;
1899
1927
  const distance = Math.abs(cardElo - userGlobalElo);
1900
- const relevance = Math.exp(-((distance / ELO_RELEVANCE_SIGMA) ** 2));
1901
- const samplingKey = relevance * (0.5 + 0.5 * Math.random());
1928
+ const jitter = 0.5 + 0.5 * Math.random();
1902
1929
  return {
1903
1930
  cardId: c.cardID,
1904
1931
  courseId: c.courseID,
1905
- score: samplingKey,
1932
+ score: jitter,
1933
+ cardElo,
1906
1934
  provenance: [
1907
1935
  {
1908
1936
  strategy: "elo",
1909
1937
  strategyName: this.strategyName || this.name,
1910
1938
  strategyId: this.strategyId || "NAVIGATION_STRATEGY-ELO-default",
1911
1939
  action: "generated",
1912
- score: samplingKey,
1913
- 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)}`
1914
1942
  }
1915
1943
  ]
1916
1944
  };
@@ -2786,43 +2814,132 @@ var init_prescribed = __esm({
2786
2814
  }
2787
2815
  });
2788
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
+
2789
2923
  // src/core/navigators/generators/srs.ts
2790
2924
  var srs_exports = {};
2791
2925
  __export(srs_exports, {
2792
2926
  default: () => SRSNavigator
2793
2927
  });
2794
2928
  import moment from "moment";
2795
- var DEFAULT_HEALTHY_BACKLOG, BACKLOG_GROWTH_RATE, SRSNavigator;
2929
+ var SRSNavigator;
2796
2930
  var init_srs = __esm({
2797
2931
  "src/core/navigators/generators/srs.ts"() {
2798
2932
  "use strict";
2799
2933
  init_navigators();
2800
2934
  init_SrsDebugger();
2935
+ init_regulators();
2801
2936
  init_logger();
2802
- DEFAULT_HEALTHY_BACKLOG = 20;
2803
- BACKLOG_GROWTH_RATE = 2;
2804
2937
  SRSNavigator = class extends ContentNavigator {
2805
2938
  /** Human-readable name for CardGenerator interface */
2806
2939
  name;
2807
- /** Healthy backlog threshold - when exceeded, backlog pressure kicks in */
2808
- healthyBacklog;
2809
2940
  constructor(user, course, strategyData) {
2810
2941
  super(user, course, strategyData);
2811
2942
  this.name = strategyData?.name || "SRS";
2812
- const config = this.parseConfig(strategyData?.serializedData);
2813
- this.healthyBacklog = config.healthyBacklog ?? DEFAULT_HEALTHY_BACKLOG;
2814
- }
2815
- /**
2816
- * Parse configuration from serialized JSON.
2817
- */
2818
- parseConfig(serializedData) {
2819
- if (!serializedData) return {};
2820
- try {
2821
- return JSON.parse(serializedData);
2822
- } catch {
2823
- logger.warn("[SRS] Failed to parse strategy config, using defaults");
2824
- return {};
2825
- }
2826
2943
  }
2827
2944
  /**
2828
2945
  * Get review cards scored by urgency.
@@ -2830,7 +2947,6 @@ var init_srs = __esm({
2830
2947
  * Score formula combines:
2831
2948
  * - Relative overdueness: hoursOverdue / intervalHours
2832
2949
  * - Interval recency: exponential decay favoring shorter intervals
2833
- * - Backlog pressure: boost when due reviews exceed healthy threshold
2834
2950
  *
2835
2951
  * Cards not yet due are excluded (not scored as 0).
2836
2952
  *
@@ -2867,7 +2983,6 @@ var init_srs = __esm({
2867
2983
  }
2868
2984
  }
2869
2985
  }
2870
- const backlogMultiplier = this.computeBacklogMultiplier(dueReviews.length);
2871
2986
  const notDue = reviews.filter((r) => !now.isAfter(moment.utc(r.reviewTime)));
2872
2987
  let nextDueIn = null;
2873
2988
  if (notDue.length > 0) {
@@ -2878,9 +2993,8 @@ var init_srs = __esm({
2878
2993
  nextDueIn = until.asHours() < 1 ? `${Math.round(until.asMinutes())}m` : until.asHours() < 24 ? `${Math.round(until.asHours())}h` : `${Math.round(until.asDays())}d`;
2879
2994
  }
2880
2995
  if (dueReviews.length > 0) {
2881
- const pressureNote = backlogMultiplier > 1 ? ` [backlog pressure: \xD7${backlogMultiplier.toFixed(2)}]` : ` [healthy backlog]`;
2882
2996
  logger.info(
2883
- `[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)`
2884
2998
  );
2885
2999
  } else if (reviews.length > 0) {
2886
3000
  const sortedByDue = [...reviews].sort(
@@ -2897,11 +3011,12 @@ var init_srs = __esm({
2897
3011
  logger.info(`[SRS] Course ${courseId}: No reviews scheduled`);
2898
3012
  }
2899
3013
  const scored = dueReviews.map((review) => {
2900
- const { score, reason } = this.computeUrgencyScore(review, now, backlogMultiplier);
3014
+ const { score, urgency, reason } = this.computeUrgencyScore(review, now);
2901
3015
  return {
2902
3016
  cardId: review.cardId,
2903
3017
  courseId: review.courseId,
2904
3018
  score,
3019
+ reviewUrgency: urgency,
2905
3020
  reviewID: review._id,
2906
3021
  provenance: [
2907
3022
  {
@@ -2920,47 +3035,20 @@ var init_srs = __esm({
2920
3035
  courseId,
2921
3036
  scheduledTotal: reviews.length,
2922
3037
  dueNow: dueReviews.length,
2923
- healthyBacklog: this.healthyBacklog,
2924
- backlogMultiplier,
2925
- backlogGrowthRate: BACKLOG_GROWTH_RATE,
3038
+ healthyBacklog: DEFAULT_REGULATOR_CONFIG.reviewMass.healthyMass,
3039
+ reviewMass: null,
3040
+ backlogMultiplier: 1,
3041
+ backlogGrowthRate: DEFAULT_REGULATOR_CONFIG.reviewMass.rate,
2926
3042
  topReviewScore: sorted.length > 0 ? sorted[0].score : null,
2927
3043
  nextDueIn,
2928
3044
  timestamp: Date.now()
2929
3045
  });
2930
3046
  return { cards: sorted.slice(0, limit) };
2931
3047
  }
2932
- /**
2933
- * Compute the multiplicative backlog pressure based on number of due reviews.
2934
- *
2935
- * ×1.0 at or below the healthy threshold (no boost); above it, grows as
2936
- * BACKLOG_GROWTH_RATE raised to the excess expressed in multiples of the
2937
- * healthy threshold. Uncapped — self-regulating instead: reviews winning
2938
- * slots depletes dueCount, which drops the ratio and relaxes the multiplier
2939
- * next run.
2940
- *
2941
- * Examples (with default healthyBacklog=20, BACKLOG_GROWTH_RATE=1.5):
2942
- * - 10 due reviews → ×1.00 (healthy)
2943
- * - 20 due reviews → ×1.00 (at threshold, ratio 0)
2944
- * - 40 due reviews → ×1.50 (ratio 1, 2x threshold)
2945
- * - 60 due reviews → ×2.25 (ratio 2, 3x threshold — old hard cap was ×2.00 here)
2946
- * - 100 due reviews → ×5.06 (ratio 4, 5x threshold)
2947
- * - 160 due reviews → ×17.09 (ratio 7, 8x threshold)
2948
- *
2949
- * @param dueCount - Number of reviews currently due
2950
- * @returns Multiplier applied to review urgency (>= 1.0, unbounded)
2951
- */
2952
- computeBacklogMultiplier(dueCount) {
2953
- if (dueCount <= this.healthyBacklog) {
2954
- return 1;
2955
- }
2956
- const excess = dueCount - this.healthyBacklog;
2957
- const ratio = excess / this.healthyBacklog;
2958
- return Math.pow(BACKLOG_GROWTH_RATE, ratio);
2959
- }
2960
3048
  /**
2961
3049
  * Compute urgency score for a review card.
2962
3050
  *
2963
- * Three factors:
3051
+ * Two factors:
2964
3052
  * 1. Relative overdueness = hoursOverdue / intervalHours
2965
3053
  * - 2 days overdue on 3-day interval = 0.67 (urgent)
2966
3054
  * - 2 days overdue on 180-day interval = 0.01 (not urgent)
@@ -2970,20 +3058,14 @@ var init_srs = __esm({
2970
3058
  * - 30 days (720h) → ~0.56
2971
3059
  * - 180 days → ~0.30
2972
3060
  *
2973
- * 3. Backlog pressure = global *multiplier* when review backlog exceeds the
2974
- * healthy threshold (×1.0 healthy → exponential growth, uncapped, above it).
2975
- *
2976
- * Combined: (base 0.5 + urgency factors * 0.45) × backlog multiplier.
2977
- * Per-card range before pressure: ~0.57–0.95. NOT clamped to 1.0 — under a
2978
- * heavy backlog reviews scale onto the open scale to compete with (and exceed)
2979
- * new cards; there's no ceiling at all now, so a bad enough backlog always
2980
- * 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).
2981
3064
  *
2982
3065
  * @param review - The scheduled card to score
2983
3066
  * @param now - Current time
2984
- * @param backlogMultiplier - Pre-computed backlog multiplier (>= 1.0, unbounded)
2985
3067
  */
2986
- computeUrgencyScore(review, now, backlogMultiplier) {
3068
+ computeUrgencyScore(review, now) {
2987
3069
  const scheduledAt = moment.utc(review.scheduledAt);
2988
3070
  const due = moment.utc(review.reviewTime);
2989
3071
  const intervalHours = Math.max(1, due.diff(scheduledAt, "hours"));
@@ -2992,20 +3074,16 @@ var init_srs = __esm({
2992
3074
  const recencyFactor = 0.3 + 0.7 * Math.exp(-intervalHours / 720);
2993
3075
  const overdueContribution = Math.min(1, Math.max(0, relativeOverdue));
2994
3076
  const urgency = overdueContribution * 0.5 + recencyFactor * 0.5;
2995
- const baseScore = 0.5 + urgency * 0.45;
2996
- const score = baseScore * backlogMultiplier;
3077
+ const score = 0.5 + urgency * 0.45;
2997
3078
  const reasonParts = [
2998
3079
  `${Math.round(hoursOverdue)}h overdue`,
2999
3080
  `interval: ${Math.round(intervalHours)}h`,
3000
3081
  `relative: ${relativeOverdue.toFixed(2)}`,
3001
3082
  `recency: ${recencyFactor.toFixed(2)}`
3002
3083
  ];
3003
- if (backlogMultiplier > 1) {
3004
- reasonParts.push(`backlog: \xD7${backlogMultiplier.toFixed(2)}`);
3005
- }
3006
3084
  reasonParts.push("review");
3007
3085
  const reason = reasonParts.join(", ");
3008
- return { score, reason };
3086
+ return { score, urgency, reason };
3009
3087
  }
3010
3088
  };
3011
3089
  }
@@ -3060,6 +3138,8 @@ var init_WeightedFilter = __esm({
3060
3138
  init_contentNavigationStrategy();
3061
3139
  WeightedFilter = class {
3062
3140
  name;
3141
+ kind;
3142
+ liveOnly;
3063
3143
  inner;
3064
3144
  learnable;
3065
3145
  staticWeight;
@@ -3067,6 +3147,8 @@ var init_WeightedFilter = __esm({
3067
3147
  constructor(inner, learnable = DEFAULT_LEARNABLE_WEIGHT, staticWeight = false, strategyId) {
3068
3148
  this.inner = inner;
3069
3149
  this.name = inner.name;
3150
+ this.kind = inner.kind;
3151
+ this.liveOnly = inner.liveOnly;
3070
3152
  this.learnable = learnable;
3071
3153
  this.staticWeight = staticWeight;
3072
3154
  this.strategyId = strategyId;
@@ -3131,58 +3213,141 @@ var init_WeightedFilter = __esm({
3131
3213
  // src/core/navigators/filters/eloDistance.ts
3132
3214
  var eloDistance_exports = {};
3133
3215
  __export(eloDistance_exports, {
3134
- DEFAULT_HALF_LIFE: () => DEFAULT_HALF_LIFE,
3135
- DEFAULT_MAX_MULTIPLIER: () => DEFAULT_MAX_MULTIPLIER,
3136
- DEFAULT_MIN_MULTIPLIER: () => DEFAULT_MIN_MULTIPLIER,
3137
- createEloDistanceFilter: () => createEloDistanceFilter
3216
+ DEFAULT_ELO_DISTANCE_CONFIG: () => DEFAULT_ELO_DISTANCE_CONFIG,
3217
+ createEloDistanceFilter: () => createEloDistanceFilter,
3218
+ default: () => EloDistanceFilter,
3219
+ tagAwareGap: () => tagAwareGap
3138
3220
  });
3139
3221
  function computeMultiplier(distance, halfLife, minMultiplier, maxMultiplier) {
3140
3222
  const normalizedDistance = distance / halfLife;
3141
3223
  const decay = Math.exp(-(normalizedDistance * normalizedDistance));
3142
3224
  return minMultiplier + (maxMultiplier - minMultiplier) * decay;
3143
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
+ }
3144
3296
  function createEloDistanceFilter(config) {
3145
- const halfLife = config?.halfLife ?? DEFAULT_HALF_LIFE;
3146
- const minMultiplier = config?.minMultiplier ?? DEFAULT_MIN_MULTIPLIER;
3147
- const maxMultiplier = config?.maxMultiplier ?? DEFAULT_MAX_MULTIPLIER;
3297
+ const resolved = resolveConfig(config);
3298
+ const source = { name: "ELO Distance Filter", strategyId: "ELO_DISTANCE_FILTER" };
3148
3299
  return {
3149
- name: "ELO Distance Filter",
3150
- async transform(cards, context) {
3151
- const { course, userElo } = context;
3152
- const cardIds = cards.map((c) => c.cardId);
3153
- const cardElos = await course.getCardEloData(cardIds);
3154
- return cards.map((card, i) => {
3155
- const cardElo = cardElos[i]?.global?.score ?? 1e3;
3156
- const distance = Math.abs(cardElo - userElo);
3157
- const multiplier = computeMultiplier(distance, halfLife, minMultiplier, maxMultiplier);
3158
- const newScore = card.score * multiplier;
3159
- const action = multiplier < maxMultiplier - 0.01 ? "penalized" : "passed";
3160
- return {
3161
- ...card,
3162
- score: newScore,
3163
- provenance: [
3164
- ...card.provenance,
3165
- {
3166
- strategy: "eloDistance",
3167
- strategyName: "ELO Distance Filter",
3168
- strategyId: "ELO_DISTANCE_FILTER",
3169
- action,
3170
- score: newScore,
3171
- reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userElo)}) \u2192 ${multiplier.toFixed(2)}x`
3172
- }
3173
- ]
3174
- };
3175
- });
3176
- }
3300
+ name: source.name,
3301
+ kind: "signal",
3302
+ liveOnly: true,
3303
+ transform: (cards, context) => applyEloDistance(cards, context, resolved, source)
3177
3304
  };
3178
3305
  }
3179
- 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;
3180
3307
  var init_eloDistance = __esm({
3181
3308
  "src/core/navigators/filters/eloDistance.ts"() {
3182
3309
  "use strict";
3183
- DEFAULT_HALF_LIFE = 200;
3184
- DEFAULT_MIN_MULTIPLIER = 0.3;
3185
- 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
+ };
3186
3351
  }
3187
3352
  });
3188
3353
 
@@ -3199,10 +3364,13 @@ var init_hierarchyDefinition = __esm({
3199
3364
  init_navigators();
3200
3365
  init_logger();
3201
3366
  DEFAULT_MIN_COUNT2 = 3;
3202
- HierarchyDefinitionNavigator = class extends ContentNavigator {
3367
+ HierarchyDefinitionNavigator = class _HierarchyDefinitionNavigator extends ContentNavigator {
3203
3368
  config;
3204
3369
  /** Human-readable name for CardFilter interface */
3205
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;
3206
3374
  constructor(user, course, strategyData) {
3207
3375
  super(user, course, strategyData);
3208
3376
  this.config = this.parseConfig(strategyData.serializedData);
@@ -3469,10 +3637,13 @@ var init_userTagPreference = __esm({
3469
3637
  "src/core/navigators/filters/userTagPreference.ts"() {
3470
3638
  "use strict";
3471
3639
  init_navigators();
3472
- UserTagPreferenceFilter = class extends ContentNavigator {
3640
+ UserTagPreferenceFilter = class _UserTagPreferenceFilter extends ContentNavigator {
3473
3641
  _strategyData;
3474
3642
  /** Human-readable name for CardFilter interface */
3475
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;
3476
3647
  constructor(user, course, strategyData) {
3477
3648
  super(user, course, strategyData);
3478
3649
  this._strategyData = strategyData;
@@ -3582,6 +3753,7 @@ var init_userTagPreference = __esm({
3582
3753
  // src/core/navigators/filters/index.ts
3583
3754
  var filters_exports = {};
3584
3755
  __export(filters_exports, {
3756
+ EloDistanceFilter: () => EloDistanceFilter,
3585
3757
  UserTagPreferenceFilter: () => UserTagPreferenceFilter,
3586
3758
  createEloDistanceFilter: () => createEloDistanceFilter
3587
3759
  });
@@ -3620,10 +3792,13 @@ var init_interferenceMitigator = __esm({
3620
3792
  DEFAULT_MIN_COUNT3 = 10;
3621
3793
  DEFAULT_MIN_ELAPSED_DAYS = 3;
3622
3794
  DEFAULT_INTERFERENCE_DECAY = 0.8;
3623
- InterferenceMitigatorNavigator = class extends ContentNavigator {
3795
+ InterferenceMitigatorNavigator = class _InterferenceMitigatorNavigator extends ContentNavigator {
3624
3796
  config;
3625
3797
  /** Human-readable name for CardFilter interface */
3626
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;
3627
3802
  /** Precomputed map: tag -> set of { partner, decay } it interferes with */
3628
3803
  interferenceMap;
3629
3804
  constructor(user, course, strategyData) {
@@ -3839,10 +4014,13 @@ var init_relativePriority = __esm({
3839
4014
  DEFAULT_PRIORITY = 0.5;
3840
4015
  DEFAULT_PRIORITY_INFLUENCE = 0.5;
3841
4016
  DEFAULT_COMBINE_MODE = "max";
3842
- RelativePriorityNavigator = class extends ContentNavigator {
4017
+ RelativePriorityNavigator = class _RelativePriorityNavigator extends ContentNavigator {
3843
4018
  config;
3844
4019
  /** Human-readable name for CardFilter interface */
3845
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;
3846
4024
  constructor(user, course, strategyData) {
3847
4025
  super(user, course, strategyData);
3848
4026
  this.config = this.parseConfig(strategyData.serializedData);
@@ -4250,6 +4428,8 @@ var init_Pipeline = __esm({
4250
4428
  init_orchestration();
4251
4429
  init_PipelineDebugger();
4252
4430
  init_diversityRerank();
4431
+ init_regulators();
4432
+ init_SrsDebugger();
4253
4433
  VERBOSE_RESULTS = true;
4254
4434
  Pipeline = class extends ContentNavigator {
4255
4435
  generator;
@@ -4275,6 +4455,13 @@ var init_Pipeline = __esm({
4275
4455
  * getWeightedCards() call, then cleared.
4276
4456
  */
4277
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();
4278
4465
  /**
4279
4466
  * Create a new pipeline.
4280
4467
  *
@@ -4349,13 +4536,12 @@ var init_Pipeline = __esm({
4349
4536
  }
4350
4537
  }
4351
4538
  generatorSummaries = Array.from(genMap.entries()).map(([name, data]) => {
4352
- const newCards = data.cards.filter((c) => c.provenance[0]?.reason?.includes("new card"));
4353
- const reviewCards = data.cards.filter((c) => c.provenance[0]?.reason?.includes("review"));
4539
+ const reviewCount = data.cards.filter((c) => c.reviewID).length;
4354
4540
  return {
4355
4541
  name,
4356
4542
  cardCount: data.cards.length,
4357
- newCount: newCards.length,
4358
- reviewCount: reviewCards.length,
4543
+ newCount: data.cards.length - reviewCount,
4544
+ reviewCount,
4359
4545
  topScore: Math.max(...data.cards.map((c) => c.score), 0)
4360
4546
  };
4361
4547
  });
@@ -4391,19 +4577,24 @@ var init_Pipeline = __esm({
4391
4577
  cards.filter((c) => c.provenance.some((p) => p.strategy === "prescribed")).map((c) => c.cardId)
4392
4578
  );
4393
4579
  const filterImpacts = [];
4580
+ const generatedScores = new Map(cards.map((c) => [c.cardId, c.score]));
4581
+ const gated = /* @__PURE__ */ new Set();
4394
4582
  for (const filter of this.filters) {
4395
4583
  const beforeCount = cards.length;
4396
4584
  const beforeScores = new Map(cards.map((c) => [c.cardId, c.score]));
4397
4585
  cards = await filter.transform(cards, context);
4398
4586
  let boosted = 0, penalized = 0, passed = 0;
4399
4587
  const removed = beforeCount - cards.length;
4588
+ const kind = filter.kind ?? "gate";
4400
4589
  for (const card of cards) {
4401
4590
  const before = beforeScores.get(card.cardId) ?? 0;
4402
4591
  if (card.score > before) boosted++;
4403
- else if (card.score < before) penalized++;
4404
- else passed++;
4592
+ else if (card.score < before) {
4593
+ penalized++;
4594
+ if (kind === "gate") gated.add(card.cardId);
4595
+ } else passed++;
4405
4596
  }
4406
- filterImpacts.push({ name: filter.name, boosted, penalized, passed, removed });
4597
+ filterImpacts.push({ name: filter.name, kind, boosted, penalized, passed, removed });
4407
4598
  if (prescribedIds.size > 0) {
4408
4599
  const survivingIds = new Set(cards.map((c) => c.cardId));
4409
4600
  const killedPrescribed = [...prescribedIds].filter((id) => !survivingIds.has(id));
@@ -4417,7 +4608,9 @@ var init_Pipeline = __esm({
4417
4608
  }
4418
4609
  logger.debug(`[Pipeline] Filter '${filter.name}': ${beforeScores.size} \u2192 ${cards.length} cards (\u2191${boosted} \u2193${penalized} =${passed})`);
4419
4610
  }
4611
+ const scoredCards = cards;
4420
4612
  cards = cards.filter((c) => c.score > 0);
4613
+ const regulators = await this.regulate(cards, generatedScores, gated);
4421
4614
  const hints = this._ephemeralHints;
4422
4615
  if (hints) {
4423
4616
  this._ephemeralHints = null;
@@ -4453,7 +4646,9 @@ var init_Pipeline = __esm({
4453
4646
  cards,
4454
4647
  result,
4455
4648
  context.userElo,
4456
- hints ?? void 0
4649
+ hints ?? void 0,
4650
+ scoredCards,
4651
+ regulators
4457
4652
  );
4458
4653
  captureRun(report);
4459
4654
  } catch (e) {
@@ -4632,6 +4827,77 @@ var init_Pipeline = __esm({
4632
4827
  logger.info(`[Pipeline] Hints applied: ${beforeCount} \u2192 ${cards.length} cards`);
4633
4828
  return cards;
4634
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
+ }
4635
4901
  /**
4636
4902
  * Build shared context for generator and filters.
4637
4903
  *
@@ -4642,10 +4908,11 @@ var init_Pipeline = __esm({
4642
4908
  */
4643
4909
  async buildContext() {
4644
4910
  let userElo = 1e3;
4911
+ let userCourseElo;
4645
4912
  try {
4646
4913
  const courseReg = await this.user.getCourseRegDoc(this.course.getCourseID());
4647
- const courseElo = toCourseElo5(courseReg.elo);
4648
- userElo = courseElo.global.score;
4914
+ userCourseElo = toCourseElo5(courseReg.elo);
4915
+ userElo = userCourseElo.global.score;
4649
4916
  } catch (e) {
4650
4917
  logger.debug(`[Pipeline] Could not get user ELO, using default: ${e}`);
4651
4918
  }
@@ -4657,6 +4924,7 @@ var init_Pipeline = __esm({
4657
4924
  user: this.user,
4658
4925
  course: this.course,
4659
4926
  userElo,
4927
+ ...userCourseElo ? { userCourseElo } : {},
4660
4928
  orchestration
4661
4929
  };
4662
4930
  }
@@ -4770,7 +5038,7 @@ var init_Pipeline = __esm({
4770
5038
  cards = await this.hydrateTags(cards);
4771
5039
  const fullPool = cards.slice();
4772
5040
  const context = await this.buildContext();
4773
- for (const filter of this.filters) {
5041
+ for (const filter of this.forecastFilters()) {
4774
5042
  cards = await filter.transform(cards, context);
4775
5043
  }
4776
5044
  if (opts?.hints) {
@@ -4789,6 +5057,14 @@ var init_Pipeline = __esm({
4789
5057
  cards.sort((a, b) => b.score - a.score);
4790
5058
  return opts?.limit ? cards.slice(0, opts.limit) : cards;
4791
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
+ }
4792
5068
  /**
4793
5069
  * Scan every card in the course through the filter chain and report
4794
5070
  * how many are "well indicated" (score >= threshold) for the current user.
@@ -4810,7 +5086,7 @@ var init_Pipeline = __esm({
4810
5086
  cards = await this.hydrateTags(cards);
4811
5087
  const context = await this.buildContext();
4812
5088
  const filterBreakdown = [];
4813
- for (const filter of this.filters) {
5089
+ for (const filter of this.forecastFilters()) {
4814
5090
  cards = await filter.transform(cards, context);
4815
5091
  const wi = cards.filter((c) => c.score >= THRESHOLD).length;
4816
5092
  filterBreakdown.push({ name: filter.name, wellIndicated: wi });
@@ -4874,6 +5150,7 @@ var init_Pipeline = __esm({
4874
5150
  // src/core/navigators/defaults.ts
4875
5151
  var defaults_exports = {};
4876
5152
  __export(defaults_exports, {
5153
+ createDefaultEloDistanceStrategy: () => createDefaultEloDistanceStrategy,
4877
5154
  createDefaultEloStrategy: () => createDefaultEloStrategy,
4878
5155
  createDefaultPipeline: () => createDefaultPipeline,
4879
5156
  createDefaultSrsStrategy: () => createDefaultSrsStrategy
@@ -4900,12 +5177,28 @@ function createDefaultSrsStrategy(courseId) {
4900
5177
  serializedData: ""
4901
5178
  };
4902
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
+ }
4903
5192
  function createDefaultPipeline(user, course) {
4904
5193
  const courseId = course.getCourseID();
4905
5194
  const eloNavigator = new ELONavigator(user, course, createDefaultEloStrategy(courseId));
4906
5195
  const srsNavigator = new SRSNavigator(user, course, createDefaultSrsStrategy(courseId));
4907
5196
  const compositeGenerator = new CompositeGenerator([eloNavigator, srsNavigator]);
4908
- const eloDistanceFilter = createEloDistanceFilter();
5197
+ const eloDistanceFilter = new EloDistanceFilter(
5198
+ user,
5199
+ course,
5200
+ createDefaultEloDistanceStrategy(courseId)
5201
+ );
4909
5202
  return new Pipeline(compositeGenerator, [eloDistanceFilter], user, course);
4910
5203
  }
4911
5204
  var init_defaults = __esm({
@@ -4921,6 +5214,131 @@ var init_defaults = __esm({
4921
5214
  }
4922
5215
  });
4923
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
+
4924
5342
  // src/core/navigators/PipelineAssembler.ts
4925
5343
  var PipelineAssembler_exports = {};
4926
5344
  __export(PipelineAssembler_exports, {
@@ -4935,16 +5353,16 @@ var init_PipelineAssembler = __esm({
4935
5353
  init_Pipeline();
4936
5354
  init_logger();
4937
5355
  init_CompositeGenerator();
4938
- init_defaults();
5356
+ init_pipelinePlan();
4939
5357
  PipelineAssembler = class {
4940
5358
  /**
4941
5359
  * Assembles a navigation pipeline from strategy documents.
4942
5360
  *
4943
- * 1. Separates into generators and filters by role
4944
- * 2. Validates at least one generator exists (or creates default ELO)
4945
- * 3. Instantiates generators - wraps multiple in CompositeGenerator
4946
- * 4. Instantiates filters
4947
- * 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)
4948
5366
  *
4949
5367
  * @param input - Strategy documents plus user/course interfaces
4950
5368
  * @returns Assembled pipeline and any warnings
@@ -4960,28 +5378,17 @@ var init_PipelineAssembler = __esm({
4960
5378
  warnings
4961
5379
  };
4962
5380
  }
4963
- const generatorStrategies = [];
4964
- const filterStrategies = [];
4965
- for (const s of strategies) {
4966
- if (isGenerator(s.implementingClass)) {
4967
- generatorStrategies.push(s);
4968
- } else if (isFilter(s.implementingClass)) {
4969
- filterStrategies.push(s);
4970
- } else {
4971
- 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
+ );
4972
5388
  }
4973
5389
  }
4974
- const courseId = course.getCourseID();
4975
- const hasElo = generatorStrategies.some((s) => s.implementingClass === "elo" /* ELO */);
4976
- const hasSrs = generatorStrategies.some((s) => s.implementingClass === "srs" /* SRS */);
4977
- if (!hasElo) {
4978
- logger.debug("[PipelineAssembler] No ELO generator configured, adding default");
4979
- generatorStrategies.push(createDefaultEloStrategy(courseId));
4980
- }
4981
- if (!hasSrs) {
4982
- logger.debug("[PipelineAssembler] No SRS generator configured, adding default");
4983
- generatorStrategies.push(createDefaultSrsStrategy(courseId));
4984
- }
5390
+ const generatorStrategies = plan.generators.map((g) => g.strategy);
5391
+ const sortedFilterStrategies = plan.filters.map((f) => f.strategy);
4985
5392
  if (generatorStrategies.length === 0) {
4986
5393
  warnings.push("No generator strategy found");
4987
5394
  return {
@@ -5003,9 +5410,6 @@ var init_PipelineAssembler = __esm({
5003
5410
  generator = await CompositeGenerator.fromStrategies(user, course, generatorStrategies);
5004
5411
  }
5005
5412
  const filters = [];
5006
- const sortedFilterStrategies = [...filterStrategies].sort(
5007
- (a, b) => a.name.localeCompare(b.name)
5008
- );
5009
5413
  for (const filterStrategy of sortedFilterStrategies) {
5010
5414
  try {
5011
5415
  const nav = await ContentNavigator.create(user, course, filterStrategy);
@@ -5073,7 +5477,9 @@ var init_3 = __esm({
5073
5477
  "./generators/prescribed.ts": () => Promise.resolve().then(() => (init_prescribed(), prescribed_exports)),
5074
5478
  "./generators/srs.ts": () => Promise.resolve().then(() => (init_srs(), srs_exports)),
5075
5479
  "./generators/types.ts": () => Promise.resolve().then(() => (init_types(), types_exports)),
5076
- "./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))
5077
5483
  });
5078
5484
  }
5079
5485
  });
@@ -5094,6 +5500,7 @@ __export(navigators_exports, {
5094
5500
  drainCapturedRuns: () => drainCapturedRuns,
5095
5501
  getActivePipeline: () => getActivePipeline,
5096
5502
  getCardOrigin: () => getCardOrigin,
5503
+ getRegisteredFilterKind: () => getRegisteredFilterKind,
5097
5504
  getRegisteredNavigator: () => getRegisteredNavigator,
5098
5505
  getRegisteredNavigatorNames: () => getRegisteredNavigatorNames,
5099
5506
  getRegisteredNavigatorRole: () => getRegisteredNavigatorRole,
@@ -5122,6 +5529,10 @@ function hasRegisteredNavigator(implementingClass) {
5122
5529
  function getRegisteredNavigatorRole(implementingClass) {
5123
5530
  return navigatorRegistry.get(implementingClass)?.role;
5124
5531
  }
5532
+ function getRegisteredFilterKind(implementingClass) {
5533
+ const ctor = navigatorRegistry.get(implementingClass)?.constructor;
5534
+ return ctor?.kind;
5535
+ }
5125
5536
  function getRegisteredNavigatorNames() {
5126
5537
  return Array.from(navigatorRegistry.keys());
5127
5538
  }
@@ -5139,17 +5550,20 @@ async function initializeNavigatorRegistry() {
5139
5550
  hierarchyModule,
5140
5551
  interferenceModule,
5141
5552
  relativePriorityModule,
5142
- userTagPreferenceModule
5553
+ userTagPreferenceModule,
5554
+ eloDistanceModule
5143
5555
  ] = await Promise.all([
5144
5556
  Promise.resolve().then(() => (init_hierarchyDefinition(), hierarchyDefinition_exports)),
5145
5557
  Promise.resolve().then(() => (init_interferenceMitigator(), interferenceMitigator_exports)),
5146
5558
  Promise.resolve().then(() => (init_relativePriority(), relativePriority_exports)),
5147
- Promise.resolve().then(() => (init_userTagPreference(), userTagPreference_exports))
5559
+ Promise.resolve().then(() => (init_userTagPreference(), userTagPreference_exports)),
5560
+ Promise.resolve().then(() => (init_eloDistance(), eloDistance_exports))
5148
5561
  ]);
5149
5562
  registerNavigator("hierarchyDefinition", hierarchyModule.default);
5150
5563
  registerNavigator("interferenceMitigator", interferenceModule.default);
5151
5564
  registerNavigator("relativePriority", relativePriorityModule.default);
5152
5565
  registerNavigator("userTagPreference", userTagPreferenceModule.default);
5566
+ registerNavigator("eloDistance", eloDistanceModule.default);
5153
5567
  logger.debug(
5154
5568
  `[NavigatorRegistry] Initialized ${navigatorRegistry.size} navigators: ${getRegisteredNavigatorNames().join(", ")}`
5155
5569
  );
@@ -5197,6 +5611,7 @@ var init_navigators = __esm({
5197
5611
  Navigators2["INTERFERENCE"] = "interferenceMitigator";
5198
5612
  Navigators2["RELATIVE_PRIORITY"] = "relativePriority";
5199
5613
  Navigators2["USER_TAG_PREFERENCE"] = "userTagPreference";
5614
+ Navigators2["ELO_DISTANCE"] = "eloDistance";
5200
5615
  return Navigators2;
5201
5616
  })(Navigators || {});
5202
5617
  NavigatorRole = /* @__PURE__ */ ((NavigatorRole2) => {
@@ -5211,7 +5626,8 @@ var init_navigators = __esm({
5211
5626
  ["hierarchyDefinition" /* HIERARCHY */]: "filter" /* FILTER */,
5212
5627
  ["interferenceMitigator" /* INTERFERENCE */]: "filter" /* FILTER */,
5213
5628
  ["relativePriority" /* RELATIVE_PRIORITY */]: "filter" /* FILTER */,
5214
- ["userTagPreference" /* USER_TAG_PREFERENCE */]: "filter" /* FILTER */
5629
+ ["userTagPreference" /* USER_TAG_PREFERENCE */]: "filter" /* FILTER */,
5630
+ ["eloDistance" /* ELO_DISTANCE */]: "filter" /* FILTER */
5215
5631
  };
5216
5632
  ContentNavigator = class {
5217
5633
  /** User interface for this navigation session */
@@ -6037,6 +6453,14 @@ ${e.stack}` : JSON.stringify(e);
6037
6453
  setEphemeralHints(hints) {
6038
6454
  this._pendingHints = hints;
6039
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
+ }
6040
6464
  async getWeightedCards(limit) {
6041
6465
  const u = await this._getCurrentUser();
6042
6466
  try {
@@ -8803,10 +9227,11 @@ function backlogHtml(backlog) {
8803
9227
  const rows = backlog.map((b) => {
8804
9228
  const hot = b.backlogMultiplier >= 3;
8805
9229
  const multColor = b.backlogMultiplier <= 1 ? "#86efac" : hot ? "#fca5a5" : "#fcd34d";
8806
- 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)}` : "";
8807
9232
  const top = b.topReviewScore !== null ? b.topReviewScore.toFixed(2) : "\u2014";
8808
9233
  const next = b.nextDueIn ? ` <span style="opacity:.6">\xB7 next due ${esc(b.nextDueIn)}</span>` : "";
8809
- 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>`;
8810
9235
  }).join("");
8811
9236
  return `<div style="margin-bottom:6px"><div style="color:#93c5fd">review backpressure</div>${rows}</div>`;
8812
9237
  }
@@ -8945,8 +9370,9 @@ function snapshotToText(s) {
8945
9370
  const headroom = b.backlogMultiplier > 1 ? "climbing" : "healthy";
8946
9371
  const top = b.topReviewScore !== null ? b.topReviewScore.toFixed(2) : "\u2014";
8947
9372
  const next = b.nextDueIn ? `, next due ${b.nextDueIn}` : "";
9373
+ const mass = b.reviewMass !== null ? `, mass ${b.reviewMass.toFixed(1)}` : "";
8948
9374
  lines.push(
8949
- ` ${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}`
8950
9376
  );
8951
9377
  }
8952
9378
  }