@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
@@ -0,0 +1,86 @@
1
+ import { CourseConfig, ClassroomConfig } from '@vue-skuilder/common';
2
+
3
+ /**
4
+ * Admin functionality
5
+ */
6
+ interface AdminDBInterface {
7
+ /**
8
+ * Get all users
9
+ */
10
+ getUsers(): Promise<PouchDB.Core.Document<{}>[]>;
11
+ /**
12
+ * Get all courses
13
+ */
14
+ getCourses(): Promise<CourseConfig[]>;
15
+ /**
16
+ * Remove a course
17
+ */
18
+ removeCourse(id: string): Promise<PouchDB.Core.Response>;
19
+ /**
20
+ * Get all classrooms
21
+ */
22
+ getClassrooms(): Promise<(ClassroomConfig & {
23
+ _id: string;
24
+ })[]>;
25
+ }
26
+
27
+ /**
28
+ * Classroom management
29
+ */
30
+ interface ClassroomDBInterface {
31
+ /**
32
+ * Get classroom config
33
+ */
34
+ getConfig(): ClassroomConfig;
35
+ /**
36
+ * Get assigned content
37
+ */
38
+ getAssignedContent(): Promise<AssignedContent[]>;
39
+ }
40
+ interface TeacherClassroomDBInterface extends ClassroomDBInterface {
41
+ /**
42
+ * For teacher interfaces: assign content
43
+ */
44
+ assignContent?(content: AssignedContent): Promise<boolean>;
45
+ /**
46
+ * For teacher interfaces: remove content
47
+ */
48
+ removeContent?(content: AssignedContent): Promise<void>;
49
+ }
50
+ /**
51
+ * Student-facing classroom interface.
52
+ * Content is accessed via StudyContentSource.getWeightedCards().
53
+ */
54
+ type StudentClassroomDBInterface = ClassroomDBInterface;
55
+ type AssignedContent = AssignedCourse | AssignedTag | AssignedCard;
56
+ interface AssignedTag extends ContentBase {
57
+ type: 'tag';
58
+ tagID: string;
59
+ }
60
+ interface AssignedCourse extends ContentBase {
61
+ type: 'course';
62
+ }
63
+ interface AssignedCard extends ContentBase {
64
+ type: 'card';
65
+ cardID: string;
66
+ }
67
+ interface ContentBase {
68
+ type: 'course' | 'tag' | 'card';
69
+ /**
70
+ * Username of the assigning teacher.
71
+ */
72
+ assignedBy: string;
73
+ /**
74
+ * Date the content was assigned.
75
+ */
76
+ assignedOn: moment.Moment;
77
+ /**
78
+ * A 'due' date for this assigned content, for scheduling content
79
+ * in advance. Content will not be actively pushed to students until
80
+ * this date.
81
+ */
82
+ activeOn: moment.Moment;
83
+ courseID: string;
84
+ }
85
+
86
+ export type { AdminDBInterface as A, ClassroomDBInterface as C, StudentClassroomDBInterface as S, TeacherClassroomDBInterface as T, AssignedContent as a, AssignedTag as b, AssignedCourse as c, AssignedCard as d };
@@ -0,0 +1,86 @@
1
+ import { CourseConfig, ClassroomConfig } from '@vue-skuilder/common';
2
+
3
+ /**
4
+ * Admin functionality
5
+ */
6
+ interface AdminDBInterface {
7
+ /**
8
+ * Get all users
9
+ */
10
+ getUsers(): Promise<PouchDB.Core.Document<{}>[]>;
11
+ /**
12
+ * Get all courses
13
+ */
14
+ getCourses(): Promise<CourseConfig[]>;
15
+ /**
16
+ * Remove a course
17
+ */
18
+ removeCourse(id: string): Promise<PouchDB.Core.Response>;
19
+ /**
20
+ * Get all classrooms
21
+ */
22
+ getClassrooms(): Promise<(ClassroomConfig & {
23
+ _id: string;
24
+ })[]>;
25
+ }
26
+
27
+ /**
28
+ * Classroom management
29
+ */
30
+ interface ClassroomDBInterface {
31
+ /**
32
+ * Get classroom config
33
+ */
34
+ getConfig(): ClassroomConfig;
35
+ /**
36
+ * Get assigned content
37
+ */
38
+ getAssignedContent(): Promise<AssignedContent[]>;
39
+ }
40
+ interface TeacherClassroomDBInterface extends ClassroomDBInterface {
41
+ /**
42
+ * For teacher interfaces: assign content
43
+ */
44
+ assignContent?(content: AssignedContent): Promise<boolean>;
45
+ /**
46
+ * For teacher interfaces: remove content
47
+ */
48
+ removeContent?(content: AssignedContent): Promise<void>;
49
+ }
50
+ /**
51
+ * Student-facing classroom interface.
52
+ * Content is accessed via StudyContentSource.getWeightedCards().
53
+ */
54
+ type StudentClassroomDBInterface = ClassroomDBInterface;
55
+ type AssignedContent = AssignedCourse | AssignedTag | AssignedCard;
56
+ interface AssignedTag extends ContentBase {
57
+ type: 'tag';
58
+ tagID: string;
59
+ }
60
+ interface AssignedCourse extends ContentBase {
61
+ type: 'course';
62
+ }
63
+ interface AssignedCard extends ContentBase {
64
+ type: 'card';
65
+ cardID: string;
66
+ }
67
+ interface ContentBase {
68
+ type: 'course' | 'tag' | 'card';
69
+ /**
70
+ * Username of the assigning teacher.
71
+ */
72
+ assignedBy: string;
73
+ /**
74
+ * Date the content was assigned.
75
+ */
76
+ assignedOn: moment.Moment;
77
+ /**
78
+ * A 'due' date for this assigned content, for scheduling content
79
+ * in advance. Content will not be actively pushed to students until
80
+ * this date.
81
+ */
82
+ activeOn: moment.Moment;
83
+ courseID: string;
84
+ }
85
+
86
+ export type { AdminDBInterface as A, ClassroomDBInterface as C, StudentClassroomDBInterface as S, TeacherClassroomDBInterface as T, AssignedContent as a, AssignedTag as b, AssignedCourse as c, AssignedCard as d };
@@ -1,89 +1,6 @@
1
- import { CourseConfig, ClassroomConfig, Status, SkuilderCourseData as SkuilderCourseData$1, CourseElo, DataShape, TagFilter } from '@vue-skuilder/common';
1
+ import { Status, CourseConfig, SkuilderCourseData as SkuilderCourseData$1, CourseElo, DataShape, TagFilter } from '@vue-skuilder/common';
2
2
  import { Moment } from 'moment';
