@vue-skuilder/db 0.1.16 → 0.1.18

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 (80) hide show
  1. package/dist/{userDB-DNa0XPtn.d.ts → classroomDB-BgfrVb8d.d.ts} +357 -103
  2. package/dist/{userDB-BqwxtJ_7.d.mts → classroomDB-CTOenngH.d.cts} +358 -104
  3. package/dist/core/index.d.cts +230 -0
  4. package/dist/core/index.d.ts +161 -23
  5. package/dist/core/index.js +1964 -154
  6. package/dist/core/index.js.map +1 -1
  7. package/dist/core/index.mjs +1925 -121
  8. package/dist/core/index.mjs.map +1 -1
  9. package/dist/{dataLayerProvider-BV5iZqt_.d.ts → dataLayerProvider-CZxC9GtB.d.ts} +1 -1
  10. package/dist/{dataLayerProvider-VlngD19_.d.mts → dataLayerProvider-D6PoCwS6.d.cts} +1 -1
  11. package/dist/impl/couch/{index.d.mts → index.d.cts} +46 -5
  12. package/dist/impl/couch/index.d.ts +44 -3
  13. package/dist/impl/couch/index.js +1971 -171
  14. package/dist/impl/couch/index.js.map +1 -1
  15. package/dist/impl/couch/index.mjs +1933 -134
  16. package/dist/impl/couch/index.mjs.map +1 -1
  17. package/dist/impl/static/{index.d.mts → index.d.cts} +5 -6
  18. package/dist/impl/static/index.d.ts +2 -3
  19. package/dist/impl/static/index.js +1614 -119
  20. package/dist/impl/static/index.js.map +1 -1
  21. package/dist/impl/static/index.mjs +1585 -92
  22. package/dist/impl/static/index.mjs.map +1 -1
  23. package/dist/{index-Bmll7Xse.d.mts → index-D-Fa4Smt.d.cts} +1 -1
  24. package/dist/{index.d.mts → index.d.cts} +97 -13
  25. package/dist/index.d.ts +90 -6
  26. package/dist/index.js +2085 -153
  27. package/dist/index.js.map +1 -1
  28. package/dist/index.mjs +2031 -106
  29. package/dist/index.mjs.map +1 -1
  30. package/dist/pouch/index.js +3 -3
  31. package/dist/{types-Dbp5DaRR.d.mts → types-CzPDLAK6.d.cts} +1 -1
  32. package/dist/util/packer/{index.d.mts → index.d.cts} +3 -3
  33. package/dist/util/packer/index.js.map +1 -1
  34. package/dist/util/packer/index.mjs.map +1 -1
  35. package/docs/brainstorm-navigation-paradigm.md +369 -0
  36. package/docs/navigators-architecture.md +265 -0
  37. package/docs/todo-evolutionary-orchestration.md +310 -0
  38. package/docs/todo-nominal-tag-types.md +121 -0
  39. package/docs/todo-pipeline-optimization.md +117 -0
  40. package/docs/todo-strategy-authoring.md +401 -0
  41. package/docs/todo-strategy-state-storage.md +278 -0
  42. package/eslint.config.mjs +1 -1
  43. package/package.json +9 -4
  44. package/src/core/interfaces/contentSource.ts +88 -4
  45. package/src/core/interfaces/navigationStrategyManager.ts +0 -5
  46. package/src/core/navigators/CompositeGenerator.ts +268 -0
  47. package/src/core/navigators/Pipeline.ts +205 -0
  48. package/src/core/navigators/PipelineAssembler.ts +194 -0
  49. package/src/core/navigators/elo.ts +104 -15
  50. package/src/core/navigators/filters/eloDistance.ts +132 -0
  51. package/src/core/navigators/filters/index.ts +6 -0
  52. package/src/core/navigators/filters/types.ts +115 -0
  53. package/src/core/navigators/generators/index.ts +2 -0
  54. package/src/core/navigators/generators/types.ts +107 -0
  55. package/src/core/navigators/hardcodedOrder.ts +111 -12
  56. package/src/core/navigators/hierarchyDefinition.ts +266 -0
  57. package/src/core/navigators/index.ts +345 -3
  58. package/src/core/navigators/interferenceMitigator.ts +367 -0
  59. package/src/core/navigators/relativePriority.ts +267 -0
  60. package/src/core/navigators/srs.ts +195 -0
  61. package/src/impl/couch/classroomDB.ts +51 -0
  62. package/src/impl/couch/courseDB.ts +117 -39
  63. package/src/impl/static/courseDB.ts +0 -4
  64. package/src/study/SessionController.ts +149 -1
  65. package/src/study/TagFilteredContentSource.ts +255 -0
  66. package/src/study/index.ts +1 -0
  67. package/src/util/dataDirectory.test.ts +51 -22
  68. package/src/util/logger.ts +0 -1
  69. package/tests/core/navigators/CompositeGenerator.test.ts +455 -0
  70. package/tests/core/navigators/Pipeline.test.ts +405 -0
  71. package/tests/core/navigators/PipelineAssembler.test.ts +351 -0
  72. package/tests/core/navigators/SRSNavigator.test.ts +344 -0
  73. package/tests/core/navigators/eloDistanceFilter.test.ts +192 -0
  74. package/tests/core/navigators/navigators.test.ts +710 -0
  75. package/tsconfig.json +1 -1
  76. package/vitest.config.ts +29 -0
  77. package/dist/core/index.d.mts +0 -92
  78. /package/dist/{SyncStrategy-CyATpyLQ.d.mts → SyncStrategy-CyATpyLQ.d.cts} +0 -0
  79. /package/dist/pouch/{index.d.mts → index.d.cts} +0 -0
  80. /package/dist/{types-legacy-6ettoclI.d.mts → types-legacy-6ettoclI.d.cts} +0 -0
