@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
@@ -0,0 +1,245 @@
1
+ import type { ContentNavigationStrategyData } from '../types/contentNavigationStrategy';
2
+ import { getRegisteredFilterKind, isFilter, isGenerator, NavigatorRole } from './index';
3
+ import type { FilterKind } from './filters/types';
4
+ import { DEFAULT_REGULATOR_CONFIG, type RegulatorConfig } from './regulators';
5
+ import {
6
+ createDefaultEloDistanceStrategy,
7
+ createDefaultEloStrategy,
8
+ createDefaultSrsStrategy,
9
+ } from './defaults';
10
+
11
+ // ============================================================================
12
+ // PIPELINE PLAN
13
+ // ============================================================================
14
+ //
15
+ // What a course's strategy documents assemble into, as data: which generators
16
+ // and filters run, in what order, and which ones the assembler added itself.
17
+ // Pure: no user, no instantiation. PipelineAssembler builds from this plan and
18
+ // the admin pipeline view renders it, so the view can't drift from what runs.
19
+ //
20
+ // Roles come from the navigator registry, so a plan reflects the app it's
21
+ // computed in. A course's consumer-registered filters plan as `skipped` in an
22
+ // app that never registered them, which is also how they'd assemble there.
23
+ //
24
+ // Not exported from './index' (the navigators barrel): './defaults' imports the
25
+ // generator classes, which extend ContentNavigator from that barrel.
26
+ //
27
+ // ============================================================================
28
+
29
+ export type PlannedNavigatorOrigin =
30
+ /** From the course's strategy documents. */
31
+ | 'strategy-doc'
32
+ /** Added by the assembler because the course declared none of its kind. */
33
+ | 'assembler-default'
34
+ /** Part of the fallback pipeline for a course with no strategy documents. */
35
+ | 'default-pipeline';
36
+
37
+ export interface PlannedNavigator {
38
+ role: NavigatorRole;
39
+ origin: PlannedNavigatorOrigin;
40
+ /** The name runs report this navigator under (generator summaries, filter impacts). */
41
+ name: string;
42
+ implementingClass: string;
43
+ /** The strategy document: the course's own, or the default the assembler supplies. */
44
+ strategy: ContentNavigationStrategyData;
45
+ /**
46
+ * Filters only: the kind its class declares (`static kind`), read from the
47
+ * navigator registry. Undefined if undeclared, which runs as a gate.
48
+ */
49
+ kind?: FilterKind;
50
+ }
51
+
52
+ export interface SkippedStrategy {
53
+ strategy: ContentNavigationStrategyData;
54
+ reason: string;
55
+ }
56
+
57
+ export interface PipelinePlan {
58
+ /** Assembled from strategy documents, or the fallback for a course with none. */
59
+ kind: 'assembled' | 'default';
60
+ generators: PlannedNavigator[];
61
+ /** In run order. */
62
+ filters: PlannedNavigator[];
63
+ skipped: SkippedStrategy[];
64
+ warnings: string[];
65
+ /** Consequences of the plan worth knowing that aren't errors. */
66
+ notes: string[];
67
+ /** The regulator stage's settings (see regulators.ts). */
68
+ regulators: RegulatorConfig;
69
+ }
70
+
71
+ export type PipelineStageKey =
72
+ | 'generate'
73
+ | 'filter'
74
+ | 'drop-zero'
75
+ | 'regulate'
76
+ | 'hints'
77
+ | 'diversity'
78
+ | 'select';
79
+
80
+ /** One step of a pipeline run, in order. Shared by views and text exports. */
81
+ export interface PipelineStageInfo {
82
+ key: PipelineStageKey;
83
+ title: string;
84
+ summary: string;
85
+ }
86
+
87
+ /**
88
+ * The steps every pipeline run takes, in order (`Pipeline.getWeightedCards`).
89
+ * `generate` and `filter` are where a plan's navigators run; the rest are
90
+ * fixed framework behaviour.
91
+ */
92
+ export const PIPELINE_STAGES: readonly PipelineStageInfo[] = [
93
+ {
94
+ key: 'generate',
95
+ title: 'Generate',
96
+ summary:
97
+ 'Each generator proposes candidates (up to 500 in all), scored on what is specific to its ' +
98
+ 'source. A card proposed by several generators keeps their mean score, raised 10% per extra ' +
99
+ 'generator.',
100
+ },
101
+ {
102
+ key: 'filter',
103
+ title: 'Filter',
104
+ summary:
105
+ 'Each filter multiplies candidate scores, in the order shown. A gate says a card is not ready ' +
106
+ 'yet; a signal expresses preference. Gates usually penalize rather than remove, so a gated ' +
107
+ 'card stays in the pool at a low score.',
108
+ },
109
+ {
110
+ key: 'drop-zero',
111
+ title: 'Drop zero scores',
112
+ summary: 'Candidates whose score reached 0 leave the pool.',
113
+ },
114
+ {
115
+ key: 'regulate',
116
+ title: 'Regulate',
117
+ summary:
118
+ 'Balances reviews against new cards. Review mass: the due reviews weighed by their filtered ' +
119
+ 'scores; above a healthy level, every review is lifted. Intake: hours since a new card was ' +
120
+ 'last presented; new cards no gate penalized are lifted, and the clock stops while there are ' +
121
+ 'none.',
122
+ },
123
+ {
124
+ key: 'hints',
125
+ title: 'Apply hints',
126
+ summary:
127
+ "The session's hints (from the app: an intro's follow-up, a difficulty boost) exclude, " +
128
+ 'boost, or require cards. Required cards skip the filters entirely.',
129
+ },
130
+ {
131
+ key: 'diversity',
132
+ title: 'Diversity re-rank',
133
+ summary:
134
+ 'Demotes candidates that repeat a distinctive tag already ranked above them, so one ' +
135
+ 'concept or answer cannot take the whole head of the queue. Sees this run only, not what ' +
136
+ 'the session already served.',
137
+ },
138
+ {
139
+ key: 'select',
140
+ title: 'Select',
141
+ summary:
142
+ "Highest scores first, up to the run's limit. The session mixes them into its supply queue.",
143
+ },
144
+ ];
145
+
146
+ function planned(
147
+ strategy: ContentNavigationStrategyData,
148
+ role: NavigatorRole,
149
+ origin: PlannedNavigatorOrigin
150
+ ): PlannedNavigator {
151
+ const kind =
152
+ role === NavigatorRole.FILTER ? getRegisteredFilterKind(strategy.implementingClass) : undefined;
153
+ return {
154
+ role,
155
+ origin,
156
+ name: strategy.name,
157
+ implementingClass: strategy.implementingClass,
158
+ strategy,
159
+ ...(kind ? { kind } : {}),
160
+ };
161
+ }
162
+
163
+ /**
164
+ * Plan the pipeline a course's strategy documents assemble into.
165
+ *
166
+ * Mirrors the assembly rules: generators keep document order, with ELO and SRS
167
+ * added when absent; an ELO distance filter is added when absent; filters run
168
+ * sorted by name; unknown implementing classes are skipped with a warning. With no documents at all, describes the default
169
+ * pipeline that `createDefaultPipeline` builds instead.
170
+ */
171
+ export function planPipeline(
172
+ strategies: ContentNavigationStrategyData[],
173
+ courseId: string
174
+ ): PipelinePlan {
175
+ if (strategies.length === 0) {
176
+ return {
177
+ kind: 'default',
178
+ generators: [
179
+ planned(createDefaultEloStrategy(courseId), NavigatorRole.GENERATOR, 'default-pipeline'),
180
+ planned(createDefaultSrsStrategy(courseId), NavigatorRole.GENERATOR, 'default-pipeline'),
181
+ ],
182
+ filters: [
183
+ planned(
184
+ createDefaultEloDistanceStrategy(courseId),
185
+ NavigatorRole.FILTER,
186
+ 'default-pipeline'
187
+ ),
188
+ ],
189
+ skipped: [],
190
+ warnings: [],
191
+ notes: [],
192
+ regulators: DEFAULT_REGULATOR_CONFIG,
193
+ };
194
+ }
195
+
196
+ const generators: PlannedNavigator[] = [];
197
+ const filters: PlannedNavigator[] = [];
198
+ const skipped: SkippedStrategy[] = [];
199
+ const warnings: string[] = [];
200
+
201
+ for (const s of strategies) {
202
+ if (isGenerator(s.implementingClass)) {
203
+ generators.push(planned(s, NavigatorRole.GENERATOR, 'strategy-doc'));
204
+ } else if (isFilter(s.implementingClass)) {
205
+ filters.push(planned(s, NavigatorRole.FILTER, 'strategy-doc'));
206
+ } else {
207
+ skipped.push({ strategy: s, reason: 'not a registered generator or filter' });
208
+ warnings.push(`Unknown strategy type '${s.implementingClass}', skipping: ${s.name}`);
209
+ }
210
+ }
211
+
212
+ // ELO and SRS are always present; custom generators supplement, never replace them.
213
+ const declared = new Set(generators.map((g) => g.implementingClass));
214
+ if (!declared.has(createDefaultEloStrategy(courseId).implementingClass)) {
215
+ generators.push(
216
+ planned(createDefaultEloStrategy(courseId), NavigatorRole.GENERATOR, 'assembler-default')
217
+ );
218
+ }
219
+ if (!declared.has(createDefaultSrsStrategy(courseId).implementingClass)) {
220
+ generators.push(
221
+ planned(createDefaultSrsStrategy(courseId), NavigatorRole.GENERATOR, 'assembler-default')
222
+ );
223
+ }
224
+
225
+ // ELO distance is the one place distance counts, for reviews and new cards alike
226
+ // (the ELO generator only retrieves near the learner's ELO). A course tunes it
227
+ // by declaring its own.
228
+ const eloDistance = createDefaultEloDistanceStrategy(courseId);
229
+ if (!filters.some((f) => f.implementingClass === eloDistance.implementingClass)) {
230
+ filters.push(planned(eloDistance, NavigatorRole.FILTER, 'assembler-default'));
231
+ }
232
+
233
+ // Sorted by name for deterministic ordering.
234
+ filters.sort((a, b) => a.name.localeCompare(b.name));
235
+
236
+ return {
237
+ kind: 'assembled',
238
+ generators,
239
+ filters,
240
+ skipped,
241
+ warnings,
242
+ notes: [],
243
+ regulators: DEFAULT_REGULATOR_CONFIG,
244
+ };
245
+ }
@@ -0,0 +1,230 @@
1
+ import type { WeightedCard } from './index';
2
+
3
+ // ============================================================================
4
+ // REGULATORS (pipeline stage, after filters, before hints)
5
+ // ============================================================================
6
+ //
7
+ // Review and new cards compete in one ranking. Regulators set the balance
8
+ // between the two classes: each valve measures an urgency `u` for its class
9
+ // and multiplies that class's scores by `rate^(u / scale)` above a threshold.
10
+ // Uncapped on both sides, so neither class can be permanently silenced.
11
+ //
12
+ // - Review mass: reviews pile up. Measured as the *value* of the due backlog,
13
+ // not its count: each due review weighs its SRS urgency (0–1) times the
14
+ // filters' net effect on it, so the reserve lake of low-value reviews
15
+ // (moved-beyond, long-interval, barely overdue) weighs little. The SRS
16
+ // score itself won't do: it carries a fixed 0.5 ranking offset, so every
17
+ // review would weigh at least ~0.6.
18
+ // - Intake: new content stalls. Measured as hours since a new card was last
19
+ // presented, counting only time when an eligible new card existed.
20
+ //
21
+ // A stage, not a filter: a regulator reads an aggregate of every candidate's
22
+ // *final* filtered score, so it must run after all filters (which run in name
23
+ // order and are assumed commutative). Before hints, so session intent (an
24
+ // intro's follow-up, a difficulty boost) still wins over pressure.
25
+ //
26
+ // Design note: agent/pipeline-regulation/a.0.regulator-stage.md.
27
+ //
28
+ // ============================================================================
29
+
30
+ export type RegulatorName = 'review-mass' | 'intake';
31
+
32
+ /** One regulator's reading for one pipeline run. Persisted on run summaries. */
33
+ export interface RegulatorReading {
34
+ name: RegulatorName;
35
+ /** The class the multiplier applies to. */
36
+ class: 'review' | 'new';
37
+ /** The valve's urgency: review mass (card-equivalents) or intake hours. */
38
+ urgency: number;
39
+ multiplier: number;
40
+ /** Candidates the multiplier applied to. */
41
+ applied: number;
42
+ inputs: Record<string, number>;
43
+ }
44
+
45
+ export interface RegulatorConfig {
46
+ reviewMass: {
47
+ /**
48
+ * Unit of mass for reviews without an SRS urgency (from another
49
+ * generator): a filtered score this high weighs 1.
50
+ */
51
+ referenceScore: number;
52
+ /** Mass (card-equivalents) at or below which there's no pressure. */
53
+ healthyMass: number;
54
+ /** Multiplier growth per multiple of `healthyMass` in excess. */
55
+ rate: number;
56
+ };
57
+ intake: {
58
+ /** Multiplier growth per `scaleHours` without a new card. */
59
+ rate: number;
60
+ scaleHours: number;
61
+ };
62
+ }
63
+
64
+ /**
65
+ * Defaults. Review mass keeps the SRS generator's former healthy threshold and
66
+ * growth rate (20, ×2), now applied to mass instead of count. Intake doubles
67
+ * per day of servable time without a new card.
68
+ */
69
+ export const DEFAULT_REGULATOR_CONFIG: RegulatorConfig = {
70
+ reviewMass: { referenceScore: 0.95, healthyMass: 20, rate: 2 },
71
+ intake: { rate: 2, scaleHours: 24 },
72
+ };
73
+
74
+ // ----------------------------------------------------------------------------
75
+ // Review mass
76
+ // ----------------------------------------------------------------------------
77
+
78
+ function clamp01(x: number): number {
79
+ return Math.min(1, Math.max(0, x));
80
+ }
81
+
82
+ /**
83
+ * One due review's weight in the mass, in [0, 1]: its SRS urgency times the
84
+ * filters' net effect on it (filtered score ÷ the score it was generated
85
+ * with), so every course signal discounts it. A review without an urgency
86
+ * weighs its filtered score against the reference.
87
+ */
88
+ export function reviewWeight(
89
+ card: WeightedCard,
90
+ generatedScore: number | undefined,
91
+ referenceScore: number
92
+ ): number {
93
+ if (card.reviewUrgency !== undefined && generatedScore !== undefined && generatedScore > 0) {
94
+ return clamp01(card.reviewUrgency * (card.score / generatedScore));
95
+ }
96
+ return clamp01(card.score / referenceScore);
97
+ }
98
+
99
+ /**
100
+ * @param reviews - Due reviews, after filters
101
+ * @param generatedScores - Each card's score as generated, before filters
102
+ */
103
+ export function reviewMassReading(
104
+ reviews: WeightedCard[],
105
+ generatedScores: ReadonlyMap<string, number>,
106
+ config: RegulatorConfig['reviewMass'] = DEFAULT_REGULATOR_CONFIG.reviewMass
107
+ ): RegulatorReading {
108
+ const mass = reviews.reduce(
109
+ (m, c) => m + reviewWeight(c, generatedScores.get(c.cardId), config.referenceScore),
110
+ 0
111
+ );
112
+ const multiplier =
113
+ mass > config.healthyMass
114
+ ? Math.pow(config.rate, (mass - config.healthyMass) / config.healthyMass)
115
+ : 1;
116
+ return {
117
+ name: 'review-mass',
118
+ class: 'review',
119
+ urgency: mass,
120
+ multiplier,
121
+ applied: reviews.length,
122
+ inputs: { due: reviews.length, mass, healthyMass: config.healthyMass },
123
+ };
124
+ }
125
+
126
+ // ----------------------------------------------------------------------------
127
+ // Intake
128
+ // ----------------------------------------------------------------------------
129
+
130
+ /** The intake valve's clock, persisted per user and course (strategy state). */
131
+ export interface IntakeClockState {
132
+ /** When a new card was last presented (ISO). */
133
+ lastNewAt: string;
134
+ /** Closed stretches since then during which no eligible new card existed (ms). */
135
+ frozenMs: number;
136
+ /** Start of the current stretch with no eligible new card (ISO), or null. */
137
+ unservableSince: string | null;
138
+ }
139
+
140
+ /** Strategy-state key for the intake clock. */
141
+ export const INTAKE_CLOCK_KEY = 'IntakeClock';
142
+
143
+ /** A fresh clock: a new card was just presented (or the clock is starting). */
144
+ export function resetIntakeClock(nowMs: number): IntakeClockState {
145
+ return { lastNewAt: new Date(nowMs).toISOString(), frozenMs: 0, unservableSince: null };
146
+ }
147
+
148
+ /** Frozen time so far, including an open unservable stretch. */
149
+ export function frozenMsAt(state: IntakeClockState, nowMs: number): number {
150
+ const open = state.unservableSince ? Math.max(0, nowMs - Date.parse(state.unservableSince)) : 0;
151
+ return state.frozenMs + open;
152
+ }
153
+
154
+ /** Servable hours since a new card was last presented. */
155
+ export function intakeHours(state: IntakeClockState, nowMs: number): number {
156
+ const elapsed = nowMs - Date.parse(state.lastNewAt);
157
+ return Math.max(0, elapsed - frozenMsAt(state, nowMs)) / 3_600_000;
158
+ }
159
+
160
+ /**
161
+ * Advance the clock's freeze bookkeeping for a run that found `eligibleNew`
162
+ * eligible new candidates. The clock freezes while there are none (exhaustion
163
+ * isn't starvation) and resumes when some appear. Returns the same object when
164
+ * nothing changed, so callers persist only on transitions.
165
+ */
166
+ export function stepIntakeClock(
167
+ state: IntakeClockState,
168
+ nowMs: number,
169
+ eligibleNew: number
170
+ ): IntakeClockState {
171
+ if (eligibleNew === 0 && !state.unservableSince) {
172
+ return { ...state, unservableSince: new Date(nowMs).toISOString() };
173
+ }
174
+ if (eligibleNew > 0 && state.unservableSince) {
175
+ return { ...state, frozenMs: frozenMsAt(state, nowMs), unservableSince: null };
176
+ }
177
+ return state;
178
+ }
179
+
180
+ export function intakeReading(
181
+ state: IntakeClockState,
182
+ nowMs: number,
183
+ counts: { eligibleNew: number; newCandidates: number },
184
+ config: RegulatorConfig['intake'] = DEFAULT_REGULATOR_CONFIG.intake
185
+ ): RegulatorReading {
186
+ const hours = intakeHours(state, nowMs);
187
+ const multiplier = counts.eligibleNew > 0 ? Math.pow(config.rate, hours / config.scaleHours) : 1;
188
+ return {
189
+ name: 'intake',
190
+ class: 'new',
191
+ urgency: hours,
192
+ multiplier,
193
+ applied: counts.eligibleNew,
194
+ inputs: {
195
+ hoursSinceNew: hours,
196
+ frozenHours: frozenMsAt(state, nowMs) / 3_600_000,
197
+ eligibleNew: counts.eligibleNew,
198
+ newCandidates: counts.newCandidates,
199
+ },
200
+ };
201
+ }
202
+
203
+ // ----------------------------------------------------------------------------
204
+ // Applying
205
+ // ----------------------------------------------------------------------------
206
+
207
+ const REGULATOR_LABEL: Record<RegulatorName, string> = {
208
+ 'review-mass': 'Review mass',
209
+ intake: 'Intake',
210
+ };
211
+
212
+ /** Multiply `cards` (in place) by a reading's multiplier, with a provenance entry when it changes them. */
213
+ export function applyReading(cards: WeightedCard[], reading: RegulatorReading): void {
214
+ if (reading.multiplier === 1) return;
215
+ const reason =
216
+ reading.name === 'review-mass'
217
+ ? `review mass ${reading.urgency.toFixed(1)} (healthy ${reading.inputs.healthyMass}) → ×${reading.multiplier.toFixed(2)}`
218
+ : `${reading.urgency.toFixed(1)}h since a new card → ×${reading.multiplier.toFixed(2)}`;
219
+ for (const card of cards) {
220
+ card.score *= reading.multiplier;
221
+ card.provenance.push({
222
+ strategy: 'regulator',
223
+ strategyName: `Regulator: ${REGULATOR_LABEL[reading.name]}`,
224
+ strategyId: `regulator-${reading.name}`,
225
+ action: reading.multiplier > 1 ? 'boosted' : 'penalized',
226
+ score: card.score,
227
+ reason,
228
+ });
229
+ }
230
+ }
@@ -1,6 +1,7 @@
1
1
  import { DocType, DocTypePrefixes } from './types-legacy';
