@vue-skuilder/db 0.2.27 → 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 (82) hide show
  1. package/dist/classroomDB-DLTtLZct.d.cts +86 -0
  2. package/dist/classroomDB-DLTtLZct.d.ts +86 -0
  3. package/dist/{contentSource-LPf044hY.d.ts → contentSource-B6FrSihy.d.cts} +282 -99
  4. package/dist/{contentSource-D3c1fMAk.d.cts → contentSource-CqJmbOZN.d.ts} +282 -99
  5. package/dist/core/index.d.cts +16 -92
  6. package/dist/core/index.d.ts +16 -92
  7. package/dist/core/index.js +607 -179
  8. package/dist/core/index.js.map +1 -1
  9. package/dist/core/index.mjs +606 -179
  10. package/dist/core/index.mjs.map +1 -1
  11. package/dist/{dataLayerProvider-DaAootVV.d.ts → dataLayerProvider-B9_UCvkR.d.ts} +2 -8
  12. package/dist/{dataLayerProvider-CeLiFbHv.d.cts → dataLayerProvider-DUxDqMtZ.d.cts} +2 -8
  13. package/dist/diagnostics/index.d.cts +443 -0
  14. package/dist/diagnostics/index.d.ts +443 -0
  15. package/dist/diagnostics/index.js +932 -0
  16. package/dist/diagnostics/index.js.map +1 -0
  17. package/dist/diagnostics/index.mjs +881 -0
  18. package/dist/diagnostics/index.mjs.map +1 -0
  19. package/dist/impl/couch/index.d.cts +13 -3
  20. package/dist/impl/couch/index.d.ts +13 -3
  21. package/dist/impl/couch/index.js +605 -179
  22. package/dist/impl/couch/index.js.map +1 -1
  23. package/dist/impl/couch/index.mjs +605 -179
  24. package/dist/impl/couch/index.mjs.map +1 -1
  25. package/dist/impl/static/index.d.cts +11 -5
  26. package/dist/impl/static/index.d.ts +11 -5
  27. package/dist/impl/static/index.js +602 -185
  28. package/dist/impl/static/index.js.map +1 -1
  29. package/dist/impl/static/index.mjs +602 -185
  30. package/dist/impl/static/index.mjs.map +1 -1
  31. package/dist/{index-BkBJlGDX.d.ts → index-CVGehe_t.d.ts} +1 -1
  32. package/dist/{index-D7WdMDAs.d.cts → index-Ktg72jKb.d.cts} +1 -1
  33. package/dist/index.d.cts +73 -11
  34. package/dist/index.d.ts +73 -11
  35. package/dist/index.js +696 -200
  36. package/dist/index.js.map +1 -1
  37. package/dist/index.mjs +683 -200
  38. package/dist/index.mjs.map +1 -1
  39. package/dist/{types-DjiFOZxJ.d.cts → types-D0oQeJAi.d.cts} +1 -1
  40. package/dist/{types-uJ2Xn3_X.d.ts → types-dXWfyz9B.d.ts} +1 -1
  41. package/dist/{types-legacy-CrwyZIvI.d.cts → types-legacy-BkOYOR6U.d.cts} +1 -1
  42. package/dist/{types-legacy-CrwyZIvI.d.ts → types-legacy-BkOYOR6U.d.ts} +1 -1
  43. package/dist/util/packer/index.d.cts +3 -3
  44. package/dist/util/packer/index.d.ts +3 -3
  45. package/package.json +15 -3
  46. package/src/core/interfaces/contentSource.ts +7 -0
  47. package/src/core/interfaces/dataLayerProvider.ts +3 -8
  48. package/src/core/navigators/Pipeline.ts +149 -14
  49. package/src/core/navigators/PipelineAssembler.ts +19 -40
  50. package/src/core/navigators/PipelineDebugger.ts +74 -17
  51. package/src/core/navigators/SrsDebugger.ts +37 -12
  52. package/src/core/navigators/defaults.ts +29 -5
  53. package/src/core/navigators/filters/WeightedFilter.ts +5 -1
  54. package/src/core/navigators/filters/eloDistance.ts +261 -76
  55. package/src/core/navigators/filters/hierarchyDefinition.ts +5 -1
  56. package/src/core/navigators/filters/index.ts +2 -2
  57. package/src/core/navigators/filters/interferenceMitigator.ts +5 -1
  58. package/src/core/navigators/filters/relativePriority.ts +5 -1
  59. package/src/core/navigators/filters/types.ts +24 -1
  60. package/src/core/navigators/filters/userTagPreference.ts +5 -1
  61. package/src/core/navigators/generators/elo.ts +23 -53
  62. package/src/core/navigators/generators/srs.ts +27 -124
  63. package/src/core/navigators/index.ts +32 -5
  64. package/src/core/navigators/pipelinePlan.ts +245 -0
  65. package/src/core/navigators/regulators.ts +230 -0
  66. package/src/core/types/studySession.ts +40 -0
  67. package/src/diagnostics/dataset.ts +242 -0
  68. package/src/diagnostics/derive.ts +555 -0
  69. package/src/diagnostics/index.ts +27 -0
  70. package/src/diagnostics/loader.ts +194 -0
  71. package/src/diagnostics/pipeline.ts +236 -0
  72. package/src/diagnostics/text.ts +265 -0
  73. package/src/impl/couch/PouchDataLayerProvider.ts +0 -23
  74. package/src/impl/couch/courseDB.ts +13 -0
  75. package/src/impl/static/StaticDataLayerProvider.ts +0 -11
  76. package/src/impl/static/courseDB.ts +9 -0
  77. package/src/index.ts +4 -0
  78. package/src/study/SessionController.ts +76 -2
  79. package/src/study/SessionOverlay.ts +7 -4
  80. package/tests/core/navigators/PipelineAssembler.test.ts +20 -5
  81. package/tests/core/navigators/eloDistanceFilter.test.ts +9 -9
  82. package/tsup.config.ts +1 -0
