@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
@@ -1,132 +1,376 @@
1
+ import type { CourseDBInterface } from '../../interfaces/courseDB';
2
+ import type { UserDBInterface } from '../../interfaces/userDB';
3
+ import type { ContentNavigationStrategyData } from '../../types/contentNavigationStrategy';
4
+ import { ContentNavigator } from '../index';
1
5
  import type { WeightedCard } from '../index';
2
- import type { CardFilter, FilterContext } from './types';
6
+ import type { GeneratorResult } from '../generators/types';
7
+ import type { CardFilter, FilterContext, FilterKind } from './types';
8
+ import type { CourseElo } from '@vue-skuilder/common';
9
+ import { logger } from '../../../util/logger';
3
10
 
4
11
  // ============================================================================
5
12
  // ELO DISTANCE FILTER
6
13
  // ============================================================================
7
14
  //
8
- // Penalizes cards that are far from the user's current ELO using a smooth curve.
15
+ // Scales every candidate by how close its ELO is to the learner's, on a smooth
16
+ // Gaussian (no discontinuities, never zero).
9
17
  //
10
- // This filter addresses cross-strategy coordination:
11
- // - SRS generates reviews based on scheduling
12
- // - But some scheduled cards may be "below" the user's current level
13
- // - Or "above" (shouldn't happen often, but possible)
18
+ // The one place ELO distance counts. Generators retrieve (the ELO generator
19
+ // pulls a window of cards near the learner's ELO) and score only on what's
20
+ // specific to their source; a signal that applies to every card lives in one
21
+ // heap-wide filter, so new cards and reviews are weighed on the same terms:
22
+ // - reviews the learner has moved beyond fade, and may never surface over
23
+ // higher-priority work;
24
+ // - new cards far from the learner's level rank low (this used to live in the
25
+ // ELO generator's own score, which double-counted alongside this filter).
14
26
  //
15
- // By applying ELO distance penalties, we can:
16
- // - Deprioritize reviews the user has "moved beyond"
17
- // - Deprioritize cards that are too hard for current skill level
27
+ // Tag-aware (opt-in, experimental): a card's difficulty for this learner is
28
+ // read on the skills they share, not only on global ELO. Card and learner keep
29
+ // paired ratings per tag (each graded response adjusts both), so a tag's gap
30
+ // (card − learner) is as meaningful as the global one, and often more: a card
31
+ // can sit at the learner's global level while testing their weakest skill.
32
+ // See tagAwareGap for the combination. Global distance is the default; a course
33
+ // opts in with `tagAware`, a browser with `window.skuilder.multiDimElo = true`
34
+ // (see the toggle below), for side-by-side testing.
18
35
  //
19
- // The penalty curve is smooth (no discontinuities) using a Gaussian-like decay.
36
+ // A `signal`, not a gate: it expresses preference, not readiness. `liveOnly`:
37
+ // forecasts and card-space scans start every card at 1.0 without a generator,
38
+ // and never applied ELO distance, so they skip it.
39
+ //
40
+ // The assembler adds this filter (as "ELO Distance (default)") to every
41
+ // pipeline whose strategy docs don't declare one. A course tunes it by
42
+ // declaring its own `eloDistance` strategy doc with an EloDistanceConfig.
20
43
  //
21
44
  // ============================================================================
22
45
 
23
46
  /**
24
- * Configuration for the ELO distance filter.
47
+ * Configuration for the ELO distance curve:
48
+ * `minMultiplier + (maxMultiplier − minMultiplier) · exp(−(distance / halfLife)²)`.
25
49
  */