2
2
  import type { ReplanHints } from '../navigators/generators/types';
3
3
  import type { GeneratorSummary, FilterImpact } from '../navigators/PipelineDebugger';
4
+ import type { RegulatorReading } from '../navigators/regulators';
4
5
  import type { StrategyContribution } from '../navigators';
5
6
 
6
7
  /**
@@ -119,6 +120,8 @@ export interface StudySessionRunSummary {
119
120
  nextInLine?: StudySessionRunCardTrail;
120
121
  topGenerated?: StudySessionRunCardTrail;
121
122
  };
123
+ /** The regulator stage's readings: review mass and intake, each with its multiplier (0.2.29+). */
124
+ regulators?: RegulatorReading[];
122
125
  }
123
126
 
124
127
  /** A card as persisted on a run. `origin` is as counted in `newSelected`/`reviewsSelected`. */
@@ -8,6 +8,7 @@ import type {
8
8
  } from '../core/types/types-legacy';
9
9
  import type { CourseRegistrationDoc, ScheduledCard } from '../core/types/user';
10
10
  import type { StudySessionDoc } from '../core/types/studySession';
11
+ import type { ContentNavigationStrategyData } from '../core/types/contentNavigationStrategy';
11
12
 
12
13
  // Literal prefixes rather than `DocTypePrefixes`: this entry stays free of