@@ -1,5 +1,5 @@
1
1
  import { CourseConfig } from '@vue-skuilder/common';
2
- import { D as DocType } from './types-legacy-CrwyZIvI.cjs';
2
+ import { D as DocType } from './types-legacy-BkOYOR6U.cjs';
3
3
 
4
4
  interface StaticCourseManifest {
5
5
  version: string;
@@ -1,5 +1,5 @@
1
1
  import { CourseConfig } from '@vue-skuilder/common';
2
- import { D as DocType } from './types-legacy-CrwyZIvI.js';
2
+ import { D as DocType } from './types-legacy-BkOYOR6U.js';
3
3
 
4
4
  interface StaticCourseManifest {
5
5
  version: string;
@@ -165,4 +165,4 @@ interface QuestionRecord extends CardRecord, Evaluation {
165
165
  priorAttemps: number;
166
166
  }
167
167
 
168
- export { type CardHistory as C, DocType as D, type Field as F, GuestUsername as G, type QualifiedCardID as Q, type SkuilderCourseData as S, type TagStub as T, type Tag as a, type CardRecord as b, type QuestionRecord as c, type CardData as d, type CourseListData as e, type DisplayableData as f, type DataShapeData as g, type QuestionData as h, DocTypePrefixes as i, log as l };
168
+ export { type CardData as C, DocType as D, type Field as F, GuestUsername as G, type QuestionRecord as Q, type SkuilderCourseData as S, type Tag as T, type DisplayableData as a, type CardRecord as b, type CardHistory as c, type QualifiedCardID as d, type TagStub as e, DocTypePrefixes as f, type CourseListData as g, type DataShapeData as h, type QuestionData as i, log as l };
@@ -165,4 +165,4 @@ interface QuestionRecord extends CardRecord, Evaluation {
165
165
  priorAttemps: number;
166
166
  }
167
167
 
168
- export { type CardHistory as C, DocType as D, type Field as F, GuestUsername as G, type QualifiedCardID as Q, type SkuilderCourseData as S, type TagStub as T, type Tag as a, type CardRecord as b, type QuestionRecord as c, type CardData as d, type CourseListData as e, type DisplayableData as f, type DataShapeData as g, type QuestionData as h, DocTypePrefixes as i, log as l };
168
+ export { type CardData as C, DocType as D, type Field as F, GuestUsername as G, type QuestionRecord as Q, type SkuilderCourseData as S, type Tag as T, type DisplayableData as a, type CardRecord as b, type CardHistory as c, type QualifiedCardID as d, type TagStub as e, DocTypePrefixes as f, type CourseListData as g, type DataShapeData as h, type QuestionData as i, log as l };
@@ -1,5 +1,5 @@
1
- export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-DjiFOZxJ.cjs';
2
- export { C as CouchDBToStaticPacker } from '../../index-D7WdMDAs.cjs';
1
+ export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-D0oQeJAi.cjs';
2
+ export { C as CouchDBToStaticPacker } from '../../index-Ktg72jKb.cjs';
3
3
  import '@vue-skuilder/common';
4
- import '../../types-legacy-CrwyZIvI.cjs';
4
+ import '../../types-legacy-BkOYOR6U.cjs';
5
5
  import 'moment';
@@ -1,5 +1,5 @@
1
- export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-uJ2Xn3_X.js';
2
- export { C as CouchDBToStaticPacker } from '../../index-BkBJlGDX.js';
1
+ export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-dXWfyz9B.js';
2
+ export { C as CouchDBToStaticPacker } from '../../index-CVGehe_t.js';
3
3
  import '@vue-skuilder/common';
4
- import '../../types-legacy-CrwyZIvI.js';
4
+ import '../../types-legacy-BkOYOR6U.js';
5
5
  import 'moment';
package/package.json CHANGED
@@ -4,7 +4,7 @@
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
7
- "version": "0.2.27",
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",
@@ -34,6 +34,18 @@
34
34
  "types": "./dist/impl/static/index.d.ts",
35
35
  "import": "./dist/impl/static/index.mjs",
36
36
  "require": "./dist/impl/static/index.js"
37
+ },
38
+ "./diagnostics": {
39
+ "types": "./dist/diagnostics/index.d.ts",
40
+ "import": "./dist/diagnostics/index.mjs",
41
+ "require": "./dist/diagnostics/index.js"
42
+ }
43
+ },
44
+ "typesVersions": {
45
+ "*": {
46
+ "diagnostics": [
47
+ "./dist/diagnostics/index.d.ts"
48
+ ]
37
49
  }
38
50
  },