3
- import { S as SkuilderCourseData, i as DocTypePrefixes, D as DocType, Q as QualifiedCardID, T as TagStub, a as Tag, C as CardHistory, b as CardRecord, c as QuestionRecord } from './types-legacy-CrwyZIvI.js';
4
-
5
- /**
6
- * Admin functionality
7
- */
8
- interface AdminDBInterface {
9
- /**
10
- * Get all users
11
- */
12
- getUsers(): Promise<PouchDB.Core.Document<{}>[]>;
13
- /**
14
- * Get all courses
15
- */
16
- getCourses(): Promise<CourseConfig[]>;
17
- /**
18
- * Remove a course
19
- */
20
- removeCourse(id: string): Promise<PouchDB.Core.Response>;
21
- /**
22
- * Get all classrooms
23
- */
24
- getClassrooms(): Promise<(ClassroomConfig & {
25
- _id: string;
26
- })[]>;
27
- }
28
-
29
- /**
30
- * Classroom management
31
- */
32
- interface ClassroomDBInterface {
33
- /**
34
- * Get classroom config
35
- */
36
- getConfig(): ClassroomConfig;
37
- /**
38
- * Get assigned content
39
- */
40
- getAssignedContent(): Promise<AssignedContent[]>;
41
- }
42
- interface TeacherClassroomDBInterface extends ClassroomDBInterface {
43
- /**
44
- * For teacher interfaces: assign content
45
- */
46
- assignContent?(content: AssignedContent): Promise<boolean>;
47
- /**
48
- * For teacher interfaces: remove content
49
- */
50
- removeContent?(content: AssignedContent): Promise<void>;
51
- }
52
- /**
53
- * Student-facing classroom interface.
54
- * Content is accessed via StudyContentSource.getWeightedCards().
55
- */
56
- type StudentClassroomDBInterface = ClassroomDBInterface;
57
- type AssignedContent = AssignedCourse | AssignedTag | AssignedCard;
58
- interface AssignedTag extends ContentBase {
59
- type: 'tag';
60
- tagID: string;
61
- }
62
- interface AssignedCourse extends ContentBase {
63
- type: 'course';
64
- }
65
- interface AssignedCard extends ContentBase {
66
- type: 'card';
67
- cardID: string;
68
- }
69
- interface ContentBase {
70
- type: 'course' | 'tag' | 'card';
71
- /**
72
- * Username of the assigning teacher.
73
- */
74
- assignedBy: string;
75
- /**
76
- * Date the content was assigned.
77
- */
78
- assignedOn: moment.Moment;
79
- /**
80
- * A 'due' date for this assigned content, for scheduling content
81
- * in advance. Content will not be actively pushed to students until
82
- * this date.
83
- */
84
- activeOn: moment.Moment;
85
- courseID: string;
86
- }
3
+ import { S as SkuilderCourseData, f as DocTypePrefixes, D as DocType, d as QualifiedCardID, e as TagStub, T as Tag, c as CardHistory, b as CardRecord, Q as QuestionRecord } from './types-legacy-BkOYOR6U.cjs';
87
4
 
