@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
package/package.json CHANGED
@@ -4,7 +4,7 @@
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
7
- "version": "0.2.28",
7
+ "version": "0.2.29",
8
8
  "description": "Database layer for vue-skuilder",
9
9
  "main": "dist/index.js",
10
10
  "module": "dist/index.mjs",
@@ -60,7 +60,7 @@
60
60
  },
61
61
  "dependencies": {
62
62
  "@nilock2/pouchdb-authentication": "^1.0.2",
63
- "@vue-skuilder/common": "0.2.28",
63
+ "@vue-skuilder/common": "0.2.29",
64
64
  "cross-fetch": "^4.1.0",
65
65
  "moment": "^2.29.4",
66
66
  "pouchdb": "^9.0.0",
@@ -75,5 +75,5 @@
75
75
  "vite": "^8.0.0",
76
76
  "vitest": "^4.1.0"
77
77
  },
78
- "stableVersion": "0.2.28"
78
+ "stableVersion": "0.2.29"
79
79
  }
@@ -92,6 +92,13 @@ export interface StudyContentSource {
92
92
  * No-op for sources that don't support hints.
93
93
  */
94
94
  setEphemeralHints?(hints: ReplanHints): void;
95
+
96
+ /**
97
+ * A card was just presented. `status` is the session item's (`'new'`,
98
+ * `'review'`, `'failed-new'`, ...). Pipelines use a new card's first
99
+ * presentation to restart their intake valve's clock.
100
+ */
101
+ notePresented?(card: { cardId: string; courseId: string; status: string }): void;
95
102
  }
96
103
  // #endregion docs_StudyContentSource
97
104
 
@@ -1,4 +1,4 @@
1
- import { toCourseElo } from '@vue-skuilder/common';
1
+ import { toCourseElo, type CourseElo } from '@vue-skuilder/common';
2
2
  import type { CourseDBInterface } from '../interfaces/courseDB';
3
3
  import type { UserDBInterface } from '../interfaces/userDB';
4
4
  import { ContentNavigator } from './index';
@@ -10,6 +10,18 @@ import { logger } from '../../util/logger';
10
10
  import { createOrchestrationContext, OrchestrationContext } from '../orchestration';
11
11
  import { captureRun, buildRunReport, registerPipelineForDebug, type GeneratorSummary, type FilterImpact } from './PipelineDebugger';
12
12
  import { diversityRerank } from './diversityRerank';
13
+ import {
14
+ applyReading,
15
+ DEFAULT_REGULATOR_CONFIG,
16
+ INTAKE_CLOCK_KEY,
17
+ intakeReading,
18
+ resetIntakeClock,
19
+ reviewMassReading,
20
+ stepIntakeClock,
21
+ type IntakeClockState,
22
+ type RegulatorReading,
23
+ } from './regulators';
24
+ import { noteReviewPressure } from './SrsDebugger';
13
25
 
14
26
  // ============================================================================
15
27
  // REPLAN HINTS
@@ -298,6 +310,14 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
298
310
  */
299
311
  private _ephemeralHints: ReplanHints | null = null;
300
312
 