39
51
  "scripts": {
@@ -48,7 +60,7 @@
48
60
  },
49
61
  "dependencies": {
50
62
  "@nilock2/pouchdb-authentication": "^1.0.2",
51
- "@vue-skuilder/common": "0.2.27",
63
+ "@vue-skuilder/common": "0.2.29",
52
64
  "cross-fetch": "^4.1.0",
53
65
  "moment": "^2.29.4",
54
66
  "pouchdb": "^9.0.0",
@@ -63,5 +75,5 @@
63
75
  "vite": "^8.0.0",
64
76
  "vitest": "^4.1.0"
65
77
  },
66
- "stableVersion": "0.2.27"
78
+ "stableVersion": "0.2.29"
67
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,6 +1,6 @@
1
1
  // db/src/core/interfaces.ts
2
2
 
3
- import { UserDBInterface, UserDBReader } from './userDB';
3
+ import { UserDBInterface } from './userDB';
4
4
  import { CourseDBInterface, CoursesDBInterface } from './courseDB';
5
5
  import { ClassroomDBInterface } from './classroomDB';
6
6
  import { AdminDBInterface } from './adminDB';
@@ -14,13 +14,8 @@ export interface DataLayerProvider {
14
14
  */
15
15
  getUserDB(): UserDBInterface;
16
16
 
17
- /**
18
- * Create a UserDBReader for a specific user (admin access required)
19
- * Uses session authentication to verify requesting user is admin
20
- * @param targetUsername - The username to create a reader for
21
- * @throws Error if requesting user is not 'admin'
22
- */
23
- createUserReaderForUser(targetUsername: string): Promise<UserDBReader>;
17
+ // Reading another learner's records (admin): see `@vue-skuilder/db/diagnostics`
18
+ // (`fetchLearnerDump`). A second UserDB would replace the logged-in one.
24
19
 
25
20
  /**
26
21
  * Get a course database interface
@@ -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) {
@@ -501,9 +530,15 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
501
530
  logger.debug(`[Pipeline] Filter '${filter.name}': ${beforeScores.size} → ${cards.length} cards (↑${boosted} ↓${penalized} =${passed})`);
502
531
  }
503
532
 
504
- // Remove zero-score cards (hard filtered)
533
+ // Remove zero-score cards (hard filtered). The debug report still wants
534
+ // them: they're the answer to "which filter sank this card?"
535
+ const scoredCards = cards;
505
536
  cards = cards.filter((c) => c.score > 0);
506
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
+
507
542
  // Apply ephemeral hints (one-shot, post-filter)
508
543
  const hints = this._ephemeralHints;
509
544
  if (hints) {
@@ -568,7 +603,9 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
568
603
  cards,
569
604
  result,
570
605
  context.userElo,
571
- hints?? undefined
606
+ hints?? undefined,
607
+ scoredCards,
608
+ regulators
572
609
  );
573
610
  captureRun(report);
574
611
  } catch (e) {
@@ -782,6 +819,93 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
782
819
  return cards;
783
820
  }
784
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
+
785
909
  /**
786
910
  * Build shared context for generator and filters.
787
911
  *
@@ -792,11 +916,12 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
792
916
  */
793
917
  private async buildContext(): Promise<GeneratorContext & FilterContext> {
794
918
  let userElo = 1000; // Default ELO
919
+ let userCourseElo: CourseElo | undefined;
795
920
 
796
921
  try {
797
922
  const courseReg = await this.user!.getCourseRegDoc(this.course!.getCourseID());
798
- const courseElo = toCourseElo(courseReg.elo);
799
- userElo = courseElo.global.score;
923
+ userCourseElo = toCourseElo(courseReg.elo);
924
+ userElo = userCourseElo.global.score;
800
925
  } catch (e) {
801
926
  logger.debug(`[Pipeline] Could not get user ELO, using default: ${e}`);
802
927
  }
@@ -813,6 +938,7 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
813
938
  user: this.user!,
814
939
  course: this.course!,
815
940
  userElo,
941
+ ...(userCourseElo ? { userCourseElo } : {}),
816
942
  orchestration,
817
943
  };
818
944
  }