88
5
  interface DataLayerResult {
89
6
  status: Status;
@@ -552,6 +469,86 @@ interface CardSpaceDiagnosis {
552
469
  elapsedMs: number;
553
470
  }
554
471
 
472
+ type RegulatorName = 'review-mass' | 'intake';
473
+ /** One regulator's reading for one pipeline run. Persisted on run summaries. */
474
+ interface RegulatorReading {
475
+ name: RegulatorName;
476
+ /** The class the multiplier applies to. */
477
+ class: 'review' | 'new';
478
+ /** The valve's urgency: review mass (card-equivalents) or intake hours. */
479
+ urgency: number;
480
+ multiplier: number;
481
+ /** Candidates the multiplier applied to. */
482
+ applied: number;
483
+ inputs: Record<string, number>;
484
+ }
485
+ interface RegulatorConfig {
486
+ reviewMass: {
487
+ /**
488
+ * Unit of mass for reviews without an SRS urgency (from another
489
+ * generator): a filtered score this high weighs 1.
490
+ */
491
+ referenceScore: number;
492
+ /** Mass (card-equivalents) at or below which there's no pressure. */
493
+ healthyMass: number;
494
+ /** Multiplier growth per multiple of `healthyMass` in excess. */
495
+ rate: number;
496
+ };
497
+ intake: {
498
+ /** Multiplier growth per `scaleHours` without a new card. */
499
+ rate: number;
500
+ scaleHours: number;
501
+ };
502
+ }
503
+ /**
504
+ * Defaults. Review mass keeps the SRS generator's former healthy threshold and
505
+ * growth rate (20, ×2), now applied to mass instead of count. Intake doubles
506
+ * per day of servable time without a new card.
507
+ */
508
+ declare const DEFAULT_REGULATOR_CONFIG: RegulatorConfig;
509
+ /**
510
+ * One due review's weight in the mass, in [0, 1]: its SRS urgency times the
511
+ * filters' net effect on it (filtered score ÷ the score it was generated
512
+ * with), so every course signal discounts it. A review without an urgency
513
+ * weighs its filtered score against the reference.
514
+ */
515
+ declare function reviewWeight(card: WeightedCard, generatedScore: number | undefined, referenceScore: number): number;
516
+ /**
517
+ * @param reviews - Due reviews, after filters
518
+ * @param generatedScores - Each card's score as generated, before filters
519
+ */
520
+ declare function reviewMassReading(reviews: WeightedCard[], generatedScores: ReadonlyMap<string, number>, config?: RegulatorConfig['reviewMass']): RegulatorReading;
521
+ /** The intake valve's clock, persisted per user and course (strategy state). */
522
+ interface IntakeClockState {
523
+ /** When a new card was last presented (ISO). */
524
+ lastNewAt: string;
525
+ /** Closed stretches since then during which no eligible new card existed (ms). */
526
+ frozenMs: number;
527
+ /** Start of the current stretch with no eligible new card (ISO), or null. */
528
+ unservableSince: string | null;
529
+ }
530
+ /** Strategy-state key for the intake clock. */
531
+ declare const INTAKE_CLOCK_KEY = "IntakeClock";
532
+ /** A fresh clock: a new card was just presented (or the clock is starting). */
533
+ declare function resetIntakeClock(nowMs: number): IntakeClockState;
534
+ /** Frozen time so far, including an open unservable stretch. */
535
+ declare function frozenMsAt(state: IntakeClockState, nowMs: number): number;
536
+ /** Servable hours since a new card was last presented. */
537
+ declare function intakeHours(state: IntakeClockState, nowMs: number): number;
538
+ /**
539
+ * Advance the clock's freeze bookkeeping for a run that found `eligibleNew`
540
+ * eligible new candidates. The clock freezes while there are none (exhaustion
541
+ * isn't starvation) and resumes when some appear. Returns the same object when
542
+ * nothing changed, so callers persist only on transitions.
543
+ */
544
+ declare function stepIntakeClock(state: IntakeClockState, nowMs: number, eligibleNew: number): IntakeClockState;
545
+ declare function intakeReading(state: IntakeClockState, nowMs: number, counts: {
546
+ eligibleNew: number;
547
+ newCandidates: number;
548
+ }, config?: RegulatorConfig['intake']): RegulatorReading;
549
+ /** Multiply `cards` (in place) by a reading's multiplier, with a provenance entry when it changes them. */
550
+ declare function applyReading(cards: WeightedCard[], reading: RegulatorReading): void;
551
+
555
552
  /**
556
553
  * The most recently constructed pipeline for the current session, or null if
557
554
  * none has been built yet. This is the supported, non-debug accessor for
@@ -574,11 +571,26 @@ interface GeneratorSummary {
574
571
  */
575
572
  interface FilterImpact {
576
573
  name: string;
574
+ /** Effective kind: undeclared filters count as gates. Absent on runs before 0.2.29. */
575
+ kind?: FilterKind;
577
576
  boosted: number;
578
577
  penalized: number;
579
578
  passed: number;
580
579
  removed: number;
581
580
  }
581
+ /** One card as retained in a {@link PipelineRunReport}. */
582
+ interface RunReportCard {
583
+ cardId: string;
584
+ courseId: string;
585
+ origin: 'new' | 'review' | 'unknown';
586
+ generator?: string;
587
+ finalScore: number;
588
+ /** Card's ELO (parsed from ELO generator provenance, if available) */
589
+ cardElo?: number;
590
+ provenance: StrategyContribution[];
591
+ tags?: string[];
592
+ selected: boolean;
593
+ }
582
594
  /**
583
595
  * Complete record of a single pipeline execution.
584
596
  */
@@ -613,18 +625,23 @@ interface PipelineRunReport {
613
625
  * rather than retained verbatim — each retained card carries a multi-KB
614
626
  * provenance trail, and the tail is typically hundreds of cards per run.
615
627
  */
616
- cards: Array<{
617
- cardId: string;
618
- courseId: string;
619
- origin: 'new' | 'review' | 'unknown';
620
- generator?: string;
621
- finalScore: number;
622
- /** Card's ELO (parsed from ELO generator provenance, if available) */
623
- cardElo?: number;
624
- provenance: StrategyContribution[];
625
- tags?: string[];
626
- selected: boolean;
627
- }>;
628
+ cards: RunReportCard[];
629
+ /**
630
+ * The two unselected non-review cards most worth explaining when a run
631
+ * picks no new content. Non-review means no `reviewID`, so prescribed and
632
+ * required cards count (their `origin` reads `'unknown'`).
633
+ *
634
+ * - `nextInLine`: highest final score. How close new content came.
635
+ * - `topGenerated`: highest generator score, zero-scored cards included.
636
+ * Its provenance shows which filter sank it. Omitted when it is the same
637
+ * card as `nextInLine`.
638
+ */
639
+ unselectedNew?: {
640
+ nextInLine?: RunReportCard;
641
+ topGenerated?: RunReportCard;
642
+ };
643
+ /** The regulator stage's readings: each class's pressure and the multiplier it got. */
644
+ regulators?: RegulatorReading[];
628
645
  /**
629
646
  * Summary of the discarded tail of the candidate pool — cards that were
630
647
  * generated and scored but neither selected nor retained in `cards`.
@@ -852,6 +869,42 @@ interface StudySessionRunSummary {
852
869
  eloRange?: [number, number];
853
870
  note: string;
854
871
  };
872
+ /**
873
+ * The selected cards, then the top few unselected ones, each in score
874
+ * order. The lowest selected score against the first runner-up is this
875
+ * run's cutoff.
876
+ */
877
+ cards?: StudySessionRunCard[];
878
+ /**
879
+ * The unselected non-review cards most worth explaining, with their
880
+ * score-changing provenance. See `PipelineRunReport.unselectedNew`.
881
+ */
882
+ unselectedNew?: {
883
+ nextInLine?: StudySessionRunCardTrail;
884
+ topGenerated?: StudySessionRunCardTrail;
885
+ };
886
+ /** The regulator stage's readings: review mass and intake, each with its multiplier (0.2.29+). */
887
+ regulators?: RegulatorReading[];
888
+ }
889
+ /** A card as persisted on a run. `origin` is as counted in `newSelected`/`reviewsSelected`. */
890
+ interface StudySessionRunCard {
891
+ cardId: string;
892
+ origin: 'new' | 'review' | 'unknown';
893
+ generator?: string;
894
+ score: number;
895
+ selected: boolean;
896
+ }
897
+ /**
898
+ * A card plus the provenance entries that changed its score, in order.
899
+ * `'passed'` entries are dropped. Strategy ids are dropped (the name is kept).
900
+ */
901
+ interface StudySessionRunCardTrail extends StudySessionRunCard {
902
+ trail: Array<{
903
+ strategyName: string;
904
+ action: StrategyContribution['action'];
905
+ score: number;
906
+ reason: string;
907
+ }>;
855
908
  }
856
909
  /**
857
910
  * One learner↔card ELO exchange, captured at the moment it resolved so a
@@ -1280,6 +1333,107 @@ interface ClassroomRegistrationDoc {
1280
1333
  registrations: ClassroomRegistration[];
1281
1334
  }
1282
1335
 
1336
+ /**
1337
+ * Shared context available to all filters in a pipeline.
1338
+ *
1339
+ * Built once per getWeightedCards() call and passed to each filter.
1340
+ * This avoids repeated lookups for common data like user ELO.
1341
+ */
1342
+ interface FilterContext {
1343
+ /** User database interface */
1344
+ user: UserDBInterface;
1345
+ /** Course database interface */
1346
+ course: CourseDBInterface;
1347
+ /** User's global ELO score for this course */
1348
+ userElo: number;
1349
+ /** User's full ELO for this course: global and per tag. Absent if it couldn't be read. */
1350
+ userCourseElo?: CourseElo;
1351
+ /** Orchestration context for evolutionary weighting */
1352
+ orchestration?: OrchestrationContext;
1353
+ }
1354
+ /**
1355
+ * A filter that transforms a list of weighted cards.
1356
+ *
1357
+ * Filters are pure transforms - they receive cards and context,
1358
+ * and return a modified list of cards. No delegate wrapping,
1359
+ * no side effects beyond provenance tracking.
1360
+ *
1361
+ * ## Implementation Guidelines
1362
+ *
1363
+ * 1. **Append provenance**: Every filter should add a StrategyContribution
1364
+ * entry documenting its decision for each card.
1365
+ *
1366
+ * 2. **Use multipliers**: Adjust scores by multiplying, not replacing.
1367
+ * This ensures filter order doesn't matter.
1368
+ *
1369
+ * 3. **Score 0 for exclusion**: To exclude a card, set score to 0.
1370
+ * Don't filter it out - let provenance show why it was excluded.
1371
+ *
1372
+ * 4. **Don't sort**: The Pipeline handles final sorting.
1373
+ * Filters just transform scores.
1374
+ *
1375
+ * ## Example Implementation
1376
+ *
1377
+ * ```typescript
1378
+ * const myFilter: CardFilter = {
1379
+ * name: 'My Filter',
1380
+ * async transform(cards, context) {
1381
+ * return cards.map(card => {
1382
+ * const multiplier = computeMultiplier(card, context);
1383
+ * const newScore = card.score * multiplier;
1384
+ * return {
1385
+ * ...card,
1386
+ * score: newScore,
1387
+ * provenance: [...card.provenance, {
1388
+ * strategy: 'myFilter',
1389
+ * strategyName: 'My Filter',
1390
+ * strategyId: 'MY_FILTER',
1391
+ * action: multiplier < 1 ? 'penalized' : 'passed',
1392
+ * score: newScore,
1393
+ * reason: 'Explanation of decision'
1394
+ * }]
1395
+ * };
1396
+ * });
1397
+ * }
1398
+ * };
1399
+ * ```
1400
+ */
1401
+ /**
1402
+ * What a filter's penalties mean. A `gate` says a card isn't ready yet
1403
+ * (prerequisites, lessons, unlocks); a `signal` expresses preference
1404
+ * (priority, interference, ELO distance).
1405
+ */
1406
+ type FilterKind = 'gate' | 'signal';
1407
+ interface CardFilter {
1408
+ /** Human-readable name for this filter */
1409
+ name: string;
1410
+ /**
1411
+ * Regulators lift only new cards that no gate penalized, so pressure can't
1412
+ * override "not ready". Undeclared filters count as gates: a penalty of
1413
+ * unknown meaning shouldn't be overridden by pressure.
1414
+ */
1415
+ kind?: FilterKind;
1416
+ /**
1417
+ * Applies to live runs only. `forecast` and `diagnoseCardSpace` start every
1418
+ * card at 1.0 without a generator, and skip these filters.
1419
+ */
1420
+ liveOnly?: boolean;
1421
+ /**
1422
+ * Transform a list of weighted cards.
1423
+ *
1424
+ * @param cards - Cards to transform (already scored by generator)
1425
+ * @param context - Shared context (user, course, userElo, etc.)
1426
+ * @returns Transformed cards with updated scores and provenance
1427
+ */
1428
+ transform(cards: WeightedCard[], context: FilterContext): Promise<WeightedCard[]>;
1429
+ }
1430
+ /**
1431
+ * Factory function type for creating filters from configuration.
1432
+ *
1433
+ * Used by PipelineAssembler to instantiate filters from strategy documents.
1434
+ */
1435
+ type CardFilterFactory<TConfig = unknown> = (config: TConfig) => CardFilter;
1436
+
1283
1437
  /**
1284
1438
  * Type for navigator constructor functions.
1285
1439
  */
@@ -1320,6 +1474,13 @@ declare function hasRegisteredNavigator(implementingClass: string): boolean;
1320
1474
  * @returns The role, or undefined if not registered or no role was specified
1321
1475
  */
1322
1476
  declare function getRegisteredNavigatorRole(implementingClass: string): NavigatorRole | undefined;
1477
+ /**
1478
+ * A registered filter's declared kind (see `CardFilter.kind`): the static
1479
+ * `kind` on its class. Undefined if unregistered or undeclared; undeclared
1480
+ * filters count as gates at run time.
1481
+ * @param implementingClass - The class name to look up
1482
+ */
1483
+ declare function getRegisteredFilterKind(implementingClass: string): FilterKind | undefined;
1323
1484
  /**
1324
1485
  * Get all registered navigator names.
1325
1486
  * Useful for debugging and testing.
@@ -1441,6 +1602,17 @@ interface WeightedCard {
1441
1602
  * Used by SessionController to track review outcomes and maintain review state.
1442
1603
  */
1443
1604
  reviewID?: string;
1605
+ /**
1606
+ * The card's global ELO, when the generator already knows it (the ELO
1607
+ * generator reads it during retrieval). Lets the ELO distance filter skip a
1608
+ * fetch.
1609
+ */
1610
+ cardElo?: number;
1611
+ /**
1612
+ * A review's SRS urgency in [0, 1] (overdueness and interval recency), set by
1613
+ * the SRS generator. The review-mass regulator weighs the backlog by it.
1614
+ */
1615
+ reviewUrgency?: number;
1444
1616
  }