313
+ /**
314
+ * The intake valve's clock (see regulators.ts), loaded from strategy state on
315
+ * first use and kept in memory. Writes are chained so a presentation and a
316
+ * run can't race each other's revision.
317
+ */
318
+ private _intakeClock: IntakeClockState | null = null;
319
+ private _intakeClockWrite: Promise<void> = Promise.resolve();
320
+
301
321
  /**
302
322
  * Create a new pipeline.
303
323
  *
@@ -401,13 +421,14 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
401
421
  }
402
422
  }
403
423
  generatorSummaries = Array.from(genMap.entries()).map(([name, data]) => {
404
- const newCards = data.cards.filter((c) => c.provenance[0]?.reason?.includes('new card'));
405
- const reviewCards = data.cards.filter((c) => c.provenance[0]?.reason?.includes('review'));
424
+ // Reviews carry `reviewID`; everything else a generator emits is unseen.
425
+ // (Reason text can't tell: the ELO generator's never says "new card".)
426
+ const reviewCount = data.cards.filter((c) => c.reviewID).length;
406
427
  return {
407
428
  name,
408
429
  cardCount: data.cards.length,
409
- newCount: newCards.length,
410
- reviewCount: reviewCards.length,
430
+ newCount: data.cards.length - reviewCount,
431
+ reviewCount,
411
432
  topScore: Math.max(...data.cards.map((c) => c.score), 0),
412
433
  };
413
434
  });
@@ -459,6 +480,10 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
459
480
  .map((c) => c.cardId)
460
481
  );
461
482
  const filterImpacts: FilterImpact[] = [];
483
+ // Scores as generated, so regulators can read the filters' net effect on each card.
484
+ const generatedScores = new Map(cards.map((c) => [c.cardId, c.score]));
485
+ // Cards a gate penalized: not ready, so regulators won't lift them.
486
+ const gated = new Set<string>();
462
487
  // [perf] parked 2026-05 (pipeline-docs-workup) — uncomment to re-measure
463
488
  // const filterTimings: string[] = [];
464
489
  for (const filter of this.filters) {
@@ -472,13 +497,17 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
472
497
  let boosted = 0, penalized = 0, passed = 0;
473
498
  const removed = beforeCount - cards.length;
474
499
 
500
+ // Undeclared filters count as gates (see CardFilter.kind).
501
+ const kind = filter.kind ?? 'gate';
475
502
  for (const card of cards) {
476
503
  const before = beforeScores.get(card.cardId) ?? 0;
477
504
  if (card.score > before) boosted++;
478
- else if (card.score < before) penalized++;
479
- else passed++;
505
+ else if (card.score < before) {
506
+ penalized++;
507
+ if (kind === 'gate') gated.add(card.cardId);
508
+ } else passed++;
480
509
  }
481
- filterImpacts.push({ name: filter.name, boosted, penalized, passed, removed });
510
+ filterImpacts.push({ name: filter.name, kind, boosted, penalized, passed, removed });
482
511
 
483
512
  // Report prescribed card fate through each filter
484
513
  if (prescribedIds.size > 0) {
@@ -506,6 +535,10 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
506
535
  const scoredCards = cards;
507
536
  cards = cards.filter((c) => c.score > 0);
508
537
 
538
+ // Regulators: class-level pressure between reviews and new cards, from the
539
+ // filtered scores (see regulators.ts). Before hints, so session intent wins.
540
+ const regulators = await this.regulate(cards, generatedScores, gated);
541
+
509
542
  // Apply ephemeral hints (one-shot, post-filter)
510
543
  const hints = this._ephemeralHints;
511
544
  if (hints) {
@@ -571,7 +604,8 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
571
604
  result,
572
605
  context.userElo,
573
606
  hints?? undefined,
574
- scoredCards
607
+ scoredCards,
608
+ regulators
575
609
  );
576
610
  captureRun(report);
577
611
  } catch (e) {
@@ -785,6 +819,93 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
785
819
  return cards;
786
820
  }
787
821
 
822
+ /**
823
+ * The regulator stage: measure each class's pressure and scale it.
824
+ *
825
+ * - Review mass: every due review's SRS urgency times the filters' net
826
+ * effect on it.
827
+ * - Intake: servable hours since a new card was presented, applied only to
828
+ * eligible new cards (no gate penalized them). With none eligible, the
829
+ * clock freezes.
830
+ *
831
+ * Mutates `cards` in place; returns the readings for the run report.
832
+ */
833
+ private async regulate(
834
+ cards: WeightedCard[],
835
+ generatedScores: ReadonlyMap<string, number>,
836
+ gated: Set<string>
837
+ ): Promise<RegulatorReading[]> {
838
+ const config = DEFAULT_REGULATOR_CONFIG;
839
+ const reviews = cards.filter((c) => c.reviewID);
840
+ const newCards = cards.filter((c) => !c.reviewID);
841
+ const eligibleNew = newCards.filter((c) => !gated.has(c.cardId));
842
+
843
+ const mass = reviewMassReading(reviews, generatedScores, config.reviewMass);
844
+ applyReading(reviews, mass);
845
+ noteReviewPressure(this.course!.getCourseID(), {
846
+ mass: mass.urgency,
847
+ healthyMass: config.reviewMass.healthyMass,
848
+ rate: config.reviewMass.rate,
849
+ multiplier: mass.multiplier,
850
+ });
851
+
852
+ const now = Date.now();
853
+ const clock = await this.loadIntakeClock(now);
854
+ const stepped = stepIntakeClock(clock, now, eligibleNew.length);
855
+ if (stepped !== clock) this.saveIntakeClock(stepped);
856
+ const intake = intakeReading(
857
+ stepped,
858
+ now,
859
+ { eligibleNew: eligibleNew.length, newCandidates: newCards.length },
860
+ config.intake
861
+ );
862
+ applyReading(eligibleNew, intake);
863
+
864
+ logger.info(
865
+ `[Pipeline:regulators] review mass ${mass.urgency.toFixed(1)} over ${reviews.length} due → ` +
866
+ `×${mass.multiplier.toFixed(2)}; intake ${intake.urgency.toFixed(1)}h, ` +
867
+ `${eligibleNew.length}/${newCards.length} new eligible → ×${intake.multiplier.toFixed(2)}`
868
+ );
869
+ return [mass, intake];
870
+ }
871
+
872
+ /**
873
+ * A card was presented. A new card's first presentation discharges the
874
+ * intake valve: its clock restarts. Called by the SessionController.
875
+ */
876
+ notePresented(card: { cardId: string; courseId: string; status: string }): void {
877
+ if (card.status !== 'new' || card.courseId !== this.course?.getCourseID()) return;
878
+ this.saveIntakeClock(resetIntakeClock(Date.now()));
879
+ }
880
+
881
+ private async loadIntakeClock(nowMs: number): Promise<IntakeClockState> {
882
+ if (this._intakeClock) return this._intakeClock;
883
+ let stored: IntakeClockState | null = null;
884
+ try {
885
+ stored = await this.user!.getStrategyState<IntakeClockState>(
886
+ this.course!.getCourseID(),
887
+ INTAKE_CLOCK_KEY
888
+ );
889
+ } catch (e) {
890
+ logger.warn(`[Pipeline:regulators] Could not read the intake clock: ${e}`);
891
+ }
892
+ if (stored) {
893
+ this._intakeClock = stored;
894
+ } else {
895
+ // No clock yet: start it now.
896
+ this.saveIntakeClock(resetIntakeClock(nowMs));
897
+ }
898
+ return this._intakeClock!;
899
+ }
900
+
901
+ private saveIntakeClock(state: IntakeClockState): void {
902
+ this._intakeClock = state;
903
+ const courseId = this.course!.getCourseID();
904
+ this._intakeClockWrite = this._intakeClockWrite
905
+ .then(() => this.user!.putStrategyState(courseId, INTAKE_CLOCK_KEY, state))
906
+ .catch((e) => logger.warn(`[Pipeline:regulators] Could not save the intake clock: ${e}`));
907
+ }
908
+
788
909
  /**
789
910
  * Build shared context for generator and filters.
790
911
  *
@@ -795,11 +916,12 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
795
916
  */
