@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.
- package/dist/{contentSource-DpQqTG3m.d.cts → contentSource-B6FrSihy.d.cts} +218 -2
- package/dist/{contentSource-BoFBwvYa.d.ts → contentSource-CqJmbOZN.d.ts} +218 -2
- package/dist/core/index.d.cts +13 -90
- package/dist/core/index.d.ts +13 -90
- package/dist/core/index.js +621 -179
- package/dist/core/index.js.map +1 -1
- package/dist/core/index.mjs +620 -179
- package/dist/core/index.mjs.map +1 -1
- package/dist/{dataLayerProvider-D_LJT3F4.d.ts → dataLayerProvider-B9_UCvkR.d.ts} +1 -1
- package/dist/{dataLayerProvider-Dl3cAAvQ.d.cts → dataLayerProvider-DUxDqMtZ.d.cts} +1 -1
- package/dist/diagnostics/index.d.cts +79 -6
- package/dist/diagnostics/index.d.ts +79 -6
- package/dist/diagnostics/index.js +158 -4
- package/dist/diagnostics/index.js.map +1 -1
- package/dist/diagnostics/index.mjs +156 -4
- package/dist/diagnostics/index.mjs.map +1 -1
- package/dist/impl/couch/index.d.cts +11 -2
- package/dist/impl/couch/index.d.ts +11 -2
- package/dist/impl/couch/index.js +619 -179
- package/dist/impl/couch/index.js.map +1 -1
- package/dist/impl/couch/index.mjs +619 -179
- package/dist/impl/couch/index.mjs.map +1 -1
- package/dist/impl/static/index.d.cts +8 -2
- package/dist/impl/static/index.d.ts +8 -2
- package/dist/impl/static/index.js +616 -179
- package/dist/impl/static/index.js.map +1 -1
- package/dist/impl/static/index.mjs +616 -179
- package/dist/impl/static/index.mjs.map +1 -1
- package/dist/index.d.cts +66 -5
- package/dist/index.d.ts +66 -5
- package/dist/index.js +669 -180
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +656 -180
- package/dist/index.mjs.map +1 -1
- package/package.json +3 -3
- package/src/core/interfaces/contentSource.ts +7 -0
- package/src/core/navigators/Pipeline.ts +145 -13
- package/src/core/navigators/PipelineAssembler.ts +19 -40
- package/src/core/navigators/PipelineDebugger.ts +11 -2
- package/src/core/navigators/SrsDebugger.ts +37 -12
- package/src/core/navigators/defaults.ts +29 -5
- package/src/core/navigators/filters/WeightedFilter.ts +5 -1
- package/src/core/navigators/filters/eloDistance.ts +320 -76
- package/src/core/navigators/filters/hierarchyDefinition.ts +5 -1
- package/src/core/navigators/filters/index.ts +2 -2
- package/src/core/navigators/filters/interferenceMitigator.ts +5 -1
- package/src/core/navigators/filters/relativePriority.ts +5 -1
- package/src/core/navigators/filters/types.ts +24 -1
- package/src/core/navigators/filters/userTagPreference.ts +5 -1
- package/src/core/navigators/generators/elo.ts +23 -53
- package/src/core/navigators/generators/srs.ts +27 -124
- package/src/core/navigators/index.ts +31 -5
- package/src/core/navigators/pipelinePlan.ts +245 -0
- package/src/core/navigators/regulators.ts +230 -0
- package/src/core/types/studySession.ts +3 -0
- package/src/diagnostics/dataset.ts +13 -2
- package/src/diagnostics/index.ts +3 -0
- package/src/diagnostics/loader.ts +5 -2
- package/src/diagnostics/pipeline.ts +236 -0
- package/src/diagnostics/text.ts +26 -3
- package/src/impl/couch/courseDB.ts +13 -0
- package/src/impl/static/courseDB.ts +9 -0
- package/src/index.ts +4 -0
- package/src/study/SessionController.ts +20 -0
- package/src/study/SessionOverlay.ts +7 -4
- package/tests/core/navigators/PipelineAssembler.test.ts +20 -5
- 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
|
|
14
|
+
// A generator strategy that retrieves new cards near the learner's ELO.
|
|
22
15
|
//
|
|
23
|
-
//
|
|
24
|
-
//
|
|
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
|
|
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
|
|
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
|
-
//
|
|
107
|
-
// jitter
|
|
108
|
-
//
|
|
109
|
-
//
|
|
110
|
-
//
|
|
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
|
|
134
|
-
// fetch
|
|
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
|
|
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:
|
|
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:
|
|
153
|
-
reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userGlobalElo)}),
|
|
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
|
|
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
|
|
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
|
-
//
|
|
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
|
-
*
|
|
73
|
-
*
|
|
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)
|
|
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
|
|
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:
|
|
259
|
-
|
|
260
|
-
|
|
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
|
-
*
|
|
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
|
-
*
|
|
321
|
-
*
|
|
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
|
-
|
|
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
|
|
358
|
-
|
|
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
|
/**
|