@vue-skuilder/db 0.2.28 → 0.2.30

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. package/dist/{contentSource-DpQqTG3m.d.cts → contentSource-B6FrSihy.d.cts} +218 -2
  2. package/dist/{contentSource-BoFBwvYa.d.ts → contentSource-CqJmbOZN.d.ts} +218 -2
  3. package/dist/core/index.d.cts +13 -90
  4. package/dist/core/index.d.ts +13 -90
  5. package/dist/core/index.js +621 -179
  6. package/dist/core/index.js.map +1 -1
  7. package/dist/core/index.mjs +620 -179
  8. package/dist/core/index.mjs.map +1 -1
  9. package/dist/{dataLayerProvider-D_LJT3F4.d.ts → dataLayerProvider-B9_UCvkR.d.ts} +1 -1
  10. package/dist/{dataLayerProvider-Dl3cAAvQ.d.cts → dataLayerProvider-DUxDqMtZ.d.cts} +1 -1
  11. package/dist/diagnostics/index.d.cts +79 -6
  12. package/dist/diagnostics/index.d.ts +79 -6
  13. package/dist/diagnostics/index.js +158 -4
  14. package/dist/diagnostics/index.js.map +1 -1
  15. package/dist/diagnostics/index.mjs +156 -4
  16. package/dist/diagnostics/index.mjs.map +1 -1
  17. package/dist/impl/couch/index.d.cts +11 -2
  18. package/dist/impl/couch/index.d.ts +11 -2
  19. package/dist/impl/couch/index.js +619 -179
  20. package/dist/impl/couch/index.js.map +1 -1
  21. package/dist/impl/couch/index.mjs +619 -179
  22. package/dist/impl/couch/index.mjs.map +1 -1
  23. package/dist/impl/static/index.d.cts +8 -2
  24. package/dist/impl/static/index.d.ts +8 -2
  25. package/dist/impl/static/index.js +616 -179
  26. package/dist/impl/static/index.js.map +1 -1
  27. package/dist/impl/static/index.mjs +616 -179
  28. package/dist/impl/static/index.mjs.map +1 -1
  29. package/dist/index.d.cts +66 -5
  30. package/dist/index.d.ts +66 -5
  31. package/dist/index.js +669 -180
  32. package/dist/index.js.map +1 -1
  33. package/dist/index.mjs +656 -180
  34. package/dist/index.mjs.map +1 -1
  35. package/package.json +3 -3
  36. package/src/core/interfaces/contentSource.ts +7 -0
  37. package/src/core/navigators/Pipeline.ts +145 -13
  38. package/src/core/navigators/PipelineAssembler.ts +19 -40
  39. package/src/core/navigators/PipelineDebugger.ts +11 -2
  40. package/src/core/navigators/SrsDebugger.ts +37 -12
  41. package/src/core/navigators/defaults.ts +29 -5
  42. package/src/core/navigators/filters/WeightedFilter.ts +5 -1
  43. package/src/core/navigators/filters/eloDistance.ts +320 -76
  44. package/src/core/navigators/filters/hierarchyDefinition.ts +5 -1
  45. package/src/core/navigators/filters/index.ts +2 -2
  46. package/src/core/navigators/filters/interferenceMitigator.ts +5 -1
  47. package/src/core/navigators/filters/relativePriority.ts +5 -1
  48. package/src/core/navigators/filters/types.ts +24 -1
  49. package/src/core/navigators/filters/userTagPreference.ts +5 -1
  50. package/src/core/navigators/generators/elo.ts +23 -53
  51. package/src/core/navigators/generators/srs.ts +27 -124
  52. package/src/core/navigators/index.ts +31 -5
  53. package/src/core/navigators/pipelinePlan.ts +245 -0
  54. package/src/core/navigators/regulators.ts +230 -0
  55. package/src/core/types/studySession.ts +3 -0
  56. package/src/diagnostics/dataset.ts +13 -2
  57. package/src/diagnostics/index.ts +3 -0
  58. package/src/diagnostics/loader.ts +5 -2
  59. package/src/diagnostics/pipeline.ts +236 -0
  60. package/src/diagnostics/text.ts +26 -3
  61. package/src/impl/couch/courseDB.ts +13 -0
  62. package/src/impl/static/courseDB.ts +9 -0
  63. package/src/index.ts +4 -0
  64. package/src/study/SessionController.ts +20 -0
  65. package/src/study/SessionOverlay.ts +7 -4
  66. package/tests/core/navigators/PipelineAssembler.test.ts +20 -5
  67. package/tests/core/navigators/eloDistanceFilter.test.ts +9 -9