796
917
  private async buildContext(): Promise<GeneratorContext & FilterContext> {
797
918
  let userElo = 1000; // Default ELO
919
+ let userCourseElo: CourseElo | undefined;
798
920
 
799
921
  try {
800
922
  const courseReg = await this.user!.getCourseRegDoc(this.course!.getCourseID());
801
- const courseElo = toCourseElo(courseReg.elo);
802
- userElo = courseElo.global.score;
923
+ userCourseElo = toCourseElo(courseReg.elo);
924
+ userElo = userCourseElo.global.score;
803
925
  } catch (e) {
804
926
  logger.debug(`[Pipeline] Could not get user ELO, using default: ${e}`);
805
927
  }
@@ -816,6 +938,7 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
816
938
  user: this.user!,
817
939
  course: this.course!,
818
940
  userElo,
941
+ ...(userCourseElo ? { userCourseElo } : {}),
819
942
  orchestration,
820
943
  };
821
944
  }
@@ -961,7 +1084,7 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
961
1084
  const fullPool = cards.slice();
962
1085
 
963
1086
  const context = await this.buildContext();
964
- for (const filter of this.filters) {
1087
+ for (const filter of this.forecastFilters()) {
965
1088
  cards = await filter.transform(cards, context);
966
1089
  }
967
1090
 
@@ -985,6 +1108,15 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
985
1108
  return opts?.limit ? cards.slice(0, opts.limit) : cards;
986
1109
  }
987
1110
 