@@ -958,7 +1084,7 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
958
1084
  const fullPool = cards.slice();
959
1085
 
960
1086
  const context = await this.buildContext();
961
- for (const filter of this.filters) {
1087
+ for (const filter of this.forecastFilters()) {
962
1088
  cards = await filter.transform(cards, context);
963
1089
  }
964
1090
 
@@ -982,6 +1108,15 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
982
1108
  return opts?.limit ? cards.slice(0, opts.limit) : cards;
983
1109
  }
984
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
+
985
1120
  /**
986
1121
  * Scan every card in the course through the filter chain and report
987
1122
  * how many are "well indicated" (score >= threshold) for the current user.
@@ -1013,7 +1148,7 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
1013
1148
  const filterBreakdown: Array<{ name: string; wellIndicated: number }> = [];
1014
1149
 
1015
1150
  // Track cumulative filter effects
1016
- for (const filter of this.filters) {
1151
+ for (const filter of this.forecastFilters()) {
1017
1152
  cards = await filter.transform(cards, context);
1018
1153
  const wi = cards.filter((c) => c.score >= THRESHOLD).length;
1019
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,12 +70,28 @@ 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;
74
78
  removed: number;
75
79
  }
76
80
 
81
+ /** One card as retained in a {@link PipelineRunReport}. */
82
+ export interface RunReportCard {
83
+ cardId: string;
84
+ courseId: string;
85
+ origin: 'new' | 'review' | 'unknown';
86
+ generator?: string;
87
+ finalScore: number;
88
+ /** Card's ELO (parsed from ELO generator provenance, if available) */
89
+ cardElo?: number;
90
+ provenance: StrategyContribution[];
91
+ tags?: string[];
92
+ selected: boolean;
93
+ }
94
+
77
95
  /**
78
96
  * Complete record of a single pipeline execution.
79
97
  */