@@ -7,21 +7,17 @@ import type { QualifiedCardID } from '../..';
7
7
  import type { CardGenerator, GeneratorContext, GeneratorResult } from './types';
8
8
  import { logger } from '@db/util/logger';
9
9
 
10
- /**
11
- * Std-dev (in ELO points) of the Gaussian that converts card↔user ELO distance
12
- * into a relevance weight. 300 reproduces the legacy linear ramp's half-weight
13
- * point (distance 250 → ~0.5) while removing its hard zero beyond distance 500.
14
- */
15
- const ELO_RELEVANCE_SIGMA = 300;
16
-
17
10
  // ============================================================================
18
11
  // ELO NAVIGATOR
19
12
  // ============================================================================
20
13
  //
21
- // A generator strategy that selects new cards based on ELO proximity.
14
+ // A generator strategy that retrieves new cards near the learner's ELO.
22
15
  //
23
- // Cards closer to the user's skill level (ELO) receive higher scores.
24
- // This ensures learners see content matched to their current ability.
16
+ // It retrieves; it doesn't rank by distance. Scores are a flat jitter in
17
+ // [0.5, 1] for session-to-session variety. ELO distance is scored once, for
18
+ // new cards and reviews alike, by the ELO distance filter (filters/eloDistance),
19
+ // which the assembler adds to every pipeline. Scoring it here too counted it
20
+ // twice for new cards and once for reviews.
25
21
  //
26
22
  // NOTE: This generator only handles NEW cards. Reviews are handled by
27
23
  // SRSNavigator. Use CompositeGenerator to combine both.
@@ -29,15 +25,11 @@ const ELO_RELEVANCE_SIGMA = 300;
29
25
  // ============================================================================
30
26
 
31
27
  /**
32
- * A navigation strategy that scores new cards by ELO proximity.
28
+ * A navigation strategy that retrieves new cards near the learner's ELO.
33
29
  *
34
30
  * Implements CardGenerator for use in Pipeline architecture.
35
31
  * Also extends ContentNavigator for backward compatibility with legacy code.
36
32
  *
37
- * Higher scores indicate better ELO match:
38
- * - Cards at user's ELO level score highest
39
- * - Score decreases with ELO distance
40
- *
41
33
  * Only returns new cards - use SRSNavigator for reviews.
42
34
  */
43
35
  export default class ELONavigator extends ContentNavigator implements CardGenerator {
@@ -58,10 +50,8 @@ export default class ELONavigator extends ContentNavigator implements CardGenera
58
50
  }
59
51
 