26
50
  export interface EloDistanceConfig {
27
51
  /**
28
- * The ELO distance at which the multiplier is ~0.6 (one standard deviation).
29
- * Default: 200 ELO points.
52
+ * The Gaussian's scale in ELO points (despite the name, not a half-life).
53
+ * Default 300: distance 250 → ~0.5, as the ELO generator scored new cards.
30
54
  *
31
- * - At distance 0: multiplier ≈ 1.0
32
- * - At distance = halfLife: multiplier ≈ 0.6
33
- * - At distance = 2 * halfLife: multiplier ≈ 0.37
34
- * - At distance = 3 * halfLife: multiplier ≈ 0.22
55
+ * - distance 0: maxMultiplier
56
+ * - distance = halfLife: ~0.4 (with the default floor)
57
+ * - distance = 2 · halfLife: ~0.07
35
58
  */
36
59
  halfLife?: number;
37
60
 
38
61
  /**
39
- * Minimum multiplier (floor) to prevent scores from going too low.
40
- * Default: 0.3
62
+ * Floor, so far-off cards keep a nonzero score (the pipeline drops zero
63
+ * scores before hints, and a hint must be able to lift any card). Default 0.05.
41
64
  */
42
65
  minMultiplier?: number;
43
66
 
67
+ /** Ceiling. Usually 1.0 (no boost for close cards). Default 1.0. */
68
+ maxMultiplier?: number;
69
+
44
70
  /**
45
- * Maximum multiplier (ceiling). Usually 1.0 (no boost for close cards).
46
- * Default: 1.0
71
+ * Measure distance on the tags the card and learner share (see
72
+ * tagAwareGap), falling back to global ELO where they share none.
73
+ * Default false. `window.skuilder.multiDimElo` turns it on in one browser.
47
74
  */
48
- maxMultiplier?: number;
75
+ tagAware?: boolean;
76
+
77
+ /**
78
+ * A learner's tag rating counts once it rests on at least this many graded
79
+ * responses. Count-only (exposure) tags never count. Default 3.
80
+ */
81
+ minTagCount?: number;
49
82
  }
50
83
 
51
- const DEFAULT_HALF_LIFE = 200;
52
- const DEFAULT_MIN_MULTIPLIER = 0.3;
53
- const DEFAULT_MAX_MULTIPLIER = 1.0;
84
+ /**
85
+ * The default curve. The default strategy doc carries it as its config, so
86
+ * the admin pipeline view shows what runs.
87
+ */
88
+ export const DEFAULT_ELO_DISTANCE_CONFIG: Required<EloDistanceConfig> = {
89
+ halfLife: 300,
90
+ minMultiplier: 0.05,
91
+ maxMultiplier: 1.0,
92
+ tagAware: false,
93
+ minTagCount: 3,
94
+ };
54
95
 
55
96
  /**
56
- * Compute the multiplier for a given ELO distance using Gaussian decay.
57
- *
58
- * Formula: minMultiplier + (maxMultiplier - minMultiplier) * exp(-(distance/halfLife)^2)
59
- *
60
- * This produces a smooth bell curve centered at distance=0:
61
- * - At distance 0: multiplier = maxMultiplier (1.0)
62
- * - As distance increases: multiplier smoothly decays toward minMultiplier
63
- * - No discontinuities or sudden jumps
97
+ * Graded responses at which a tag's gap carries half its full weight. Thin
98
+ * tag evidence leans on global ELO; well-practised tags dominate.
64
99
  */
100
+ const TAG_CONFIDENCE_HALF = 10;
101
+
102
+ /** Count-only tag ratings (exposure tracking) carry this sentinel score. */
103
+ const COUNT_ONLY_SENTINEL = -1;
104
+
105
+ /** Fallback card ELO when a card has none recorded. */
106
+ const DEFAULT_CARD_ELO = 1000;
107
+
65
108
  function computeMultiplier(
66
109
  distance: number,
67
110
  halfLife: number,
68
111
  minMultiplier: number,
69
112
  maxMultiplier: number
70
113
  ): number {
71
- // Gaussian decay: exp(-(d/h)^2)
72
114
  const normalizedDistance = distance / halfLife;
73
115
  const decay = Math.exp(-(normalizedDistance * normalizedDistance));
74
-
75
- // Scale between min and max
76
116
  return minMultiplier + (maxMultiplier - minMultiplier) * decay;
77
117
  }
78
118
 
