@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
@@ -0,0 +1,236 @@
1
+ import type { DatasetRecord, LearnerDataset } from './dataset';
2
+ import type { FilterKind } from '../core/navigators/filters/types';
3
+ import type { RegulatorName, RegulatorReading } from '../core/navigators/regulators';
4
+
5
+ // ============================================================================
6
+ // Pipeline run stats
7
+ // ============================================================================
8
+ //
9
+ // What each pipeline piece did across a learner's persisted runs, keyed by the
10
+ // names runs report generators and filters under. Those are the strategy docs'
11
+ // names, so these join to a `PipelinePlan` (`@vue-skuilder/db`) by name.
12
+ //
13
+ // Selection and outcome counts need runs that persist their selected cards
14
+ // (`StudySessionRunSummary.cards`, 0.2.28+). Older runs contribute only their
15
+ // generator and filter summaries.
16
+ //
17
+ // Generator new/review counts: before 0.2.29 the ELO generator's cards were
18
+ // counted as neither (the counts went by reason text), so means over older
19
+ // runs undercount `new`.
20
+ //
21
+ // ============================================================================
22
+
23
+ /** One generator across persisted runs. */
24
+ export interface GeneratorRunStat {
25
+ /** The name runs report it under (its strategy doc's name). */
26
+ name: string;
27
+ /** Runs it emitted at least one candidate in. */
28
+ runs: number;
29
+ /** Mean candidates per run, over the runs it appeared in. */
30
+ meanCards: number;
31
+ meanNew: number;
32
+ meanReview: number;
33
+ topScoreMax: number;
34
+ /** Top score in the most recent run it appeared in. */
35
+ topScoreLast: number;
36
+ /** Selected cards it originated (first provenance entry), over runs that persist selection. */
37
+ selected: number;
38
+ /** First attempts at those cards in the same session. */
39
+ firstAttempts: number;
40
+ firstAttemptsCorrect: number;
41
+ }
42
+
43
+ /** One filter across persisted runs: candidate counts summed over runs. */
44
+ export interface FilterRunStat {
45
+ name: string;
46
+ /** As recorded by the most recent run that recorded it (0.2.29+). */
47
+ kind?: FilterKind;
48
+ runs: number;
49
+ boosted: number;
50
+ penalized: number;
51
+ passed: number;
52
+ removed: number;
53
+ }
54
+
55
+ /** One regulator across persisted runs (0.2.29+). */
56
+ export interface RegulatorRunStat {
57
+ name: RegulatorName;
58
+ class: RegulatorReading['class'];
59
+ runs: number;
60
+ meanMultiplier: number;
61
+ maxMultiplier: number;
62
+ /** Runs where the multiplier was above 1. */
63
+ runsActive: number;
64
+ /** The most recent reading. */
65
+ last: RegulatorReading;
66
+ }
67
+
68
+ export interface PipelineRunStats {
69
+ sessions: number;
70
+ runs: number;
71
+ /** Runs that persist their selected cards. Selection and outcome counts cover only these. */
72
+ runsWithSelection: number;
73
+ firstRunAt?: string;
74
+ lastRunAt?: string;
75
+ /** Busiest first. */
76
+ generators: GeneratorRunStat[];
77
+ /** By name. */
78
+ filters: FilterRunStat[];
79
+ /** Empty before 0.2.29. */
80
+ regulators: RegulatorRunStat[];
81
+ /** Selected cards with no originating generator: cards forced in by `requireCards`. */
82
+ selectedUnattributed: number;
83
+ }
84
+
85
+ /** Aggregate a learner's persisted pipeline runs, optionally only sessions started at or after `since` (ISO). */
86
+ export function pipelineRunStats(
87
+ ds: LearnerDataset,
88
+ opts: { since?: string } = {}
89
+ ): PipelineRunStats {
90
+ const sessions = ds.sessions.filter((s) => !opts.since || s.startTime >= opts.since);
91
+
92
+ const recordsBySession = new Map<string, Array<{ cardId: string; record: DatasetRecord }>>();
93
+ for (const h of ds.cardHistories) {
94
+ for (const record of h.records) {
95
+ if (!record.sessionId) continue;
96
+ const list = recordsBySession.get(record.sessionId) ?? [];
97
+ list.push({ cardId: h.cardID, record });
98
+ recordsBySession.set(record.sessionId, list);
99
+ }
100
+ }
101
+
102
+ type GenAcc = Omit<GeneratorRunStat, 'meanCards' | 'meanNew' | 'meanReview'> & {
103
+ cards: number;
104
+ newCards: number;
105
+ reviewCards: number;
106
+ };
107
+ const gens = new Map<string, GenAcc>();
108
+ const gen = (name: string): GenAcc => {
109
+ let g = gens.get(name);
110
+ if (!g) {
111
+ g = {
112
+ name,
113
+ runs: 0,
114
+ cards: 0,
115
+ newCards: 0,
116
+ reviewCards: 0,
117
+ topScoreMax: 0,
118
+ topScoreLast: 0,
119
+ selected: 0,
120
+ firstAttempts: 0,
121
+ firstAttemptsCorrect: 0,
122
+ };
123
+ gens.set(name, g);
124
+ }
125
+ return g;
126
+ };
127
+ const filters = new Map<string, FilterRunStat>();
128
+ const regulators = new Map<RegulatorName, RegulatorRunStat & { sumMultiplier: number }>();
129
+
130
+ let runs = 0;
131
+ let runsWithSelection = 0;
132
+ let selectedUnattributed = 0;
133
+ let firstRunAt: string | undefined;
134
+ let lastRunAt: string | undefined;
135
+
136
+ for (const session of sessions) {
137
+ // A card selected by several runs is credited to the first run that chose it.
138
+ const originBySelectedCard = new Map<string, string>();
139
+
140
+ for (const run of session.runs ?? []) {
141
+ runs++;
142
+ if (!firstRunAt || run.at < firstRunAt) firstRunAt = run.at;
143
+ if (!lastRunAt || run.at > lastRunAt) lastRunAt = run.at;
144
+
145
+ for (const s of run.generators ?? []) {
146
+ const g = gen(s.name);
147
+ g.runs++;
148
+ g.cards += s.cardCount;
149
+ g.newCards += s.newCount;
150
+ g.reviewCards += s.reviewCount;
151
+ g.topScoreMax = Math.max(g.topScoreMax, s.topScore);
152
+ g.topScoreLast = s.topScore;
153
+ }
154
+
155
+ for (const f of run.filters ?? []) {
156
+ const acc = filters.get(f.name) ?? {
157
+ name: f.name,
158
+ runs: 0,
159
+ boosted: 0,
160
+ penalized: 0,
161
+ passed: 0,
162
+ removed: 0,
163
+ };
164
+ acc.runs++;
165
+ if (f.kind) acc.kind = f.kind;
166
+ acc.boosted += f.boosted;
167
+ acc.penalized += f.penalized;
168
+ acc.passed += f.passed;
169
+ acc.removed += f.removed;
170
+ filters.set(f.name, acc);
171
+ }
172
+
173
+ for (const r of run.regulators ?? []) {
174
+ const acc = regulators.get(r.name) ?? {
175
+ name: r.name,
176
+ class: r.class,
177
+ runs: 0,
178
+ meanMultiplier: 0,
179
+ maxMultiplier: 0,
180
+ runsActive: 0,
181
+ last: r,
182
+ sumMultiplier: 0,
183
+ };
184
+ acc.runs++;
185
+ acc.sumMultiplier += r.multiplier;
186
+ acc.maxMultiplier = Math.max(acc.maxMultiplier, r.multiplier);
187
+ if (r.multiplier > 1) acc.runsActive++;
188
+ acc.last = r;
189
+ regulators.set(r.name, acc);
190
+ }
191
+
192
+ if (run.cards) {
193
+ runsWithSelection++;
194
+ for (const c of run.cards) {
195
+ if (!c.selected) continue;
196
+ if (!c.generator) {
197
+ selectedUnattributed++;
198
+ continue;
199
+ }
200
+ gen(c.generator).selected++;
201
+ if (!originBySelectedCard.has(c.cardId)) originBySelectedCard.set(c.cardId, c.generator);
202
+ }
203
+ }
204
+ }
205
+
206
+ for (const { cardId, record } of recordsBySession.get(session.sessionId) ?? []) {
207
+ const origin = originBySelectedCard.get(cardId);
208
+ if (!origin || record.priorAttemps !== 0) continue;
209
+ const g = gen(origin);
210
+ g.firstAttempts++;
211
+ if (record.isCorrect === true) g.firstAttemptsCorrect++;
212
+ }
213
+ }
214
+
215
+ return {
216
+ sessions: sessions.length,
217
+ runs,
218
+ runsWithSelection,
219
+ firstRunAt,
220
+ lastRunAt,
221
+ generators: [...gens.values()]
222
+ .map(({ cards, newCards, reviewCards, ...g }) => ({
223
+ ...g,
224
+ meanCards: g.runs ? cards / g.runs : 0,
225
+ meanNew: g.runs ? newCards / g.runs : 0,
226
+ meanReview: g.runs ? reviewCards / g.runs : 0,
227
+ }))
228
+ .sort((a, b) => b.runs - a.runs || a.name.localeCompare(b.name)),
229
+ filters: [...filters.values()].sort((a, b) => a.name.localeCompare(b.name)),
230
+ regulators: [...regulators.values()].map(({ sumMultiplier, ...r }) => ({
231
+ ...r,
232
+ meanMultiplier: r.runs ? sumMultiplier / r.runs : 0,
233
+ })),
234
+ selectedUnattributed,
235
+ };
236
+ }
@@ -4,6 +4,7 @@
4
4
  * text; these are those texts. Also the shared number formatting.