60
52
  /**
61
- * Get new cards with suitability scores based on ELO distance.
62
- *
63
- * Cards closer to user's ELO get higher scores.
64
- * Score formula: max(0, 1 - distance / 500)
53
+ * Get the new cards nearest the learner's ELO, each scored with a flat
54
+ * jitter in [0.5, 1]. Carries each card's ELO for the ELO distance filter.
65
55
  *
66
56
  * NOTE: This generator only handles NEW cards. Reviews are handled by
67
57
  * SRSNavigator. Use CompositeGenerator to combine both.
@@ -103,60 +93,40 @@ export default class ELONavigator extends ContentNavigator implements CardGenera
103
93
  // `[active=${activeCards.length} candidates=${newCards.length}]`
104
94
  // );
105
95
 
106
- // Score new cards by ELO proximity, then apply bounded multiplicative
107
- // jitter for session-to-session variety.
108
- //
109
- // relevance = exp(-(distance / SIGMA)^2) // Gaussian: smooth, always > 0
110
- // score = relevance * (0.5 + 0.5 * U) // U ~ Uniform(0, 1)
111
- //
112
- // This replaces the legacy `rawScore = max(0, 1 - distance/500)` ramp +
113
- // Efraimidis-Spirakis key `U^(1/rawScore)`, which introduced two
114
- // discontinuities that defeated downstream replan boosts:
115
- // 1. The ramp's clamp made every card ≥500 ELO from the user a HARD zero.
116
- // The pipeline DELETES zero-score cards (filter score>0) *before* boosts
117
- // are applied, so no boost could resurface an under-ELO'd target — e.g.
118
- // a freshly-introduced grapheme sitting ~475 below an inflated global
119
- // ELO. (See packages/db/docs/todo-intro-concept-emphasis-and-retrieval.md.)
120
- // 2. The A-Res key `U^(1/rawScore)` ALSO manufactured effective zeros: as
121
- // rawScore→0 the exponent explodes and `U^huge` underflows to 0, with
122
- // wild variance just above it — so a downstream boost multiplied a
123
- // lottery ticket rather than a stable relevance.
124
- //
125
- // Gaussian relevance never hits zero (no cliff, survives the score>0 filter,
126
- // so a boost can always lift a low-ELO target), and the [0.5, 1] jitter keeps
127
- // ELO ordering up to a 2× factor while still shuffling near-equal cards so the
128
- // same cards don't loop every session. SIGMA=300 reproduces the old ramp's
129
- // half-weight point (distance 250 → ~0.5), leaving center-of-range difficulty
130
- // matching unchanged.
96
+ // Retrieval is by ELO (the window above); scoring isn't. Each card gets a
97
+ // jitter in [0.5, 1] so near-equal cards shuffle between sessions instead of
98
+ // looping. Distance is scored by the ELO distance filter, on the Gaussian
99
+ // this generator used to apply itself (sigma 300, never zero, so a
100
+ // downstream boost can always lift a low-ELO target; see filters/eloDistance
101
+ // and packages/db/docs/todo-intro-concept-emphasis-and-retrieval.md).
131
102
  //
132
103
  // Card ELO is read from the pooled `.elo` carried on each candidate by
133
- // getCardsCenteredAtELO — verified equal to a separate getCardEloData()
134
- // fetch (0/500 mismatch on real data), so the redundant fetch is gone.
104
+ // getCardsCenteredAtELO, and passed on as `cardElo` so the filter needn't
105
+ // fetch it again.
135
106
  const scored: WeightedCard[] = newCards.map((c) => {
136
107
  const cardElo = c.elo ?? 1000;
137
-
138
108
  const distance = Math.abs(cardElo - userGlobalElo);
139
- const relevance = Math.exp(-((distance / ELO_RELEVANCE_SIGMA) ** 2));
140
- const samplingKey = relevance * (0.5 + 0.5 * Math.random());
109
+ const jitter = 0.5 + 0.5 * Math.random();
141
110
 
142
111
  return {
143
112
  cardId: c.cardID,
144
113
  courseId: c.courseID,
145
- score: samplingKey,
114
+ score: jitter,
115
+ cardElo,
146
116
  provenance: [
147
117
  {
148
118
  strategy: 'elo',
149
119
  strategyName: this.strategyName || this.name,
150
120
  strategyId: this.strategyId || 'NAVIGATION_STRATEGY-ELO-default',
151
121
  action: 'generated',
152
- score: samplingKey,
153
- reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userGlobalElo)}), relevance ${relevance.toFixed(3)}, key ${samplingKey.toFixed(3)}`,
122
+ score: jitter,
123
+ reason: `new card near learner ELO: distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userGlobalElo)}), jitter ${jitter.toFixed(3)}`,
154
124
  },
155
125
  ],
156
126
  };
157
127
  });
158
128
 
159
- // Sort by sampling key descending (weighted sample without replacement)
129
+ // Sort by jitter descending (a uniform random sample of the window)
160
130
  scored.sort((a, b) => b.score - a.score);
161
131
 
162
132
  const cards = scored.slice(0, limit);
@@ -4,6 +4,7 @@ import type { CourseDBInterface } from '../../interfaces/courseDB';
4
4
  import type { UserDBInterface } from '../../interfaces/userDB';
5
5
  import { ContentNavigator } from '../index';
6
6
  import { captureSrsBacklog } from '../SrsDebugger';
7
+ import { DEFAULT_REGULATOR_CONFIG } from '../regulators';
7
8
  import type { ContentNavigationStrategyData } from '../../types/contentNavigationStrategy';
8
9
  import type { CardGenerator, GeneratorContext, GeneratorResult } from './types';
9
10
  import { logger } from '@db/util/logger';
@@ -14,10 +15,14 @@ import { logger } from '@db/util/logger';
14
15
  //
15
16
  // A generator strategy that scores review cards by urgency.
16
17
  //
17
- // Urgency is determined by three factors:
18
+ // Urgency is determined by two factors:
18
19
  // 1. Overdueness - how far past the scheduled review time
19
20
  // 2. Interval recency - shorter scheduled intervals indicate "novel content in progress"
20
- // 3. Backlog pressure - when too many reviews pile up, urgency increases globally
21
+ //
22
+ // Backlog pressure (reviews piling up) isn't scored here: the pipeline's
23
+ // regulator stage measures the due backlog's *mass* after filters (so reviews
24
+ // the learner has moved beyond weigh little) and scales all reviews by it.
25
+ // See regulators.ts.
21
26
  //
22
27
  // A card with a 3-day interval that's 2 days overdue is more urgent than a card
23
28
  // with a 6-month interval that's 2 days overdue. The shorter interval represents
@@ -34,44 +39,13 @@ import { logger } from '@db/util/logger';
34
39
  //
35
40
  // ============================================================================
36
41
 
37
- /**
38
- * Default healthy backlog size.
39
- * When due reviews exceed this, backlog pressure kicks in.
40
- * Can be overridden via strategy config.
41
- */
42
- const DEFAULT_HEALTHY_BACKLOG = 20;
43
-
44
- /**
45
- * Growth-rate base for backlog pressure as a *multiplier* on review urgency.
46
- *
47
- * Backlog pressure is multiplicative (×1.0 at/below healthy) and exponential
48
- * in the backlog's excess over healthy, expressed in multiples of
49
- * `healthyBacklog` (see computeBacklogMultiplier) — deliberately uncapped. It
50
- * replaces an older additive +0..+0.5 term that was a [0,1]-era modifier —
51
- * once review scores stopped being clamped to 1.0 and new cards could be
52
- * boosted well past it (e.g. an intro ×5 → 7+), a flat +0.5 was both too small
53
- * to compete and mostly eaten by the old 1.0 clamp. A linear-then-capped
54
- * multiplier came next, but that just moved the problem: other generators
55
- * (e.g. Prescribed Intro Backpressure) score on a much larger open scale with
56
- * their own, independently-tuned caps, so a hard review-side ceiling meant
57
- * reviews could never win out no matter how backlogged they got. Exponential
58
- * growth has no such ceiling — a sufficiently neglected backlog keeps
59
- * climbing until it outcompetes anything, which is the intended long-term
60
- * fallback: other generators can dominate short-term, but SRS is the
61
- * framework-invariant backstop and should always win eventually. Tunable —
62
- * verify review vs new ordering in the dbg overlay's "review backpressure"
63
- * panel.
64
- */
65
- const BACKLOG_GROWTH_RATE = 2;
66
-
67
42
  /**
68
43
  * Configuration for the SRS strategy.
69
44
  */