119
+ function resolveConfig(config?: EloDistanceConfig): Required<EloDistanceConfig> {
120
+ return { ...DEFAULT_ELO_DISTANCE_CONFIG, ...config };
121
+ }
122
+
123
+ // ----------------------------------------------------------------------------
124
+ // Live toggle: window.skuilder.multiDimElo
125
+ // ----------------------------------------------------------------------------
126
+ //
127
+ // `window.skuilder.multiDimElo = true` turns tag-aware distance on in this
128
+ // browser, whatever the strategy config says; `false` returns it to the
129
+ // config. Read on every run, so it takes effect at the next replan. Kept in
130
+ // localStorage so it survives reloads across a testing stretch. Runs it shapes
131
+ // say so in every card's ELO distance reason ("tag-aware").
132
+
133
+ const MULTI_DIM_ELO_KEY = 'skuilder:multiDimElo';
134
+
135
+ let multiDimElo = readMultiDimElo();
136
+
137
+ function readMultiDimElo(): boolean {
138
+ try {
139
+ return typeof localStorage !== 'undefined' && localStorage.getItem(MULTI_DIM_ELO_KEY) === 'true';
140
+ } catch {
141
+ return false;
142
+ }
143
+ }
144
+
79
145
  /**
80
- * Create an ELO distance filter.
146
+ * Mount the toggle on window.skuilder.multiDimElo.
147
+ */
148
+ export function mountMultiDimEloToggle(): void {
149
+ if (typeof window === 'undefined') return;
150
+
151
+ const win = window as any;
152
+ win.skuilder = win.skuilder || {};
153
+ Object.defineProperty(win.skuilder, 'multiDimElo', {
154
+ configurable: true,
155
+ enumerable: true,
156
+ get: () => multiDimElo,
157
+ set: (on: unknown) => {
158
+ multiDimElo = on === true;
159
+ try {
160
+ if (multiDimElo) localStorage.setItem(MULTI_DIM_ELO_KEY, 'true');
161
+ else localStorage.removeItem(MULTI_DIM_ELO_KEY);
162
+ } catch (e) {
163
+ logger.warn(`[EloDistance] multiDimElo not persisted (localStorage unavailable): ${e}`);
164
+ }
165
+ logger.info(
166
+ `[EloDistance] multiDimElo ${multiDimElo ? 'on: tag-aware' : 'off: per strategy config'}` +
167
+ ' ELO distance from the next replan'
168
+ );
169
+ },
170
+ });
171
+ }
172
+
173
+ // Auto-mount when module is loaded
174
+ mountMultiDimEloToggle();
175
+
176
+ /** One shared tag's contribution to a card's tag-aware gap. */
177
+ interface TagGap {
178
+ tag: string;
179
+ /** Card's tag rating minus the learner's: positive = harder than their level. */
180
+ gap: number;
181
+ weight: number;
182
+ }
183
+
184
+ /**
185
+ * The card's difficulty for this learner, in ELO points (card − learner),
186
+ * read on the tags they share.
187
+ *
188
+ * - Shared tags: the card's tags on which the learner has a real rating
189
+ * (not the count-only sentinel) resting on at least `minTagCount` graded
190
+ * responses. A card with no rating of its own on a tag uses its global, as
191
+ * the ELO update does when it first grades that tag.
192
+ * - Each tag's gap is weighted by the learner's evidence on it,
193
+ * n / (n + TAG_CONFIDENCE_HALF).
194
+ * - The weighted mean of the tag gaps is blended with the global gap by the
195
+ * total evidence W: λ = W / (W + 1). One thin tag barely moves it; several
196
+ * practised tags dominate it.
81
197
  *
82
- * Penalizes cards that are far from the user's current ELO level
83
- * using a smooth Gaussian decay curve. No discontinuities.
198
+ * OPEN (draft, 2026-10-01). Shipped on by default in 0.2.29 by accident (it
199
+ * rode along in the version-bump commit); off by default since, and live only
200
+ * behind the toggle. On one LP learner's 09-30 dump the effect was modest: every touched card shared a rated tag
201
+ * (median 4); mean multiplier ×0.70 → ×0.75 over 352 touched cards, ×0.84 →
202
+ * ×0.88 over 42 due reviews. The biggest movers were old who-said-that cards:
203
+ * ~400 below the learner globally, ~280 below on their own skills.
84
204
  *
85
- * @param config - Optional configuration for the decay curve
86
- * @returns A CardFilter that applies ELO distance penalties
205
+ * 1. Compensatory or conjunctive. This averages: a weak skill is offset by
206
+ * strong ones. For spelling a word, which needs every grapheme, the hardest
207
+ * shared skill arguably sets the difficulty: take the largest gap instead.
208
+ * The main design question.
209
+ * 2. Which tags count. Broad tags (`concept:match:simple`, `ui:*`) sit on most
210
+ * cards and act like a second global rating. The framework may want the
211
+ * course to say which tags are skills (cf. LP's diagnostics interpreter
212
+ * `isSkillTag`), e.g. as tag patterns in the strategy config.
213
+ * 3. New cards matter most, and that dump couldn't show them. An unseen
214
+ * card's tag ratings fall back to its global, so for new cards this reads
215
+ * "card global vs the learner's rating on that skill". Measuring it needs a
216
+ * `--course all` dump.
217
+ * 4. Cost. Tag-aware fetches full ratings for every candidate (~500 card docs
218
+ * per run); global-only fetches only reviews'.
219
+ * 5. Retrieval stays global. The ELO generator's window is the cards nearest
220
+ * the learner's global ELO, so a card that's well matched on its skills but
221
+ * far off globally may never be retrieved.
222
+ * 6. Target. Distance 0 means ~50% expected success. Early learners may do
223
+ * better aiming higher: a shift of the curve's centre, independent of this.
87
224
  */