5
5
  */
6
6
  import type { StudySessionRunCardTrail, StudySessionRunSummary } from '../core/types/studySession';
7
+ import type { RegulatorReading } from '../core/navigators/regulators';
7
8
  import {
8
9
  shortTag,
9
10
  type DiagnosticsInterpreters,
@@ -55,6 +56,22 @@ function trailText(label: string, t: StudySessionRunCardTrail): string[] {
55
56
  return lines;
56
57
  }
57
58
 
59
+ /** One regulator reading as a line: its urgency, inputs, and multiplier. */
60
+ export function regulatorText(r: RegulatorReading): string {
61
+ const i = r.inputs;
62
+ if (r.name === 'review-mass') {
63
+ return (
64
+ `review mass ${r.urgency.toFixed(1)} over ${i.due ?? r.applied} due` +
65
+ ` (healthy ${i.healthyMass}) → ×${r.multiplier.toFixed(2)}`
66
+ );
67
+ }
68
+ const frozen = i.frozenHours ? `, ${i.frozenHours.toFixed(1)}h frozen` : '';
69
+ return (
70
+ `intake ${r.urgency.toFixed(1)}h since a new card${frozen};` +
71
+ ` ${i.eligibleNew ?? r.applied}/${i.newCandidates ?? '?'} new eligible → ×${r.multiplier.toFixed(2)}`
72
+ );
73
+ }
74
+
58
75
  /** One run as a compact text block. */
59
76
  export function runText(run: StudySessionRunSummary): string {
60
77
  const L: string[] = [];
@@ -78,11 +95,15 @@ export function runText(run: StudySessionRunSummary): string {
78
95
  L.push(' filters:');
79
96
  for (const f of run.filters) {
80
97
  L.push(
81
- ` - ${f.name}: +${f.boosted} boosted, -${f.penalized} penalized,` +
82
- ` ${f.passed} passed, ${f.removed} removed`
98
+ ` - ${f.name}${f.kind ? ` (${f.kind})` : ''}: +${f.boosted} boosted,` +
99
+ ` -${f.penalized} penalized, ${f.passed} passed, ${f.removed} removed`
83
100
  );
84
101
  }
85
102
  }
103
+ if (run.regulators?.length) {
104
+ L.push(' regulators:');
105
+ for (const r of run.regulators) L.push(` - ${regulatorText(r)}`);
106
+ }
86
107
  if (run.hints) L.push(` hints: ${JSON.stringify(run.hints)}`);
87
108
  if (run.cards?.length) {
88
109
  L.push(' selection (✓ selected, · runner-up):');
@@ -151,7 +172,9 @@ export function sessionText(
151
172
  L.push('- RUN "generated N → selected M (a new, b review)": the pipeline produced N');
152
173
  L.push(' candidates and chose M. "nothing survived" = generated > 0 but 0 selected.');
153
174
  L.push(' Bootstrap runs fire before card #1; replans are interleaved by time.');
154
- L.push("- generators: each source's contribution. filters: how each reshaped scores.");
175
+ L.push("- generators: each source's contribution. filters: how each reshaped scores");
176
+ L.push(' (gate: not ready yet; signal: preference). regulators: the pressure on each class,');
177
+ L.push(' review mass (due reviews by value) and intake (hours since a new card).');
155
178
  L.push(' hints: the ReplanHints the navigator was told (_label = replan reason).');
156
179
  L.push(' selection: the chosen cards and top runners-up. "next new in line" / "top-generated');
157
180
  L.push(' new (sunk)": the unselected new cards worth explaining, with each score change.');
@@ -12,6 +12,7 @@ import {
12
12
 
13
13
  import { filterAllDocsByPrefix, getCourseDB } from '.';
14
14
  import UpdateQueue from './updateQueue';
15
+ import type { StudyContentSource } from '../../core/interfaces/contentSource';
15
16
  import { StudySessionItem } from '../../core/interfaces/contentSource';
16
17
  import {
17
18
  CardData,
@@ -712,6 +713,18 @@ above:\n${above.rows.map((r) => `\t${r.id}-${r.key}\n`)}`;
712
713
  this._pendingHints = hints;
713
714
  }
714
715
 
716
+ /**
717
+ * Forward a presentation to the navigator (a new card restarts its intake
718
+ * clock). Builds the navigator if the cached one has expired.
719
+ */
720
+ public notePresented(card: { cardId: string; courseId: string; status: string }): void {
721
+ if (card.status !== 'new') return;
722
+ void this._getCurrentUser()
723
+ .then((u) => this._getCachedNavigator(u))
724
+ .then(({ navigator }) => (navigator as StudyContentSource).notePresented?.(card))
725
+ .catch((e) => logger.warn(`[courseDB] Could not note a presentation: ${e}`));
726
+ }
727
+
715
728
  public async getWeightedCards(limit: number): Promise<GeneratorResult> {
716
729
  const u = await this._getCurrentUser();
717
730
 
@@ -5,6 +5,7 @@ import {
5
5
  UserDBInterface,
6
6
  CourseInfo,
7
7
  StudySessionItem,
8
+ type StudyContentSource,
8
9
  } from '../../core/interfaces';
9
10
  import type { GeneratorResult, ReplanHints } from '../../core/navigators/generators/types';
10
11
  import { StaticDataUnpacker } from './StaticDataUnpacker';
@@ -450,6 +451,14 @@ export class StaticCourseDB implements CourseDBInterface {
450
451
  this._pendingHints = hints;
451
452
  }
452
453
 
454
+ /** Forward a presentation to the navigator (a new card restarts its intake clock). */
455
+ notePresented(card: { cardId: string; courseId: string; status: string }): void {
456
+ if (card.status !== 'new') return;
457
+ void this.createNavigator(this.userDB)
458
+ .then((navigator) => (navigator as StudyContentSource).notePresented?.(card))
459
+ .catch((e) => logger.warn(`[static/courseDB] Could not note a presentation: ${e}`));
460
+ }
461
+
453
462
  async getWeightedCards(limit: number): Promise<GeneratorResult> {
454
463
  try {
455
464
  const navigator = await this.createNavigator(this.userDB);
package/src/index.ts CHANGED
@@ -1,5 +1,9 @@
1
1
  export * from './core';
2
2
 
3
+ // Not via the navigators barrel: see the note in pipelinePlan.ts.
4
+ export * from './core/navigators/pipelinePlan';
5
+ export * from './core/navigators/regulators';
6
+
3
7
  export { default as CourseLookup } from './impl/couch/courseLookupDB';
4
8
 
5
9
  export * from './courseConfigRegistration';
@@ -38,6 +38,7 @@ import {
38
38
  import type { PipelineRunReport, RunReportCard } from '@db/core/navigators';
39
39
  import { ReplanHints } from '@db/core/navigators/generators/types';
40
40
  import { mergeHints } from '@db/core/navigators/Pipeline';
41
+ import type { RegulatorReading } from '@db/core/navigators/regulators';
41
42
  import { SourceMixer, QuotaRoundRobinMixer, SourceBatch } from './SourceMixer';
42
43
  import { captureMixerRun } from './MixerDebugger';
43
44
  import { startSessionTracking, recordCardPresentation, snapshotQueues, endSessionTracking, clearStaleSessionDebugState } from './SessionDebugger';
@@ -257,6 +258,15 @@ function toRunCardTrail(c: RunReportCard): StudySessionRunCardTrail {
257
258
  };
258
259
  }
259
260
 
261
+ function persistedReading(r: RegulatorReading): RegulatorReading {
262
+ return {
263
+ ...r,
264
+ urgency: sig4(r.urgency),
265
+ multiplier: sig4(r.multiplier),
266
+ inputs: Object.fromEntries(Object.entries(r.inputs).map(([k, v]) => [k, sig4(v)])),
267
+ };
268
+ }
269
+
260
270
  /** `run.cards` is selected-then-near-misses, each in score order. */
261
271
  function persistedRunCards(run: PipelineRunReport): StudySessionRunCard[] {
262
272
  const selected = run.cards.filter((c) => c.selected);
@@ -636,6 +646,7 @@ export class SessionController<TView = unknown> extends Loggable {
636
646
  ...(run.discardedTail ? { discardedTail: run.discardedTail } : {}),
637
647
  cards: persistedRunCards(run),
638
648
  ...(run.unselectedNew ? { unselectedNew: persistedUnselectedNew(run.unselectedNew) } : {}),
649
+ ...(run.regulators ? { regulators: run.regulators.map(persistedReading) } : {}),
639
650
  });
640
651
  }
641
652
  }
@@ -1756,6 +1767,15 @@ export class SessionController<TView = unknown> extends Loggable {
1756
1767
  nextItem.score
1757
1768
  );
1758
1769
 
1770
+ // Tell the sources (a new card discharges a pipeline's intake valve).
1771
+ for (const source of this.sources) {
1772
+ source.notePresented?.({
1773
+ cardId: nextItem.cardID,
1774
+ courseId: nextItem.courseID,
1775
+ status: nextItem.status,
1776
+ });
1777
+ }
1778
+
1759
1779
  // Snapshot queue state
1760
1780
  snapshotQueues(this.supplyQ.length, this.failedQ.length);
1761
1781
 
@@ -403,14 +403,16 @@ function backlogHtml(backlog: SrsBacklogDebug[]): string {
403
403
  const multColor = b.backlogMultiplier <= 1 ? '#86efac' : hot ? '#fca5a5' : '#fcd34d';
404
404
  const headroom =
405
405
  b.backlogMultiplier > 1
406
- ? `climbing (×${b.backlogGrowthRate.toFixed(2)} per ${b.healthyBacklog}-review excess, unbounded)`
406
+ ? `climbing (×${b.backlogGrowthRate.toFixed(2)} per ${b.healthyBacklog} of mass in excess, unbounded)`
407
407
  : 'healthy — no pressure';
408
+ const mass =
409
+ b.reviewMass !== null ? ` · mass ${b.reviewMass.toFixed(1)}` : '';
408
410
  const top = b.topReviewScore !== null ? b.topReviewScore.toFixed(2) : '—';
409
411
  const next = b.nextDueIn ? ` <span style="opacity:.6">· next due ${esc(b.nextDueIn)}</span>` : '';
410
412
  return (
411
413
  `<div style="margin-left:6px">` +
412
414
  `<span style="opacity:.7">${esc(b.courseId.slice(0, 8))}</span> ` +
413
- `due ${b.dueNow}/${b.scheduledTotal} <span style="opacity:.6">(healthy ${b.healthyBacklog})</span>${next}` +
415
+ `due ${b.dueNow}/${b.scheduledTotal}${mass} <span style="opacity:.6">(healthy mass ${b.healthyBacklog})</span>${next}` +
414
416
  `<div style="margin-left:6px">` +
415
417
  `pressure <span style="color:${multColor}">×${b.backlogMultiplier.toFixed(2)}</span> ` +
416
418
  `<span style="opacity:.6">${headroom} · top review ${top}</span></div>` +
@@ -651,9 +653,10 @@ function snapshotToText(s: SessionDebugSnapshot | null): string {
651
653
  const headroom = b.backlogMultiplier > 1 ? 'climbing' : 'healthy';
652
654
  const top = b.topReviewScore !== null ? b.topReviewScore.toFixed(2) : '—';
653
655
  const next = b.nextDueIn ? `, next due ${b.nextDueIn}` : '';
656
+ const mass = b.reviewMass !== null ? `, mass ${b.reviewMass.toFixed(1)}` : '';
654
657
  lines.push(
655
- ` ${b.courseId.slice(0, 8)}: due ${b.dueNow}/${b.scheduledTotal} ` +
656
- `(healthy ${b.healthyBacklog})${next}; pressure ×${b.backlogMultiplier.toFixed(2)} ` +
658
+ ` ${b.courseId.slice(0, 8)}: due ${b.dueNow}/${b.scheduledTotal}${mass} ` +
659
+ `(healthy mass ${b.healthyBacklog})${next}; pressure ×${b.backlogMultiplier.toFixed(2)} ` +
657
660
  `${headroom}; top review ${top}`
658
661
  );
659
662
  }
@@ -185,7 +185,7 @@ describe('PipelineAssembler', () => {
185
185
  expect(result.generatorStrategies).toHaveLength(2);
186
186
  const strategyNames = result.generatorStrategies.map((s) => s.name).sort();
187
187
  expect(strategyNames).toEqual(['ELO (default)', 'SRS (default)']);
188
- expect(result.filterStrategies).toEqual([hierarchy]);
188
+ expect(result.filterStrategies.map((f) => f.name)).toEqual(['ELO Distance (default)', 'hierarchy']);
189
189
  expect(result.warnings).toEqual([]);
190
190
  });
191
191
  });
@@ -199,10 +199,18 @@ describe('PipelineAssembler', () => {
199
199
 
200
200
  expect(result.pipeline).toBeInstanceOf(Pipeline);
201
201
  // expect(result.generatorStrategies).toEqual([elo]); // default pipeline now includes srs+elo
202
- expect(result.filterStrategies).toEqual([hierarchy]);
202
+ expect(result.filterStrategies.map((f) => f.name)).toEqual(['ELO Distance (default)', 'hierarchy']);
203
203
  expect(result.warnings).toEqual([]);
204
204
  });
205
205
 
206
+ it('adds the default ELO distance filter only when the course declares none', async () => {
207
+ const own = createStrategy('own-elo-distance', 'eloDistance', '{"halfLife": 200}');
208
+ const input = createInput([own]);
209
+ const result = await assembler.assemble(input);
210
+
211
+ expect(result.filterStrategies).toEqual([own]);
212
+ });
213
+
206
214
  it('sorts filters alphabetically for deterministic ordering', async () => {
207
215
  const elo = createStrategy('elo', 'elo');
208
216
  const relativePriority = createStrategy(
@@ -230,6 +238,7 @@ describe('PipelineAssembler', () => {
230
238
  // Filters should be sorted alphabetically by name
231
239
  expect(result.filterStrategies.map((f) => f.name)).toEqual([
232
240
  'a-hierarchy',
241
+ 'ELO Distance (default)',
233
242
  'm-interference',
234
243
  'z-relative-priority',
235
244
  ]);
@@ -247,7 +256,7 @@ describe('PipelineAssembler', () => {
247
256
 
248
257
  expect(result.pipeline).toBeInstanceOf(Pipeline);
249
258
  // expect(result.generatorStrategies).toEqual([elo]); // default pipeline now includes srs+elo
250
- expect(result.filterStrategies).toEqual([hierarchy]);
259
+ expect(result.filterStrategies.map((f) => f.name)).toEqual(['ELO Distance (default)', 'hierarchy']);
251
260
  expect(result.warnings).toContain(
252
261
  "Unknown strategy type 'unknownStrategyType', skipping: unknown"
253
262
  );
@@ -266,8 +275,12 @@ describe('PipelineAssembler', () => {
266
275
  // Should have both generators
267
276
  // expect(result.generatorStrategies).toEqual([elo]);
268
277
 
269
- // Should have both filters (sorted alphabetically)
270
- expect(result.filterStrategies.map((f) => f.name)).toEqual(['hierarchy', 'priority']);
278
+ // Should have both filters plus the default ELO distance (sorted alphabetically)
279
+ expect(result.filterStrategies.map((f) => f.name)).toEqual([
280
+ 'ELO Distance (default)',
281
+ 'hierarchy',
282
+ 'priority',
283
+ ]);
271
284
 
272
285
  // Should produce a valid pipeline
273
286
  expect(result.pipeline).toBeInstanceOf(Pipeline);
@@ -291,11 +304,13 @@ describe('PipelineAssembler', () => {
291
304
  'a-filter',
292
305
  'b-filter',
293
306
  'c-filter',
307
+ 'ELO Distance (default)',
294
308
  ]);
295
309
  expect(result2.filterStrategies.map((f) => f.name)).toEqual([
296
310
  'a-filter',
297
311
  'b-filter',
298
312
  'c-filter',
313
+ 'ELO Distance (default)',
299
314
  ]);
300
315
  });
301
316
  });
@@ -63,27 +63,27 @@ describe('ELO Distance Filter', () => {
63
63
  expect(result[0].score).toBeCloseTo(1.0, 2);
64
64
  });
65
65
 
66
- it('should return ~0.6 multiplier at halfLife distance (200 ELO)', async () => {
66
+ it('should return ~0.4 multiplier at halfLife distance (300 ELO)', async () => {
67
67
  const filter = createEloDistanceFilter();
68
68
  const cards = [createCard('card-1', 1.0)];
69
- const context = createMockContext(1000, { 'card-1': 1200 }); // 200 distance
69
+ const context = createMockContext(1000, { 'card-1': 1300 }); // 300 distance
70
70
 
71
71
  const result = await filter.transform(cards, context);
72
72
 
73
73
  // At halfLife: minMultiplier + (maxMultiplier - minMultiplier) * exp(-1)
74
- // = 0.3 + 0.7 * 0.368 ≈ 0.56
75
- expect(result[0].score).toBeCloseTo(0.56, 1);
74
+ // = 0.05 + 0.95 * 0.368 ≈ 0.40
75
+ expect(result[0].score).toBeCloseTo(0.4, 1);
76
76
  });
77
77
 
78
78
  it('should approach minMultiplier for very large distances', async () => {
79
79
  const filter = createEloDistanceFilter();
80
80
  const cards = [createCard('card-1', 1.0)];
81
- const context = createMockContext(1000, { 'card-1': 2000 }); // 1000 distance (5x halfLife)
81
+ const context = createMockContext(1000, { 'card-1': 2000 }); // 1000 distance (3.3x halfLife)
82
82
 
83
83
  const result = await filter.transform(cards, context);
84
84
 
85
- // Should be very close to minMultiplier (0.3)
86
- expect(result[0].score).toBeCloseTo(0.3, 1);
85
+ // Should be very close to minMultiplier (0.05)
86
+ expect(result[0].score).toBeCloseTo(0.05, 2);
87
87
  });
88
88
 
89
89
  it('should be symmetric - same penalty above and below user ELO', async () => {
@@ -162,14 +162,14 @@ describe('ELO Distance Filter', () => {
162
162
 
163
163
  describe('custom configuration', () => {
164
164
  it('should use custom halfLife when provided', async () => {
165
- // With halfLife=100, distance 100 should give ~0.56 multiplier
165
+ // With halfLife=100, distance 100 should give ~0.4 multiplier
166
166
  const filter = createEloDistanceFilter({ halfLife: 100 });
167
167
  const cards = [createCard('card-1', 1.0)];
168
168
  const context = createMockContext(1000, { 'card-1': 1100 }); // 100 distance
169
169
 
170
170
  const result = await filter.transform(cards, context);
171
171
 
172
- expect(result[0].score).toBeCloseTo(0.56, 1);
172
+ expect(result[0].score).toBeCloseTo(0.4, 1);
173
173
  });
174
174
 
175
175
  it('should use custom min/max multipliers when provided', async () => {