1445
1617
  /**
1446
1618
  * Extract card origin from provenance trail.
@@ -1460,7 +1632,8 @@ declare enum Navigators {
1460
1632
  HIERARCHY = "hierarchyDefinition",
1461
1633
  INTERFERENCE = "interferenceMitigator",
1462
1634
  RELATIVE_PRIORITY = "relativePriority",
1463
- USER_TAG_PREFERENCE = "userTagPreference"
1635
+ USER_TAG_PREFERENCE = "userTagPreference",
1636
+ ELO_DISTANCE = "eloDistance"
1464
1637
  }
1465
1638
  /**
1466
1639
  * Role classification for navigation strategies.
@@ -1781,7 +1954,17 @@ interface StudyContentSource {
1781
1954
  * No-op for sources that don't support hints.
1782
1955
  */
1783
1956
  setEphemeralHints?(hints: ReplanHints): void;
1957
+ /**
1958
+ * A card was just presented. `status` is the session item's (`'new'`,
1959
+ * `'review'`, `'failed-new'`, ...). Pipelines use a new card's first
1960
+ * presentation to restart their intake valve's clock.
1961
+ */
1962
+ notePresented?(card: {
1963
+ cardId: string;
1964
+ courseId: string;
1965
+ status: string;
1966
+ }): void;
1784
1967
  }