13
14
  // runtime imports from `core`, so it loads in the browser, node, and the CLI
@@ -29,7 +30,7 @@ type RawDoc = { _id: string; [key: string]: unknown };
29
30
  *
30
31
  * - v0 (LP `scripts/dump-user-db.ts` before 2026-09-30): no `formatVersion`,
31
32
  * `courseId`, `tombstones`, or `course`.
32
- * - v1: adds all four.
33
+ * - v1: adds all four. Later v1 dumps also carry `course.strategies` (optional).
33
34
  */
34
35
  export interface LearnerDump {
35
36
  formatVersion?: 1;
@@ -64,6 +65,11 @@ export interface CourseSlice {
64
65
  * and `taggedCount` keeps the full length.
65
66
  */
66
67
  tags: Array<Tag & { _id: string; taggedCount: number }>;
68
+ /**
69
+ * The course's NAVIGATION_STRATEGY docs, as they stood when the dump was
70
+ * taken (current state, not as of any session). Absent in older dumps.
71
+ */
72
+ strategies?: ContentNavigationStrategyData[];
67
73
  }
68
74
 
69
75
  /** A card-history record with an ISO `timeStamp`. Question fields exist on question records only. */
@@ -105,6 +111,8 @@ export interface LearnerDataset {
105
111
  tombstones: Array<{ id: string; seq: number }>;
106
112
  /** Absent when the dump carried no course slice. */
107
113
  cards?: Map<string, CardSummary>;
114
+ /** The course's strategy docs at dump time. Absent when the dump didn't carry them. */
115
+ strategies?: ContentNavigationStrategyData[];
108
116
  }
109
117
 
110
118
  /**
@@ -225,7 +233,10 @@ export function fromDump(dump: LearnerDump, courseId?: string): LearnerDataset {
225
233
  strategyState,
226
234
  tombstones: (dump.tombstones ?? []).map(({ id, seq }) => ({ id, seq })),
227
235
  ...(dump.course && dump.course.courseId === course
228
- ? { cards: summarizeCards(dump.course) }
236
+ ? {
237
+ cards: summarizeCards(dump.course),
238
+ ...(dump.course.strategies ? { strategies: dump.course.strategies } : {}),
239
+ }
229
240
  : {}),
230
241
  };
231
242
  }
@@ -14,6 +14,7 @@ export * from './dataset';
14
14
  export * from './loader';
15
15
  export * from './derive';
16
16
  export * from './text';
17
+ export * from './pipeline';
17
18
  export type {
18
19
  SessionEloEvent,
19
20
  SessionStateSnapshot,
@@ -22,3 +23,5 @@ export type {
22
23
  StudySessionRunCardTrail,
23
24
  StudySessionRunSummary,
24
25
  } from '../core/types/studySession';
26
+ export type { RegulatorName, RegulatorReading } from '../core/navigators/regulators';
27
+ export type { FilterKind } from '../core/navigators/filters/types';
@@ -108,8 +108,9 @@ function touchedCardIds(docs: RawDoc[]): string[] {
108
108
  /**
109
109
  * Read one learner's records for one course into a {@link LearnerDump}: the
110
110
  * whole user DB, its tombstones, and (by default) the course cards the user
111
- * has touched, with their displayable data and tags. Needs admin rights on
112
- * the couch, via basic auth or the browser's session cookie.
111
+ * has touched, with their displayable data and tags, plus the course's strategy
112
+ * docs. Needs admin rights on the couch, via basic auth or the browser's
113
+ * session cookie.
113
114
  */
114
115
  export async function fetchLearnerDump(opts: FetchLearnerDumpOptions): Promise<LearnerDump> {
115
116
  const couch = couchReader(opts);
@@ -165,6 +166,7 @@ export async function fetchLearnerDump(opts: FetchLearnerDumpOptions): Promise<L
165
166
  };
166
167
  })
167
168
  .filter((t) => scope === 'all' || t.taggedCards.length > 0);
169
+ const strategies = await couch.byPrefix(courseDb, 'NAVIGATION_STRATEGY');
168
170
 
169
171
  course = {
170
172
  courseId: opts.courseId,
@@ -173,6 +175,7 @@ export async function fetchLearnerDump(opts: FetchLearnerDumpOptions): Promise<L
173
175
  cards,
174
176
  displayableData,
175
177
  tags,
178
+ strategies,
176
179
  } as unknown as CourseSlice;
177
180
  }
178
181