@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
@@ -798,7 +798,7 @@ function parseCardElo(provenance) {
798
798
  const match = eloEntry.reason.match(/card:\s*(\d+)/);
799
799
  return match ? parseInt(match[1], 10) : void 0;
800
800
  }
801
- function buildRunReport(courseId, courseName, generatorName, generators, generatedCount, filters, allCards, selectedCards, userElo, hints, scoredCards) {
801
+ function buildRunReport(courseId, courseName, generatorName, generators, generatedCount, filters, allCards, selectedCards, userElo, hints, scoredCards, regulators) {
802
802
  const selectedIds = new Set(selectedCards.map((c) => c.cardId));
803
803
  const toReport = (card) => ({
804
804
  cardId: card.cardId,
@@ -806,7 +806,7 @@ function buildRunReport(courseId, courseName, generatorName, generators, generat
806
806
  origin: getOrigin(card),
807
807
  generator: card.provenance[0]?.strategyName || card.provenance[0]?.strategy,
808
808
  finalScore: card.score,
809
- cardElo: parseCardElo(card.provenance),
809
+ cardElo: card.cardElo ?? parseCardElo(card.provenance),
810
810
  provenance: card.provenance,
811
811
  tags: card.tags,
812
812
  selected: selectedIds.has(card.cardId)
@@ -884,7 +884,8 @@ function buildRunReport(courseId, courseName, generatorName, generators, generat
884
884
  newSelected,
885
885
  cards,
886
886
  unselectedNew,
887
- discardedTail
887
+ discardedTail,
888
+ ...regulators ? { regulators } : {}
888
889
  };
889
890
  }
890
891
  function formatProvenance(provenance) {
@@ -1608,11 +1609,23 @@ var SrsDebugger_exports = {};
1608
1609
  __export(SrsDebugger_exports, {
1609
1610
  captureSrsBacklog: () => captureSrsBacklog,
1610
1611
  clearSrsBacklogDebug: () => clearSrsBacklogDebug,
1611
- getSrsBacklogDebug: () => getSrsBacklogDebug
1612
+ getSrsBacklogDebug: () => getSrsBacklogDebug,
1613
+ noteReviewPressure: () => noteReviewPressure
1612
1614
  });
1613
1615
  function captureSrsBacklog(snapshot) {
1614
1616
  snapshots.set(snapshot.courseId, snapshot);
1615
1617
  }
1618
+ function noteReviewPressure(courseId, pressure) {
1619
+ const snapshot = snapshots.get(courseId);
1620
+ if (!snapshot) return;
1621
+ snapshots.set(courseId, {
1622
+ ...snapshot,
1623
+ reviewMass: pressure.mass,
1624
+ healthyBacklog: pressure.healthyMass,
1625
+ backlogGrowthRate: pressure.rate,
1626
+ backlogMultiplier: pressure.multiplier
1627
+ });
1628
+ }
1616
1629
  function getSrsBacklogDebug() {
1617
1630
  return [...snapshots.values()].sort((a, b) => b.timestamp - a.timestamp);
1618
1631
  }
@@ -1890,14 +1903,13 @@ var elo_exports = {};
1890
1903
  __export(elo_exports, {
1891
1904
  default: () => ELONavigator
1892
1905
  });
1893
- var import_common5, ELO_RELEVANCE_SIGMA, ELONavigator;
1906
+ var import_common5, ELONavigator;
1894
1907
  var init_elo = __esm({
1895
1908
  "src/core/navigators/generators/elo.ts"() {
1896
1909
  "use strict";
1897
1910
  init_navigators();
1898
1911
  import_common5 = require("@vue-skuilder/common");
1899
1912
  init_logger();
1900
- ELO_RELEVANCE_SIGMA = 300;
1901
1913
  ELONavigator = class extends ContentNavigator {
1902
1914
  /** Human-readable name for CardGenerator interface */
1903
1915
  name;
@@ -1906,10 +1918,8 @@ var init_elo = __esm({
1906
1918
  this.name = strategyData?.name || "ELO";
1907
1919
  }
1908
1920
  /**
1909
- * Get new cards with suitability scores based on ELO distance.
1910
- *
1911
- * Cards closer to user's ELO get higher scores.
1912
- * Score formula: max(0, 1 - distance / 500)
1921
+ * Get the new cards nearest the learner's ELO, each scored with a flat
1922
+ * jitter in [0.5, 1]. Carries each card's ELO for the ELO distance filter.
1913
1923
  *
1914
1924
  * NOTE: This generator only handles NEW cards. Reviews are handled by
1915
1925
  * SRSNavigator. Use CompositeGenerator to combine both.
@@ -1937,20 +1947,20 @@ var init_elo = __esm({
1937
1947
  const scored = newCards.map((c) => {
1938
1948
  const cardElo = c.elo ?? 1e3;
1939
1949
  const distance = Math.abs(cardElo - userGlobalElo);
1940
- const relevance = Math.exp(-((distance / ELO_RELEVANCE_SIGMA) ** 2));
1941
- const samplingKey = relevance * (0.5 + 0.5 * Math.random());
1950
+ const jitter = 0.5 + 0.5 * Math.random();
1942
1951
  return {
1943
1952
  cardId: c.cardID,
1944
1953
  courseId: c.courseID,
1945
- score: samplingKey,
1954
+ score: jitter,
1955
+ cardElo,
1946
1956
  provenance: [
1947
1957
  {
1948
1958
  strategy: "elo",
1949
1959
  strategyName: this.strategyName || this.name,
1950
1960
  strategyId: this.strategyId || "NAVIGATION_STRATEGY-ELO-default",
1951
1961
  action: "generated",
1952
- score: samplingKey,
1953
- reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userGlobalElo)}), relevance ${relevance.toFixed(3)}, key ${samplingKey.toFixed(3)}`
1962
+ score: jitter,
1963
+ reason: `new card near learner ELO: distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userGlobalElo)}), jitter ${jitter.toFixed(3)}`
1954
1964
  }
1955
1965
  ]
1956
1966
  };
@@ -2826,43 +2836,132 @@ var init_prescribed = __esm({
2826
2836
  }
2827
2837
  });
2828
2838
 
2839
+ // src/core/navigators/regulators.ts
2840
+ var regulators_exports = {};
2841
+ __export(regulators_exports, {
2842
+ DEFAULT_REGULATOR_CONFIG: () => DEFAULT_REGULATOR_CONFIG,
2843
+ INTAKE_CLOCK_KEY: () => INTAKE_CLOCK_KEY,
2844
+ applyReading: () => applyReading,
2845
+ frozenMsAt: () => frozenMsAt,
2846
+ intakeHours: () => intakeHours,
2847
+ intakeReading: () => intakeReading,
2848
+ resetIntakeClock: () => resetIntakeClock,
2849
+ reviewMassReading: () => reviewMassReading,
2850
+ reviewWeight: () => reviewWeight,
2851
+ stepIntakeClock: () => stepIntakeClock
2852
+ });
2853
+ function clamp01(x) {
2854
+ return Math.min(1, Math.max(0, x));
2855
+ }
2856
+ function reviewWeight(card, generatedScore, referenceScore) {
2857
+ if (card.reviewUrgency !== void 0 && generatedScore !== void 0 && generatedScore > 0) {
2858
+ return clamp01(card.reviewUrgency * (card.score / generatedScore));
2859
+ }
2860
+ return clamp01(card.score / referenceScore);
2861
+ }
2862
+ function reviewMassReading(reviews, generatedScores, config = DEFAULT_REGULATOR_CONFIG.reviewMass) {
2863
+ const mass = reviews.reduce(
2864
+ (m, c) => m + reviewWeight(c, generatedScores.get(c.cardId), config.referenceScore),
2865
+ 0
2866
+ );
2867
+ const multiplier = mass > config.healthyMass ? Math.pow(config.rate, (mass - config.healthyMass) / config.healthyMass) : 1;
2868
+ return {
2869
+ name: "review-mass",
2870
+ class: "review",
2871
+ urgency: mass,
2872
+ multiplier,
2873
+ applied: reviews.length,
2874
+ inputs: { due: reviews.length, mass, healthyMass: config.healthyMass }
2875
+ };
2876
+ }
2877
+ function resetIntakeClock(nowMs) {
2878
+ return { lastNewAt: new Date(nowMs).toISOString(), frozenMs: 0, unservableSince: null };
2879
+ }
2880
+ function frozenMsAt(state, nowMs) {
2881
+ const open = state.unservableSince ? Math.max(0, nowMs - Date.parse(state.unservableSince)) : 0;
2882
+ return state.frozenMs + open;
2883
+ }
2884
+ function intakeHours(state, nowMs) {
2885
+ const elapsed = nowMs - Date.parse(state.lastNewAt);
2886
+ return Math.max(0, elapsed - frozenMsAt(state, nowMs)) / 36e5;
2887
+ }
2888
+ function stepIntakeClock(state, nowMs, eligibleNew) {
2889
+ if (eligibleNew === 0 && !state.unservableSince) {
2890
+ return { ...state, unservableSince: new Date(nowMs).toISOString() };
2891
+ }
2892
+ if (eligibleNew > 0 && state.unservableSince) {
2893
+ return { ...state, frozenMs: frozenMsAt(state, nowMs), unservableSince: null };
2894
+ }
2895
+ return state;
2896
+ }
2897
+ function intakeReading(state, nowMs, counts, config = DEFAULT_REGULATOR_CONFIG.intake) {
2898
+ const hours = intakeHours(state, nowMs);
2899
+ const multiplier = counts.eligibleNew > 0 ? Math.pow(config.rate, hours / config.scaleHours) : 1;
2900
+ return {
2901
+ name: "intake",
2902
+ class: "new",
2903
+ urgency: hours,
2904
+ multiplier,
2905
+ applied: counts.eligibleNew,
2906
+ inputs: {
2907
+ hoursSinceNew: hours,
2908
+ frozenHours: frozenMsAt(state, nowMs) / 36e5,
2909
+ eligibleNew: counts.eligibleNew,
2910
+ newCandidates: counts.newCandidates
2911
+ }
2912
+ };
2913
+ }
2914
+ function applyReading(cards, reading) {
2915
+ if (reading.multiplier === 1) return;
2916
+ 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)}`;
2917
+ for (const card of cards) {
2918
+ card.score *= reading.multiplier;
2919
+ card.provenance.push({
2920
+ strategy: "regulator",
2921
+ strategyName: `Regulator: ${REGULATOR_LABEL[reading.name]}`,
2922
+ strategyId: `regulator-${reading.name}`,
2923
+ action: reading.multiplier > 1 ? "boosted" : "penalized",
2924
+ score: card.score,
2925
+ reason
2926
+ });
2927
+ }
2928
+ }
2929
+ var DEFAULT_REGULATOR_CONFIG, INTAKE_CLOCK_KEY, REGULATOR_LABEL;
2930
+ var init_regulators = __esm({
2931
+ "src/core/navigators/regulators.ts"() {
2932
+ "use strict";
2933
+ DEFAULT_REGULATOR_CONFIG = {
2934
+ reviewMass: { referenceScore: 0.95, healthyMass: 20, rate: 2 },
2935
+ intake: { rate: 2, scaleHours: 24 }
2936
+ };
2937
+ INTAKE_CLOCK_KEY = "IntakeClock";
2938
+ REGULATOR_LABEL = {
2939
+ "review-mass": "Review mass",
2940
+ intake: "Intake"
2941
+ };
2942
+ }
2943
+ });
2944
+
2829
2945
  // src/core/navigators/generators/srs.ts
2830
2946
  var srs_exports = {};
2831
2947
  __export(srs_exports, {
2832
2948
  default: () => SRSNavigator
2833
2949
  });
2834
- var import_moment, DEFAULT_HEALTHY_BACKLOG, BACKLOG_GROWTH_RATE, SRSNavigator;
2950
+ var import_moment, SRSNavigator;
2835
2951
  var init_srs = __esm({
2836
2952
  "src/core/navigators/generators/srs.ts"() {
2837
2953
  "use strict";
2838
2954
  import_moment = __toESM(require("moment"), 1);
2839
2955
  init_navigators();
2840
2956
  init_SrsDebugger();
2957
+ init_regulators();
2841
2958
  init_logger();
2842
- DEFAULT_HEALTHY_BACKLOG = 20;
2843
- BACKLOG_GROWTH_RATE = 2;
2844
2959
  SRSNavigator = class extends ContentNavigator {
2845
2960
  /** Human-readable name for CardGenerator interface */
2846
2961
  name;
2847
- /** Healthy backlog threshold - when exceeded, backlog pressure kicks in */
2848
- healthyBacklog;
2849
2962
  constructor(user, course, strategyData) {
2850
2963
  super(user, course, strategyData);
2851
2964
  this.name = strategyData?.name || "SRS";
2852
- const config = this.parseConfig(strategyData?.serializedData);
2853
- this.healthyBacklog = config.healthyBacklog ?? DEFAULT_HEALTHY_BACKLOG;
2854
- }
2855
- /**
2856
- * Parse configuration from serialized JSON.
2857
- */
2858
- parseConfig(serializedData) {
2859
- if (!serializedData) return {};
2860
- try {
2861
- return JSON.parse(serializedData);
2862
- } catch {
2863
- logger.warn("[SRS] Failed to parse strategy config, using defaults");
2864
- return {};
2865
- }
2866
2965
  }
2867
2966
  /**
2868
2967
  * Get review cards scored by urgency.
@@ -2870,7 +2969,6 @@ var init_srs = __esm({
2870
2969
  * Score formula combines:
2871
2970
  * - Relative overdueness: hoursOverdue / intervalHours
2872
2971
  * - Interval recency: exponential decay favoring shorter intervals
2873
- * - Backlog pressure: boost when due reviews exceed healthy threshold
2874
2972
  *
2875
2973
  * Cards not yet due are excluded (not scored as 0).
2876
2974
  *
@@ -2907,7 +3005,6 @@ var init_srs = __esm({
2907
3005
  }
2908
3006
  }
2909
3007
  }
2910
- const backlogMultiplier = this.computeBacklogMultiplier(dueReviews.length);
2911
3008
  const notDue = reviews.filter((r) => !now.isAfter(import_moment.default.utc(r.reviewTime)));
2912
3009
  let nextDueIn = null;
2913
3010
  if (notDue.length > 0) {
@@ -2918,9 +3015,8 @@ var init_srs = __esm({
2918
3015
  nextDueIn = until.asHours() < 1 ? `${Math.round(until.asMinutes())}m` : until.asHours() < 24 ? `${Math.round(until.asHours())}h` : `${Math.round(until.asDays())}d`;
2919
3016
  }
2920
3017
  if (dueReviews.length > 0) {
2921
- const pressureNote = backlogMultiplier > 1 ? ` [backlog pressure: \xD7${backlogMultiplier.toFixed(2)}]` : ` [healthy backlog]`;
2922
3018
  logger.info(
2923
- `[SRS] Course ${courseId}: ${dueReviews.length} reviews due now (of ${reviews.length} scheduled)${pressureNote}`
3019
+ `[SRS] Course ${courseId}: ${dueReviews.length} reviews due now (of ${reviews.length} scheduled)`
2924
3020
  );
2925
3021
  } else if (reviews.length > 0) {
2926
3022
  const sortedByDue = [...reviews].sort(
@@ -2937,11 +3033,12 @@ var init_srs = __esm({
2937
3033
  logger.info(`[SRS] Course ${courseId}: No reviews scheduled`);
2938
3034
  }
2939
3035
  const scored = dueReviews.map((review) => {
2940
- const { score, reason } = this.computeUrgencyScore(review, now, backlogMultiplier);
3036
+ const { score, urgency, reason } = this.computeUrgencyScore(review, now);
2941
3037
  return {
2942
3038
  cardId: review.cardId,
2943
3039
  courseId: review.courseId,
2944
3040
  score,
3041
+ reviewUrgency: urgency,
2945
3042
  reviewID: review._id,
2946
3043
  provenance: [
2947
3044
  {
@@ -2960,47 +3057,20 @@ var init_srs = __esm({
2960
3057
  courseId,
2961
3058
  scheduledTotal: reviews.length,
2962
3059
  dueNow: dueReviews.length,
2963
- healthyBacklog: this.healthyBacklog,
2964
- backlogMultiplier,
2965
- backlogGrowthRate: BACKLOG_GROWTH_RATE,
3060
+ healthyBacklog: DEFAULT_REGULATOR_CONFIG.reviewMass.healthyMass,
3061
+ reviewMass: null,
3062
+ backlogMultiplier: 1,
3063
+ backlogGrowthRate: DEFAULT_REGULATOR_CONFIG.reviewMass.rate,
2966
3064
  topReviewScore: sorted.length > 0 ? sorted[0].score : null,
2967
3065
  nextDueIn,
2968
3066
  timestamp: Date.now()
2969
3067
  });
2970
3068
  return { cards: sorted.slice(0, limit) };
2971
3069
  }
2972
- /**
2973
- * Compute the multiplicative backlog pressure based on number of due reviews.
2974
- *
2975
- * ×1.0 at or below the healthy threshold (no boost); above it, grows as
2976
- * BACKLOG_GROWTH_RATE raised to the excess expressed in multiples of the
2977
- * healthy threshold. Uncapped — self-regulating instead: reviews winning
2978
- * slots depletes dueCount, which drops the ratio and relaxes the multiplier
2979
- * next run.
2980
- *
2981
- * Examples (with default healthyBacklog=20, BACKLOG_GROWTH_RATE=1.5):
2982
- * - 10 due reviews → ×1.00 (healthy)
2983
- * - 20 due reviews → ×1.00 (at threshold, ratio 0)
2984
- * - 40 due reviews → ×1.50 (ratio 1, 2x threshold)
2985
- * - 60 due reviews → ×2.25 (ratio 2, 3x threshold — old hard cap was ×2.00 here)
2986
- * - 100 due reviews → ×5.06 (ratio 4, 5x threshold)
2987
- * - 160 due reviews → ×17.09 (ratio 7, 8x threshold)
2988
- *
2989
- * @param dueCount - Number of reviews currently due
2990
- * @returns Multiplier applied to review urgency (>= 1.0, unbounded)
2991
- */
2992
- computeBacklogMultiplier(dueCount) {
2993
- if (dueCount <= this.healthyBacklog) {
2994
- return 1;
2995
- }
2996
- const excess = dueCount - this.healthyBacklog;
2997
- const ratio = excess / this.healthyBacklog;
2998
- return Math.pow(BACKLOG_GROWTH_RATE, ratio);
2999
- }
3000
3070
  /**
3001
3071
  * Compute urgency score for a review card.
3002
3072
  *
3003
- * Three factors:
3073
+ * Two factors:
3004
3074
  * 1. Relative overdueness = hoursOverdue / intervalHours
3005
3075
  * - 2 days overdue on 3-day interval = 0.67 (urgent)
3006
3076
  * - 2 days overdue on 180-day interval = 0.01 (not urgent)
@@ -3010,20 +3080,14 @@ var init_srs = __esm({
3010
3080
  * - 30 days (720h) → ~0.56
3011
3081
  * - 180 days → ~0.30
3012
3082
  *
3013
- * 3. Backlog pressure = global *multiplier* when review backlog exceeds the
3014
- * healthy threshold (×1.0 healthy → exponential growth, uncapped, above it).
3015
- *
3016
- * Combined: (base 0.5 + urgency factors * 0.45) × backlog multiplier.
3017
- * Per-card range before pressure: ~0.57–0.95. NOT clamped to 1.0 — under a
3018
- * heavy backlog reviews scale onto the open scale to compete with (and exceed)
3019
- * new cards; there's no ceiling at all now, so a bad enough backlog always
3020
- * wins eventually — self-regulating because winning slots depletes dueCount.
3083
+ * Combined: base 0.5 + urgency factors * 0.45, so ~0.57–0.95 per card.
3084
+ * Backlog pressure is applied later, by the regulator stage, which can lift
3085
+ * reviews onto the open scale above new cards (see regulators.ts).
3021
3086
  *
3022
3087
  * @param review - The scheduled card to score
3023
3088
  * @param now - Current time
3024
- * @param backlogMultiplier - Pre-computed backlog multiplier (>= 1.0, unbounded)
3025
3089
  */
3026
- computeUrgencyScore(review, now, backlogMultiplier) {
3090
+ computeUrgencyScore(review, now) {
3027
3091
  const scheduledAt = import_moment.default.utc(review.scheduledAt);
3028
3092
  const due = import_moment.default.utc(review.reviewTime);
3029
3093
  const intervalHours = Math.max(1, due.diff(scheduledAt, "hours"));
@@ -3032,20 +3096,16 @@ var init_srs = __esm({
3032
3096
  const recencyFactor = 0.3 + 0.7 * Math.exp(-intervalHours / 720);
3033
3097
  const overdueContribution = Math.min(1, Math.max(0, relativeOverdue));
3034
3098
  const urgency = overdueContribution * 0.5 + recencyFactor * 0.5;
3035
- const baseScore = 0.5 + urgency * 0.45;
3036
- const score = baseScore * backlogMultiplier;
3099
+ const score = 0.5 + urgency * 0.45;
3037
3100
  const reasonParts = [
3038
3101
  `${Math.round(hoursOverdue)}h overdue`,
3039
3102
  `interval: ${Math.round(intervalHours)}h`,
3040
3103
  `relative: ${relativeOverdue.toFixed(2)}`,
3041
3104
  `recency: ${recencyFactor.toFixed(2)}`
3042
3105
  ];
3043
- if (backlogMultiplier > 1) {
3044
- reasonParts.push(`backlog: \xD7${backlogMultiplier.toFixed(2)}`);
3045
- }
3046
3106
  reasonParts.push("review");
3047
3107
  const reason = reasonParts.join(", ");
3048
- return { score, reason };
3108
+ return { score, urgency, reason };
3049
3109
  }
3050
3110
  };
3051
3111
  }
@@ -3100,6 +3160,8 @@ var init_WeightedFilter = __esm({
3100
3160
  init_contentNavigationStrategy();
3101
3161
  WeightedFilter = class {
3102
3162
  name;
3163
+ kind;
3164
+ liveOnly;
3103
3165
  inner;
3104
3166
  learnable;
3105
3167
  staticWeight;
@@ -3107,6 +3169,8 @@ var init_WeightedFilter = __esm({
3107
3169
  constructor(inner, learnable = DEFAULT_LEARNABLE_WEIGHT, staticWeight = false, strategyId) {
3108
3170
  this.inner = inner;
3109
3171
  this.name = inner.name;
3172
+ this.kind = inner.kind;
3173
+ this.liveOnly = inner.liveOnly;
3110
3174
  this.learnable = learnable;
3111
3175
  this.staticWeight = staticWeight;
3112
3176
  this.strategyId = strategyId;
@@ -3171,58 +3235,141 @@ var init_WeightedFilter = __esm({
3171
3235
  // src/core/navigators/filters/eloDistance.ts
3172
3236
  var eloDistance_exports = {};
3173
3237
  __export(eloDistance_exports, {
3174
- DEFAULT_HALF_LIFE: () => DEFAULT_HALF_LIFE,
3175
- DEFAULT_MAX_MULTIPLIER: () => DEFAULT_MAX_MULTIPLIER,
3176
- DEFAULT_MIN_MULTIPLIER: () => DEFAULT_MIN_MULTIPLIER,
3177
- createEloDistanceFilter: () => createEloDistanceFilter
3238
+ DEFAULT_ELO_DISTANCE_CONFIG: () => DEFAULT_ELO_DISTANCE_CONFIG,
3239
+ createEloDistanceFilter: () => createEloDistanceFilter,
3240
+ default: () => EloDistanceFilter,
3241
+ tagAwareGap: () => tagAwareGap
3178
3242
  });
3179
3243
  function computeMultiplier(distance, halfLife, minMultiplier, maxMultiplier) {
3180
3244
  const normalizedDistance = distance / halfLife;
3181
3245
  const decay = Math.exp(-(normalizedDistance * normalizedDistance));
3182
3246
  return minMultiplier + (maxMultiplier - minMultiplier) * decay;
3183
3247
  }
3248
+ function resolveConfig(config) {
3249
+ return { ...DEFAULT_ELO_DISTANCE_CONFIG, ...config };
3250
+ }
3251
+ function tagAwareGap(cardTags, cardElo, userElo, minTagCount) {
3252
+ const globalGap = cardElo.global.score - userElo.global.score;
3253
+ const tags = [];
3254
+ for (const tag of cardTags) {
3255
+ const user = userElo.tags[tag];
3256
+ if (!user || user.score === COUNT_ONLY_SENTINEL || user.count < minTagCount) continue;
3257
+ const card = cardElo.tags[tag]?.score ?? cardElo.global.score;
3258
+ tags.push({
3259
+ tag,
3260
+ gap: card - user.score,
3261
+ weight: user.count / (user.count + TAG_CONFIDENCE_HALF)
3262
+ });
3263
+ }
3264
+ if (tags.length === 0) return { gap: globalGap, globalGap, tags };
3265
+ const total = tags.reduce((w, t) => w + t.weight, 0);
3266
+ const tagGap = tags.reduce((g, t) => g + t.weight * t.gap, 0) / total;
3267
+ const lambda = total / (total + 1);
3268
+ return { gap: lambda * tagGap + (1 - lambda) * globalGap, globalGap, tags };
3269
+ }
3270
+ function tagReason(tags, globalGap) {
3271
+ 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(", ");
3272
+ const more = tags.length > 3 ? `, +${tags.length - 3} more` : "";
3273
+ return ` on ${tags.length} shared tag(s) [${shown}${more}] (global ${globalGap >= 0 ? "+" : ""}${Math.round(globalGap)})`;
3274
+ }
3275
+ async function applyEloDistance(cards, context, config, source) {
3276
+ const { course, userElo, userCourseElo } = context;
3277
+ const { halfLife, minMultiplier, maxMultiplier } = config;
3278
+ const tagAware = config.tagAware && userCourseElo !== void 0;
3279
+ const missing = cards.filter((c) => tagAware || c.cardElo === void 0).map((c) => c.cardId);
3280
+ const fetched = /* @__PURE__ */ new Map();
3281
+ if (missing.length > 0) {
3282
+ const elos = await course.getCardEloData(missing);
3283
+ missing.forEach((id, i) => {
3284
+ if (elos[i]) fetched.set(id, elos[i]);
3285
+ });
3286
+ }
3287
+ return cards.map((card) => {
3288
+ const full = fetched.get(card.cardId);
3289
+ const cardElo = full?.global?.score ?? card.cardElo ?? DEFAULT_CARD_ELO;
3290
+ let distance = Math.abs(cardElo - userElo);
3291
+ let how = "";
3292
+ if (tagAware && full) {
3293
+ const t = tagAwareGap(card.tags ?? [], full, userCourseElo, config.minTagCount);
3294
+ distance = Math.abs(t.gap);
3295
+ if (t.tags.length > 0) how = tagReason(t.tags, t.globalGap);
3296
+ }
3297
+ const multiplier = computeMultiplier(distance, halfLife, minMultiplier, maxMultiplier);
3298
+ const newScore = card.score * multiplier;
3299
+ const action = multiplier < maxMultiplier - 0.01 ? "penalized" : "passed";
3300
+ return {
3301
+ ...card,
3302
+ cardElo,
3303
+ score: newScore,
3304
+ provenance: [
3305
+ ...card.provenance,
3306
+ {
3307
+ strategy: "eloDistance",
3308
+ strategyName: source.name,
3309
+ strategyId: source.strategyId,
3310
+ action,
3311
+ score: newScore,
3312
+ reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userElo)})${how} \u2192 ${multiplier.toFixed(2)}x`
3313
+ }
3314
+ ]
3315
+ };
3316
+ });
3317
+ }
3184
3318
  function createEloDistanceFilter(config) {
3185
- const halfLife = config?.halfLife ?? DEFAULT_HALF_LIFE;
3186
- const minMultiplier = config?.minMultiplier ?? DEFAULT_MIN_MULTIPLIER;
3187
- const maxMultiplier = config?.maxMultiplier ?? DEFAULT_MAX_MULTIPLIER;
3319
+ const resolved = resolveConfig(config);
3320
+ const source = { name: "ELO Distance Filter", strategyId: "ELO_DISTANCE_FILTER" };
3188
3321
  return {
3189
- name: "ELO Distance Filter",
3190
- async transform(cards, context) {
3191
- const { course, userElo } = context;
3192
- const cardIds = cards.map((c) => c.cardId);
3193
- const cardElos = await course.getCardEloData(cardIds);
3194
- return cards.map((card, i) => {
3195
- const cardElo = cardElos[i]?.global?.score ?? 1e3;
3196
- const distance = Math.abs(cardElo - userElo);
3197
- const multiplier = computeMultiplier(distance, halfLife, minMultiplier, maxMultiplier);
3198
- const newScore = card.score * multiplier;
3199
- const action = multiplier < maxMultiplier - 0.01 ? "penalized" : "passed";
3200
- return {
3201
- ...card,
3202
- score: newScore,
3203
- provenance: [
3204
- ...card.provenance,
3205
- {
3206
- strategy: "eloDistance",
3207
- strategyName: "ELO Distance Filter",
3208
- strategyId: "ELO_DISTANCE_FILTER",
3209
- action,
3210
- score: newScore,
3211
- reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userElo)}) \u2192 ${multiplier.toFixed(2)}x`
3212
- }
3213
- ]
3214
- };
3215
- });
3216
- }
3322
+ name: source.name,
3323
+ kind: "signal",
3324
+ liveOnly: true,
3325
+ transform: (cards, context) => applyEloDistance(cards, context, resolved, source)
3217
3326
  };
3218
3327
  }
3219
- var DEFAULT_HALF_LIFE, DEFAULT_MIN_MULTIPLIER, DEFAULT_MAX_MULTIPLIER;
3328
+ var DEFAULT_ELO_DISTANCE_CONFIG, TAG_CONFIDENCE_HALF, COUNT_ONLY_SENTINEL, DEFAULT_CARD_ELO, EloDistanceFilter;
3220
3329
  var init_eloDistance = __esm({
3221
3330
  "src/core/navigators/filters/eloDistance.ts"() {
3222
3331
  "use strict";
3223
- DEFAULT_HALF_LIFE = 200;
3224
- DEFAULT_MIN_MULTIPLIER = 0.3;
3225
- DEFAULT_MAX_MULTIPLIER = 1;
3332
+ init_navigators();
3333
+ DEFAULT_ELO_DISTANCE_CONFIG = {
3334
+ halfLife: 300,
3335
+ minMultiplier: 0.05,
3336
+ maxMultiplier: 1,
3337
+ tagAware: true,
3338
+ minTagCount: 3
3339
+ };
3340
+ TAG_CONFIDENCE_HALF = 10;
3341
+ COUNT_ONLY_SENTINEL = -1;
3342
+ DEFAULT_CARD_ELO = 1e3;
3343
+ EloDistanceFilter = class _EloDistanceFilter extends ContentNavigator {
3344
+ name;
3345
+ /** See CardFilter.kind. Static, so the pipeline plan can read it without an instance. */
3346
+ static kind = "signal";
3347
+ kind = _EloDistanceFilter.kind;
3348
+ liveOnly = true;
3349
+ config;
3350
+ constructor(user, course, strategyData) {
3351
+ super(user, course, strategyData);
3352
+ this.name = strategyData.name || "ELO Distance";
3353
+ let parsed;
3354
+ try {
3355
+ parsed = strategyData.serializedData ? JSON.parse(strategyData.serializedData) : void 0;
3356
+ } catch {
3357
+ parsed = void 0;
3358
+ }
3359
+ this.config = resolveConfig(parsed);
3360
+ }
3361
+ transform(cards, context) {
3362
+ return applyEloDistance(cards, context, this.config, {
3363
+ name: this.name,
3364
+ strategyId: this.strategyId || "NAVIGATION_STRATEGY-eloDistance-default"
3365
+ });
3366
+ }
3367
+ async getWeightedCards(_limit) {
3368
+ throw new Error(
3369
+ "EloDistanceFilter is a filter and should not be used as a generator. Use Pipeline with a generator and this filter via transform()."
3370
+ );
3371
+ }
3372
+ };
3226
3373
  }
3227
3374
  });
3228
3375
 
@@ -3239,10 +3386,13 @@ var init_hierarchyDefinition = __esm({
3239
3386
  import_common6 = require("@vue-skuilder/common");
3240
3387
  init_logger();
3241
3388
  DEFAULT_MIN_COUNT2 = 3;
3242
- HierarchyDefinitionNavigator = class extends ContentNavigator {
3389
+ HierarchyDefinitionNavigator = class _HierarchyDefinitionNavigator extends ContentNavigator {
3243
3390
  config;
3244
3391
  /** Human-readable name for CardFilter interface */
3245
3392
  name;
3393
+ /** See CardFilter.kind. Static, so the pipeline plan can read it without an instance. */
3394
+ static kind = "gate";
3395
+ kind = _HierarchyDefinitionNavigator.kind;
3246
3396
  constructor(user, course, strategyData) {
3247
3397
  super(user, course, strategyData);
3248
3398
  this.config = this.parseConfig(strategyData.serializedData);
@@ -3509,10 +3659,13 @@ var init_userTagPreference = __esm({
3509
3659
  "src/core/navigators/filters/userTagPreference.ts"() {
3510
3660
  "use strict";
3511
3661
  init_navigators();
3512
- UserTagPreferenceFilter = class extends ContentNavigator {
3662
+ UserTagPreferenceFilter = class _UserTagPreferenceFilter extends ContentNavigator {
3513
3663
  _strategyData;
3514
3664
  /** Human-readable name for CardFilter interface */
3515
3665
  name;
3666
+ /** See CardFilter.kind. Static, so the pipeline plan can read it without an instance. */
3667
+ static kind = "signal";
3668
+ kind = _UserTagPreferenceFilter.kind;
3516
3669
  constructor(user, course, strategyData) {
3517
3670
  super(user, course, strategyData);
3518
3671
  this._strategyData = strategyData;
@@ -3622,6 +3775,7 @@ var init_userTagPreference = __esm({
3622
3775
  // src/core/navigators/filters/index.ts
3623
3776
  var filters_exports = {};
3624
3777
  __export(filters_exports, {
3778
+ EloDistanceFilter: () => EloDistanceFilter,
3625
3779
  UserTagPreferenceFilter: () => UserTagPreferenceFilter,
3626
3780
  createEloDistanceFilter: () => createEloDistanceFilter
3627
3781
  });
@@ -3660,10 +3814,13 @@ var init_interferenceMitigator = __esm({
3660
3814
  DEFAULT_MIN_COUNT3 = 10;
3661
3815
  DEFAULT_MIN_ELAPSED_DAYS = 3;
3662
3816
  DEFAULT_INTERFERENCE_DECAY = 0.8;
3663
- InterferenceMitigatorNavigator = class extends ContentNavigator {
3817
+ InterferenceMitigatorNavigator = class _InterferenceMitigatorNavigator extends ContentNavigator {
3664
3818
  config;
3665
3819
  /** Human-readable name for CardFilter interface */
3666
3820
  name;
3821
+ /** See CardFilter.kind. Static, so the pipeline plan can read it without an instance. */
3822
+ static kind = "signal";
3823
+ kind = _InterferenceMitigatorNavigator.kind;
3667
3824
  /** Precomputed map: tag -> set of { partner, decay } it interferes with */
3668
3825
  interferenceMap;
3669
3826
  constructor(user, course, strategyData) {
@@ -3879,10 +4036,13 @@ var init_relativePriority = __esm({
3879
4036
  DEFAULT_PRIORITY = 0.5;
3880
4037
  DEFAULT_PRIORITY_INFLUENCE = 0.5;
3881
4038
  DEFAULT_COMBINE_MODE = "max";
3882
- RelativePriorityNavigator = class extends ContentNavigator {
4039
+ RelativePriorityNavigator = class _RelativePriorityNavigator extends ContentNavigator {
3883
4040
  config;
3884
4041
  /** Human-readable name for CardFilter interface */
3885
4042
  name;
4043
+ /** See CardFilter.kind. Static, so the pipeline plan can read it without an instance. */
4044
+ static kind = "signal";
4045
+ kind = _RelativePriorityNavigator.kind;
3886
4046
  constructor(user, course, strategyData) {
3887
4047
  super(user, course, strategyData);
3888
4048
  this.config = this.parseConfig(strategyData.serializedData);
@@ -4290,6 +4450,8 @@ var init_Pipeline = __esm({
4290
4450
  init_orchestration();
4291
4451
  init_PipelineDebugger();
4292
4452
  init_diversityRerank();
4453
+ init_regulators();
4454
+ init_SrsDebugger();
4293
4455
  VERBOSE_RESULTS = true;
4294
4456
  Pipeline = class extends ContentNavigator {
4295
4457
  generator;
@@ -4315,6 +4477,13 @@ var init_Pipeline = __esm({
4315
4477
  * getWeightedCards() call, then cleared.
4316
4478
  */
4317
4479
  _ephemeralHints = null;
4480
+ /**
4481
+ * The intake valve's clock (see regulators.ts), loaded from strategy state on
4482
+ * first use and kept in memory. Writes are chained so a presentation and a
4483
+ * run can't race each other's revision.
4484
+ */
4485
+ _intakeClock = null;
4486
+ _intakeClockWrite = Promise.resolve();
4318
4487
  /**
4319
4488
  * Create a new pipeline.
4320
4489
  *
@@ -4389,13 +4558,12 @@ var init_Pipeline = __esm({
4389
4558
  }
4390
4559
  }
4391
4560
  generatorSummaries = Array.from(genMap.entries()).map(([name, data]) => {
4392
- const newCards = data.cards.filter((c) => c.provenance[0]?.reason?.includes("new card"));
4393
- const reviewCards = data.cards.filter((c) => c.provenance[0]?.reason?.includes("review"));
4561
+ const reviewCount = data.cards.filter((c) => c.reviewID).length;
4394
4562
  return {
4395
4563
  name,
4396
4564
  cardCount: data.cards.length,
4397
- newCount: newCards.length,
4398
- reviewCount: reviewCards.length,
4565
+ newCount: data.cards.length - reviewCount,
4566
+ reviewCount,
4399
4567
  topScore: Math.max(...data.cards.map((c) => c.score), 0)
4400
4568
  };
4401
4569
  });
@@ -4431,19 +4599,24 @@ var init_Pipeline = __esm({
4431
4599
  cards.filter((c) => c.provenance.some((p) => p.strategy === "prescribed")).map((c) => c.cardId)
4432
4600
  );
4433
4601
  const filterImpacts = [];
4602
+ const generatedScores = new Map(cards.map((c) => [c.cardId, c.score]));
4603
+ const gated = /* @__PURE__ */ new Set();
4434
4604
  for (const filter of this.filters) {
4435
4605
  const beforeCount = cards.length;
4436
4606
  const beforeScores = new Map(cards.map((c) => [c.cardId, c.score]));
4437
4607
  cards = await filter.transform(cards, context);
4438
4608
  let boosted = 0, penalized = 0, passed = 0;
4439
4609
  const removed = beforeCount - cards.length;
4610
+ const kind = filter.kind ?? "gate";
4440
4611
  for (const card of cards) {
4441
4612
  const before = beforeScores.get(card.cardId) ?? 0;
4442
4613
  if (card.score > before) boosted++;
4443
- else if (card.score < before) penalized++;
4444
- else passed++;
4614
+ else if (card.score < before) {
4615
+ penalized++;
4616
+ if (kind === "gate") gated.add(card.cardId);
4617
+ } else passed++;
4445
4618
  }
4446
- filterImpacts.push({ name: filter.name, boosted, penalized, passed, removed });
4619
+ filterImpacts.push({ name: filter.name, kind, boosted, penalized, passed, removed });
4447
4620
  if (prescribedIds.size > 0) {
4448
4621
  const survivingIds = new Set(cards.map((c) => c.cardId));
4449
4622
  const killedPrescribed = [...prescribedIds].filter((id) => !survivingIds.has(id));
@@ -4459,6 +4632,7 @@ var init_Pipeline = __esm({
4459
4632
  }
4460
4633
  const scoredCards = cards;
4461
4634
  cards = cards.filter((c) => c.score > 0);
4635
+ const regulators = await this.regulate(cards, generatedScores, gated);
4462
4636
  const hints = this._ephemeralHints;
4463
4637
  if (hints) {
4464
4638
  this._ephemeralHints = null;
@@ -4495,7 +4669,8 @@ var init_Pipeline = __esm({
4495
4669
  result,
4496
4670
  context.userElo,
4497
4671
  hints ?? void 0,
4498
- scoredCards
4672
+ scoredCards,
4673
+ regulators
4499
4674
  );
4500
4675
  captureRun(report);
4501
4676
  } catch (e) {
@@ -4674,6 +4849,77 @@ var init_Pipeline = __esm({
4674
4849
  logger.info(`[Pipeline] Hints applied: ${beforeCount} \u2192 ${cards.length} cards`);
4675
4850
  return cards;
4676
4851
  }
4852
+ /**
4853
+ * The regulator stage: measure each class's pressure and scale it.
4854
+ *
4855
+ * - Review mass: every due review's SRS urgency times the filters' net
4856
+ * effect on it.
4857
+ * - Intake: servable hours since a new card was presented, applied only to
4858
+ * eligible new cards (no gate penalized them). With none eligible, the
4859
+ * clock freezes.
4860
+ *
4861
+ * Mutates `cards` in place; returns the readings for the run report.
4862
+ */
4863
+ async regulate(cards, generatedScores, gated) {
4864
+ const config = DEFAULT_REGULATOR_CONFIG;
4865
+ const reviews = cards.filter((c) => c.reviewID);
4866
+ const newCards = cards.filter((c) => !c.reviewID);
4867
+ const eligibleNew = newCards.filter((c) => !gated.has(c.cardId));
4868
+ const mass = reviewMassReading(reviews, generatedScores, config.reviewMass);
4869
+ applyReading(reviews, mass);
4870
+ noteReviewPressure(this.course.getCourseID(), {
4871
+ mass: mass.urgency,
4872
+ healthyMass: config.reviewMass.healthyMass,
4873
+ rate: config.reviewMass.rate,
4874
+ multiplier: mass.multiplier
4875
+ });
4876
+ const now = Date.now();
4877
+ const clock = await this.loadIntakeClock(now);
4878
+ const stepped = stepIntakeClock(clock, now, eligibleNew.length);
4879
+ if (stepped !== clock) this.saveIntakeClock(stepped);
4880
+ const intake = intakeReading(
4881
+ stepped,
4882
+ now,
4883
+ { eligibleNew: eligibleNew.length, newCandidates: newCards.length },
4884
+ config.intake
4885
+ );
4886
+ applyReading(eligibleNew, intake);
4887
+ logger.info(
4888
+ `[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)}`
4889
+ );
4890
+ return [mass, intake];
4891
+ }
4892
+ /**
4893
+ * A card was presented. A new card's first presentation discharges the
4894
+ * intake valve: its clock restarts. Called by the SessionController.
4895
+ */
4896
+ notePresented(card) {
4897
+ if (card.status !== "new" || card.courseId !== this.course?.getCourseID()) return;
4898
+ this.saveIntakeClock(resetIntakeClock(Date.now()));
4899
+ }
4900
+ async loadIntakeClock(nowMs) {
4901
+ if (this._intakeClock) return this._intakeClock;
4902
+ let stored = null;
4903
+ try {
4904
+ stored = await this.user.getStrategyState(
4905
+ this.course.getCourseID(),
4906
+ INTAKE_CLOCK_KEY
4907
+ );
4908
+ } catch (e) {
4909
+ logger.warn(`[Pipeline:regulators] Could not read the intake clock: ${e}`);
4910
+ }
4911
+ if (stored) {
4912
+ this._intakeClock = stored;
4913
+ } else {
4914
+ this.saveIntakeClock(resetIntakeClock(nowMs));
4915
+ }
4916
+ return this._intakeClock;
4917
+ }
4918
+ saveIntakeClock(state) {
4919
+ this._intakeClock = state;
4920
+ const courseId = this.course.getCourseID();
4921
+ 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}`));
4922
+ }
4677
4923
  /**
4678
4924
  * Build shared context for generator and filters.
4679
4925
  *
@@ -4684,10 +4930,11 @@ var init_Pipeline = __esm({
4684
4930
  */
4685
4931
  async buildContext() {
4686
4932
  let userElo = 1e3;
4933
+ let userCourseElo;
4687
4934
  try {
4688
4935
  const courseReg = await this.user.getCourseRegDoc(this.course.getCourseID());
4689
- const courseElo = (0, import_common8.toCourseElo)(courseReg.elo);
4690
- userElo = courseElo.global.score;
4936
+ userCourseElo = (0, import_common8.toCourseElo)(courseReg.elo);
4937
+ userElo = userCourseElo.global.score;
4691
4938
  } catch (e) {
4692
4939
  logger.debug(`[Pipeline] Could not get user ELO, using default: ${e}`);
4693
4940
  }
@@ -4699,6 +4946,7 @@ var init_Pipeline = __esm({
4699
4946
  user: this.user,
4700
4947
  course: this.course,
4701
4948
  userElo,
4949
+ ...userCourseElo ? { userCourseElo } : {},
4702
4950
  orchestration
4703
4951
  };
4704
4952
  }
@@ -4812,7 +5060,7 @@ var init_Pipeline = __esm({
4812
5060
  cards = await this.hydrateTags(cards);
4813
5061
  const fullPool = cards.slice();
4814
5062
  const context = await this.buildContext();
4815
- for (const filter of this.filters) {
5063
+ for (const filter of this.forecastFilters()) {
4816
5064
  cards = await filter.transform(cards, context);
4817
5065
  }
4818
5066
  if (opts?.hints) {
@@ -4831,6 +5079,14 @@ var init_Pipeline = __esm({
4831
5079
  cards.sort((a, b) => b.score - a.score);
4832
5080
  return opts?.limit ? cards.slice(0, opts.limit) : cards;
4833
5081
  }
5082
+ /**
5083
+ * The filters a forecast or card-space scan applies. Those start every card at
5084
+ * 1.0 without a generator, so they skip `liveOnly` filters (ELO distance),
5085
+ * which only make sense against generator scores.
5086
+ */
5087
+ forecastFilters() {
5088
+ return this.filters.filter((f) => !f.liveOnly);
5089
+ }
4834
5090
  /**
4835
5091
  * Scan every card in the course through the filter chain and report
4836
5092
  * how many are "well indicated" (score >= threshold) for the current user.
@@ -4852,7 +5108,7 @@ var init_Pipeline = __esm({
4852
5108
  cards = await this.hydrateTags(cards);
4853
5109
  const context = await this.buildContext();
4854
5110
  const filterBreakdown = [];
4855
- for (const filter of this.filters) {
5111
+ for (const filter of this.forecastFilters()) {
4856
5112
  cards = await filter.transform(cards, context);
4857
5113
  const wi = cards.filter((c) => c.score >= THRESHOLD).length;
4858
5114
  filterBreakdown.push({ name: filter.name, wellIndicated: wi });
@@ -4916,6 +5172,7 @@ var init_Pipeline = __esm({
4916
5172
  // src/core/navigators/defaults.ts
4917
5173
  var defaults_exports = {};
4918
5174
  __export(defaults_exports, {
5175
+ createDefaultEloDistanceStrategy: () => createDefaultEloDistanceStrategy,
4919
5176
  createDefaultEloStrategy: () => createDefaultEloStrategy,
4920
5177
  createDefaultPipeline: () => createDefaultPipeline,
4921
5178
  createDefaultSrsStrategy: () => createDefaultSrsStrategy
@@ -4942,12 +5199,28 @@ function createDefaultSrsStrategy(courseId) {
4942
5199
  serializedData: ""
4943
5200
  };
4944
5201
  }
5202
+ function createDefaultEloDistanceStrategy(courseId) {
5203
+ return {
5204
+ _id: "NAVIGATION_STRATEGY-eloDistance-default",
5205
+ docType: "NAVIGATION_STRATEGY" /* NAVIGATION_STRATEGY */,
5206
+ name: "ELO Distance (default)",
5207
+ description: "Scales every candidate, new or review, by its distance from the learner's ELO",
5208
+ implementingClass: "eloDistance" /* ELO_DISTANCE */,
5209
+ course: courseId,
5210
+ // Explicit, though the filter would default to it anyway: views show what runs.
5211
+ serializedData: JSON.stringify(DEFAULT_ELO_DISTANCE_CONFIG)
5212
+ };
5213
+ }
4945
5214
  function createDefaultPipeline(user, course) {
4946
5215
  const courseId = course.getCourseID();
4947
5216
  const eloNavigator = new ELONavigator(user, course, createDefaultEloStrategy(courseId));
4948
5217
  const srsNavigator = new SRSNavigator(user, course, createDefaultSrsStrategy(courseId));
4949
5218
  const compositeGenerator = new CompositeGenerator([eloNavigator, srsNavigator]);
4950
- const eloDistanceFilter = createEloDistanceFilter();
5219
+ const eloDistanceFilter = new EloDistanceFilter(
5220
+ user,
5221
+ course,
5222
+ createDefaultEloDistanceStrategy(courseId)
5223
+ );
4951
5224
  return new Pipeline(compositeGenerator, [eloDistanceFilter], user, course);
4952
5225
  }
4953
5226
  var init_defaults = __esm({
@@ -4963,6 +5236,131 @@ var init_defaults = __esm({
4963
5236
  }
4964
5237
  });
4965
5238
 
5239
+ // src/core/navigators/pipelinePlan.ts
5240
+ var pipelinePlan_exports = {};
5241
+ __export(pipelinePlan_exports, {
5242
+ PIPELINE_STAGES: () => PIPELINE_STAGES,
5243
+ planPipeline: () => planPipeline
5244
+ });
5245
+ function planned(strategy, role, origin) {
5246
+ const kind = role === "filter" /* FILTER */ ? getRegisteredFilterKind(strategy.implementingClass) : void 0;
5247
+ return {
5248
+ role,
5249
+ origin,
5250
+ name: strategy.name,
5251
+ implementingClass: strategy.implementingClass,
5252
+ strategy,
5253
+ ...kind ? { kind } : {}
5254
+ };
5255
+ }
5256
+ function planPipeline(strategies, courseId) {
5257
+ if (strategies.length === 0) {
5258
+ return {
5259
+ kind: "default",
5260
+ generators: [
5261
+ planned(createDefaultEloStrategy(courseId), "generator" /* GENERATOR */, "default-pipeline"),
5262
+ planned(createDefaultSrsStrategy(courseId), "generator" /* GENERATOR */, "default-pipeline")
5263
+ ],
5264
+ filters: [
5265
+ planned(
5266
+ createDefaultEloDistanceStrategy(courseId),
5267
+ "filter" /* FILTER */,
5268
+ "default-pipeline"
5269
+ )
5270
+ ],
5271
+ skipped: [],
5272
+ warnings: [],
5273
+ notes: [],
5274
+ regulators: DEFAULT_REGULATOR_CONFIG
5275
+ };
5276
+ }
5277
+ const generators = [];
5278
+ const filters = [];
5279
+ const skipped = [];
5280
+ const warnings = [];
5281
+ for (const s of strategies) {
5282
+ if (isGenerator(s.implementingClass)) {
5283
+ generators.push(planned(s, "generator" /* GENERATOR */, "strategy-doc"));
5284
+ } else if (isFilter(s.implementingClass)) {
5285
+ filters.push(planned(s, "filter" /* FILTER */, "strategy-doc"));
5286
+ } else {
5287
+ skipped.push({ strategy: s, reason: "not a registered generator or filter" });
5288
+ warnings.push(`Unknown strategy type '${s.implementingClass}', skipping: ${s.name}`);
5289
+ }
5290
+ }
5291
+ const declared = new Set(generators.map((g) => g.implementingClass));
5292
+ if (!declared.has(createDefaultEloStrategy(courseId).implementingClass)) {
5293
+ generators.push(
5294
+ planned(createDefaultEloStrategy(courseId), "generator" /* GENERATOR */, "assembler-default")
5295
+ );
5296
+ }
5297
+ if (!declared.has(createDefaultSrsStrategy(courseId).implementingClass)) {
5298
+ generators.push(
5299
+ planned(createDefaultSrsStrategy(courseId), "generator" /* GENERATOR */, "assembler-default")
5300
+ );
5301
+ }
5302
+ const eloDistance = createDefaultEloDistanceStrategy(courseId);
5303
+ if (!filters.some((f) => f.implementingClass === eloDistance.implementingClass)) {
5304
+ filters.push(planned(eloDistance, "filter" /* FILTER */, "assembler-default"));
5305
+ }
5306
+ filters.sort((a, b) => a.name.localeCompare(b.name));
5307
+ return {
5308
+ kind: "assembled",
5309
+ generators,
5310
+ filters,
5311
+ skipped,
5312
+ warnings,
5313
+ notes: [],
5314
+ regulators: DEFAULT_REGULATOR_CONFIG
5315
+ };
5316
+ }
5317
+ var PIPELINE_STAGES;
5318
+ var init_pipelinePlan = __esm({
5319
+ "src/core/navigators/pipelinePlan.ts"() {
5320
+ "use strict";
5321
+ init_navigators();
5322
+ init_regulators();
5323
+ init_defaults();
5324
+ PIPELINE_STAGES = [
5325
+ {
5326
+ key: "generate",
5327
+ title: "Generate",
5328
+ 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."
5329
+ },
5330
+ {
5331
+ key: "filter",
5332
+ title: "Filter",
5333
+ 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."
5334
+ },
5335
+ {
5336
+ key: "drop-zero",
5337
+ title: "Drop zero scores",
5338
+ summary: "Candidates whose score reached 0 leave the pool."
5339
+ },
5340
+ {
5341
+ key: "regulate",
5342
+ title: "Regulate",
5343
+ 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."
5344
+ },
5345
+ {
5346
+ key: "hints",
5347
+ title: "Apply hints",
5348
+ 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."
5349
+ },
5350
+ {
5351
+ key: "diversity",
5352
+ title: "Diversity re-rank",
5353
+ 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."
5354
+ },
5355
+ {
5356
+ key: "select",
5357
+ title: "Select",
5358
+ summary: "Highest scores first, up to the run's limit. The session mixes them into its supply queue."
5359
+ }
5360
+ ];
5361
+ }
5362
+ });
5363
+
4966
5364
  // src/core/navigators/PipelineAssembler.ts
4967
5365
  var PipelineAssembler_exports = {};
4968
5366
  __export(PipelineAssembler_exports, {
@@ -4977,16 +5375,16 @@ var init_PipelineAssembler = __esm({
4977
5375
  init_Pipeline();
4978
5376
  init_logger();
4979
5377
  init_CompositeGenerator();
4980
- init_defaults();
5378
+ init_pipelinePlan();
4981
5379
  PipelineAssembler = class {
4982
5380
  /**
4983
5381
  * Assembles a navigation pipeline from strategy documents.
4984
5382
  *
4985
- * 1. Separates into generators and filters by role
4986
- * 2. Validates at least one generator exists (or creates default ELO)
4987
- * 3. Instantiates generators - wraps multiple in CompositeGenerator
4988
- * 4. Instantiates filters
4989
- * 5. Returns Pipeline(generator, filters)
5383
+ * 1. Plans: classifies by role, adds default ELO/SRS and ELO distance, orders filters
5384
+ * (`planPipeline`)
5385
+ * 2. Instantiates generators - wraps multiple in CompositeGenerator
5386
+ * 3. Instantiates filters
5387
+ * 4. Returns Pipeline(generator, filters)
4990
5388
  *
4991
5389
  * @param input - Strategy documents plus user/course interfaces
4992
5390
  * @returns Assembled pipeline and any warnings
@@ -5002,28 +5400,17 @@ var init_PipelineAssembler = __esm({
5002
5400
  warnings
5003
5401
  };
5004
5402
  }
5005
- const generatorStrategies = [];
5006
- const filterStrategies = [];
5007
- for (const s of strategies) {
5008
- if (isGenerator(s.implementingClass)) {
5009
- generatorStrategies.push(s);
5010
- } else if (isFilter(s.implementingClass)) {
5011
- filterStrategies.push(s);
5012
- } else {
5013
- warnings.push(`Unknown strategy type '${s.implementingClass}', skipping: ${s.name}`);
5403
+ const plan = planPipeline(strategies, course.getCourseID());
5404
+ warnings.push(...plan.warnings);
5405
+ for (const n of [...plan.generators, ...plan.filters]) {
5406
+ if (n.origin === "assembler-default") {
5407
+ logger.debug(
5408
+ `[PipelineAssembler] No ${n.implementingClass} ${n.role} configured, adding default`
5409
+ );
5014
5410
  }
5015
5411
  }
5016
- const courseId = course.getCourseID();
5017
- const hasElo = generatorStrategies.some((s) => s.implementingClass === "elo" /* ELO */);
5018
- const hasSrs = generatorStrategies.some((s) => s.implementingClass === "srs" /* SRS */);
5019
- if (!hasElo) {
5020
- logger.debug("[PipelineAssembler] No ELO generator configured, adding default");
5021
- generatorStrategies.push(createDefaultEloStrategy(courseId));
5022
- }
5023
- if (!hasSrs) {
5024
- logger.debug("[PipelineAssembler] No SRS generator configured, adding default");
5025
- generatorStrategies.push(createDefaultSrsStrategy(courseId));
5026
- }
5412
+ const generatorStrategies = plan.generators.map((g) => g.strategy);
5413
+ const sortedFilterStrategies = plan.filters.map((f) => f.strategy);
5027
5414
  if (generatorStrategies.length === 0) {
5028
5415
  warnings.push("No generator strategy found");
5029
5416
  return {
@@ -5045,9 +5432,6 @@ var init_PipelineAssembler = __esm({
5045
5432
  generator = await CompositeGenerator.fromStrategies(user, course, generatorStrategies);
5046
5433
  }
5047
5434
  const filters = [];
5048
- const sortedFilterStrategies = [...filterStrategies].sort(
5049
- (a, b) => a.name.localeCompare(b.name)
5050
- );
5051
5435
  for (const filterStrategy of sortedFilterStrategies) {
5052
5436
  try {
5053
5437
  const nav = await ContentNavigator.create(user, course, filterStrategy);
@@ -5115,7 +5499,9 @@ var init_3 = __esm({
5115
5499
  "./generators/prescribed.ts": () => Promise.resolve().then(() => (init_prescribed(), prescribed_exports)),
5116
5500
  "./generators/srs.ts": () => Promise.resolve().then(() => (init_srs(), srs_exports)),
5117
5501
  "./generators/types.ts": () => Promise.resolve().then(() => (init_types(), types_exports)),
5118
- "./index.ts": () => Promise.resolve().then(() => (init_navigators(), navigators_exports))
5502
+ "./index.ts": () => Promise.resolve().then(() => (init_navigators(), navigators_exports)),
5503
+ "./pipelinePlan.ts": () => Promise.resolve().then(() => (init_pipelinePlan(), pipelinePlan_exports)),
5504
+ "./regulators.ts": () => Promise.resolve().then(() => (init_regulators(), regulators_exports))
5119
5505
  });
5120
5506
  }
5121
5507
  });
@@ -5136,6 +5522,7 @@ __export(navigators_exports, {
5136
5522
  drainCapturedRuns: () => drainCapturedRuns,
5137
5523
  getActivePipeline: () => getActivePipeline,
5138
5524
  getCardOrigin: () => getCardOrigin,
5525
+ getRegisteredFilterKind: () => getRegisteredFilterKind,
5139
5526
  getRegisteredNavigator: () => getRegisteredNavigator,
5140
5527
  getRegisteredNavigatorNames: () => getRegisteredNavigatorNames,
5141
5528
  getRegisteredNavigatorRole: () => getRegisteredNavigatorRole,
@@ -5164,6 +5551,10 @@ function hasRegisteredNavigator(implementingClass) {
5164
5551
  function getRegisteredNavigatorRole(implementingClass) {
5165
5552
  return navigatorRegistry.get(implementingClass)?.role;
5166
5553
  }
5554
+ function getRegisteredFilterKind(implementingClass) {
5555
+ const ctor = navigatorRegistry.get(implementingClass)?.constructor;
5556
+ return ctor?.kind;
5557
+ }
5167
5558
  function getRegisteredNavigatorNames() {
5168
5559
  return Array.from(navigatorRegistry.keys());
5169
5560
  }
@@ -5181,17 +5572,20 @@ async function initializeNavigatorRegistry() {
5181
5572
  hierarchyModule,
5182
5573
  interferenceModule,
5183
5574
  relativePriorityModule,
5184
- userTagPreferenceModule
5575
+ userTagPreferenceModule,
5576
+ eloDistanceModule
5185
5577
  ] = await Promise.all([
5186
5578
  Promise.resolve().then(() => (init_hierarchyDefinition(), hierarchyDefinition_exports)),
5187
5579
  Promise.resolve().then(() => (init_interferenceMitigator(), interferenceMitigator_exports)),
5188
5580
  Promise.resolve().then(() => (init_relativePriority(), relativePriority_exports)),
5189
- Promise.resolve().then(() => (init_userTagPreference(), userTagPreference_exports))
5581
+ Promise.resolve().then(() => (init_userTagPreference(), userTagPreference_exports)),
5582
+ Promise.resolve().then(() => (init_eloDistance(), eloDistance_exports))
5190
5583
  ]);
5191
5584
  registerNavigator("hierarchyDefinition", hierarchyModule.default);
5192
5585
  registerNavigator("interferenceMitigator", interferenceModule.default);
5193
5586
  registerNavigator("relativePriority", relativePriorityModule.default);
5194
5587
  registerNavigator("userTagPreference", userTagPreferenceModule.default);
5588
+ registerNavigator("eloDistance", eloDistanceModule.default);
5195
5589
  logger.debug(
5196
5590
  `[NavigatorRegistry] Initialized ${navigatorRegistry.size} navigators: ${getRegisteredNavigatorNames().join(", ")}`
5197
5591
  );
@@ -5239,6 +5633,7 @@ var init_navigators = __esm({
5239
5633
  Navigators2["INTERFERENCE"] = "interferenceMitigator";
5240
5634
  Navigators2["RELATIVE_PRIORITY"] = "relativePriority";
5241
5635
  Navigators2["USER_TAG_PREFERENCE"] = "userTagPreference";
5636
+ Navigators2["ELO_DISTANCE"] = "eloDistance";
5242
5637
  return Navigators2;
5243
5638
  })(Navigators || {});
5244
5639
  NavigatorRole = /* @__PURE__ */ ((NavigatorRole2) => {
@@ -5253,7 +5648,8 @@ var init_navigators = __esm({
5253
5648
  ["hierarchyDefinition" /* HIERARCHY */]: "filter" /* FILTER */,
5254
5649
  ["interferenceMitigator" /* INTERFERENCE */]: "filter" /* FILTER */,
5255
5650
  ["relativePriority" /* RELATIVE_PRIORITY */]: "filter" /* FILTER */,
5256
- ["userTagPreference" /* USER_TAG_PREFERENCE */]: "filter" /* FILTER */
5651
+ ["userTagPreference" /* USER_TAG_PREFERENCE */]: "filter" /* FILTER */,
5652
+ ["eloDistance" /* ELO_DISTANCE */]: "filter" /* FILTER */
5257
5653
  };
5258
5654
  ContentNavigator = class {
5259
5655
  /** User interface for this navigation session */
@@ -6074,6 +6470,14 @@ ${e.stack}` : JSON.stringify(e);
6074
6470
  setEphemeralHints(hints) {
6075
6471
  this._pendingHints = hints;
6076
6472
  }
6473
+ /**
6474
+ * Forward a presentation to the navigator (a new card restarts its intake
6475
+ * clock). Builds the navigator if the cached one has expired.
6476
+ */
6477
+ notePresented(card) {
6478
+ if (card.status !== "new") return;
6479
+ 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}`));
6480
+ }
6077
6481
  async getWeightedCards(limit) {
6078
6482
  const u = await this._getCurrentUser();
6079
6483
  try {
@@ -8838,10 +9242,11 @@ function backlogHtml(backlog) {
8838
9242
  const rows = backlog.map((b) => {
8839
9243
  const hot = b.backlogMultiplier >= 3;
8840
9244
  const multColor = b.backlogMultiplier <= 1 ? "#86efac" : hot ? "#fca5a5" : "#fcd34d";
8841
- const headroom = b.backlogMultiplier > 1 ? `climbing (\xD7${b.backlogGrowthRate.toFixed(2)} per ${b.healthyBacklog}-review excess, unbounded)` : "healthy \u2014 no pressure";
9245
+ const headroom = b.backlogMultiplier > 1 ? `climbing (\xD7${b.backlogGrowthRate.toFixed(2)} per ${b.healthyBacklog} of mass in excess, unbounded)` : "healthy \u2014 no pressure";
9246
+ const mass = b.reviewMass !== null ? ` \xB7 mass ${b.reviewMass.toFixed(1)}` : "";
8842
9247
  const top = b.topReviewScore !== null ? b.topReviewScore.toFixed(2) : "\u2014";
8843
9248
  const next = b.nextDueIn ? ` <span style="opacity:.6">\xB7 next due ${esc(b.nextDueIn)}</span>` : "";
8844
- 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>`;
9249
+ 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>`;
8845
9250
  }).join("");
8846
9251
  return `<div style="margin-bottom:6px"><div style="color:#93c5fd">review backpressure</div>${rows}</div>`;
8847
9252
  }
@@ -8980,8 +9385,9 @@ function snapshotToText(s) {
8980
9385
  const headroom = b.backlogMultiplier > 1 ? "climbing" : "healthy";
8981
9386
  const top = b.topReviewScore !== null ? b.topReviewScore.toFixed(2) : "\u2014";
8982
9387
  const next = b.nextDueIn ? `, next due ${b.nextDueIn}` : "";
9388
+ const mass = b.reviewMass !== null ? `, mass ${b.reviewMass.toFixed(1)}` : "";
8983
9389
  lines.push(
8984
- ` ${b.courseId.slice(0, 8)}: due ${b.dueNow}/${b.scheduledTotal} (healthy ${b.healthyBacklog})${next}; pressure \xD7${b.backlogMultiplier.toFixed(2)} ${headroom}; top review ${top}`
9390
+ ` ${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}`
8985
9391
  );
8986
9392
  }
8987
9393
  }