1111
+ /**
1112
+ * The filters a forecast or card-space scan applies. Those start every card at
1113
+ * 1.0 without a generator, so they skip `liveOnly` filters (ELO distance),
1114
+ * which only make sense against generator scores.
1115
+ */
1116
+ private forecastFilters(): CardFilter[] {
1117
+ return this.filters.filter((f) => !f.liveOnly);
1118
+ }
1119
+
988
1120
  /**
989
1121
  * Scan every card in the course through the filter chain and report
990
1122
  * how many are "well indicated" (score >= threshold) for the current user.
@@ -1016,7 +1148,7 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
1016
1148
  const filterBreakdown: Array<{ name: string; wellIndicated: number }> = [];
1017
1149
 
1018
1150
  // Track cumulative filter effects
1019
- for (const filter of this.filters) {
1151
+ for (const filter of this.forecastFilters()) {
1020
1152
  cards = await filter.transform(cards, context);
1021
1153
  const wi = cards.filter((c) => c.score >= THRESHOLD).length;
1022
1154
  filterBreakdown.push({ name: filter.name, wellIndicated: wi });
@@ -1,5 +1,5 @@
1
1
  import type { ContentNavigationStrategyData } from '../types/contentNavigationStrategy';
2
- import { ContentNavigator, isGenerator, isFilter, Navigators } from './index';
2
+ import { ContentNavigator } from './index';
3
3
  import type { CardFilter } from './filters/types';
4
4
  import { WeightedFilter } from './filters/WeightedFilter';
5
5
  import type { CardGenerator } from './generators/types';
@@ -8,7 +8,7 @@ import { logger } from '../../util/logger';
8
8
  import type { CourseDBInterface } from '../interfaces/courseDB';
9
9
  import type { UserDBInterface } from '../interfaces/userDB';
10
10
  import CompositeGenerator from './generators/CompositeGenerator';
11
- import { createDefaultEloStrategy, createDefaultSrsStrategy } from './defaults';
11
+ import { planPipeline } from './pipelinePlan';
12
12
 
13
13
  // ============================================================================
14
14
  // PIPELINE ASSEMBLER
@@ -23,7 +23,7 @@ import { createDefaultEloStrategy, createDefaultSrsStrategy } from './defaults';
23
23
  // 3. Easy unit testing without DB mocking
24
24
  //
25
25
  // Pipeline assembly:
26
- // 1. Separate strategies into generators and filters by role
26
+ // 1. Plan: classify by role, add defaults, order filters (pipelinePlan.ts)
27
27
  // 2. Instantiate generator(s) - wrap multiple in CompositeGenerator
28
28
  // 3. Instantiate filters
29
29
  // 4. Return Pipeline(generator, filters)
@@ -66,11 +66,11 @@ export class PipelineAssembler {
66
66
  /**
67
67
  * Assembles a navigation pipeline from strategy documents.
68
68
  *
69
- * 1. Separates into generators and filters by role
70
- * 2. Validates at least one generator exists (or creates default ELO)
71
- * 3. Instantiates generators - wraps multiple in CompositeGenerator
72
- * 4. Instantiates filters
73
- * 5. Returns Pipeline(generator, filters)
69
+ * 1. Plans: classifies by role, adds default ELO/SRS and ELO distance, orders filters
70
+ * (`planPipeline`)
71
+ * 2. Instantiates generators - wraps multiple in CompositeGenerator
72
+ * 3. Instantiates filters
73
+ * 4. Returns Pipeline(generator, filters)
74
74
  *
75
75
  * @param input - Strategy documents plus user/course interfaces
76
76
  * @returns Assembled pipeline and any warnings
@@ -88,35 +88,19 @@ export class PipelineAssembler {
88
88
  };
89
89
  }
90
90
 
91
- // Separate generators from filters
92
- const generatorStrategies: ContentNavigationStrategyData[] = [];
93
- const filterStrategies: ContentNavigationStrategyData[] = [];
94
-
95
- for (const s of strategies) {
96
- if (isGenerator(s.implementingClass)) {
97
- generatorStrategies.push(s);
98
- } else if (isFilter(s.implementingClass)) {
99
- filterStrategies.push(s);
100
- } else {
101
- // Unknown strategy type — skip with warning
102
- warnings.push(`Unknown strategy type '${s.implementingClass}', skipping: ${s.name}`);
91
+ // Classify, add defaults, and order filters: the same plan the admin
92
+ // pipeline view renders.
93
+ const plan = planPipeline(strategies, course.getCourseID());
94
+ warnings.push(...plan.warnings);
95
+ for (const n of [...plan.generators, ...plan.filters]) {
96
+ if (n.origin === 'assembler-default') {
97
+ logger.debug(
98
+ `[PipelineAssembler] No ${n.implementingClass} ${n.role} configured, adding default`
99
+ );
103
100
  }
104
101
  }
105
-
106
- // Always ensure ELO and SRS generators are present.
107
- // Custom generators (e.g., prescribed) supplement but don't replace them.
108
- const courseId = course.getCourseID();
109
- const hasElo = generatorStrategies.some((s) => s.implementingClass === Navigators.ELO);
110
- const hasSrs = generatorStrategies.some((s) => s.implementingClass === Navigators.SRS);
111
-
112
- if (!hasElo) {
113
- logger.debug('[PipelineAssembler] No ELO generator configured, adding default');
114
- generatorStrategies.push(createDefaultEloStrategy(courseId));
115
- }
116
- if (!hasSrs) {
117
- logger.debug('[PipelineAssembler] No SRS generator configured, adding default');
118
- generatorStrategies.push(createDefaultSrsStrategy(courseId));
119
- }
102
+ const generatorStrategies = plan.generators.map((g) => g.strategy);
103
+ const sortedFilterStrategies = plan.filters.map((f) => f.strategy);
120
104
 
121
105
  if (generatorStrategies.length === 0) {
122
106
  warnings.push('No generator strategy found');
@@ -147,11 +131,6 @@ export class PipelineAssembler {
147
131
  // Instantiate filters
148
132
  const filters: CardFilter[] = [];
149
133
 
150
- // Sort filters alphabetically for deterministic ordering
151
- const sortedFilterStrategies = [...filterStrategies].sort((a, b) =>
152
- a.name.localeCompare(b.name)
153
- );
154
-
155
134
  for (const filterStrategy of sortedFilterStrategies) {
156
135
  try {
157
136
  const nav = await ContentNavigator.create(user, course, filterStrategy);
@@ -10,6 +10,8 @@ import {
10
10
  import { logger } from '../../util/logger';
11
11
  import type { Pipeline, CardSpaceDiagnosis, PipelineForecaster } from './Pipeline';
12
12
  import type { ReplanHints } from './generators/types';
13
+ import type { FilterKind } from './filters/types';
14
+ import type { RegulatorReading } from './regulators';
13
15
 
14
16
  /**
15
17
  * Captured reference to the most recently created Pipeline instance.
@@ -68,6 +70,8 @@ export interface GeneratorSummary {
68
70
  */