@@ -140,9 +140,9 @@ var import_pouchdb, import_pouchdb_find, import_pouchdb_authentication, pouchdb_
140
140
  var init_pouchdb_setup = __esm({
141
141
  "src/impl/couch/pouchdb-setup.ts"() {
142
142
  "use strict";
143
- import_pouchdb = __toESM(require("pouchdb"));
144
- import_pouchdb_find = __toESM(require("pouchdb-find"));
145
- import_pouchdb_authentication = __toESM(require("@nilock2/pouchdb-authentication"));
143
+ import_pouchdb = __toESM(require("pouchdb"), 1);
144
+ import_pouchdb_find = __toESM(require("pouchdb-find"), 1);
145
+ import_pouchdb_authentication = __toESM(require("@nilock2/pouchdb-authentication"), 1);
146
146
  import_pouchdb.default.plugin(import_pouchdb_find.default);
147
147
  import_pouchdb.default.plugin(import_pouchdb_authentication.default);
148
148
  import_pouchdb.default.defaults({
@@ -177,8 +177,8 @@ var path, os;
177
177
  var init_dataDirectory = __esm({
178
178
  "src/util/dataDirectory.ts"() {
179
179
  "use strict";
180
- path = __toESM(require("path"));
181
- os = __toESM(require("os"));
180
+ path = __toESM(require("path"), 1);
181
+ os = __toESM(require("os"), 1);
182
182
  init_tuiLogger();
183
183
  init_factory();
184
184
  }
@@ -238,7 +238,7 @@ var import_moment, REVIEW_TIME_FORMAT, log;
238
238
  var init_userDBHelpers = __esm({
239
239
  "src/impl/common/userDBHelpers.ts"() {
240
240
  "use strict";
241
- import_moment = __toESM(require("moment"));
241
+ import_moment = __toESM(require("moment"), 1);
242
242
  init_core();
243
243
  init_logger();
244
244
  init_pouchdb_setup();
@@ -394,7 +394,7 @@ var import_moment2, UsrCrsData;
394
394
  var init_user_course_relDB = __esm({
395
395
  "src/impl/couch/user-course-relDB.ts"() {
396
396
  "use strict";
397
- import_moment2 = __toESM(require("moment"));
397
+ import_moment2 = __toESM(require("moment"), 1);
398
398
  init_logger();
399
399
  UsrCrsData = class {
400
400
  user;
@@ -499,23 +499,460 @@ var init_courseLookupDB = __esm({
499
499
  }
500
500
  });
501
501
 
502
+ // src/core/navigators/CompositeGenerator.ts
503
+ var CompositeGenerator_exports = {};
504
+ __export(CompositeGenerator_exports, {
505
+ AggregationMode: () => AggregationMode,
506
+ default: () => CompositeGenerator
507
+ });
508
+ var AggregationMode, DEFAULT_AGGREGATION_MODE, FREQUENCY_BOOST_FACTOR, CompositeGenerator;
509
+ var init_CompositeGenerator = __esm({
510
+ "src/core/navigators/CompositeGenerator.ts"() {
511
+ "use strict";
512
+ init_navigators();
513
+ init_logger();
514
+ AggregationMode = /* @__PURE__ */ ((AggregationMode2) => {
515
+ AggregationMode2["MAX"] = "max";
516
+ AggregationMode2["AVERAGE"] = "average";
517
+ AggregationMode2["FREQUENCY_BOOST"] = "frequencyBoost";
518
+ return AggregationMode2;
519
+ })(AggregationMode || {});
520
+ DEFAULT_AGGREGATION_MODE = "frequencyBoost" /* FREQUENCY_BOOST */;
521
+ FREQUENCY_BOOST_FACTOR = 0.1;
522
+ CompositeGenerator = class _CompositeGenerator extends ContentNavigator {
523
+ /** Human-readable name for CardGenerator interface */
524
+ name = "Composite Generator";
525
+ generators;
526
+ aggregationMode;
527
+ constructor(generators, aggregationMode = DEFAULT_AGGREGATION_MODE) {
528
+ super();
529
+ this.generators = generators;
530
+ this.aggregationMode = aggregationMode;
531
+ if (generators.length === 0) {
532
+ throw new Error("CompositeGenerator requires at least one generator");
533
+ }
534
+ logger.debug(
535
+ `[CompositeGenerator] Created with ${generators.length} generators, mode: ${aggregationMode}`
536
+ );
537
+ }
538
+ /**
539
+ * Creates a CompositeGenerator from strategy data.
540
+ *
541
+ * This is a convenience factory for use by PipelineAssembler.
542
+ */
543
+ static async fromStrategies(user, course, strategies, aggregationMode = DEFAULT_AGGREGATION_MODE) {
544
+ const generators = await Promise.all(
545
+ strategies.map((s) => ContentNavigator.create(user, course, s))
546
+ );
547
+ return new _CompositeGenerator(generators, aggregationMode);
548
+ }
549
+ /**
550
+ * Get weighted cards from all generators, merge and deduplicate.
551
+ *
552
+ * Cards appearing in multiple generators receive a score boost.
553
+ * Provenance tracks which generators produced each card and how scores were aggregated.
554
+ *
555
+ * This method supports both the legacy signature (limit only) and the
556
+ * CardGenerator interface signature (limit, context).
557
+ *
558
+ * @param limit - Maximum number of cards to return
559
+ * @param context - Optional GeneratorContext passed to child generators
560
+ */
561
+ async getWeightedCards(limit, context) {
562
+ const results = await Promise.all(
563
+ this.generators.map((g) => g.getWeightedCards(limit, context))
564
+ );
565
+ const byCardId = /* @__PURE__ */ new Map();
566
+ for (const cards of results) {
567
+ for (const card of cards) {
568
+ const existing = byCardId.get(card.cardId) || [];
569
+ existing.push(card);
570
+ byCardId.set(card.cardId, existing);
571
+ }
572
+ }
573
+ const merged = [];
574
+ for (const [, cards] of byCardId) {
575
+ const aggregatedScore = this.aggregateScores(cards);
576
+ const finalScore = Math.min(1, aggregatedScore);
577
+ const mergedProvenance = cards.flatMap((c) => c.provenance);
578
+ const initialScore = cards[0].score;
579
+ const action = finalScore > initialScore ? "boosted" : finalScore < initialScore ? "penalized" : "passed";
580
+ const reason = this.buildAggregationReason(cards, finalScore);
581
+ merged.push({
582
+ ...cards[0],
583
+ score: finalScore,
584
+ provenance: [
585
+ ...mergedProvenance,
586
+ {
587
+ strategy: "composite",
588
+ strategyName: "Composite Generator",
589
+ strategyId: "COMPOSITE_GENERATOR",
590
+ action,
591
+ score: finalScore,
592
+ reason
593
+ }
594
+ ]
595
+ });
596
+ }
597
+ return merged.sort((a, b) => b.score - a.score).slice(0, limit);
598
+ }
599
+ /**
600
+ * Build human-readable reason for score aggregation.
601
+ */
602
+ buildAggregationReason(cards, finalScore) {
603
+ const count = cards.length;
604
+ const scores = cards.map((c) => c.score.toFixed(2)).join(", ");
605
+ if (count === 1) {
606
+ return `Single generator, score ${finalScore.toFixed(2)}`;
607
+ }
608
+ const strategies = cards.map((c) => c.provenance[0]?.strategy || "unknown").join(", ");
609
+ switch (this.aggregationMode) {
610
+ case "max" /* MAX */:
611
+ return `Max of ${count} generators (${strategies}): scores [${scores}] \u2192 ${finalScore.toFixed(2)}`;
612
+ case "average" /* AVERAGE */:
613
+ return `Average of ${count} generators (${strategies}): scores [${scores}] \u2192 ${finalScore.toFixed(2)}`;
614
+ case "frequencyBoost" /* FREQUENCY_BOOST */: {
615
+ const avg = cards.reduce((sum, c) => sum + c.score, 0) / count;
616
+ const boost = 1 + FREQUENCY_BOOST_FACTOR * (count - 1);
617
+ return `Frequency boost from ${count} generators (${strategies}): avg ${avg.toFixed(2)} \xD7 ${boost.toFixed(2)} \u2192 ${finalScore.toFixed(2)}`;
618
+ }
619
+ default:
620
+ return `Aggregated from ${count} generators: ${finalScore.toFixed(2)}`;
621
+ }
622
+ }
623
+ /**
624
+ * Aggregate scores from multiple generators for the same card.
625
+ */
626
+ aggregateScores(cards) {
627
+ const scores = cards.map((c) => c.score);
628
+ switch (this.aggregationMode) {
629
+ case "max" /* MAX */:
630
+ return Math.max(...scores);
631
+ case "average" /* AVERAGE */:
632
+ return scores.reduce((sum, s) => sum + s, 0) / scores.length;
633
+ case "frequencyBoost" /* FREQUENCY_BOOST */: {
634
+ const avg = scores.reduce((sum, s) => sum + s, 0) / scores.length;
635
+ const frequencyBoost = 1 + FREQUENCY_BOOST_FACTOR * (cards.length - 1);
636
+ return avg * frequencyBoost;
637
+ }
638
+ default:
639
+ return scores[0];
640
+ }
641
+ }
642
+ /**
643
+ * Get new cards from all generators, merged and deduplicated.
644
+ */
645
+ async getNewCards(n) {
646
+ const legacyGenerators = this.generators.filter(
647
+ (g) => g instanceof ContentNavigator
648
+ );
649
+ const results = await Promise.all(legacyGenerators.map((g) => g.getNewCards(n)));
650
+ const seen = /* @__PURE__ */ new Set();
651
+ const merged = [];
652
+ for (const cards of results) {
653
+ for (const card of cards) {
654
+ if (!seen.has(card.cardID)) {
655
+ seen.add(card.cardID);
656
+ merged.push(card);
657
+ }
658
+ }
659
+ }
660
+ return n ? merged.slice(0, n) : merged;
661
+ }
662
+ /**
663
+ * Get pending reviews from all generators, merged and deduplicated.
664
+ */
665
+ async getPendingReviews() {
666
+ const legacyGenerators = this.generators.filter(
667
+ (g) => g instanceof ContentNavigator
668
+ );
669
+ const results = await Promise.all(legacyGenerators.map((g) => g.getPendingReviews()));
670
+ const seen = /* @__PURE__ */ new Set();
671
+ const merged = [];
672
+ for (const reviews of results) {
673
+ for (const review of reviews) {
674
+ if (!seen.has(review.cardID)) {
675
+ seen.add(review.cardID);
676
+ merged.push(review);
677
+ }
678
+ }
679
+ }
680
+ return merged;
681
+ }
682
+ };
683
+ }
684
+ });
685
+
686
+ // src/core/navigators/Pipeline.ts
687
+ var Pipeline_exports = {};
688
+ __export(Pipeline_exports, {
689
+ Pipeline: () => Pipeline
690
+ });
691
+ var import_common5, Pipeline;
692
+ var init_Pipeline = __esm({
693
+ "src/core/navigators/Pipeline.ts"() {
694
+ "use strict";
695
+ import_common5 = require("@vue-skuilder/common");
696
+ init_navigators();
697
+ init_logger();
698
+ Pipeline = class extends ContentNavigator {
699
+ generator;
700
+ filters;
701
+ /**
702
+ * Create a new pipeline.
703
+ *
704
+ * @param generator - The generator (or CompositeGenerator) that produces candidates
705
+ * @param filters - Filters to apply sequentially (order doesn't matter for multipliers)
706
+ * @param user - User database interface
707
+ * @param course - Course database interface
708
+ */
709
+ constructor(generator, filters, user, course) {
710
+ super();
711
+ this.generator = generator;
712
+ this.filters = filters;
713
+ this.user = user;
714
+ this.course = course;
715
+ logger.debug(
716
+ `[Pipeline] Created with generator '${generator.name}' and ${filters.length} filters: ${filters.map((f) => f.name).join(", ")}`
717
+ );
718
+ }
719
+ /**
720
+ * Get weighted cards by running generator and applying filters.
721
+ *
722
+ * 1. Build shared context (user ELO, etc.)
723
+ * 2. Get candidates from generator (passing context)
724
+ * 3. Apply each filter sequentially
725
+ * 4. Remove zero-score cards
726
+ * 5. Sort by score descending
727
+ * 6. Return top N
728
+ *
729
+ * @param limit - Maximum number of cards to return
730
+ * @returns Cards sorted by score descending
731
+ */
732
+ async getWeightedCards(limit) {
733
+ const context = await this.buildContext();
734
+ const overFetchMultiplier = 2 + this.filters.length * 0.5;
735
+ const fetchLimit = Math.ceil(limit * overFetchMultiplier);
736
+ logger.debug(
737
+ `[Pipeline] Fetching ${fetchLimit} candidates from generator '${this.generator.name}'`
738
+ );
739
+ let cards = await this.generator.getWeightedCards(fetchLimit, context);
740
+ logger.debug(`[Pipeline] Generator returned ${cards.length} candidates`);
741
+ for (const filter of this.filters) {
742
+ const beforeCount = cards.length;
743
+ cards = await filter.transform(cards, context);
744
+ logger.debug(`[Pipeline] Filter '${filter.name}': ${beforeCount} \u2192 ${cards.length} cards`);
745
+ }
746
+ cards = cards.filter((c) => c.score > 0);
747
+ cards.sort((a, b) => b.score - a.score);
748
+ const result = cards.slice(0, limit);
749
+ logger.debug(
750
+ `[Pipeline] Returning ${result.length} cards (top scores: ${result.slice(0, 3).map((c) => c.score.toFixed(2)).join(", ")}...)`
751
+ );
752
+ return result;
753
+ }
754
+ /**
755
+ * Build shared context for generator and filters.
756
+ *
757
+ * Called once per getWeightedCards() invocation.
758
+ * Contains data that the generator and multiple filters might need.
759
+ *
760
+ * The context satisfies both GeneratorContext and FilterContext interfaces.
761
+ */
762
+ async buildContext() {
763
+ let userElo = 1e3;
764
+ try {
765
+ const courseReg = await this.user.getCourseRegDoc(this.course.getCourseID());
766
+ const courseElo = (0, import_common5.toCourseElo)(courseReg.elo);
767
+ userElo = courseElo.global.score;
768
+ } catch (e) {
769
+ logger.debug(`[Pipeline] Could not get user ELO, using default: ${e}`);
770
+ }
771
+ return {
772
+ user: this.user,
773
+ course: this.course,
774
+ userElo
775
+ };
776
+ }
777
+ // ===========================================================================
778
+ // Legacy StudyContentSource methods
779
+ // ===========================================================================
780
+ //
781
+ // These delegate to the generator for backward compatibility.
782
+ // Eventually SessionController will use getWeightedCards() exclusively.
783
+ //
784
+ /**
785
+ * Get new cards via legacy API.
786
+ * Delegates to the generator if it supports the legacy interface.
787
+ */
788
+ async getNewCards(n) {
789
+ if ("getNewCards" in this.generator && typeof this.generator.getNewCards === "function") {
790
+ return this.generator.getNewCards(n);
791
+ }
792
+ return [];
793
+ }
794
+ /**
795
+ * Get pending reviews via legacy API.
796
+ * Delegates to the generator if it supports the legacy interface.
797
+ */
798
+ async getPendingReviews() {
799
+ if ("getPendingReviews" in this.generator && typeof this.generator.getPendingReviews === "function") {
800
+ return this.generator.getPendingReviews();
801
+ }
802
+ return [];
803
+ }
804
+ /**
805
+ * Get the course ID for this pipeline.
806
+ */
807
+ getCourseID() {
808
+ return this.course.getCourseID();
809
+ }
810
+ };
811
+ }
812
+ });
813
+
814
+ // src/core/navigators/PipelineAssembler.ts
815
+ var PipelineAssembler_exports = {};
816
+ __export(PipelineAssembler_exports, {
817
+ PipelineAssembler: () => PipelineAssembler
818
+ });
819
+ var PipelineAssembler;
820
+ var init_PipelineAssembler = __esm({
821
+ "src/core/navigators/PipelineAssembler.ts"() {
822
+ "use strict";
823
+ init_navigators();
824
+ init_Pipeline();
825
+ init_types_legacy();
826
+ init_logger();
827
+ init_CompositeGenerator();
828
+ PipelineAssembler = class {
829
+ /**
830
+ * Assembles a navigation pipeline from strategy documents.
831
+ *
832
+ * 1. Separates into generators and filters by role
833
+ * 2. Validates at least one generator exists (or creates default ELO)
834
+ * 3. Instantiates generators - wraps multiple in CompositeGenerator
835
+ * 4. Instantiates filters
836
+ * 5. Returns Pipeline(generator, filters)
837
+ *
838
+ * @param input - Strategy documents plus user/course interfaces
839
+ * @returns Assembled pipeline and any warnings
840
+ */
841
+ async assemble(input) {
842
+ const { strategies, user, course } = input;
843
+ const warnings = [];
844
+ if (strategies.length === 0) {
845
+ return {
846
+ pipeline: null,
847
+ generatorStrategies: [],
848
+ filterStrategies: [],
849
+ warnings
850
+ };
851
+ }
852
+ const generatorStrategies = [];
853
+ const filterStrategies = [];
854
+ for (const s of strategies) {
855
+ if (isGenerator(s.implementingClass)) {
856
+ generatorStrategies.push(s);
857
+ } else if (isFilter(s.implementingClass)) {
858
+ filterStrategies.push(s);
859
+ } else {
860
+ warnings.push(`Unknown strategy type '${s.implementingClass}', skipping: ${s.name}`);
861
+ }
862
+ }
863
+ if (generatorStrategies.length === 0) {
864
+ if (filterStrategies.length > 0) {
865
+ logger.debug(
866
+ "[PipelineAssembler] No generator found, using default ELO with configured filters"
867
+ );
868
+ generatorStrategies.push(this.makeDefaultEloStrategy(course.getCourseID()));
869
+ } else {
870
+ warnings.push("No generator strategy found");
871
+ return {
872
+ pipeline: null,
873
+ generatorStrategies: [],
874
+ filterStrategies: [],
875
+ warnings
876
+ };
877
+ }
878
+ }
879
+ let generator;
880
+ if (generatorStrategies.length === 1) {
881
+ const nav = await ContentNavigator.create(user, course, generatorStrategies[0]);
882
+ generator = nav;
883
+ logger.debug(`[PipelineAssembler] Using single generator: ${generatorStrategies[0].name}`);
884
+ } else {
885
+ logger.debug(
886
+ `[PipelineAssembler] Using CompositeGenerator for ${generatorStrategies.length} generators: ${generatorStrategies.map((g) => g.name).join(", ")}`
887
+ );
888
+ generator = await CompositeGenerator.fromStrategies(user, course, generatorStrategies);
889
+ }
890
+ const filters = [];
891
+ const sortedFilterStrategies = [...filterStrategies].sort(
892
+ (a, b) => a.name.localeCompare(b.name)
893
+ );
894
+ for (const filterStrategy of sortedFilterStrategies) {
895
+ try {
896
+ const nav = await ContentNavigator.create(user, course, filterStrategy);
897
+ if ("transform" in nav && typeof nav.transform === "function") {
898
+ filters.push(nav);
899
+ logger.debug(`[PipelineAssembler] Added filter: ${filterStrategy.name}`);
900
+ } else {
901
+ warnings.push(
902
+ `Filter '${filterStrategy.name}' does not implement CardFilter.transform(), skipping`
903
+ );
904
+ }
905
+ } catch (e) {
906
+ warnings.push(`Failed to instantiate filter '${filterStrategy.name}': ${e}`);
907
+ }
908
+ }
909
+ const pipeline = new Pipeline(generator, filters, user, course);
910
+ logger.debug(
911
+ `[PipelineAssembler] Assembled pipeline with ${generatorStrategies.length} generator(s) and ${filters.length} filter(s)`
912
+ );
913
+ return {
914
+ pipeline,
915
+ generatorStrategies,
916
+ filterStrategies: sortedFilterStrategies,
917
+ warnings
918
+ };
919
+ }
920
+ /**
921
+ * Creates a default ELO generator strategy.
922
+ * Used when filters are configured but no generator is specified.
923
+ */
924
+ makeDefaultEloStrategy(courseId) {
925
+ return {
926
+ _id: "NAVIGATION_STRATEGY-ELO-default",
927
+ course: courseId,
928
+ docType: "NAVIGATION_STRATEGY" /* NAVIGATION_STRATEGY */,
929
+ name: "ELO (default)",
930
+ description: "Default ELO-based generator",
931
+ implementingClass: "elo" /* ELO */,
932
+ serializedData: ""
933
+ };
934
+ }
935
+ };
936
+ }
937
+ });
938
+
502
939
  // src/core/navigators/elo.ts
503
940
  var elo_exports = {};
504
941
  __export(elo_exports, {
505
942
  default: () => ELONavigator
506
943
  });
507
- var ELONavigator;
944
+ var import_common6, ELONavigator;
508
945
  var init_elo = __esm({
509
946
  "src/core/navigators/elo.ts"() {
510
947
  "use strict";
511
948
  init_navigators();
949
+ import_common6 = require("@vue-skuilder/common");
512
950
  ELONavigator = class extends ContentNavigator {
513
- user;
514
- course;
515
- constructor(user, course) {
516
- super();
517
- this.user = user;
518
- this.course = course;
951
+ /** Human-readable name for CardGenerator interface */
952
+ name;
953
+ constructor(user, course, strategyData) {
954
+ super(user, course, strategyData);
955
+ this.name = strategyData?.name || "ELO";
519
956
  }
520
957
  async getPendingReviews() {
521
958
  const reviews = await this.user.getPendingReviews(this.course.getCourseID());
@@ -532,95 +969,994 @@ var init_elo = __esm({
532
969
  });
533
970
  return ratedReviews.map((r) => {
534
971
  return {
535
- ...r,
536
- contentSourceType: "course",
537
- contentSourceID: this.course.getCourseID(),
538
- cardID: r.cardId,
539
- courseID: r.courseId,
540
- qualifiedID: `${r.courseId}-${r.cardId}`,
541
- reviewID: r._id,
542
- status: "review"
972
+ ...r,
973
+ contentSourceType: "course",
974
+ contentSourceID: this.course.getCourseID(),
975
+ cardID: r.cardId,
976
+ courseID: r.courseId,
977
+ qualifiedID: `${r.courseId}-${r.cardId}`,
978
+ reviewID: r._id,
979
+ status: "review"
980
+ };
981
+ });
982
+ }
983
+ async getNewCards(limit = 99) {
984
+ const activeCards = await this.user.getActiveCards();
985
+ return (await this.course.getCardsCenteredAtELO(
986
+ { limit, elo: "user" },
987
+ (c) => {
988
+ if (activeCards.some((ac) => c.cardID === ac.cardID)) {
989
+ return false;
990
+ } else {
991
+ return true;
992
+ }
993
+ }
994
+ )).map((c) => {
995
+ return {
996
+ ...c,
997
+ status: "new"
998
+ };
999
+ });
1000
+ }
1001
+ /**
1002
+ * Get new cards with suitability scores based on ELO distance.
1003
+ *
1004
+ * Cards closer to user's ELO get higher scores.
1005
+ * Score formula: max(0, 1 - distance / 500)
1006
+ *
1007
+ * NOTE: This generator only handles NEW cards. Reviews are handled by
1008
+ * SRSNavigator. Use CompositeGenerator to combine both.
1009
+ *
1010
+ * This method supports both the legacy signature (limit only) and the
1011
+ * CardGenerator interface signature (limit, context).
1012
+ *
1013
+ * @param limit - Maximum number of cards to return
1014
+ * @param context - Optional GeneratorContext (used when called via Pipeline)
1015
+ */
1016
+ async getWeightedCards(limit, context) {
1017
+ let userGlobalElo;
1018
+ if (context?.userElo !== void 0) {
1019
+ userGlobalElo = context.userElo;
1020
+ } else {
1021
+ const courseReg = await this.user.getCourseRegDoc(this.course.getCourseID());
1022
+ const userElo = (0, import_common6.toCourseElo)(courseReg.elo);
1023
+ userGlobalElo = userElo.global.score;
1024
+ }
1025
+ const newCards = await this.getNewCards(limit);
1026
+ const cardIds = newCards.map((c) => c.cardID);
1027
+ const cardEloData = await this.course.getCardEloData(cardIds);
1028
+ const scored = newCards.map((c, i) => {
1029
+ const cardElo = cardEloData[i]?.global?.score ?? 1e3;
1030
+ const distance = Math.abs(cardElo - userGlobalElo);
1031
+ const score = Math.max(0, 1 - distance / 500);
1032
+ return {
1033
+ cardId: c.cardID,
1034
+ courseId: c.courseID,
1035
+ score,
1036
+ provenance: [
1037
+ {
1038
+ strategy: "elo",
1039
+ strategyName: this.strategyName || this.name,
1040
+ strategyId: this.strategyId || "NAVIGATION_STRATEGY-ELO-default",
1041
+ action: "generated",
1042
+ score,
1043
+ reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userGlobalElo)}), new card`
1044
+ }
1045
+ ]
1046
+ };
1047
+ });
1048
+ scored.sort((a, b) => b.score - a.score);
1049
+ return scored.slice(0, limit);
1050
+ }
1051
+ };
1052
+ }
1053
+ });
1054
+
1055
+ // src/core/navigators/filters/eloDistance.ts
1056
+ var eloDistance_exports = {};
1057
+ __export(eloDistance_exports, {
1058
+ DEFAULT_HALF_LIFE: () => DEFAULT_HALF_LIFE,
1059
+ DEFAULT_MAX_MULTIPLIER: () => DEFAULT_MAX_MULTIPLIER,
1060
+ DEFAULT_MIN_MULTIPLIER: () => DEFAULT_MIN_MULTIPLIER,
1061
+ createEloDistanceFilter: () => createEloDistanceFilter
1062
+ });
1063
+ function computeMultiplier(distance, halfLife, minMultiplier, maxMultiplier) {
1064
+ const normalizedDistance = distance / halfLife;
1065
+ const decay = Math.exp(-(normalizedDistance * normalizedDistance));
1066
+ return minMultiplier + (maxMultiplier - minMultiplier) * decay;
1067
+ }
1068
+ function createEloDistanceFilter(config) {
1069
+ const halfLife = config?.halfLife ?? DEFAULT_HALF_LIFE;
1070
+ const minMultiplier = config?.minMultiplier ?? DEFAULT_MIN_MULTIPLIER;
1071
+ const maxMultiplier = config?.maxMultiplier ?? DEFAULT_MAX_MULTIPLIER;
1072
+ return {
1073
+ name: "ELO Distance Filter",
1074
+ async transform(cards, context) {
1075
+ const { course, userElo } = context;
1076
+ const cardIds = cards.map((c) => c.cardId);
1077
+ const cardElos = await course.getCardEloData(cardIds);
1078
+ return cards.map((card, i) => {
1079
+ const cardElo = cardElos[i]?.global?.score ?? 1e3;
1080
+ const distance = Math.abs(cardElo - userElo);
1081
+ const multiplier = computeMultiplier(distance, halfLife, minMultiplier, maxMultiplier);
1082
+ const newScore = card.score * multiplier;
1083
+ const action = multiplier < maxMultiplier - 0.01 ? "penalized" : "passed";
1084
+ return {
1085
+ ...card,
1086
+ score: newScore,
1087
+ provenance: [
1088
+ ...card.provenance,
1089
+ {
1090
+ strategy: "eloDistance",
1091
+ strategyName: "ELO Distance Filter",
1092
+ strategyId: "ELO_DISTANCE_FILTER",
1093
+ action,
1094
+ score: newScore,
1095
+ reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userElo)}) \u2192 ${multiplier.toFixed(2)}x`
1096
+ }
1097
+ ]
1098
+ };
1099
+ });
1100
+ }
1101
+ };
1102
+ }
1103
+ var DEFAULT_HALF_LIFE, DEFAULT_MIN_MULTIPLIER, DEFAULT_MAX_MULTIPLIER;
1104
+ var init_eloDistance = __esm({
1105
+ "src/core/navigators/filters/eloDistance.ts"() {
1106
+ "use strict";
1107
+ DEFAULT_HALF_LIFE = 200;
1108
+ DEFAULT_MIN_MULTIPLIER = 0.3;
1109
+ DEFAULT_MAX_MULTIPLIER = 1;
1110
+ }
1111
+ });
1112
+
1113
+ // src/core/navigators/filters/index.ts
1114
+ var filters_exports = {};
1115
+ __export(filters_exports, {
1116
+ createEloDistanceFilter: () => createEloDistanceFilter
1117
+ });
1118
+ var init_filters = __esm({
1119
+ "src/core/navigators/filters/index.ts"() {
1120
+ "use strict";
1121
+ init_eloDistance();
1122
+ }
1123
+ });
1124
+
1125
+ // src/core/navigators/filters/types.ts
1126
+ var types_exports = {};
1127
+ var init_types = __esm({
1128
+ "src/core/navigators/filters/types.ts"() {
1129
+ "use strict";
1130
+ }
1131
+ });
1132
+
1133
+ // src/core/navigators/generators/index.ts
1134
+ var generators_exports = {};
1135
+ var init_generators = __esm({
1136
+ "src/core/navigators/generators/index.ts"() {
1137
+ "use strict";
1138
+ }
1139
+ });
1140
+
1141
+ // src/core/navigators/generators/types.ts
1142
+ var types_exports2 = {};
1143
+ var init_types2 = __esm({
1144
+ "src/core/navigators/generators/types.ts"() {
1145
+ "use strict";
1146
+ }
1147
+ });
1148
+
1149
+ // src/core/navigators/hardcodedOrder.ts
1150
+ var hardcodedOrder_exports = {};
1151
+ __export(hardcodedOrder_exports, {
1152
+ default: () => HardcodedOrderNavigator
1153
+ });
1154
+ var HardcodedOrderNavigator;
1155
+ var init_hardcodedOrder = __esm({
1156
+ "src/core/navigators/hardcodedOrder.ts"() {
1157
+ "use strict";
1158
+ init_navigators();
1159
+ init_logger();
1160
+ HardcodedOrderNavigator = class extends ContentNavigator {
1161
+ /** Human-readable name for CardGenerator interface */
1162
+ name;
1163
+ orderedCardIds = [];
1164
+ constructor(user, course, strategyData) {
1165
+ super(user, course, strategyData);
1166
+ this.name = strategyData.name || "Hardcoded Order";
1167
+ if (strategyData.serializedData) {
1168
+ try {
1169
+ this.orderedCardIds = JSON.parse(strategyData.serializedData);
1170
+ } catch (e) {
1171
+ logger.error("Failed to parse serializedData for HardcodedOrderNavigator", e);
1172
+ }
1173
+ }
1174
+ }
1175
+ async getPendingReviews() {
1176
+ const reviews = await this.user.getPendingReviews(this.course.getCourseID());
1177
+ return reviews.map((r) => {
1178
+ return {
1179
+ ...r,
1180
+ contentSourceType: "course",
1181
+ contentSourceID: this.course.getCourseID(),
1182
+ cardID: r.cardId,
1183
+ courseID: r.courseId,
1184
+ reviewID: r._id,
1185
+ status: "review"
1186
+ };
1187
+ });
1188
+ }
1189
+ async getNewCards(limit = 99) {
1190
+ const activeCardIds = (await this.user.getActiveCards()).map((c) => c.cardID);
1191
+ const newCardIds = this.orderedCardIds.filter((cardId) => !activeCardIds.includes(cardId));
1192
+ const cardsToReturn = newCardIds.slice(0, limit);
1193
+ return cardsToReturn.map((cardId) => {
1194
+ return {
1195
+ cardID: cardId,
1196
+ courseID: this.course.getCourseID(),
1197
+ contentSourceType: "course",
1198
+ contentSourceID: this.course.getCourseID(),
1199
+ status: "new"
1200
+ };
1201
+ });
1202
+ }
1203
+ /**
1204
+ * Get cards in hardcoded order with scores based on position.
1205
+ *
1206
+ * Earlier cards in the sequence get higher scores.
1207
+ * Score formula: 1.0 - (position / totalCards) * 0.5
1208
+ * This ensures scores range from 1.0 (first card) to 0.5+ (last card).
1209
+ *
1210
+ * This method supports both the legacy signature (limit only) and the
1211
+ * CardGenerator interface signature (limit, context).
1212
+ *
1213
+ * @param limit - Maximum number of cards to return
1214
+ * @param _context - Optional GeneratorContext (currently unused, but required for interface)
1215
+ */
1216
+ async getWeightedCards(limit, _context) {
1217
+ const activeCardIds = (await this.user.getActiveCards()).map((c) => c.cardID);
1218
+ const reviews = await this.getPendingReviews();
1219
+ const newCardIds = this.orderedCardIds.filter((cardId) => !activeCardIds.includes(cardId));
1220
+ const totalCards = newCardIds.length;
1221
+ const scoredNew = newCardIds.slice(0, limit).map((cardId, index) => {
1222
+ const position = index + 1;
1223
+ const score = Math.max(0.5, 1 - index / totalCards * 0.5);
1224
+ return {
1225
+ cardId,
1226
+ courseId: this.course.getCourseID(),
1227
+ score,
1228
+ provenance: [
1229
+ {
1230
+ strategy: "hardcodedOrder",
1231
+ strategyName: this.strategyName || this.name,
1232
+ strategyId: this.strategyId || "NAVIGATION_STRATEGY-hardcoded",
1233
+ action: "generated",
1234
+ score,
1235
+ reason: `Position ${position} of ${totalCards} in fixed sequence, new card`
1236
+ }
1237
+ ]
1238
+ };
1239
+ });
1240
+ const scoredReviews = reviews.map((r) => ({
1241
+ cardId: r.cardID,
1242
+ courseId: r.courseID,
1243
+ score: 1,
1244
+ provenance: [
1245
+ {
1246
+ strategy: "hardcodedOrder",
1247
+ strategyName: this.strategyName || this.name,
1248
+ strategyId: this.strategyId || "NAVIGATION_STRATEGY-hardcoded",
1249
+ action: "generated",
1250
+ score: 1,
1251
+ reason: "Scheduled review, highest priority"
1252
+ }
1253
+ ]
1254
+ }));
1255
+ const all = [...scoredReviews, ...scoredNew];
1256
+ all.sort((a, b) => b.score - a.score);
1257
+ return all.slice(0, limit);
1258
+ }
1259
+ };
1260
+ }
1261
+ });
1262
+
1263
+ // src/core/navigators/hierarchyDefinition.ts
1264
+ var hierarchyDefinition_exports = {};
1265
+ __export(hierarchyDefinition_exports, {
1266
+ default: () => HierarchyDefinitionNavigator
1267
+ });
1268
+ var import_common7, DEFAULT_MIN_COUNT, HierarchyDefinitionNavigator;
1269
+ var init_hierarchyDefinition = __esm({
1270
+ "src/core/navigators/hierarchyDefinition.ts"() {
1271
+ "use strict";
1272
+ init_navigators();
1273
+ import_common7 = require("@vue-skuilder/common");
1274
+ DEFAULT_MIN_COUNT = 3;
1275
+ HierarchyDefinitionNavigator = class extends ContentNavigator {
1276
+ config;
1277
+ _strategyData;
1278
+ /** Human-readable name for CardFilter interface */
1279
+ name;
1280
+ constructor(user, course, _strategyData) {
1281
+ super(user, course, _strategyData);
1282
+ this._strategyData = _strategyData;
1283
+ this.config = this.parseConfig(_strategyData.serializedData);
1284
+ this.name = _strategyData.name || "Hierarchy Definition";
1285
+ }
1286
+ parseConfig(serializedData) {
1287
+ try {
1288
+ const parsed = JSON.parse(serializedData);
1289
+ return {
1290
+ prerequisites: parsed.prerequisites || {}
1291
+ };
1292
+ } catch {
1293
+ return {
1294
+ prerequisites: {}
1295
+ };
1296
+ }
1297
+ }
1298
+ /**
1299
+ * Check if a specific prerequisite is satisfied
1300
+ */
1301
+ isPrerequisiteMet(prereq, userTagElo, userGlobalElo) {
1302
+ if (!userTagElo) return false;
1303
+ const minCount = prereq.masteryThreshold?.minCount ?? DEFAULT_MIN_COUNT;
1304
+ if (userTagElo.count < minCount) return false;
1305
+ if (prereq.masteryThreshold?.minElo !== void 0) {
1306
+ return userTagElo.score >= prereq.masteryThreshold.minElo;
1307
+ } else {
1308
+ return userTagElo.score >= userGlobalElo;
1309
+ }
1310
+ }
1311
+ /**
1312
+ * Get the set of tags the user has mastered.
1313
+ * A tag is "mastered" if it appears as a prerequisite somewhere and meets its threshold.
1314
+ */
1315
+ async getMasteredTags(context) {
1316
+ const mastered = /* @__PURE__ */ new Set();
1317
+ try {
1318
+ const courseReg = await context.user.getCourseRegDoc(context.course.getCourseID());
1319
+ const userElo = (0, import_common7.toCourseElo)(courseReg.elo);
1320
+ for (const prereqs of Object.values(this.config.prerequisites)) {
1321
+ for (const prereq of prereqs) {
1322
+ const tagElo = userElo.tags[prereq.tag];
1323
+ if (this.isPrerequisiteMet(prereq, tagElo, userElo.global.score)) {
1324
+ mastered.add(prereq.tag);
1325
+ }
1326
+ }
1327
+ }
1328
+ } catch {
1329
+ }
1330
+ return mastered;
1331
+ }
1332
+ /**
1333
+ * Get the set of tags that are unlocked (prerequisites met)
1334
+ */
1335
+ getUnlockedTags(masteredTags) {
1336
+ const unlocked = /* @__PURE__ */ new Set();
1337
+ for (const [tagId, prereqs] of Object.entries(this.config.prerequisites)) {
1338
+ const allPrereqsMet = prereqs.every((prereq) => masteredTags.has(prereq.tag));
1339
+ if (allPrereqsMet) {
1340
+ unlocked.add(tagId);
1341
+ }
1342
+ }
1343
+ return unlocked;
1344
+ }
1345
+ /**
1346
+ * Check if a tag has prerequisites defined in config
1347
+ */
1348
+ hasPrerequisites(tagId) {
1349
+ return tagId in this.config.prerequisites;
1350
+ }
1351
+ /**
1352
+ * Check if a card is unlocked and generate reason.
1353
+ */
1354
+ async checkCardUnlock(cardId, course, unlockedTags, masteredTags) {
1355
+ try {
1356
+ const tagResponse = await course.getAppliedTags(cardId);
1357
+ const cardTags = tagResponse.rows.map((row) => row.value?.name || row.key);
1358
+ const lockedTags = cardTags.filter(
1359
+ (tag) => this.hasPrerequisites(tag) && !unlockedTags.has(tag)
1360
+ );
1361
+ if (lockedTags.length === 0) {
1362
+ const tagList = cardTags.length > 0 ? cardTags.join(", ") : "none";
1363
+ return {
1364
+ isUnlocked: true,
1365
+ reason: `Prerequisites met, tags: ${tagList}`
1366
+ };
1367
+ }
1368
+ const missingPrereqs = lockedTags.flatMap((tag) => {
1369
+ const prereqs = this.config.prerequisites[tag] || [];
1370
+ return prereqs.filter((p) => !masteredTags.has(p.tag)).map((p) => p.tag);
1371
+ });
1372
+ return {
1373
+ isUnlocked: false,
1374
+ reason: `Blocked: missing prerequisites ${missingPrereqs.join(", ")} for tags ${lockedTags.join(", ")}`
1375
+ };
1376
+ } catch {
1377
+ return {
1378
+ isUnlocked: true,
1379
+ reason: "Prerequisites check skipped (tag lookup failed)"
1380
+ };
1381
+ }
1382
+ }
1383
+ /**
1384
+ * CardFilter.transform implementation.
1385
+ *
1386
+ * Apply prerequisite gating to cards. Cards with locked tags receive score: 0.
1387
+ */
1388
+ async transform(cards, context) {
1389
+ const masteredTags = await this.getMasteredTags(context);
1390
+ const unlockedTags = this.getUnlockedTags(masteredTags);
1391
+ const gated = [];
1392
+ for (const card of cards) {
1393
+ const { isUnlocked, reason } = await this.checkCardUnlock(
1394
+ card.cardId,
1395
+ context.course,
1396
+ unlockedTags,
1397
+ masteredTags
1398
+ );
1399
+ const finalScore = isUnlocked ? card.score : 0;
1400
+ const action = isUnlocked ? "passed" : "penalized";
1401
+ gated.push({
1402
+ ...card,
1403
+ score: finalScore,
1404
+ provenance: [
1405
+ ...card.provenance,
1406
+ {
1407
+ strategy: "hierarchyDefinition",
1408
+ strategyName: this.strategyName || this.name,
1409
+ strategyId: this.strategyId || "NAVIGATION_STRATEGY-hierarchy",
1410
+ action,
1411
+ score: finalScore,
1412
+ reason
1413
+ }
1414
+ ]
1415
+ });
1416
+ }
1417
+ return gated;
1418
+ }
1419
+ /**
1420
+ * Legacy getWeightedCards - now throws as filters should not be used as generators.
1421
+ *
1422
+ * Use transform() via Pipeline instead.
1423
+ */
1424
+ async getWeightedCards(_limit) {
1425
+ throw new Error(
1426
+ "HierarchyDefinitionNavigator is a filter and should not be used as a generator. Use Pipeline with a generator and this filter via transform()."
1427
+ );
1428
+ }
1429
+ // Legacy methods - stub implementations since filters don't generate cards
1430
+ async getNewCards(_n) {
1431
+ return [];
1432
+ }
1433
+ async getPendingReviews() {
1434
+ return [];
1435
+ }
1436
+ };
1437
+ }
1438
+ });
1439
+
1440
+ // src/core/navigators/interferenceMitigator.ts
1441
+ var interferenceMitigator_exports = {};
1442
+ __export(interferenceMitigator_exports, {
1443
+ default: () => InterferenceMitigatorNavigator
1444
+ });
1445
+ var import_common8, DEFAULT_MIN_COUNT2, DEFAULT_MIN_ELAPSED_DAYS, DEFAULT_INTERFERENCE_DECAY, InterferenceMitigatorNavigator;
1446
+ var init_interferenceMitigator = __esm({
1447
+ "src/core/navigators/interferenceMitigator.ts"() {
1448
+ "use strict";
1449
+ init_navigators();
1450
+ import_common8 = require("@vue-skuilder/common");
1451
+ DEFAULT_MIN_COUNT2 = 10;
1452
+ DEFAULT_MIN_ELAPSED_DAYS = 3;
1453
+ DEFAULT_INTERFERENCE_DECAY = 0.8;
1454
+ InterferenceMitigatorNavigator = class extends ContentNavigator {
1455
+ config;
1456
+ _strategyData;
1457
+ /** Human-readable name for CardFilter interface */
1458
+ name;
1459
+ /** Precomputed map: tag -> set of { partner, decay } it interferes with */
1460
+ interferenceMap;
1461
+ constructor(user, course, _strategyData) {
1462
+ super(user, course, _strategyData);
1463
+ this._strategyData = _strategyData;
1464
+ this.config = this.parseConfig(_strategyData.serializedData);
1465
+ this.interferenceMap = this.buildInterferenceMap();
1466
+ this.name = _strategyData.name || "Interference Mitigator";
1467
+ }
1468
+ parseConfig(serializedData) {
1469
+ try {
1470
+ const parsed = JSON.parse(serializedData);
1471
+ let sets = parsed.interferenceSets || [];
1472
+ if (sets.length > 0 && Array.isArray(sets[0])) {
1473
+ sets = sets.map((tags) => ({ tags }));
1474
+ }
1475
+ return {
1476
+ interferenceSets: sets,
1477
+ maturityThreshold: {
1478
+ minCount: parsed.maturityThreshold?.minCount ?? DEFAULT_MIN_COUNT2,
1479
+ minElo: parsed.maturityThreshold?.minElo,
1480
+ minElapsedDays: parsed.maturityThreshold?.minElapsedDays ?? DEFAULT_MIN_ELAPSED_DAYS
1481
+ },
1482
+ defaultDecay: parsed.defaultDecay ?? DEFAULT_INTERFERENCE_DECAY
1483
+ };
1484
+ } catch {
1485
+ return {
1486
+ interferenceSets: [],
1487
+ maturityThreshold: {
1488
+ minCount: DEFAULT_MIN_COUNT2,
1489
+ minElapsedDays: DEFAULT_MIN_ELAPSED_DAYS
1490
+ },
1491
+ defaultDecay: DEFAULT_INTERFERENCE_DECAY
543
1492
  };
544
- });
1493
+ }
545
1494
  }
546
- async getNewCards(limit = 99) {
547
- const activeCards = await this.user.getActiveCards();
548
- return (await this.course.getCardsCenteredAtELO(
549
- { limit, elo: "user" },
550
- (c) => {
551
- if (activeCards.some((ac) => c.cardID === ac.cardID)) {
552
- return false;
553
- } else {
554
- return true;
1495
+ /**
1496
+ * Build a map from each tag to its interference partners with decay coefficients.
1497
+ * If tags A, B, C are in an interference group with decay 0.8, then:
1498
+ * - A interferes with B (decay 0.8) and C (decay 0.8)
1499
+ * - B interferes with A (decay 0.8) and C (decay 0.8)
1500
+ * - etc.
1501
+ */
1502
+ buildInterferenceMap() {
1503
+ const map = /* @__PURE__ */ new Map();
1504
+ for (const group of this.config.interferenceSets) {
1505
+ const decay = group.decay ?? this.config.defaultDecay ?? DEFAULT_INTERFERENCE_DECAY;
1506
+ for (const tag of group.tags) {
1507
+ if (!map.has(tag)) {
1508
+ map.set(tag, []);
1509
+ }
1510
+ const partners = map.get(tag);
1511
+ for (const other of group.tags) {
1512
+ if (other !== tag) {
1513
+ const existing = partners.find((p) => p.partner === other);
1514
+ if (existing) {
1515
+ existing.decay = Math.max(existing.decay, decay);
1516
+ } else {
1517
+ partners.push({ partner: other, decay });
1518
+ }
1519
+ }
555
1520
  }
556
1521
  }
557
- )).map((c) => {
1522
+ }
1523
+ return map;
1524
+ }
1525
+ /**
1526
+ * Get the set of tags that are currently immature for this user.
1527
+ * A tag is immature if the user has interacted with it but hasn't
1528
+ * reached the maturity threshold.
1529
+ */
1530
+ async getImmatureTags(context) {
1531
+ const immature = /* @__PURE__ */ new Set();
1532
+ try {
1533
+ const courseReg = await context.user.getCourseRegDoc(context.course.getCourseID());
1534
+ const userElo = (0, import_common8.toCourseElo)(courseReg.elo);
1535
+ const minCount = this.config.maturityThreshold?.minCount ?? DEFAULT_MIN_COUNT2;
1536
+ const minElo = this.config.maturityThreshold?.minElo;
1537
+ const minElapsedDays = this.config.maturityThreshold?.minElapsedDays ?? DEFAULT_MIN_ELAPSED_DAYS;
1538
+ const minCountForElapsed = minElapsedDays * 2;
1539
+ for (const [tagId, tagElo] of Object.entries(userElo.tags)) {
1540
+ if (tagElo.count === 0) continue;
1541
+ const belowCount = tagElo.count < minCount;
1542
+ const belowElo = minElo !== void 0 && tagElo.score < minElo;
1543
+ const belowElapsed = tagElo.count < minCountForElapsed;
1544
+ if (belowCount || belowElo || belowElapsed) {
1545
+ immature.add(tagId);
1546
+ }
1547
+ }
1548
+ } catch {
1549
+ }
1550
+ return immature;
1551
+ }
1552
+ /**
1553
+ * Get all tags that interfere with any immature tag, along with their decay coefficients.
1554
+ * These are the tags we want to avoid introducing.
1555
+ */
1556
+ getTagsToAvoid(immatureTags) {
1557
+ const avoid = /* @__PURE__ */ new Map();
1558
+ for (const immatureTag of immatureTags) {
1559
+ const partners = this.interferenceMap.get(immatureTag);
1560
+ if (partners) {
1561
+ for (const { partner, decay } of partners) {
1562
+ if (!immatureTags.has(partner)) {
1563
+ const existing = avoid.get(partner) ?? 0;
1564
+ avoid.set(partner, Math.max(existing, decay));
1565
+ }
1566
+ }
1567
+ }
1568
+ }
1569
+ return avoid;
1570
+ }
1571
+ /**
1572
+ * Get tags for a single card
1573
+ */
1574
+ async getCardTags(cardId, course) {
1575
+ try {
1576
+ const tagResponse = await course.getAppliedTags(cardId);
1577
+ return tagResponse.rows.map((row) => row.value?.name || row.key).filter(Boolean);
1578
+ } catch {
1579
+ return [];
1580
+ }
1581
+ }
1582
+ /**
1583
+ * Compute interference score reduction for a card.
1584
+ * Returns: { multiplier, interfering tags, reason }
1585
+ */
1586
+ computeInterferenceEffect(cardTags, tagsToAvoid, immatureTags) {
1587
+ if (tagsToAvoid.size === 0) {
558
1588
  return {
559
- ...c,
560
- status: "new"
1589
+ multiplier: 1,
1590
+ interferingTags: [],
1591
+ reason: "No interference detected"
561
1592
  };
562
- });
1593
+ }
1594
+ let multiplier = 1;
1595
+ const interferingTags = [];
1596
+ for (const tag of cardTags) {
1597
+ const decay = tagsToAvoid.get(tag);
1598
+ if (decay !== void 0) {
1599
+ interferingTags.push(tag);
1600
+ multiplier *= 1 - decay;
1601
+ }
1602
+ }
1603
+ if (interferingTags.length === 0) {
1604
+ return {
1605
+ multiplier: 1,
1606
+ interferingTags: [],
1607
+ reason: "No interference detected"
1608
+ };
1609
+ }
1610
+ const causingTags = /* @__PURE__ */ new Set();
1611
+ for (const tag of interferingTags) {
1612
+ for (const immatureTag of immatureTags) {
1613
+ const partners = this.interferenceMap.get(immatureTag);
1614
+ if (partners?.some((p) => p.partner === tag)) {
1615
+ causingTags.add(immatureTag);
1616
+ }
1617
+ }
1618
+ }
1619
+ const reason = `Interferes with immature tags ${Array.from(causingTags).join(", ")} (tags: ${interferingTags.join(", ")}, multiplier: ${multiplier.toFixed(2)})`;
1620
+ return { multiplier, interferingTags, reason };
1621
+ }
1622
+ /**
1623
+ * CardFilter.transform implementation.
1624
+ *
1625
+ * Apply interference-aware scoring. Cards with tags that interfere with
1626
+ * immature learnings get reduced scores.
1627
+ */
1628
+ async transform(cards, context) {
1629
+ const immatureTags = await this.getImmatureTags(context);
1630
+ const tagsToAvoid = this.getTagsToAvoid(immatureTags);
1631
+ const adjusted = [];
1632
+ for (const card of cards) {
1633
+ const cardTags = await this.getCardTags(card.cardId, context.course);
1634
+ const { multiplier, reason } = this.computeInterferenceEffect(
1635
+ cardTags,
1636
+ tagsToAvoid,
1637
+ immatureTags
1638
+ );
1639
+ const finalScore = card.score * multiplier;
1640
+ const action = multiplier < 1 ? "penalized" : multiplier > 1 ? "boosted" : "passed";
1641
+ adjusted.push({
1642
+ ...card,
1643
+ score: finalScore,
1644
+ provenance: [
1645
+ ...card.provenance,
1646
+ {
1647
+ strategy: "interferenceMitigator",
1648
+ strategyName: this.strategyName || this.name,
1649
+ strategyId: this.strategyId || "NAVIGATION_STRATEGY-interference",
1650
+ action,
1651
+ score: finalScore,
1652
+ reason
1653
+ }
1654
+ ]
1655
+ });
1656
+ }
1657
+ return adjusted;
1658
+ }
1659
+ /**
1660
+ * Legacy getWeightedCards - now throws as filters should not be used as generators.
1661
+ *
1662
+ * Use transform() via Pipeline instead.
1663
+ */
1664
+ async getWeightedCards(_limit) {
1665
+ throw new Error(
1666
+ "InterferenceMitigatorNavigator is a filter and should not be used as a generator. Use Pipeline with a generator and this filter via transform()."
1667
+ );
1668
+ }
1669
+ // Legacy methods - stub implementations since filters don't generate cards
1670
+ async getNewCards(_n) {
1671
+ return [];
1672
+ }
1673
+ async getPendingReviews() {
1674
+ return [];
563
1675
  }
564
1676
  };
565
1677
  }
566
1678
  });
567
1679
 
568
- // src/core/navigators/hardcodedOrder.ts
569
- var hardcodedOrder_exports = {};
570
- __export(hardcodedOrder_exports, {
571
- default: () => HardcodedOrderNavigator
1680
+ // src/core/navigators/relativePriority.ts
1681
+ var relativePriority_exports = {};
1682
+ __export(relativePriority_exports, {
1683
+ default: () => RelativePriorityNavigator
572
1684
  });
573
- var HardcodedOrderNavigator;
574
- var init_hardcodedOrder = __esm({
575
- "src/core/navigators/hardcodedOrder.ts"() {
1685
+ var DEFAULT_PRIORITY, DEFAULT_PRIORITY_INFLUENCE, DEFAULT_COMBINE_MODE, RelativePriorityNavigator;
1686
+ var init_relativePriority = __esm({
1687
+ "src/core/navigators/relativePriority.ts"() {
576
1688
  "use strict";
577
1689
  init_navigators();
578
- init_logger();
579
- HardcodedOrderNavigator = class extends ContentNavigator {
580
- orderedCardIds = [];
581
- user;
582
- course;
583
- constructor(user, course, strategyData) {
584
- super();
585
- this.user = user;
586
- this.course = course;
587
- if (strategyData.serializedData) {
588
- try {
589
- this.orderedCardIds = JSON.parse(strategyData.serializedData);
590
- } catch (e) {
591
- logger.error("Failed to parse serializedData for HardcodedOrderNavigator", e);
592
- }
1690
+ DEFAULT_PRIORITY = 0.5;
1691
+ DEFAULT_PRIORITY_INFLUENCE = 0.5;
1692
+ DEFAULT_COMBINE_MODE = "max";
1693
+ RelativePriorityNavigator = class extends ContentNavigator {
1694
+ config;
1695
+ _strategyData;
1696
+ /** Human-readable name for CardFilter interface */
1697
+ name;
1698
+ constructor(user, course, _strategyData) {
1699
+ super(user, course, _strategyData);
1700
+ this._strategyData = _strategyData;
1701
+ this.config = this.parseConfig(_strategyData.serializedData);
1702
+ this.name = _strategyData.name || "Relative Priority";
1703
+ }
1704
+ parseConfig(serializedData) {
1705
+ try {
1706
+ const parsed = JSON.parse(serializedData);
1707
+ return {
1708
+ tagPriorities: parsed.tagPriorities || {},
1709
+ defaultPriority: parsed.defaultPriority ?? DEFAULT_PRIORITY,
1710
+ combineMode: parsed.combineMode ?? DEFAULT_COMBINE_MODE,
1711
+ priorityInfluence: parsed.priorityInfluence ?? DEFAULT_PRIORITY_INFLUENCE
1712
+ };
1713
+ } catch {
1714
+ return {
1715
+ tagPriorities: {},
1716
+ defaultPriority: DEFAULT_PRIORITY,
1717
+ combineMode: DEFAULT_COMBINE_MODE,
1718
+ priorityInfluence: DEFAULT_PRIORITY_INFLUENCE
1719
+ };
1720
+ }
1721
+ }
1722
+ /**
1723
+ * Look up the priority for a tag.
1724
+ */
1725
+ getTagPriority(tagId) {
1726
+ return this.config.tagPriorities[tagId] ?? this.config.defaultPriority ?? DEFAULT_PRIORITY;
1727
+ }
1728
+ /**
1729
+ * Compute combined priority for a card based on its tags.
1730
+ */
1731
+ computeCardPriority(cardTags) {
1732
+ if (cardTags.length === 0) {
1733
+ return this.config.defaultPriority ?? DEFAULT_PRIORITY;
1734
+ }
1735
+ const priorities = cardTags.map((tag) => this.getTagPriority(tag));
1736
+ switch (this.config.combineMode) {
1737
+ case "max":
1738
+ return Math.max(...priorities);
1739
+ case "min":
1740
+ return Math.min(...priorities);
1741
+ case "average":
1742
+ return priorities.reduce((sum, p) => sum + p, 0) / priorities.length;
1743
+ default:
1744
+ return Math.max(...priorities);
1745
+ }
1746
+ }
1747
+ /**
1748
+ * Compute boost factor based on priority.
1749
+ *
1750
+ * The formula: 1 + (priority - 0.5) * priorityInfluence
1751
+ *
1752
+ * This creates a multiplier centered around 1.0:
1753
+ * - Priority 1.0 with influence 0.5 → 1.25 (25% boost)
1754
+ * - Priority 0.5 with any influence → 1.00 (neutral)
1755
+ * - Priority 0.0 with influence 0.5 → 0.75 (25% reduction)
1756
+ */
1757
+ computeBoostFactor(priority) {
1758
+ const influence = this.config.priorityInfluence ?? DEFAULT_PRIORITY_INFLUENCE;
1759
+ return 1 + (priority - 0.5) * influence;
1760
+ }
1761
+ /**
1762
+ * Build human-readable reason for priority adjustment.
1763
+ */
1764
+ buildPriorityReason(cardTags, priority, boostFactor, finalScore) {
1765
+ if (cardTags.length === 0) {
1766
+ return `No tags, neutral priority (${priority.toFixed(2)})`;
1767
+ }
1768
+ const tagList = cardTags.slice(0, 3).join(", ");
1769
+ const more = cardTags.length > 3 ? ` (+${cardTags.length - 3} more)` : "";
1770
+ if (boostFactor === 1) {
1771
+ return `Neutral priority (${priority.toFixed(2)}) for tags: ${tagList}${more}`;
1772
+ } else if (boostFactor > 1) {
1773
+ return `High-priority tags: ${tagList}${more} (priority ${priority.toFixed(2)} \u2192 boost ${boostFactor.toFixed(2)}x \u2192 ${finalScore.toFixed(2)})`;
1774
+ } else {
1775
+ return `Low-priority tags: ${tagList}${more} (priority ${priority.toFixed(2)} \u2192 reduce ${boostFactor.toFixed(2)}x \u2192 ${finalScore.toFixed(2)})`;
1776
+ }
1777
+ }
1778
+ /**
1779
+ * Get tags for a single card.
1780
+ */
1781
+ async getCardTags(cardId, course) {
1782
+ try {
1783
+ const tagResponse = await course.getAppliedTags(cardId);
1784
+ return tagResponse.rows.map((r) => r.doc?.name).filter((x) => !!x);
1785
+ } catch {
1786
+ return [];
593
1787
  }
594
1788
  }
1789
+ /**
1790
+ * CardFilter.transform implementation.
1791
+ *
1792
+ * Apply priority-adjusted scoring. Cards with high-priority tags get boosted,
1793
+ * cards with low-priority tags get reduced scores.
1794
+ */
1795
+ async transform(cards, context) {
1796
+ const adjusted = await Promise.all(
1797
+ cards.map(async (card) => {
1798
+ const cardTags = await this.getCardTags(card.cardId, context.course);
1799
+ const priority = this.computeCardPriority(cardTags);
1800
+ const boostFactor = this.computeBoostFactor(priority);
1801
+ const finalScore = Math.max(0, Math.min(1, card.score * boostFactor));
1802
+ const action = boostFactor > 1 ? "boosted" : boostFactor < 1 ? "penalized" : "passed";
1803
+ const reason = this.buildPriorityReason(cardTags, priority, boostFactor, finalScore);
1804
+ return {
1805
+ ...card,
1806
+ score: finalScore,
1807
+ provenance: [
1808
+ ...card.provenance,
1809
+ {
1810
+ strategy: "relativePriority",
1811
+ strategyName: this.strategyName || this.name,
1812
+ strategyId: this.strategyId || "NAVIGATION_STRATEGY-priority",
1813
+ action,
1814
+ score: finalScore,
1815
+ reason
1816
+ }
1817
+ ]
1818
+ };
1819
+ })
1820
+ );
1821
+ return adjusted;
1822
+ }
1823
+ /**
1824
+ * Legacy getWeightedCards - now throws as filters should not be used as generators.
1825
+ *
1826
+ * Use transform() via Pipeline instead.
1827
+ */
1828
+ async getWeightedCards(_limit) {
1829
+ throw new Error(
1830
+ "RelativePriorityNavigator is a filter and should not be used as a generator. Use Pipeline with a generator and this filter via transform()."
1831
+ );
1832
+ }
1833
+ // Legacy methods - stub implementations since filters don't generate cards
1834
+ async getNewCards(_n) {
1835
+ return [];
1836
+ }
595
1837
  async getPendingReviews() {
1838
+ return [];
1839
+ }
1840
+ };
1841
+ }
1842
+ });
1843
+
1844
+ // src/core/navigators/srs.ts
1845
+ var srs_exports = {};
1846
+ __export(srs_exports, {
1847
+ default: () => SRSNavigator
1848
+ });
1849
+ var import_moment3, SRSNavigator;
1850
+ var init_srs = __esm({
1851
+ "src/core/navigators/srs.ts"() {
1852
+ "use strict";
1853
+ import_moment3 = __toESM(require("moment"), 1);
1854
+ init_navigators();
1855
+ SRSNavigator = class extends ContentNavigator {
1856
+ /** Human-readable name for CardGenerator interface */
1857
+ name;
1858
+ constructor(user, course, strategyData) {
1859
+ super(user, course, strategyData);
1860
+ this.name = strategyData?.name || "SRS";
1861
+ }
1862
+ /**
1863
+ * Get review cards scored by urgency.
1864
+ *
1865
+ * Score formula combines:
1866
+ * - Relative overdueness: hoursOverdue / intervalHours
1867
+ * - Interval recency: exponential decay favoring shorter intervals
1868
+ *
1869
+ * Cards not yet due are excluded (not scored as 0).
1870
+ *
1871
+ * This method supports both the legacy signature (limit only) and the
1872
+ * CardGenerator interface signature (limit, context).
1873
+ *
1874
+ * @param limit - Maximum number of cards to return
1875
+ * @param _context - Optional GeneratorContext (currently unused, but required for interface)
1876
+ */
1877
+ async getWeightedCards(limit, _context) {
1878
+ if (!this.user || !this.course) {
1879
+ throw new Error("SRSNavigator requires user and course to be set");
1880
+ }
596
1881
  const reviews = await this.user.getPendingReviews(this.course.getCourseID());
597
- return reviews.map((r) => {
1882
+ const now = import_moment3.default.utc();
1883
+ const dueReviews = reviews.filter((r) => now.isAfter(import_moment3.default.utc(r.reviewTime)));
1884
+ const scored = dueReviews.map((review) => {
1885
+ const { score, reason } = this.computeUrgencyScore(review, now);
598
1886
  return {
599
- ...r,
600
- contentSourceType: "course",
601
- contentSourceID: this.course.getCourseID(),
602
- cardID: r.cardId,
603
- courseID: r.courseId,
604
- reviewID: r._id,
605
- status: "review"
1887
+ cardId: review.cardId,
1888
+ courseId: review.courseId,
1889
+ score,
1890
+ provenance: [
1891
+ {
1892
+ strategy: "srs",
1893
+ strategyName: this.strategyName || this.name,
1894
+ strategyId: this.strategyId || "NAVIGATION_STRATEGY-SRS-default",
1895
+ action: "generated",
1896
+ score,
1897
+ reason
1898
+ }
1899
+ ]
606
1900
  };
607
1901
  });
1902
+ return scored.sort((a, b) => b.score - a.score).slice(0, limit);
608
1903
  }
609
- async getNewCards(limit = 99) {
610
- const activeCardIds = (await this.user.getActiveCards()).map((c) => c.cardID);
611
- const newCardIds = this.orderedCardIds.filter(
612
- (cardId) => !activeCardIds.includes(cardId)
613
- );
614
- const cardsToReturn = newCardIds.slice(0, limit);
615
- return cardsToReturn.map((cardId) => {
616
- return {
617
- cardID: cardId,
618
- courseID: this.course.getCourseID(),
619
- contentSourceType: "course",
620
- contentSourceID: this.course.getCourseID(),
621
- status: "new"
622
- };
623
- });
1904
+ /**
1905
+ * Compute urgency score for a review card.
1906
+ *
1907
+ * Two factors:
1908
+ * 1. Relative overdueness = hoursOverdue / intervalHours
1909
+ * - 2 days overdue on 3-day interval = 0.67 (urgent)
1910
+ * - 2 days overdue on 180-day interval = 0.01 (not urgent)
1911
+ *
1912
+ * 2. Interval recency factor = 0.3 + 0.7 * exp(-intervalHours / 720)
1913
+ * - 24h interval → ~1.0 (very recent learning)
1914
+ * - 30 days (720h) → ~0.56
1915
+ * - 180 days → ~0.30
1916
+ *
1917
+ * Combined: base 0.5 + weighted average of factors * 0.45
1918
+ * Result range: approximately 0.5 to 0.95
1919
+ */
1920
+ computeUrgencyScore(review, now) {
1921
+ const scheduledAt = import_moment3.default.utc(review.scheduledAt);
1922
+ const due = import_moment3.default.utc(review.reviewTime);
1923
+ const intervalHours = Math.max(1, due.diff(scheduledAt, "hours"));
1924
+ const hoursOverdue = now.diff(due, "hours");
1925
+ const relativeOverdue = hoursOverdue / intervalHours;
1926
+ const recencyFactor = 0.3 + 0.7 * Math.exp(-intervalHours / 720);
1927
+ const overdueContribution = Math.min(1, Math.max(0, relativeOverdue));
1928
+ const urgency = overdueContribution * 0.5 + recencyFactor * 0.5;
1929
+ const score = Math.min(0.95, 0.5 + urgency * 0.45);
1930
+ const reason = `${Math.round(hoursOverdue)}h overdue (interval: ${Math.round(intervalHours)}h, relative: ${relativeOverdue.toFixed(2)}), recency: ${recencyFactor.toFixed(2)}, review`;
1931
+ return { score, reason };
1932
+ }
1933
+ /**
1934
+ * Get pending reviews in legacy format.
1935
+ *
1936
+ * Returns all pending reviews for the course, enriched with session item fields.
1937
+ */
1938
+ async getPendingReviews() {
1939
+ if (!this.user || !this.course) {
1940
+ throw new Error("SRSNavigator requires user and course to be set");
1941
+ }
1942
+ const reviews = await this.user.getPendingReviews(this.course.getCourseID());
1943
+ return reviews.map((r) => ({
1944
+ ...r,
1945
+ contentSourceType: "course",
1946
+ contentSourceID: this.course.getCourseID(),
1947
+ cardID: r.cardId,
1948
+ courseID: r.courseId,
1949
+ qualifiedID: `${r.courseId}-${r.cardId}`,
1950
+ reviewID: r._id,
1951
+ status: "review"
1952
+ }));
1953
+ }
1954
+ /**
1955
+ * SRS does not generate new cards.
1956
+ * Use ELONavigator or another generator for new cards.
1957
+ */
1958
+ async getNewCards(_n) {
1959
+ return [];
624
1960
  }
625
1961
  };
626
1962
  }
@@ -631,9 +1967,21 @@ var globImport;
631
1967
  var init_ = __esm({
632
1968
  'import("./**/*") in src/core/navigators/index.ts'() {
633
1969
  globImport = __glob({
1970
+ "./CompositeGenerator.ts": () => Promise.resolve().then(() => (init_CompositeGenerator(), CompositeGenerator_exports)),
1971
+ "./Pipeline.ts": () => Promise.resolve().then(() => (init_Pipeline(), Pipeline_exports)),
1972
+ "./PipelineAssembler.ts": () => Promise.resolve().then(() => (init_PipelineAssembler(), PipelineAssembler_exports)),
634
1973
  "./elo.ts": () => Promise.resolve().then(() => (init_elo(), elo_exports)),
1974
+ "./filters/eloDistance.ts": () => Promise.resolve().then(() => (init_eloDistance(), eloDistance_exports)),
1975
+ "./filters/index.ts": () => Promise.resolve().then(() => (init_filters(), filters_exports)),
1976
+ "./filters/types.ts": () => Promise.resolve().then(() => (init_types(), types_exports)),
1977
+ "./generators/index.ts": () => Promise.resolve().then(() => (init_generators(), generators_exports)),
1978
+ "./generators/types.ts": () => Promise.resolve().then(() => (init_types2(), types_exports2)),
635
1979
  "./hardcodedOrder.ts": () => Promise.resolve().then(() => (init_hardcodedOrder(), hardcodedOrder_exports)),
636
- "./index.ts": () => Promise.resolve().then(() => (init_navigators(), navigators_exports))
1980
+ "./hierarchyDefinition.ts": () => Promise.resolve().then(() => (init_hierarchyDefinition(), hierarchyDefinition_exports)),
1981
+ "./index.ts": () => Promise.resolve().then(() => (init_navigators(), navigators_exports)),
1982
+ "./interferenceMitigator.ts": () => Promise.resolve().then(() => (init_interferenceMitigator(), interferenceMitigator_exports)),
1983
+ "./relativePriority.ts": () => Promise.resolve().then(() => (init_relativePriority(), relativePriority_exports)),
1984
+ "./srs.ts": () => Promise.resolve().then(() => (init_srs(), srs_exports))
637
1985
  });
638
1986
  }
639
1987
  });
@@ -642,9 +1990,34 @@ var init_ = __esm({
642
1990
  var navigators_exports = {};
643
1991
  __export(navigators_exports, {
644
1992
  ContentNavigator: () => ContentNavigator,
645
- Navigators: () => Navigators
1993
+ NavigatorRole: () => NavigatorRole,
1994
+ NavigatorRoles: () => NavigatorRoles,
1995
+ Navigators: () => Navigators,
1996
+ getCardOrigin: () => getCardOrigin,
1997
+ isFilter: () => isFilter,
1998
+ isGenerator: () => isGenerator
646
1999
  });
647
- var Navigators, ContentNavigator;
2000
+ function getCardOrigin(card) {
2001
+ if (card.provenance.length === 0) {
2002
+ throw new Error("Card has no provenance - cannot determine origin");
2003
+ }
2004
+ const firstEntry = card.provenance[0];
2005
+ const reason = firstEntry.reason.toLowerCase();
2006
+ if (reason.includes("failed")) {
2007
+ return "failed";
2008
+ }
2009
+ if (reason.includes("review")) {
2010
+ return "review";
2011
+ }
2012
+ return "new";
2013
+ }
2014
+ function isGenerator(impl) {
2015
+ return NavigatorRoles[impl] === "generator" /* GENERATOR */;
2016
+ }
2017
+ function isFilter(impl) {
2018
+ return NavigatorRoles[impl] === "filter" /* FILTER */;
2019
+ }
2020
+ var Navigators, NavigatorRole, NavigatorRoles, ContentNavigator;
648
2021
  var init_navigators = __esm({
649
2022
  "src/core/navigators/index.ts"() {
650
2023
  "use strict";
@@ -652,14 +2025,55 @@ var init_navigators = __esm({
652
2025
  init_();
653
2026
  Navigators = /* @__PURE__ */ ((Navigators2) => {
654
2027
  Navigators2["ELO"] = "elo";
2028
+ Navigators2["SRS"] = "srs";
655
2029
  Navigators2["HARDCODED"] = "hardcodedOrder";
2030
+ Navigators2["HIERARCHY"] = "hierarchyDefinition";
2031
+ Navigators2["INTERFERENCE"] = "interferenceMitigator";
2032
+ Navigators2["RELATIVE_PRIORITY"] = "relativePriority";
656
2033
  return Navigators2;
657
2034
  })(Navigators || {});
2035
+ NavigatorRole = /* @__PURE__ */ ((NavigatorRole2) => {
2036
+ NavigatorRole2["GENERATOR"] = "generator";
2037
+ NavigatorRole2["FILTER"] = "filter";
2038
+ return NavigatorRole2;
2039
+ })(NavigatorRole || {});
2040
+ NavigatorRoles = {
2041
+ ["elo" /* ELO */]: "generator" /* GENERATOR */,
2042
+ ["srs" /* SRS */]: "generator" /* GENERATOR */,
2043
+ ["hardcodedOrder" /* HARDCODED */]: "generator" /* GENERATOR */,
2044
+ ["hierarchyDefinition" /* HIERARCHY */]: "filter" /* FILTER */,
2045
+ ["interferenceMitigator" /* INTERFERENCE */]: "filter" /* FILTER */,
2046
+ ["relativePriority" /* RELATIVE_PRIORITY */]: "filter" /* FILTER */
2047
+ };
658
2048
  ContentNavigator = class {
2049
+ /** User interface for this navigation session */
2050
+ user;
2051
+ /** Course interface for this navigation session */
2052
+ course;
2053
+ /** Human-readable name for this strategy instance (from ContentNavigationStrategyData.name) */
2054
+ strategyName;
2055
+ /** Unique document ID for this strategy instance (from ContentNavigationStrategyData._id) */
2056
+ strategyId;
659
2057
  /**
2058
+ * Constructor for standard navigators.
2059
+ * Call this from subclass constructors to initialize common fields.
660
2060
  *
661
- * @param user
662
- * @param strategyData
2061
+ * Note: CompositeGenerator doesn't use this pattern and should call super() without args.
2062
+ */
2063
+ constructor(user, course, strategyData) {
2064
+ if (user && course && strategyData) {
2065
+ this.user = user;
2066
+ this.course = course;
2067
+ this.strategyName = strategyData.name;
2068
+ this.strategyId = strategyData._id;
2069
+ }
2070
+ }
2071
+ /**
2072
+ * Factory method to create navigator instances dynamically.
2073
+ *
2074
+ * @param user - User interface
2075
+ * @param course - Course interface
2076
+ * @param strategyData - Strategy configuration document
663
2077
  * @returns the runtime object used to steer a study session.
664
2078
  */
665
2079
  static async create(user, course, strategyData) {
@@ -680,16 +2094,80 @@ var init_navigators = __esm({
680
2094
  }
681
2095
  return new NavigatorImpl(user, course, strategyData);
682
2096
  }
2097
+ /**
2098
+ * Get cards with suitability scores and provenance trails.
2099
+ *
2100
+ * **This is the PRIMARY API for navigation strategies.**
2101
+ *
2102
+ * Returns cards ranked by suitability score (0-1). Higher scores indicate
2103
+ * better candidates for presentation. Each card includes a provenance trail
2104
+ * documenting how strategies contributed to the final score.
2105
+ *
2106
+ * ## For Generators
2107
+ * Override this method to generate candidates and compute scores based on
2108
+ * your strategy's logic (e.g., ELO proximity, review urgency). Create the
2109
+ * initial provenance entry with action='generated'.
2110
+ *
2111
+ * ## Default Implementation
2112
+ * The base class provides a backward-compatible default that:
2113
+ * 1. Calls legacy getNewCards() and getPendingReviews()
2114
+ * 2. Assigns score=1.0 to all cards
2115
+ * 3. Creates minimal provenance from legacy methods
2116
+ * 4. Returns combined results up to limit
2117
+ *
2118
+ * This allows existing strategies to work without modification while
2119
+ * new strategies can override with proper scoring and provenance.
2120
+ *
2121
+ * @param limit - Maximum cards to return
2122
+ * @returns Cards sorted by score descending, with provenance trails
2123
+ */
2124
+ async getWeightedCards(limit) {
2125
+ const newCards = await this.getNewCards(limit);
2126
+ const reviews = await this.getPendingReviews();
2127
+ const weighted = [
2128
+ ...newCards.map((c) => ({
2129
+ cardId: c.cardID,
2130
+ courseId: c.courseID,
2131
+ score: 1,
2132
+ provenance: [
2133
+ {
2134
+ strategy: "legacy",
2135
+ strategyName: this.strategyName || "Legacy API",
2136
+ strategyId: this.strategyId || "legacy-fallback",
2137
+ action: "generated",
2138
+ score: 1,
2139
+ reason: "Generated via legacy getNewCards(), new card"
2140
+ }
2141
+ ]
2142
+ })),
2143
+ ...reviews.map((r) => ({
2144
+ cardId: r.cardID,
2145
+ courseId: r.courseID,
2146
+ score: 1,
2147
+ provenance: [
2148
+ {
2149
+ strategy: "legacy",
2150
+ strategyName: this.strategyName || "Legacy API",
2151
+ strategyId: this.strategyId || "legacy-fallback",
2152
+ action: "generated",
2153
+ score: 1,
2154
+ reason: "Generated via legacy getPendingReviews(), review"
2155
+ }
2156
+ ]
2157
+ }))
2158
+ ];
2159
+ return weighted.slice(0, limit);
2160
+ }
683
2161
  };
684
2162
  }
685
2163
  });
686
2164
 
687
2165
  // src/impl/couch/courseDB.ts
688
- var import_common5;
2166
+ var import_common9;
689
2167
  var init_courseDB = __esm({
690
2168
  "src/impl/couch/courseDB.ts"() {
691
2169
  "use strict";
692
- import_common5 = require("@vue-skuilder/common");
2170
+ import_common9 = require("@vue-skuilder/common");
693
2171
  init_couch();
694
2172
  init_updateQueue();
695
2173
  init_types_legacy();
@@ -698,17 +2176,23 @@ var init_courseDB = __esm({
698
2176
  init_courseAPI();
699
2177
  init_courseLookupDB();
700
2178
  init_navigators();
2179
+ init_Pipeline();
2180
+ init_PipelineAssembler();
2181
+ init_CompositeGenerator();
2182
+ init_elo();
2183
+ init_srs();
2184
+ init_eloDistance();
701
2185
  }
702
2186
  });
703
2187
 
704
2188
  // src/impl/couch/classroomDB.ts
705
- var import_moment3;
2189
+ var import_moment4;
706
2190
  var init_classroomDB2 = __esm({
707
2191
  "src/impl/couch/classroomDB.ts"() {
708
2192
  "use strict";
709
2193
  init_factory();
710
2194
  init_logger();
711
- import_moment3 = __toESM(require("moment"));
2195
+ import_moment4 = __toESM(require("moment"), 1);
712
2196
  init_pouchdb_setup();
713
2197
  init_couch();
714
2198
  init_courseDB();
@@ -735,19 +2219,19 @@ var init_auth = __esm({
735
2219
  "use strict";
736
2220
  init_factory();
737
2221
  init_logger();
738
- import_cross_fetch = __toESM(require("cross-fetch"));
2222
+ import_cross_fetch = __toESM(require("cross-fetch"), 1);
739
2223
  }
740
2224
  });
741
2225
 
742
2226
  // src/impl/couch/CouchDBSyncStrategy.ts
743
- var import_common6;
2227
+ var import_common10;
744
2228
  var init_CouchDBSyncStrategy = __esm({
745
2229
  "src/impl/couch/CouchDBSyncStrategy.ts"() {
746
2230
  "use strict";
747
2231
  init_factory();
748
2232
  init_types_legacy();
749
2233
  init_logger();
750
- import_common6 = require("@vue-skuilder/common");
2234
+ import_common10 = require("@vue-skuilder/common");
751
2235
  init_common();
752
2236
  init_pouchdb_setup();
753
2237
  init_couch();
@@ -775,17 +2259,17 @@ function createPouchDBConfig() {
775
2259
  }
776
2260
  return pouchDBincludeCredentialsConfig;
777
2261
  }
778
- var import_cross_fetch2, import_moment4, import_process, isBrowser, GUEST_LOCAL_DB, localUserDB, pouchDBincludeCredentialsConfig;
2262
+ var import_cross_fetch2, import_moment5, import_process, isBrowser, GUEST_LOCAL_DB, localUserDB, pouchDBincludeCredentialsConfig;
779
2263
  var init_couch = __esm({
780
2264
  "src/impl/couch/index.ts"() {
781
2265
  "use strict";
782
2266
  init_factory();
783
2267
  init_types_legacy();
784
- import_cross_fetch2 = __toESM(require("cross-fetch"));
785
- import_moment4 = __toESM(require("moment"));
2268
+ import_cross_fetch2 = __toESM(require("cross-fetch"), 1);
2269
+ import_moment5 = __toESM(require("moment"), 1);
786
2270
  init_logger();
787
2271
  init_pouchdb_setup();
788
- import_process = __toESM(require("process"));
2272
+ import_process = __toESM(require("process"), 1);
789
2273
  init_contentSource();
790
2274
  init_adminDB2();
791
2275
  init_classroomDB2();
@@ -979,14 +2463,14 @@ async function dropUserFromClassroom(user, classID) {
979
2463
  async function getUserClassrooms(user) {
980
2464
  return getOrCreateClassroomRegistrationsDoc(user);
981
2465
  }
982
- var import_common8, import_moment5, log3, BaseUser, userCoursesDoc, userClassroomsDoc;
2466
+ var import_common12, import_moment6, log3, BaseUser, userCoursesDoc, userClassroomsDoc;
983
2467
  var init_BaseUserDB = __esm({
984
2468
  "src/impl/common/BaseUserDB.ts"() {
985
2469
  "use strict";
986
2470
  init_core();
987
2471
  init_util();
988
- import_common8 = require("@vue-skuilder/common");
989
- import_moment5 = __toESM(require("moment"));
2472
+ import_common12 = require("@vue-skuilder/common");
2473
+ import_moment6 = __toESM(require("moment"), 1);
990
2474
  init_types_legacy();
991
2475
  init_logger();
992
2476
  init_userDBHelpers();
@@ -1035,7 +2519,7 @@ Currently logged-in as ${this._username}.`
1035
2519
  );
1036
2520
  }
1037
2521
  const result = await this.syncStrategy.createAccount(username, password);
1038
- if (result.status === import_common8.Status.ok) {
2522
+ if (result.status === import_common12.Status.ok) {
1039
2523
  log3(`Account created successfully, updating username to ${username}`);
1040
2524
  this._username = username;
1041
2525
  try {
@@ -1077,7 +2561,7 @@ Currently logged-in as ${this._username}.`
1077
2561
  async resetUserData() {
1078
2562
  if (this.syncStrategy.canAuthenticate()) {
1079
2563
  return {
1080
- status: import_common8.Status.error,
2564
+ status: import_common12.Status.error,
1081
2565
  error: "Reset user data is only available for local-only mode. Use logout instead for remote sync."
1082
2566
  };
1083
2567
  }
@@ -1096,11 +2580,11 @@ Currently logged-in as ${this._username}.`
1096
2580
  await localDB.bulkDocs(docsToDelete);
1097
2581
  }
1098
2582
  await this.init();
1099
- return { status: import_common8.Status.ok };
2583
+ return { status: import_common12.Status.ok };
1100
2584
  } catch (error) {
1101
2585
  logger.error("Failed to reset user data:", error);
1102
2586
  return {
1103
- status: import_common8.Status.error,
2587
+ status: import_common12.Status.error,
1104
2588
  error: error instanceof Error ? error.message : "Unknown error during reset"
1105
2589
  };
1106
2590
  }
@@ -1247,7 +2731,7 @@ Currently logged-in as ${this._username}.`
1247
2731
  );
1248
2732
  return reviews.rows.filter((r) => {
1249
2733
  if (r.id.startsWith(DocTypePrefixes["SCHEDULED_CARD" /* SCHEDULED_CARD */])) {
1250
- const date = import_moment5.default.utc(
2734
+ const date = import_moment6.default.utc(
1251
2735
  r.id.substr(DocTypePrefixes["SCHEDULED_CARD" /* SCHEDULED_CARD */].length),
1252
2736
  REVIEW_TIME_FORMAT
1253
2737
  );
@@ -1260,11 +2744,11 @@ Currently logged-in as ${this._username}.`
1260
2744
  }).map((r) => r.doc);
1261
2745
  }
1262
2746
  async getReviewsForcast(daysCount) {
1263
- const time = import_moment5.default.utc().add(daysCount, "days");
2747
+ const time = import_moment6.default.utc().add(daysCount, "days");
1264
2748
  return this.getReviewstoDate(time);
1265
2749
  }
1266
2750
  async getPendingReviews(course_id) {
1267
- const now = import_moment5.default.utc();
2751
+ const now = import_moment6.default.utc();
1268
2752
  return this.getReviewstoDate(now, course_id);
1269
2753
  }
1270
2754
  async getScheduledReviewCount(course_id) {
@@ -1551,7 +3035,7 @@ Currently logged-in as ${this._username}.`
1551
3035
  */
1552
3036
  async putCardRecord(record) {
1553
3037
  const cardHistoryID = getCardHistoryID(record.courseID, record.cardID);
1554
- record.timeStamp = import_moment5.default.utc(record.timeStamp).toString();
3038
+ record.timeStamp = import_moment6.default.utc(record.timeStamp).toString();
1555
3039
  try {
1556
3040
  const cardHistory = await this.update(
1557
3041
  cardHistoryID,
@@ -1567,7 +3051,7 @@ Currently logged-in as ${this._username}.`
1567
3051
  const ret = {
1568
3052
  ...record2
1569
3053
  };
1570
- ret.timeStamp = import_moment5.default.utc(record2.timeStamp);
3054
+ ret.timeStamp = import_moment6.default.utc(record2.timeStamp);
1571
3055
  return ret;
1572
3056
  });
1573
3057
  return cardHistory;
@@ -1823,12 +3307,26 @@ var init_factory = __esm({
1823
3307
  }
1824
3308
  });
1825
3309
 
3310
+ // src/study/TagFilteredContentSource.ts
3311
+ var import_common14;
3312
+ var init_TagFilteredContentSource = __esm({
3313
+ "src/study/TagFilteredContentSource.ts"() {
3314
+ "use strict";
3315
+ import_common14 = require("@vue-skuilder/common");
3316
+ init_courseDB();
3317
+ init_logger();
3318
+ }
3319
+ });
3320
+
1826
3321
  // src/core/interfaces/contentSource.ts
3322
+ var import_common15;
1827
3323
  var init_contentSource = __esm({
1828
3324
  "src/core/interfaces/contentSource.ts"() {
1829
3325
  "use strict";
1830
3326
  init_factory();
1831
3327
  init_classroomDB2();
3328
+ import_common15 = require("@vue-skuilder/common");
3329
+ init_TagFilteredContentSource();
1832
3330
  }
1833
3331
  });
1834
3332
 
@@ -1874,17 +3372,17 @@ var init_user = __esm({
1874
3372
  });
1875
3373
 
1876
3374
  // src/core/bulkImport/cardProcessor.ts
1877
- var import_common10;
3375
+ var import_common16;
1878
3376
  var init_cardProcessor = __esm({
1879
3377
  "src/core/bulkImport/cardProcessor.ts"() {
1880
3378
  "use strict";
1881
- import_common10 = require("@vue-skuilder/common");
3379
+ import_common16 = require("@vue-skuilder/common");
1882
3380
  init_logger();
1883
3381
  }
1884
3382
  });
1885
3383
 
1886
3384
  // src/core/bulkImport/types.ts
1887
- var init_types = __esm({
3385
+ var init_types3 = __esm({
1888
3386
  "src/core/bulkImport/types.ts"() {
1889
3387
  "use strict";
1890
3388
  }
@@ -1895,7 +3393,7 @@ var init_bulkImport = __esm({
1895
3393
  "src/core/bulkImport/index.ts"() {
1896
3394
  "use strict";
1897
3395
  init_cardProcessor();
1898
- init_types();
3396
+ init_types3();
1899
3397
  }
1900
3398
  });
1901
3399
 
@@ -2293,11 +3791,11 @@ var init_StaticDataUnpacker = __esm({
2293
3791
  });
2294
3792
 
2295
3793
  // src/impl/static/courseDB.ts
2296
- var import_common11, StaticCourseDB;
3794
+ var import_common17, StaticCourseDB;
2297
3795
  var init_courseDB3 = __esm({
2298
3796
  "src/impl/static/courseDB.ts"() {
2299
3797
  "use strict";
2300
- import_common11 = require("@vue-skuilder/common");
3798
+ import_common17 = require("@vue-skuilder/common");
2301
3799
  init_types_legacy();
2302
3800
  init_navigators();
2303
3801
  init_logger();
@@ -2560,7 +4058,7 @@ var init_courseDB3 = __esm({
2560
4058
  }
2561
4059
  async addNote(_codeCourse, _shape, _data, _author, _tags, _uploads, _elo) {
2562
4060
  return {
2563
- status: import_common11.Status.error,
4061
+ status: import_common17.Status.error,
2564
4062
  message: "Cannot add notes in static mode"
2565
4063
  };
2566
4064
  }
@@ -2591,9 +4089,6 @@ var init_courseDB3 = __esm({
2591
4089
  async updateNavigationStrategy(_id, _data) {
2592
4090
  throw new Error("Cannot update navigation strategies in static mode");
2593
4091
  }
2594
- async surfaceNavigationStrategy() {
2595
- return this.getNavigationStrategy("ELO");
2596
- }
2597
4092
  // Study Content Source implementation
2598
4093
  async getPendingReviews() {
2599
4094
  return [];