70
45
  export interface SRSConfig {
71
46
  /**
72
- * Target "healthy" backlog size.
73
- * When due reviews exceed this, urgency increases globally.
74
- * Default: 20
47
+ * @deprecated Ignored. Backlog pressure moved to the pipeline's regulator
48
+ * stage, which measures review mass (see regulators.ts).
75
49
  */
76
50
  healthyBacklog?: number;
77
51
  }
@@ -85,7 +59,6 @@ export interface SRSConfig {
85
59
  * Higher scores indicate more urgent reviews:
86
60
  * - Cards that are more overdue (relative to their interval) score higher
87
61
  * - Cards with shorter intervals (recent learning) score higher
88
- * - When backlog exceeds "healthy" threshold, all reviews get urgency boost
89
62
  *
90
63
  * Only returns cards that are actually due (reviewTime has passed).
91
64
  * Does not generate new cards - use with CompositeGenerator for mixed content.
@@ -94,9 +67,6 @@ export default class SRSNavigator extends ContentNavigator implements CardGenera
94
67
  /** Human-readable name for CardGenerator interface */
95
68
  name: string;
96
69
 
97
- /** Healthy backlog threshold - when exceeded, backlog pressure kicks in */
98
- private healthyBacklog: number;
99
-
100
70
  constructor(
101
71
  user: UserDBInterface,
102
72
  course: CourseDBInterface,
@@ -104,23 +74,6 @@ export default class SRSNavigator extends ContentNavigator implements CardGenera
104
74
  ) {
105
75
  super(user, course, strategyData as ContentNavigationStrategyData);
106
76
  this.name = strategyData?.name || 'SRS';
107
-
108
- // Parse config from serializedData if available
109
- const config = this.parseConfig(strategyData?.serializedData);
110
- this.healthyBacklog = config.healthyBacklog ?? DEFAULT_HEALTHY_BACKLOG;
111
- }
112
-
113
- /**
114
- * Parse configuration from serialized JSON.
115
- */
116
- private parseConfig(serializedData?: string): SRSConfig {
117
- if (!serializedData) return {};
118
- try {
119
- return JSON.parse(serializedData) as SRSConfig;
120
- } catch {
121
- logger.warn('[SRS] Failed to parse strategy config, using defaults');
122
- return {};
123
- }
124
77
  }
125
78
 
126
79
  /**
@@ -129,7 +82,6 @@ export default class SRSNavigator extends ContentNavigator implements CardGenera
129
82
  * Score formula combines:
130
83
  * - Relative overdueness: hoursOverdue / intervalHours
131
84
  * - Interval recency: exponential decay favoring shorter intervals
132
- * - Backlog pressure: boost when due reviews exceed healthy threshold
133
85
  *
134
86
  * Cards not yet due are excluded (not scored as 0).
135
87
  *
@@ -176,9 +128,6 @@ export default class SRSNavigator extends ContentNavigator implements CardGenera
176
128
  }
177
129
  }
178
130
 
179
- // Compute backlog pressure (multiplicative) - applies globally to all reviews
180
- const backlogMultiplier = this.computeBacklogMultiplier(dueReviews.length);
181
-
182
131
  // Time until the next not-yet-due review (for the debug overlay): shows
183
132
  // reviews are *coming* even when none are due right now.
184
133
  const notDue = reviews.filter((r) => !now.isAfter(moment.utc(r.reviewTime)));
@@ -198,12 +147,8 @@ export default class SRSNavigator extends ContentNavigator implements CardGenera
198
147
 
199
148
  // Log review status for transparency
200
149
  if (dueReviews.length > 0) {
201
- const pressureNote =
202
- backlogMultiplier > 1
203
- ? ` [backlog pressure: ×${backlogMultiplier.toFixed(2)}]`
204
- : ` [healthy backlog]`;
205
150
  logger.info(
206
- `[SRS] Course ${courseId}: ${dueReviews.length} reviews due now (of ${reviews.length} scheduled)${pressureNote}`
151
+ `[SRS] Course ${courseId}: ${dueReviews.length} reviews due now (of ${reviews.length} scheduled)`
207
152
  );
208
153
  } else if (reviews.length > 0) {
209
154
  // Reviews exist but none are due yet - show when next one is due
@@ -227,12 +172,13 @@ export default class SRSNavigator extends ContentNavigator implements CardGenera
227
172
  }
228
173
 
229
174
  const scored = dueReviews.map((review) => {
230
- const { score, reason } = this.computeUrgencyScore(review, now, backlogMultiplier);
175
+ const { score, urgency, reason } = this.computeUrgencyScore(review, now);
231
176
 
232
177
  return {
233
178
  cardId: review.cardId,
234
179
  courseId: review.courseId,
235
180
  score,
181
+ reviewUrgency: urgency,
236
182
  reviewID: review._id,
237
183
  provenance: [
238
184
  {
@@ -250,14 +196,16 @@ export default class SRSNavigator extends ContentNavigator implements CardGenera
250
196
  // Sort by score descending and limit
251
197
  const sorted = scored.sort((a, b) => b.score - a.score);
252
198
 
253
- // Capture backlog state for the live session overlay (see SrsDebugger).
199
+ // Capture backlog state for the live session overlay (see SrsDebugger). The
200
+ // regulator stage patches in review mass and its multiplier after filters.
254
201
  captureSrsBacklog({
255
202
  courseId,
256
203
  scheduledTotal: reviews.length,
257
204
  dueNow: dueReviews.length,
258
- healthyBacklog: this.healthyBacklog,
259
- backlogMultiplier,
260
- backlogGrowthRate: BACKLOG_GROWTH_RATE,
205
+ healthyBacklog: DEFAULT_REGULATOR_CONFIG.reviewMass.healthyMass,
206
+ reviewMass: null,
207
+ backlogMultiplier: 1,
208
+ backlogGrowthRate: DEFAULT_REGULATOR_CONFIG.reviewMass.rate,
261
209
  topReviewScore: sorted.length > 0 ? sorted[0].score : null,
262
210
  nextDueIn,
263
211
  timestamp: Date.now(),
@@ -273,41 +221,10 @@ export default class SRSNavigator extends ContentNavigator implements CardGenera
273
221
  return { cards: sorted.slice(0, limit) };
274
222
  }
275
223
 
276
- /**
277
- * Compute the multiplicative backlog pressure based on number of due reviews.
278
- *
279
- * ×1.0 at or below the healthy threshold (no boost); above it, grows as
280
- * BACKLOG_GROWTH_RATE raised to the excess expressed in multiples of the
281
- * healthy threshold. Uncapped — self-regulating instead: reviews winning
282
- * slots depletes dueCount, which drops the ratio and relaxes the multiplier
283
- * next run.
284
- *
285
- * Examples (with default healthyBacklog=20, BACKLOG_GROWTH_RATE=1.5):
286
- * - 10 due reviews → ×1.00 (healthy)
287
- * - 20 due reviews → ×1.00 (at threshold, ratio 0)
288
- * - 40 due reviews → ×1.50 (ratio 1, 2x threshold)
289
- * - 60 due reviews → ×2.25 (ratio 2, 3x threshold — old hard cap was ×2.00 here)
290
- * - 100 due reviews → ×5.06 (ratio 4, 5x threshold)
291
- * - 160 due reviews → ×17.09 (ratio 7, 8x threshold)
292
- *
293
- * @param dueCount - Number of reviews currently due
294
- * @returns Multiplier applied to review urgency (>= 1.0, unbounded)
295
- */
296
- private computeBacklogMultiplier(dueCount: number): number {
297
- if (dueCount <= this.healthyBacklog) {
298
- return 1.0;
299
- }
300
-
301
- const excess = dueCount - this.healthyBacklog;
302
- const ratio = excess / this.healthyBacklog;
303
-
304
- return Math.pow(BACKLOG_GROWTH_RATE, ratio);
305
- }
306
-
307
224
  /**
308
225
  * Compute urgency score for a review card.
309
226
  *
310
- * Three factors:
227
+ * Two factors:
311
228
  * 1. Relative overdueness = hoursOverdue / intervalHours
312
229
  * - 2 days overdue on 3-day interval = 0.67 (urgent)
313
230
  * - 2 days overdue on 180-day interval = 0.01 (not urgent)
@@ -317,24 +234,17 @@ export default class SRSNavigator extends ContentNavigator implements CardGenera
317
234
  * - 30 days (720h) → ~0.56
318
235
  * - 180 days → ~0.30
319
236
  *
320
- * 3. Backlog pressure = global *multiplier* when review backlog exceeds the
321
- * healthy threshold (×1.0 healthy → exponential growth, uncapped, above it).
322
- *
323
- * Combined: (base 0.5 + urgency factors * 0.45) × backlog multiplier.
324
- * Per-card range before pressure: ~0.57–0.95. NOT clamped to 1.0 — under a
325
- * heavy backlog reviews scale onto the open scale to compete with (and exceed)
326
- * new cards; there's no ceiling at all now, so a bad enough backlog always
327
- * wins eventually — self-regulating because winning slots depletes dueCount.
237
+ * Combined: base 0.5 + urgency factors * 0.45, so ~0.57–0.95 per card.
238
+ * Backlog pressure is applied later, by the regulator stage, which can lift
239
+ * reviews onto the open scale above new cards (see regulators.ts).
328
240
  *
329
241
  * @param review - The scheduled card to score
330
242
  * @param now - Current time
331
- * @param backlogMultiplier - Pre-computed backlog multiplier (>= 1.0, unbounded)
332
243
  */
333
244
  private computeUrgencyScore(
334
245
  review: ScheduledCard,
335
- now: moment.Moment,
336
- backlogMultiplier: number
337
- ): { score: number; reason: string } {
246
+ now: moment.Moment
247
+ ): { score: number; urgency: number; reason: string } {
338
248
  const scheduledAt = moment.utc(review.scheduledAt);
339
249
  const due = moment.utc(review.reviewTime);
340
250
 
@@ -354,11 +264,8 @@ export default class SRSNavigator extends ContentNavigator implements CardGenera
354
264
  const overdueContribution = Math.min(1.0, Math.max(0, relativeOverdue));
355
265
  const urgency = overdueContribution * 0.5 + recencyFactor * 0.5;
356
266
 
357
- // Final score: per-card urgency (base 0.5 + contribution) scaled by the
358
- // global backlog multiplier. No 1.0 clamp — reviews compete on the open
359
- // scale; the bounded multiplier (not a ceiling) caps the lift.
360
- const baseScore = 0.5 + urgency * 0.45;
361
- const score = baseScore * backlogMultiplier;
267
+ // Final score: per-card urgency, base 0.5 + contribution.
268
+ const score = 0.5 + urgency * 0.45;
362
269
 
363
270
  // Build reason string with all contributing factors
364
271
  const reasonParts = [
@@ -368,14 +275,10 @@ export default class SRSNavigator extends ContentNavigator implements CardGenera
368
275
  `recency: ${recencyFactor.toFixed(2)}`,
369
276
  ];
370
277
 
371
- if (backlogMultiplier > 1) {
372
- reasonParts.push(`backlog: ×${backlogMultiplier.toFixed(2)}`);
373
- }
374
-
375
278
  reasonParts.push('review');
376
279
 
377
280
  const reason = reasonParts.join(', ');
378
281
 
379
- return { score, reason };
282
+ return { score, urgency, reason };
380
283
  }
381
284
  }