69
71
  export interface FilterImpact {
70
72
  name: string;
73
+ /** Effective kind: undeclared filters count as gates. Absent on runs before 0.2.29. */
74
+ kind?: FilterKind;
71
75
  boosted: number;
72
76
  penalized: number;
73
77
  passed: number;
@@ -148,6 +152,9 @@ export interface PipelineRunReport {
148
152
  topGenerated?: RunReportCard;
149
153
  };
150
154
 
155
+ /** The regulator stage's readings: each class's pressure and the multiplier it got. */
156
+ regulators?: RegulatorReading[];
157
+
151
158
  /**
152
159
  * Summary of the discarded tail of the candidate pool — cards that were
153
160
  * generated and scored but neither selected nor retained in `cards`.
@@ -293,7 +300,8 @@ export function buildRunReport(
293
300
  userElo?: number,
294
301
  hints?: ReplanHints,
295
302
  /** Post-filter cards before zero-scored ones are dropped. Defaults to `allCards`. */
296
- scoredCards?: WeightedCard[]
303
+ scoredCards?: WeightedCard[],
304
+ regulators?: RegulatorReading[]
297
305
  ): Omit<PipelineRunReport, 'runId' | 'timestamp'> {
298
306
  const selectedIds = new Set(selectedCards.map((c) => c.cardId));
299
307
 
@@ -307,7 +315,7 @@ export function buildRunReport(
307
315
  origin: getOrigin(card),
308
316
  generator: card.provenance[0]?.strategyName || card.provenance[0]?.strategy,
309
317
  finalScore: card.score,
310
- cardElo: parseCardElo(card.provenance),
318
+ cardElo: card.cardElo ?? parseCardElo(card.provenance),
311
319
  provenance: card.provenance,
312
320
  tags: card.tags,
313
321
  selected: selectedIds.has(card.cardId),
@@ -406,6 +414,7 @@ export function buildRunReport(
406
414
  cards,
407
415
  unselectedNew,
408
416
  discardedTail,
417
+ ...(regulators ? { regulators } : {}),
409
418
  };
410
419
  }
411
420
 
@@ -2,15 +2,16 @@
2
2
  // SRS BACKLOG DEBUGGER
3
3
  // ============================================================================
4
4
  //
5
- // A tiny module-level capture of the SRS generator's per-run backlog state,
6
- // so the live session overlay can show how much runway remains before reviews
7
- // out-compete the current (boosted) new/prescribed cards: the backlog
8
- // multiplier is exponential and uncapped, so it always has headroom to climb
9
- // further — the question is just how large the backlog needs to get before it
10
- // crosses whatever the competing boosts currently sit at.
5
+ // A tiny module-level capture of per-run review backlog state, so the live
6
+ // session overlay can show how much runway remains before reviews out-compete
7
+ // the current (boosted) new/prescribed cards: the review-mass multiplier is
8
+ // exponential and uncapped, so it always has headroom to climb further — the
9
+ // question is just how large the backlog's mass needs to get before it crosses
10
+ // whatever the competing boosts currently sit at.
11
11
  //
12
- // Mirrors MixerDebugger/PipelineDebugger: the generator pushes a snapshot each
13
- // run (keyed by course, latest wins); the overlay reads it via the controller's
12
+ // The SRS generator captures counts each run; the pipeline's regulator stage
13
+ // then patches in the review mass and the multiplier (noteReviewPressure).
14
+ // Keyed by course, latest wins; the overlay reads it via the controller's
14
15
  // getDebugSnapshot(). No DB load on the read path.
15
16
  //
16
17
  // ============================================================================
@@ -22,13 +23,18 @@ export interface SrsBacklogDebug {
22
23
  scheduledTotal: number;
23
24
  /** Reviews eligible (due) right now. */
24
25
  dueNow: number;
25
- /** Healthy backlog threshold; multiplier is ×1.0 at or below this. */
26
+ /** Healthy review mass (card-equivalents); the multiplier is ×1.0 at or below it. */
26
27
  healthyBacklog: number;
27
- /** Global multiplier applied to every due review's urgency this run (>= 1.0, unbounded). */
28
+ /**
29
+ * Review mass: the due reviews' filtered scores against a reference, each at
30
+ * most 1. Set by the regulator stage; null until it has run.
31
+ */
32
+ reviewMass: number | null;
33
+ /** Multiplier the regulator stage applied to every due review this run (>= 1.0, unbounded). */
28
34
  backlogMultiplier: number;
29
- /** Exponential growth-rate base the multiplier climbs by per multiple of healthyBacklog excess. */
35
+ /** Exponential growth-rate base the multiplier climbs by per multiple of healthy mass in excess. */
30
36
  backlogGrowthRate: number;
31
- /** Highest review score produced this run (post-multiplier; can exceed 1.0); null if none due. */
37
+ /** Highest review urgency score from the SRS generator (before filters and regulators); null if none due. */
32
38
  topReviewScore: number | null;
33
39
  /** Human-readable time until the next review comes due, or null if some are due now. */
34
40
  nextDueIn: string | null;
@@ -43,6 +49,25 @@ export function captureSrsBacklog(snapshot: SrsBacklogDebug): void {
43
49
  snapshots.set(snapshot.courseId, snapshot);
44
50
  }
45
51
 
52
+ /**
53
+ * Called by the pipeline's regulator stage once per run: the review mass and
54
+ * the multiplier it set. Patches the course's latest SRS snapshot.
55
+ */
56
+ export function noteReviewPressure(
57
+ courseId: string,
58
+ pressure: { mass: number; healthyMass: number; rate: number; multiplier: number }
59
+ ): void {
60
+ const snapshot = snapshots.get(courseId);
61
+ if (!snapshot) return;
62
+ snapshots.set(courseId, {
63
+ ...snapshot,
64
+ reviewMass: pressure.mass,
65
+ healthyBacklog: pressure.healthyMass,
66
+ backlogGrowthRate: pressure.rate,
67
+ backlogMultiplier: pressure.multiplier,
68
+ });
69
+ }
70
+
46
71
  /** Current backlog snapshot for every course seen, newest-first. */
47
72
  export function getSrsBacklogDebug(): SrsBacklogDebug[] {
48
73
  return [...snapshots.values()].sort((a, b) => b.timestamp - a.timestamp);
@@ -3,7 +3,7 @@ import { Pipeline } from './Pipeline';
3
3
  import CompositeGenerator from './generators/CompositeGenerator';
4
4
  import ELONavigator from './generators/elo';
5
5
  import SRSNavigator from './generators/srs';
6
- import { createEloDistanceFilter } from './filters/eloDistance';
6
+ import EloDistanceFilter, { DEFAULT_ELO_DISTANCE_CONFIG } from './filters/eloDistance';
7
7
  import type { ContentNavigationStrategyData } from '../types/contentNavigationStrategy';
8
8
  import { DocType } from '../types/types-legacy';
9
9
  import type { CourseDBInterface, UserDBInterface } from '../interfaces';
@@ -53,13 +53,33 @@ export function createDefaultSrsStrategy(courseId: string): ContentNavigationStr
53
53
  };
54
54
  }
55
55
 
56
+ /**
57
+ * Create default ELO distance filter strategy data. The assembler adds it to
58
+ * any pipeline whose strategy docs declare no `eloDistance` filter.
59
+ *
60
+ * @param courseId - The course ID to associate with this strategy
61
+ * @returns Strategy data for the default ELO distance filter (default curve)
62
+ */
63
+ export function createDefaultEloDistanceStrategy(courseId: string): ContentNavigationStrategyData {
64
+ return {
65
+ _id: 'NAVIGATION_STRATEGY-eloDistance-default',
66
+ docType: DocType.NAVIGATION_STRATEGY,
67
+ name: 'ELO Distance (default)',
68
+ description: 'Scales every candidate, new or review, by its distance from the learner\'s ELO',
69
+ implementingClass: Navigators.ELO_DISTANCE,
70
+ course: courseId,
71
+ // Explicit, though the filter would default to it anyway: views show what runs.
72
+ serializedData: JSON.stringify(DEFAULT_ELO_DISTANCE_CONFIG),
73
+ };
74
+ }
75
+
56
76
  /**
57
77
  * Creates the default navigation pipeline for courses with no configured strategies.
58
78
  *
59
- * Default: Pipeline(Composite(ELO, SRS), [eloDistanceFilter])
60
- * - ELO generator: scores new cards by skill proximity
79
+ * Default: Pipeline(Composite(ELO, SRS), [ELO distance])
80
+ * - ELO generator: retrieves new cards near the learner's ELO
61
81
  * - SRS generator: scores reviews by overdueness and interval recency
62
- * - ELO distance filter: penalizes cards far from user's current level
82
+ * - ELO distance filter: scales every card by its distance from the learner's ELO
63
83
  *
64
84
  * This is the canonical default configuration used when:
65
85
  * - No navigation strategy documents exist in the course
@@ -78,7 +98,11 @@ export function createDefaultPipeline(
78
98
  const srsNavigator = new SRSNavigator(user, course, createDefaultSrsStrategy(courseId));
79
99
 
80
100
  const compositeGenerator = new CompositeGenerator([eloNavigator, srsNavigator]);
81
- const eloDistanceFilter = createEloDistanceFilter();
101
+ const eloDistanceFilter = new EloDistanceFilter(
102
+ user,
103
+ course,
104
+ createDefaultEloDistanceStrategy(courseId)
105
+ );
82
106
 
83
107
  return new Pipeline(compositeGenerator, [eloDistanceFilter], user, course);
84
108
  }
@@ -1,4 +1,4 @@
1
- import { CardFilter, FilterContext } from './types';
1
+ import { CardFilter, FilterContext, FilterKind } from './types';
2
2
  import { WeightedCard } from '../index';
3
3
  import { LearnableWeight, DEFAULT_LEARNABLE_WEIGHT } from '../../types/contentNavigationStrategy';
4
4
 
@@ -18,6 +18,8 @@ import { LearnableWeight, DEFAULT_LEARNABLE_WEIGHT } from '../../types/contentNa
18
18
  */
19
19
  export class WeightedFilter implements CardFilter {
20
20
  public name: string;
21
+ public kind?: FilterKind;
22
+ public liveOnly?: boolean;
21
23
  private inner: CardFilter;
22
24
  private learnable: LearnableWeight;
23
25
  private staticWeight: boolean;
@@ -31,6 +33,8 @@ export class WeightedFilter implements CardFilter {
31
33
  ) {
32
34
  this.inner = inner;
33
35
  this.name = inner.name;
36
+ this.kind = inner.kind;
37
+ this.liveOnly = inner.liveOnly;
34
38
  this.learnable = learnable;
35
39
  this.staticWeight = staticWeight;
36
40
  this.strategyId = strategyId;