88
- export function createEloDistanceFilter(config?: EloDistanceConfig): CardFilter {
89
- const halfLife = config?.halfLife ?? DEFAULT_HALF_LIFE;
90
- const minMultiplier = config?.minMultiplier ?? DEFAULT_MIN_MULTIPLIER;
91
- const maxMultiplier = config?.maxMultiplier ?? DEFAULT_MAX_MULTIPLIER;
225
+ export function tagAwareGap(
226
+ cardTags: readonly string[],
227
+ cardElo: CourseElo,
228
+ userElo: CourseElo,
229
+ minTagCount: number
230
+ ): { gap: number; globalGap: number; tags: TagGap[] } {
231
+ const globalGap = cardElo.global.score - userElo.global.score;
232
+ const tags: TagGap[] = [];
233
+ for (const tag of cardTags) {
234
+ const user = userElo.tags[tag];
235
+ if (!user || user.score === COUNT_ONLY_SENTINEL || user.count < minTagCount) continue;
236
+ const card = cardElo.tags[tag]?.score ?? cardElo.global.score;
237
+ tags.push({
238
+ tag,
239
+ gap: card - user.score,
240
+ weight: user.count / (user.count + TAG_CONFIDENCE_HALF),
241
+ });
242
+ }
243
+ if (tags.length === 0) return { gap: globalGap, globalGap, tags };
92
244
 
93
- return {
94
- name: 'ELO Distance Filter',
245
+ const total = tags.reduce((w, t) => w + t.weight, 0);
246
+ const tagGap = tags.reduce((g, t) => g + t.weight * t.gap, 0) / total;
247
+ const lambda = total / (total + 1);
248
+ return { gap: lambda * tagGap + (1 - lambda) * globalGap, globalGap, tags };
249
+ }
250
+
251
+ function tagReason(tags: TagGap[], globalGap: number): string {
252
+ const shown = [...tags]
253
+ .sort((a, b) => Math.abs(b.gap) * b.weight - Math.abs(a.gap) * a.weight)
254
+ .slice(0, 3)
255
+ .map((t) => `${t.tag} ${t.gap >= 0 ? '+' : ''}${Math.round(t.gap)}`)
256
+ .join(', ');
257
+ const more = tags.length > 3 ? `, +${tags.length - 3} more` : '';
258
+ return ` on ${tags.length} shared tag(s) [${shown}${more}] (global ${globalGap >= 0 ? '+' : ''}${Math.round(globalGap)})`;
259
+ }
260
+
261
+ async function applyEloDistance(
262
+ cards: WeightedCard[],
263
+ context: FilterContext,
264
+ config: Required<EloDistanceConfig>,
265
+ source: { name: string; strategyId: string }
266
+ ): Promise<WeightedCard[]> {
267
+ const { course, userElo, userCourseElo } = context;
268
+ const { halfLife, minMultiplier, maxMultiplier } = config;
269
+ const tagAware = (config.tagAware || multiDimElo) && userCourseElo !== undefined;
95
270
 
96
- async transform(cards: WeightedCard[], context: FilterContext): Promise<WeightedCard[]> {
97
- const { course, userElo } = context;
271
+ // Tag-aware needs every card's full ratings; otherwise only the ELO of cards
272
+ // that don't carry it (reviews). One batch either way.
273
+ const missing = cards.filter((c) => tagAware || c.cardElo === undefined).map((c) => c.cardId);
274
+ const fetched = new Map<string, CourseElo>();
275
+ if (missing.length > 0) {
276
+ const elos = await course.getCardEloData(missing);
277
+ missing.forEach((id, i) => {
278
+ if (elos[i]) fetched.set(id, elos[i]);
279
+ });
280
+ }
98
281
 
99
- // Batch fetch ELO data for all cards
100
- const cardIds = cards.map((c) => c.cardId);
101
- const cardElos = await course.getCardEloData(cardIds);
282
+ return cards.map((card) => {
283
+ const full = fetched.get(card.cardId);
284
+ const cardElo = full?.global?.score ?? card.cardElo ?? DEFAULT_CARD_ELO;
102
285
 
103
- return cards.map((card, i) => {
104
- const cardElo = cardElos[i]?.global?.score ?? 1000;
105
- const distance = Math.abs(cardElo - userElo);
106
- const multiplier = computeMultiplier(distance, halfLife, minMultiplier, maxMultiplier);
107
- const newScore = card.score * multiplier;
286
+ let distance = Math.abs(cardElo - userElo);
287
+ let how = '';
288
+ if (tagAware) {
289
+ const t = full ? tagAwareGap(card.tags ?? [], full, userCourseElo!, config.minTagCount) : undefined;
290
+ if (t) distance = Math.abs(t.gap);
291
+ how = t?.tags.length
292
+ ? `, tag-aware${tagReason(t.tags, t.globalGap)}`
293
+ : ', tag-aware: global (no shared tags)';
294
+ }
108
295
 
109
- const action = multiplier < maxMultiplier - 0.01 ? 'penalized' : 'passed';
296
+ const multiplier = computeMultiplier(distance, halfLife, minMultiplier, maxMultiplier);
297
+ const newScore = card.score * multiplier;
298
+ const action = multiplier < maxMultiplier - 0.01 ? 'penalized' : 'passed';
110
299
 
111
- return {
112
- ...card,
300
+ return {
301
+ ...card,
302
+ cardElo,
303
+ score: newScore,
304
+ provenance: [
305
+ ...card.provenance,
306
+ {
307
+ strategy: 'eloDistance',
308
+ strategyName: source.name,
309
+ strategyId: source.strategyId,
310
+ action,
113
311
  score: newScore,
114
- provenance: [
115
- ...card.provenance,
116
- {
117
- strategy: 'eloDistance',
118
- strategyName: 'ELO Distance Filter',
119
- strategyId: 'ELO_DISTANCE_FILTER',
120
- action,
121
- score: newScore,
122
- reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userElo)}) → ${multiplier.toFixed(2)}x`,
123
- },
124
- ],
125
- };
126
- });
127
- },
312
+ reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userElo)})${how} → ${multiplier.toFixed(2)}x`,
313
+ },
314
+ ],
315
+ };
316
+ });
317
+ }
318
+
319
+ /**
320
+ * Create an ELO distance filter outside the strategy-doc path.
321
+ *
322
+ * @param config - Optional configuration for the curve
323
+ */
324
+ export function createEloDistanceFilter(config?: EloDistanceConfig): CardFilter {
325
+ const resolved = resolveConfig(config);
326
+ const source = { name: 'ELO Distance Filter', strategyId: 'ELO_DISTANCE_FILTER' };
327
+ return {
328
+ name: source.name,
329
+ kind: 'signal',
330
+ liveOnly: true,
331
+ transform: (cards, context) => applyEloDistance(cards, context, resolved, source),
128
332
  };
129
333
  }
130
334
 
131
- // Export defaults for testing
132
- export { DEFAULT_HALF_LIFE, DEFAULT_MIN_MULTIPLIER, DEFAULT_MAX_MULTIPLIER };
335
+ /**
336
+ * The ELO distance filter as a strategy-doc navigator (`implementingClass:
337
+ * 'eloDistance'`, serializedData: an EloDistanceConfig as JSON, or empty).
338
+ */
339
+ export default class EloDistanceFilter extends ContentNavigator implements CardFilter {
340
+ name: string;
341
+ /** See CardFilter.kind. Static, so the pipeline plan can read it without an instance. */
342
+ static readonly kind: FilterKind = 'signal';
343
+ readonly kind = EloDistanceFilter.kind;
344
+ readonly liveOnly = true;
345
+ private config: Required<EloDistanceConfig>;
346
+
347
+ constructor(
348
+ user: UserDBInterface,
349
+ course: CourseDBInterface,
350
+ strategyData: ContentNavigationStrategyData
351
+ ) {
352
+ super(user, course, strategyData);
353
+ this.name = strategyData.name || 'ELO Distance';
354
+ let parsed: EloDistanceConfig | undefined;
355
+ try {
356
+ parsed = strategyData.serializedData ? JSON.parse(strategyData.serializedData) : undefined;
357
+ } catch {
358
+ parsed = undefined;
359
+ }
360
+ this.config = resolveConfig(parsed);
361
+ }
362
+
363
+ transform(cards: WeightedCard[], context: FilterContext): Promise<WeightedCard[]> {
364
+ return applyEloDistance(cards, context, this.config, {
365
+ name: this.name,
366
+ strategyId: this.strategyId || 'NAVIGATION_STRATEGY-eloDistance-default',
367
+ });
368
+ }
369
+
370
+ async getWeightedCards(_limit: number): Promise<GeneratorResult> {
371
+ throw new Error(
372
+ 'EloDistanceFilter is a filter and should not be used as a generator. ' +
373
+ 'Use Pipeline with a generator and this filter via transform().'
374
+ );
375
+ }
376
+ }
@@ -3,7 +3,7 @@ import type { UserDBInterface } from '../../interfaces/userDB';
3
3
  import { ContentNavigator } from '../index';
4
4
  import type { WeightedCard } from '../index';
5
5
  import type { ContentNavigationStrategyData } from '../../types/contentNavigationStrategy';
6
- import type { CardFilter, FilterContext } from './types';
6
+ import type { CardFilter, FilterContext, FilterKind } from './types';
7
7
  import type { GeneratorResult } from '../generators/types';
8
8
  import { toCourseElo } from '@vue-skuilder/common';
9
9
  import { logger } from '../../../util/logger';
@@ -78,6 +78,10 @@ export default class HierarchyDefinitionNavigator extends ContentNavigator imple
78
78
  /** Human-readable name for CardFilter interface */
79
79
  name: string;
80
80
 
81
+ /** See CardFilter.kind. Static, so the pipeline plan can read it without an instance. */
82
+ static readonly kind: FilterKind = 'gate';
83
+ readonly kind = HierarchyDefinitionNavigator.kind;
84
+
81
85
  constructor(
82
86
  user: UserDBInterface,
83
87
  course: CourseDBInterface,
@@ -1,8 +1,8 @@
1
1
  // Filter types and interfaces
2
- export type { CardFilter, FilterContext, CardFilterFactory } from './types';
2
+ export type { CardFilter, FilterContext, CardFilterFactory, FilterKind } from './types';
3
3
 
4
4
  // Filter implementations
5
- export { createEloDistanceFilter } from './eloDistance';
5
+ export { createEloDistanceFilter, default as EloDistanceFilter } from './eloDistance';
6
6
  export type { EloDistanceConfig } from './eloDistance';
7
7
 
8
8
  export { default as UserTagPreferenceFilter } from './userTagPreference';
@@ -3,7 +3,7 @@ import type { UserDBInterface } from '../../interfaces/userDB';
3
3
  import { ContentNavigator } from '../index';
4
4
  import type { WeightedCard } from '../index';
5
5
  import type { ContentNavigationStrategyData } from '../../types/contentNavigationStrategy';
6
- import type { CardFilter, FilterContext } from './types';
6
+ import type { CardFilter, FilterContext, FilterKind } from './types';
7
7
  import type { GeneratorResult } from '../generators/types';
8
8
  import { toCourseElo } from '@vue-skuilder/common';
9
9
 
@@ -83,6 +83,10 @@ export default class InterferenceMitigatorNavigator extends ContentNavigator imp
83
83
  /** Human-readable name for CardFilter interface */
84
84
  name: string;
85
85
 
86
+ /** See CardFilter.kind. Static, so the pipeline plan can read it without an instance. */
87
+ static readonly kind: FilterKind = 'signal';
88
+ readonly kind = InterferenceMitigatorNavigator.kind;
89
+
86
90
  /** Precomputed map: tag -> set of { partner, decay } it interferes with */
87
91
  private interferenceMap: Map<string, Array<{ partner: string; decay: number }>>;
88
92
 
@@ -3,7 +3,7 @@ import type { UserDBInterface } from '../../interfaces/userDB';
3
3
  import { ContentNavigator } from '../index';
4
4
  import type { WeightedCard } from '../index';
5
5
  import type { ContentNavigationStrategyData } from '../../types/contentNavigationStrategy';
6
- import type { CardFilter, FilterContext } from './types';
6
+ import type { CardFilter, FilterContext, FilterKind } from './types';
7
7
  import type { GeneratorResult } from '../generators/types';
8
8
 
9
9
  /**
@@ -88,6 +88,10 @@ export default class RelativePriorityNavigator extends ContentNavigator implemen
88
88
  /** Human-readable name for CardFilter interface */
89
89
  name: string;
90
90
 
91
+ /** See CardFilter.kind. Static, so the pipeline plan can read it without an instance. */
92
+ static readonly kind: FilterKind = 'signal';
93
+ readonly kind = RelativePriorityNavigator.kind;
94
+
91
95
  constructor(
92
96
  user: UserDBInterface,
93
97
  course: CourseDBInterface,
@@ -2,6 +2,7 @@ import type { WeightedCard } from '../index';
2
2
  import type { CourseDBInterface } from '../../interfaces/courseDB';
3
3
  import type { UserDBInterface } from '../../interfaces/userDB';
4
4
  import type { OrchestrationContext } from '../../orchestration';
5
+ import type { CourseElo } from '@vue-skuilder/common';
5
6
 
6
7
  // ============================================================================
7
8
  // CARD FILTER INTERFACE
@@ -41,12 +42,14 @@ export interface FilterContext {
41
42
  /** User's global ELO score for this course */
42
43
  userElo: number;
43
44
 
45
+ /** User's full ELO for this course: global and per tag. Absent if it couldn't be read. */
46
+ userCourseElo?: CourseElo;
47
+
44
48
  /** Orchestration context for evolutionary weighting */
45
49
  orchestration?: OrchestrationContext;
46
50
 
47
51
  // Future extensions:
48
52
  // - hydrated tags for all cards (batch lookup)
49
- // - user's tag-level ELO data
50
53
  // - course config
51
54
  }
52
55
 
@@ -97,10 +100,30 @@ export interface FilterContext {
97
100
  * };
98
101
  * ```
99
102
  */
103
+ /**
104
+ * What a filter's penalties mean. A `gate` says a card isn't ready yet
105
+ * (prerequisites, lessons, unlocks); a `signal` expresses preference
106
+ * (priority, interference, ELO distance).
107
+ */
108
+ export type FilterKind = 'gate' | 'signal';
109
+
100
110
  export interface CardFilter {
101
111
  /** Human-readable name for this filter */
102
112
  name: string;
103
113
 
114
+ /**
115
+ * Regulators lift only new cards that no gate penalized, so pressure can't
116
+ * override "not ready". Undeclared filters count as gates: a penalty of
117
+ * unknown meaning shouldn't be overridden by pressure.
118
+ */
119
+ kind?: FilterKind;
120
+
121
+ /**
122
+ * Applies to live runs only. `forecast` and `diagnoseCardSpace` start every
123
+ * card at 1.0 without a generator, and skip these filters.
124
+ */
125
+ liveOnly?: boolean;
126
+
104
127
  /**
105
128
  * Transform a list of weighted cards.
106
129
  *
@@ -3,7 +3,7 @@ import type { UserDBInterface } from '../../interfaces/userDB';
3
3
  import { ContentNavigator } from '../index';
4
4
  import type { WeightedCard } from '../index';
5
5
  import type { ContentNavigationStrategyData } from '../../types/contentNavigationStrategy';
6
- import type { CardFilter, FilterContext } from './types';
6
+ import type { CardFilter, FilterContext, FilterKind } from './types';
7
7
  import type { GeneratorResult } from '../generators/types';
8
8
 
9
9
  // ============================================================================
@@ -81,6 +81,10 @@ export default class UserTagPreferenceFilter extends ContentNavigator implements
81
81
  /** Human-readable name for CardFilter interface */
82
82
  name: string;
83
83
 
84
+ /** See CardFilter.kind. Static, so the pipeline plan can read it without an instance. */
85
+ static readonly kind: FilterKind = 'signal';
86
+ readonly kind = UserTagPreferenceFilter.kind;
87
+
84
88
  constructor(
85
89
  user: UserDBInterface,
86
90
  course: CourseDBInterface,