@@ -117,18 +135,25 @@ export interface PipelineRunReport {
117
135
  * rather than retained verbatim — each retained card carries a multi-KB
118
136
  * provenance trail, and the tail is typically hundreds of cards per run.
119
137
  */
120
- cards: Array<{
121
- cardId: string;
122
- courseId: string;
123
- origin: 'new' | 'review' | 'unknown';
124
- generator?: string;
125
- finalScore: number;
126
- /** Card's ELO (parsed from ELO generator provenance, if available) */
127
- cardElo?: number;
128
- provenance: StrategyContribution[];
129
- tags?: string[];
130
- selected: boolean;
131
- }>;
138
+ cards: RunReportCard[];
139
+
140
+ /**
141
+ * The two unselected non-review cards most worth explaining when a run
142
+ * picks no new content. Non-review means no `reviewID`, so prescribed and
143
+ * required cards count (their `origin` reads `'unknown'`).
144
+ *
145
+ * - `nextInLine`: highest final score. How close new content came.
146
+ * - `topGenerated`: highest generator score, zero-scored cards included.
147
+ * Its provenance shows which filter sank it. Omitted when it is the same
148
+ * card as `nextInLine`.
149
+ */
150
+ unselectedNew?: {
151
+ nextInLine?: RunReportCard;
152
+ topGenerated?: RunReportCard;
153
+ };
154
+
155
+ /** The regulator stage's readings: each class's pressure and the multiplier it got. */
156
+ regulators?: RegulatorReading[];
132
157
 
133
158
  /**
134
159
  * Summary of the discarded tail of the candidate pool — cards that were
@@ -273,7 +298,10 @@ export function buildRunReport(
273
298
  allCards: WeightedCard[],
274
299
  selectedCards: WeightedCard[],
275
300
  userElo?: number,
276
- hints?: ReplanHints
301
+ hints?: ReplanHints,
302
+ /** Post-filter cards before zero-scored ones are dropped. Defaults to `allCards`. */
303
+ scoredCards?: WeightedCard[],
304
+ regulators?: RegulatorReading[]
277
305
  ): Omit<PipelineRunReport, 'runId' | 'timestamp'> {
278
306
  const selectedIds = new Set(selectedCards.map((c) => c.cardId));
279
307
 
@@ -281,20 +309,20 @@ export function buildRunReport(
281
309
  // into selected vs not-selected, then retain only the top-N of the
282
310
  // non-selected group to bound memory. The remaining low-score tail is
283
311
  // summarized rather than kept (see discardedTail).
284
- const toReport = (card: WeightedCard) => ({
312
+ const toReport = (card: WeightedCard): RunReportCard => ({
285
313
  cardId: card.cardId,
286
314
  courseId: card.courseId,
287
315
  origin: getOrigin(card),
288
316
  generator: card.provenance[0]?.strategyName || card.provenance[0]?.strategy,
289
317
  finalScore: card.score,
290
- cardElo: parseCardElo(card.provenance),
318
+ cardElo: card.cardElo ?? parseCardElo(card.provenance),
291
319
  provenance: card.provenance,
292
320
  tags: card.tags,
293
321
  selected: selectedIds.has(card.cardId),
294
322
  });
295
323
 
296
- const selectedReported: ReturnType<typeof toReport>[] = [];
297
- const nearMissReported: ReturnType<typeof toReport>[] = [];
324
+ const selectedReported: RunReportCard[] = [];
325
+ const nearMissReported: RunReportCard[] = [];
298
326
  const discardedTailCards: WeightedCard[] = [];
299
327
 
300
328
  let nonSelectedSeen = 0;
@@ -341,6 +369,33 @@ export function buildRunReport(
341
369
  };
342
370
  }
343
371
 
372
+ // Unselected non-review candidates. `nextInLine` ranks by final score, so it
373
+ // comes from `allCards` (post-hints; zero-scored dropped). `topGenerated`
374
+ // ranks by generator score and must see the zero-scored cards too, but not
375
+ // cards a hint excluded: exclusion leaves no provenance to explain them.
376
+ const isUnselectedNew = (c: WeightedCard) => !c.reviewID && !selectedIds.has(c.cardId);
377
+ const generatorScore = (c: WeightedCard) => c.provenance[0]?.score ?? 0;
378
+ const keptIds = new Set(allCards.map((c) => c.cardId));
379
+ const hintExcluded = (c: WeightedCard) => c.score > 0 && !keptIds.has(c.cardId);
380
+ let nextInLine: WeightedCard | undefined;
381
+ for (const c of allCards) {
382
+ if (isUnselectedNew(c) && (!nextInLine || c.score > nextInLine.score)) nextInLine = c;
383
+ }
384
+ let topGenerated: WeightedCard | undefined;
385
+ for (const c of scoredCards ?? allCards) {
386
+ if (!isUnselectedNew(c) || hintExcluded(c)) continue;
387
+ if (!topGenerated || generatorScore(c) > generatorScore(topGenerated)) topGenerated = c;
388
+ }
389
+ const unselectedNew =
390
+ nextInLine || topGenerated
391
+ ? {
392
+ ...(nextInLine ? { nextInLine: toReport(nextInLine) } : {}),
393
+ ...(topGenerated && topGenerated.cardId !== nextInLine?.cardId
394
+ ? { topGenerated: toReport(topGenerated) }
395
+ : {}),
396
+ }
397
+ : undefined;
398
+
344
399
  const reviewsSelected = selectedCards.filter((c) => getOrigin(c) === 'review').length;
345
400
  const newSelected = selectedCards.filter((c) => getOrigin(c) === 'new').length;
346
401
 
@@ -357,7 +412,9 @@ export function buildRunReport(
357
412
  reviewsSelected,
358
413
  newSelected,
359
414
  cards,
415
+ unselectedNew,
360
416
  discardedTail,
417
+ ...(regulators ? { regulators } : {}),
361
418
  };
362
419
  }
363
420