@@ -1,7 +1,8 @@
1
1
  import { StudyContentSource, UserDBInterface, CourseDBInterface } from '..';
2
+ import type { FilterKind } from './filters/types';
2
3
 
3
4
  // Re-export filter types
4
- export type { CardFilter, FilterContext, CardFilterFactory } from './filters/types';
5
+ export type { CardFilter, FilterContext, CardFilterFactory, FilterKind } from './filters/types';
5
6
 
6
7
  // Re-export generator types
7
8
  export type { CardGenerator, GeneratorContext, CardGeneratorFactory, GeneratorResult, ReplanHints } from './generators/types';
@@ -148,6 +149,19 @@ export function getRegisteredNavigatorRole(implementingClass: string): Navigator
148
149
  return navigatorRegistry.get(implementingClass)?.role;
149
150
  }
150
151
 
152
+ /**
153
+ * A registered filter's declared kind (see `CardFilter.kind`): the static
154
+ * `kind` on its class. Undefined if unregistered or undeclared; undeclared
155
+ * filters count as gates at run time.
156
+ * @param implementingClass - The class name to look up
157
+ */
158
+ export function getRegisteredFilterKind(implementingClass: string): FilterKind | undefined {
159
+ const ctor = navigatorRegistry.get(implementingClass)?.constructor as
160
+ | { kind?: FilterKind }
161
+ | undefined;
162
+ return ctor?.kind;
163
+ }
164
+
151
165
  /**
152
166
  * Get all registered navigator names.
153
167
  * Useful for debugging and testing.
@@ -185,20 +199,19 @@ export async function initializeNavigatorRegistry(): Promise<void> {
185
199
  interferenceModule,
186
200
  relativePriorityModule,
187
201
  userTagPreferenceModule,
202
+ eloDistanceModule,
188
203
  ] = await Promise.all([
189
204
  import('./filters/hierarchyDefinition'),
190
205
  import('./filters/interferenceMitigator'),
191
206
  import('./filters/relativePriority'),
192
207
  import('./filters/userTagPreference'),
208
+ import('./filters/eloDistance'),
193
209
  ]);
194
210
  registerNavigator('hierarchyDefinition', hierarchyModule.default);
195
211
  registerNavigator('interferenceMitigator', interferenceModule.default);
196
212
  registerNavigator('relativePriority', relativePriorityModule.default);
197
213
  registerNavigator('userTagPreference', userTagPreferenceModule.default);
198
-
199
- // Note: eloDistance uses a factory pattern (createEloDistanceFilter) rather than
200
- // a ContentNavigator class, so it's not registered here. It's used differently
201
- // via Pipeline composition.
214
+ registerNavigator('eloDistance', eloDistanceModule.default);
202
215
 
203
216
  logger.debug(
204
217
  `[NavigatorRegistry] Initialized ${navigatorRegistry.size} navigators: ${getRegisteredNavigatorNames().join(', ')}`
@@ -350,6 +363,17 @@ export interface WeightedCard {
350
363
  * Used by SessionController to track review outcomes and maintain review state.
351
364
  */