1785
1968
  declare function getStudySource(source: ContentSourceID, user: UserDBInterface): Promise<StudyContentSource>;
1786
1969
 
1787
- export { HYDRATION_MARKER_ID as $, type AdminDBInterface as A, type UserCourseSettings as B, type CourseDBInterface as C, type DataLayerResult as D, type UserCourseSetting as E, type UsrCrsDataInterface as F, type GeneratorResult as G, type ClassroomRegistrationDesignation as H, type ClassroomRegistration as I, type ClassroomRegistrationDoc as J, type SessionTrackingData as K, type UserConfig as L, type ActivityRecord as M, type CourseRegistration as N, type UserOutcomeRecord as O, type StudySessionDoc as P, type StudySessionRunSummary as Q, type ReplanHints as R, type StudySessionItem as S, type TeacherClassroomDBInterface as T, type UserDBInterface as U, type SessionStateSnapshot as V, type WeightedCard as W, makeStudySessionId as X, newSessionId as Y, type UserHydrationState as Z, type UserHydrationStatus as _, type UserDBReader as a, type HydrationMarker as a0, type NavigatorConstructor as a1, registerNavigator as a2, getRegisteredNavigator as a3, hasRegisteredNavigator as a4, getRegisteredNavigatorRole as a5, getRegisteredNavigatorNames as a6, initializeNavigatorRegistry as a7, type StrategyContribution as a8, getCardOrigin as a9, getStreak as aA, getLapses as aB, Navigators as aa, NavigatorRole as ab, NavigatorRoles as ac, isGenerator as ad, isFilter as ae, type CardGenerator as af, type GeneratorContext as ag, type CardGeneratorFactory as ah, pipelineDebugAPI as ai, mountPipelineDebugger as aj, getActivePipeline as ak, setDebugSessionId as al, getRunsForSession as am, drainCapturedRuns as an, type PipelineRunReport as ao, type GeneratorSummary as ap, type FilterImpact as aq, type PipelineForecaster as ar, type LearnableWeight as as, type OrchestrationContext as at, computeDeviation as au, computeSpread as av, computeEffectiveWeight as aw, createOrchestrationContext as ax, type DocumentUpdater as ay, newInterval as az, type CoursesDBInterface as b, type ClassroomDBInterface as c, type CourseInfo as d, type ContentNavigationStrategyData as e, ContentNavigator as f, type AssignedContent as g, type StudyContentSource as h, type StudentClassroomDBInterface as i, type ScheduledCard as j, type StudySessionFailedItem as k, type StudySessionFailedNewItem as l, type StudySessionFailedReviewItem as m, type StudySessionNewItem as n, type StudySessionReviewItem as o, isReview as p, type ContentSourceID as q, getStudySource as r, type CourseRegistrationDoc as s, type SessionEloEvent as t, type SessionStateSnapshotProvider as u, type AssignedTag as v, type AssignedCourse as w, type AssignedCard as x, type UserDBWriter as y, type UserDBAuthenticator as z };
1970
+ export { type HydrationMarker as $, type UserDBWriter as A, type UserDBAuthenticator as B, type CourseDBInterface as C, type DataLayerResult as D, type UserCourseSettings as E, type FilterKind as F, type GeneratorResult as G, type UserCourseSetting as H, type UsrCrsDataInterface as I, type ClassroomRegistrationDesignation as J, type ClassroomRegistration as K, type ClassroomRegistrationDoc as L, type SessionTrackingData as M, NavigatorRole as N, type UserConfig as O, type ActivityRecord as P, type CourseRegistration as Q, type RegulatorReading as R, type StudySessionDoc as S, type UserOutcomeRecord as T, type UserDBInterface as U, makeStudySessionId as V, type WeightedCard as W, newSessionId as X, type UserHydrationState as Y, type UserHydrationStatus as Z, HYDRATION_MARKER_ID as _, type CoursesDBInterface as a, type NavigatorConstructor as a0, registerNavigator as a1, getRegisteredNavigator as a2, hasRegisteredNavigator as a3, getRegisteredNavigatorRole as a4, getRegisteredFilterKind as a5, getRegisteredNavigatorNames as a6, initializeNavigatorRegistry as a7, type StrategyContribution as a8, getCardOrigin as a9, createOrchestrationContext as aA, DEFAULT_REGULATOR_CONFIG as aB, reviewWeight as aC, reviewMassReading as aD, type IntakeClockState as aE, INTAKE_CLOCK_KEY as aF, resetIntakeClock as aG, frozenMsAt as aH, intakeHours as aI, stepIntakeClock as aJ, intakeReading as aK, applyReading as aL, type DocumentUpdater as aM, newInterval as aN, getStreak as aO, getLapses as aP, Navigators as aa, NavigatorRoles as ab, isGenerator as ac, isFilter as ad, type CardFilter as ae, type FilterContext as af, type CardFilterFactory as ag, type CardGenerator as ah, type GeneratorContext as ai, type CardGeneratorFactory as aj, pipelineDebugAPI as ak, mountPipelineDebugger as al, getActivePipeline as am, setDebugSessionId as an, getRunsForSession as ao, drainCapturedRuns as ap, type PipelineRunReport as aq, type RunReportCard as ar, type GeneratorSummary as as, type FilterImpact as at, type PipelineForecaster as au, type LearnableWeight as av, type OrchestrationContext as aw, computeDeviation as ax, computeSpread as ay, computeEffectiveWeight as az, type ContentNavigationStrategyData as b, type ScheduledCard as c, type CourseRegistrationDoc as d, type SessionStateSnapshot as e, type StudySessionRunSummary as f, type RegulatorName as g, type SessionEloEvent as h, type StudySessionRunCard as i, type StudySessionRunCardTrail as j, type CourseInfo as k, type StudySessionItem as l, ContentNavigator as m, type ReplanHints as n, type StudyContentSource as o, type StudySessionFailedItem as p, type StudySessionFailedNewItem as q, type StudySessionFailedReviewItem as r, type StudySessionNewItem as s, type StudySessionReviewItem as t, isReview as u, type ContentSourceID as v, getStudySource as w, type SessionStateSnapshotProvider as x, type RegulatorConfig as y, type UserDBReader as z };