@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
|
@@ -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
|
+
}
|
package/src/diagnostics/text.ts
CHANGED
|
@@ -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}
|
|
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}
|
|
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([
|
|
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.
|
|
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':
|
|
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.
|
|
75
|
-
expect(result[0].score).toBeCloseTo(0.
|
|
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 (
|
|
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.
|
|
86
|
-
expect(result[0].score).toBeCloseTo(0.
|
|
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.
|
|
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.
|
|
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 () => {
|