352
365
  reviewID?: string;
366
+ /**
367
+ * The card's global ELO, when the generator already knows it (the ELO
368
+ * generator reads it during retrieval). Lets the ELO distance filter skip a
369
+ * fetch.
370
+ */
371
+ cardElo?: number;
372
+ /**
373
+ * A review's SRS urgency in [0, 1] (overdueness and interval recency), set by
374
+ * the SRS generator. The review-mass regulator weighs the backlog by it.
375
+ */
376
+ reviewUrgency?: number;
353
377
  }
354
378
 
355
379
  /**
@@ -387,6 +411,7 @@ export enum Navigators {
387
411
  INTERFERENCE = 'interferenceMitigator',
388
412
  RELATIVE_PRIORITY = 'relativePriority',
389
413
  USER_TAG_PREFERENCE = 'userTagPreference',
414
+ ELO_DISTANCE = 'eloDistance',
390
415
  }
391
416
 
392
417
  // ============================================================================
@@ -426,6 +451,7 @@ export const NavigatorRoles: Record<Navigators, NavigatorRole> = {
426
451
  [Navigators.INTERFERENCE]: NavigatorRole.FILTER,
427
452
  [Navigators.RELATIVE_PRIORITY]: NavigatorRole.FILTER,
428
453
  [Navigators.USER_TAG_PREFERENCE]: NavigatorRole.FILTER,
454
+ [Navigators.ELO_DISTANCE]: NavigatorRole.FILTER,
429
455
  };
430
456
 
431
457
  /**