@vue-skuilder/db 0.2.35 → 0.2.36

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 (258) hide show
  1. package/CLAUDE.md +15 -4
  2. package/build.entries.mjs +12 -0
  3. package/dist/_virtual/_rolldown/runtime.mjs +8 -0
  4. package/dist/{contentSource-BteiDpxH.d.ts → contentSource-D_E7JaxR.d.ts} +1 -1
  5. package/dist/core/UserDBDebugger.mjs +285 -0
  6. package/dist/core/UserDBDebugger.mjs.map +1 -0
  7. package/dist/core/bulkImport/cardProcessor.mjs +106 -0
  8. package/dist/core/bulkImport/cardProcessor.mjs.map +1 -0
  9. package/dist/core/{index.js → index.cjs} +6438 -7784
  10. package/dist/core/index.cjs.map +1 -0
  11. package/dist/core/index.d.ts +5 -5
  12. package/dist/core/index.mjs +20 -11368
  13. package/dist/core/interfaces/contentSource.mjs +20 -0
  14. package/dist/core/interfaces/contentSource.mjs.map +1 -0
  15. package/dist/core/navigators/Pipeline.mjs +723 -0
  16. package/dist/core/navigators/Pipeline.mjs.map +1 -0
  17. package/dist/core/navigators/PipelineAssembler.mjs +86 -0
  18. package/dist/core/navigators/PipelineAssembler.mjs.map +1 -0
  19. package/dist/core/navigators/PipelineDebugger.mjs +771 -0
  20. package/dist/core/navigators/PipelineDebugger.mjs.map +1 -0
  21. package/dist/core/navigators/SrsDebugger.mjs +34 -0
  22. package/dist/core/navigators/SrsDebugger.mjs.map +1 -0
  23. package/dist/core/navigators/StrategyPressureDebugger.mjs +19 -0
  24. package/dist/core/navigators/StrategyPressureDebugger.mjs.map +1 -0
  25. package/dist/core/navigators/defaults.mjs +96 -0
  26. package/dist/core/navigators/defaults.mjs.map +1 -0
  27. package/dist/core/navigators/diversityRerank.mjs +85 -0
  28. package/dist/core/navigators/diversityRerank.mjs.map +1 -0
  29. package/dist/core/navigators/filters/WeightedFilter.mjs +81 -0
  30. package/dist/core/navigators/filters/WeightedFilter.mjs.map +1 -0
  31. package/dist/core/navigators/filters/eloDistance.mjs +244 -0
  32. package/dist/core/navigators/filters/eloDistance.mjs.map +1 -0
  33. package/dist/core/navigators/filters/hierarchyDefinition.mjs +235 -0
  34. package/dist/core/navigators/filters/hierarchyDefinition.mjs.map +1 -0
  35. package/dist/core/navigators/filters/interferenceMitigator.mjs +201 -0
  36. package/dist/core/navigators/filters/interferenceMitigator.mjs.map +1 -0
  37. package/dist/core/navigators/filters/relativePriority.mjs +135 -0
  38. package/dist/core/navigators/filters/relativePriority.mjs.map +1 -0
  39. package/dist/core/navigators/filters/userTagPreference.mjs +101 -0
  40. package/dist/core/navigators/filters/userTagPreference.mjs.map +1 -0
  41. package/dist/core/navigators/generators/CompositeGenerator.mjs +203 -0
  42. package/dist/core/navigators/generators/CompositeGenerator.mjs.map +1 -0
  43. package/dist/core/navigators/generators/elo.mjs +77 -0
  44. package/dist/core/navigators/generators/elo.mjs.map +1 -0
  45. package/dist/core/navigators/generators/prescribed.mjs +676 -0
  46. package/dist/core/navigators/generators/prescribed.mjs.map +1 -0
  47. package/dist/core/navigators/generators/srs.mjs +158 -0
  48. package/dist/core/navigators/generators/srs.mjs.map +1 -0
  49. package/dist/core/navigators/index.mjs +345 -0
  50. package/dist/core/navigators/index.mjs.map +1 -0
  51. package/dist/core/navigators/pipelinePlan.mjs +109 -0
  52. package/dist/core/navigators/pipelinePlan.mjs.map +1 -0
  53. package/dist/core/navigators/regulators.mjs +128 -0
  54. package/dist/core/navigators/regulators.mjs.map +1 -0
  55. package/dist/core/orchestration/gradient.mjs +101 -0
  56. package/dist/core/orchestration/gradient.mjs.map +1 -0
  57. package/dist/core/orchestration/index.mjs +115 -0
  58. package/dist/core/orchestration/index.mjs.map +1 -0
  59. package/dist/core/orchestration/learning.mjs +140 -0
  60. package/dist/core/orchestration/learning.mjs.map +1 -0
  61. package/dist/core/orchestration/recording.mjs +64 -0
  62. package/dist/core/orchestration/recording.mjs.map +1 -0
  63. package/dist/core/orchestration/signal.mjs +40 -0
  64. package/dist/core/orchestration/signal.mjs.map +1 -0
  65. package/dist/core/types/contentNavigationStrategy.mjs +10 -0
  66. package/dist/core/types/contentNavigationStrategy.mjs.map +1 -0
  67. package/dist/core/types/hydration.mjs +13 -0
  68. package/dist/core/types/hydration.mjs.map +1 -0
  69. package/dist/core/types/strategyState.mjs +16 -0
  70. package/dist/core/types/strategyState.mjs.map +1 -0
  71. package/dist/core/types/studySession.mjs +14 -0
  72. package/dist/core/types/studySession.mjs.map +1 -0
  73. package/dist/core/types/types-legacy.mjs +44 -0
  74. package/dist/core/types/types-legacy.mjs.map +1 -0
  75. package/dist/core/util/index.mjs +31 -0
  76. package/dist/core/util/index.mjs.map +1 -0
  77. package/dist/core/versionStamps.mjs +46 -0
  78. package/dist/core/versionStamps.mjs.map +1 -0
  79. package/dist/courseConfigRegistration.mjs +306 -0
  80. package/dist/courseConfigRegistration.mjs.map +1 -0
  81. package/dist/{dataLayerProvider-C_QWzHf-.d.ts → dataLayerProvider-BDshhSp_.d.ts} +1 -1
  82. package/dist/diagnostics/dataset.mjs +118 -0
  83. package/dist/diagnostics/dataset.mjs.map +1 -0
  84. package/dist/diagnostics/derive.mjs +318 -0
  85. package/dist/diagnostics/derive.mjs.map +1 -0
  86. package/dist/diagnostics/{index.js → index.cjs} +1 -1
  87. package/dist/diagnostics/index.d.ts +3 -3
  88. package/dist/diagnostics/index.mjs +7 -1042
  89. package/dist/diagnostics/loader.mjs +151 -0
  90. package/dist/diagnostics/loader.mjs.map +1 -0
  91. package/dist/diagnostics/pipeline.mjs +161 -0
  92. package/dist/diagnostics/pipeline.mjs.map +1 -0
  93. package/dist/diagnostics/tagElo.mjs +177 -0
  94. package/dist/diagnostics/tagElo.mjs.map +1 -0
  95. package/dist/diagnostics/text.mjs +174 -0
  96. package/dist/diagnostics/text.mjs.map +1 -0
  97. package/dist/factory.mjs +70 -0
  98. package/dist/factory.mjs.map +1 -0
  99. package/dist/impl/common/BaseUserDB.mjs +1103 -0
  100. package/dist/impl/common/BaseUserDB.mjs.map +1 -0
  101. package/dist/impl/common/userDBHelpers.mjs +49 -0
  102. package/dist/impl/common/userDBHelpers.mjs.map +1 -0
  103. package/dist/impl/common/userDBKeys.mjs +45 -0
  104. package/dist/impl/common/userDBKeys.mjs.map +1 -0
  105. package/dist/impl/couch/CouchDBSyncStrategy.mjs +272 -0
  106. package/dist/impl/couch/CouchDBSyncStrategy.mjs.map +1 -0
  107. package/dist/impl/couch/CourseSyncService.mjs +242 -0
  108. package/dist/impl/couch/CourseSyncService.mjs.map +1 -0
  109. package/dist/impl/couch/PouchDataLayerProvider.mjs +74 -0
  110. package/dist/impl/couch/PouchDataLayerProvider.mjs.map +1 -0
  111. package/dist/impl/couch/adminDB.mjs +61 -0
  112. package/dist/impl/couch/adminDB.mjs.map +1 -0
  113. package/dist/impl/couch/auth.mjs +33 -0
  114. package/dist/impl/couch/auth.mjs.map +1 -0
  115. package/dist/impl/couch/classroomDB.mjs +227 -0
  116. package/dist/impl/couch/classroomDB.mjs.map +1 -0
  117. package/dist/impl/couch/clientCache.mjs +15 -0
  118. package/dist/impl/couch/clientCache.mjs.map +1 -0
  119. package/dist/impl/couch/courseAPI.mjs +183 -0
  120. package/dist/impl/couch/courseAPI.mjs.map +1 -0
  121. package/dist/impl/couch/courseDB.mjs +729 -0
  122. package/dist/impl/couch/courseDB.mjs.map +1 -0
  123. package/dist/impl/couch/courseLookupDB.mjs +94 -0
  124. package/dist/impl/couch/courseLookupDB.mjs.map +1 -0
  125. package/dist/impl/couch/{index.js → index.cjs} +6911 -10367
  126. package/dist/impl/couch/index.cjs.map +1 -0
  127. package/dist/impl/couch/index.d.ts +12 -5
  128. package/dist/impl/couch/index.mjs +134 -12146
  129. package/dist/impl/couch/index.mjs.map +1 -1
  130. package/dist/impl/couch/pouchdb-setup.mjs +15 -0
  131. package/dist/impl/couch/pouchdb-setup.mjs.map +1 -0
  132. package/dist/impl/couch/updateQueue.mjs +101 -0
  133. package/dist/impl/couch/updateQueue.mjs.map +1 -0
  134. package/dist/impl/couch/user-course-relDB.mjs +55 -0
  135. package/dist/impl/couch/user-course-relDB.mjs.map +1 -0
  136. package/dist/impl/static/NoOpSyncStrategy.mjs +49 -0
  137. package/dist/impl/static/NoOpSyncStrategy.mjs.map +1 -0
  138. package/dist/impl/static/StaticDataLayerProvider.mjs +94 -0
  139. package/dist/impl/static/StaticDataLayerProvider.mjs.map +1 -0
  140. package/dist/impl/static/StaticDataUnpacker.mjs +311 -0
  141. package/dist/impl/static/StaticDataUnpacker.mjs.map +1 -0
  142. package/dist/impl/static/courseDB.mjs +368 -0
  143. package/dist/impl/static/courseDB.mjs.map +1 -0
  144. package/dist/impl/static/coursesDB.mjs +38 -0
  145. package/dist/impl/static/coursesDB.mjs.map +1 -0
  146. package/dist/impl/static/{index.js → index.cjs} +2461 -5992
  147. package/dist/impl/static/index.cjs.map +1 -0
  148. package/dist/impl/static/index.d.ts +4 -4
  149. package/dist/impl/static/index.mjs +6 -10741
  150. package/dist/{index-C745YB_6.d.ts → index-BLDpFYG3.d.ts} +1 -1
  151. package/dist/{index.js → index.cjs} +14070 -14239
  152. package/dist/index.cjs.map +1 -0
  153. package/dist/index.d.ts +12 -23
  154. package/dist/index.mjs +38 -16937
  155. package/dist/pouch/{index.js → index.cjs} +5 -1
  156. package/dist/pouch/index.cjs.map +1 -0
  157. package/dist/pouch/index.mjs +2 -19
  158. package/dist/study/ItemQueue.mjs +95 -0
  159. package/dist/study/ItemQueue.mjs.map +1 -0
  160. package/dist/study/MixerDebugger.mjs +303 -0
  161. package/dist/study/MixerDebugger.mjs.map +1 -0
  162. package/dist/study/SessionController.mjs +1187 -0
  163. package/dist/study/SessionController.mjs.map +1 -0
  164. package/dist/study/SessionDebugger.mjs +271 -0
  165. package/dist/study/SessionDebugger.mjs.map +1 -0
  166. package/dist/study/SessionOverlay.mjs +407 -0
  167. package/dist/study/SessionOverlay.mjs.map +1 -0
  168. package/dist/study/SourceMixer.mjs +45 -0
  169. package/dist/study/SourceMixer.mjs.map +1 -0
  170. package/dist/study/SpacedRepetition.mjs +108 -0
  171. package/dist/study/SpacedRepetition.mjs.map +1 -0
  172. package/dist/study/TagFilteredContentSource.mjs +136 -0
  173. package/dist/study/TagFilteredContentSource.mjs.map +1 -0
  174. package/dist/study/services/CardHydrationService.mjs +172 -0
  175. package/dist/study/services/CardHydrationService.mjs.map +1 -0
  176. package/dist/study/services/EloService.mjs +217 -0
  177. package/dist/study/services/EloService.mjs.map +1 -0
  178. package/dist/study/services/ResponseProcessor.mjs +190 -0
  179. package/dist/study/services/ResponseProcessor.mjs.map +1 -0
  180. package/dist/study/services/SrsService.mjs +49 -0
  181. package/dist/study/services/SrsService.mjs.map +1 -0
  182. package/dist/study/services/tagRecent.mjs +65 -0
  183. package/dist/study/services/tagRecent.mjs.map +1 -0
  184. package/dist/{types-DF0JuPbs.d.ts → types-DChCz22D.d.ts} +1 -1
  185. package/dist/{types-legacy-DdVjg81H.d.cts → types-legacy-fT5Y1Wuy.d.ts} +1 -1
  186. package/dist/userDBKeys-ne1g4Xuq.d.ts +16 -0
  187. package/dist/util/Loggable.mjs +14 -0
  188. package/dist/util/Loggable.mjs.map +1 -0
  189. package/dist/util/dataDirectory.mjs +47 -0
  190. package/dist/util/dataDirectory.mjs.map +1 -0
  191. package/dist/util/logger.mjs +86 -0
  192. package/dist/util/logger.mjs.map +1 -0
  193. package/dist/util/migrator/FileSystemAdapter.mjs +18 -0
  194. package/dist/util/migrator/FileSystemAdapter.mjs.map +1 -0
  195. package/dist/util/migrator/StaticToCouchDBMigrator.mjs +428 -0
  196. package/dist/util/migrator/StaticToCouchDBMigrator.mjs.map +1 -0
  197. package/dist/util/migrator/types.mjs +11 -0
  198. package/dist/util/migrator/types.mjs.map +1 -0
  199. package/dist/util/migrator/validation.mjs +334 -0
  200. package/dist/util/migrator/validation.mjs.map +1 -0
  201. package/dist/util/packer/CouchDBToStaticPacker.mjs +438 -0
  202. package/dist/util/packer/CouchDBToStaticPacker.mjs.map +1 -0
  203. package/dist/util/packer/{index.js → index.cjs} +73 -9
  204. package/dist/util/packer/index.cjs.map +1 -0
  205. package/dist/util/packer/index.d.ts +3 -3
  206. package/dist/util/packer/index.mjs +2 -537
  207. package/eslint.config.mjs +9 -1
  208. package/package.json +25 -13
  209. package/rolldown.config.mjs +44 -0
  210. package/src/core/UserDBDebugger.ts +47 -46
  211. package/src/core/navigators/Pipeline.ts +10 -10
  212. package/src/core/navigators/PipelineDebugger.ts +55 -55
  213. package/src/core/navigators/filters/eloDistance.ts +1 -1
  214. package/src/core/navigators/generators/elo.ts +5 -1
  215. package/src/core/navigators/index.ts +9 -3
  216. package/src/factory.ts +10 -1
  217. package/src/impl/common/BaseUserDB.ts +1 -3
  218. package/src/impl/common/index.ts +2 -0
  219. package/src/impl/common/userDBHelpers.ts +4 -58
  220. package/src/impl/common/userDBKeys.ts +64 -0
  221. package/src/impl/couch/courseDB.ts +15 -3
  222. package/src/impl/couch/index.ts +2 -18
  223. package/src/impl/couch/pouchdb-setup.ts +8 -0
  224. package/src/index.ts +1 -1
  225. package/src/study/MixerDebugger.ts +46 -46
  226. package/src/study/SessionDebugger.ts +20 -20
  227. package/src/study/SessionOverlay.ts +4 -4
  228. package/src/util/logger.ts +112 -13
  229. package/tests/core/navigators/eloGenerator.test.ts +36 -0
  230. package/tsup.config.ts +24 -21
  231. package/dist/SyncStrategy-BXliog1m.d.cts +0 -116
  232. package/dist/classroomDB-DLTtLZct.d.cts +0 -86
  233. package/dist/contentSource-FQZcZopC.d.cts +0 -2007
  234. package/dist/core/index.d.cts +0 -521
  235. package/dist/core/index.js.map +0 -1
  236. package/dist/core/index.mjs.map +0 -1
  237. package/dist/dataLayerProvider-3y21KtF-.d.cts +0 -61
  238. package/dist/diagnostics/index.d.cts +0 -561
  239. package/dist/diagnostics/index.mjs.map +0 -1
  240. package/dist/impl/couch/index.d.cts +0 -620
  241. package/dist/impl/couch/index.js.map +0 -1
  242. package/dist/impl/static/index.d.cts +0 -232
  243. package/dist/impl/static/index.js.map +0 -1
  244. package/dist/impl/static/index.mjs.map +0 -1
  245. package/dist/index-BIum9Ue2.d.cts +0 -137
  246. package/dist/index.d.cts +0 -1663
  247. package/dist/index.js.map +0 -1
  248. package/dist/index.mjs.map +0 -1
  249. package/dist/pouch/index.d.cts +0 -1
  250. package/dist/pouch/index.js.map +0 -1
  251. package/dist/pouch/index.mjs.map +0 -1
  252. package/dist/types-BcWVH4ww.d.cts +0 -58
  253. package/dist/types-legacy-DdVjg81H.d.ts +0 -168
  254. package/dist/util/packer/index.d.cts +0 -5
  255. package/dist/util/packer/index.js.map +0 -1
  256. package/dist/util/packer/index.mjs.map +0 -1
  257. package/src/study/getCardDataShape.ts +0 -34
  258. /package/dist/diagnostics/{index.js.map → index.cjs.map} +0 -0
@@ -0,0 +1,203 @@
1
+ import "../../../_virtual/_rolldown/runtime.mjs";
2
+ import { logger } from "../../../util/logger.mjs";
3
+ import { ContentNavigator } from "../index.mjs";
4
+ //#region src/core/navigators/generators/CompositeGenerator.ts
5
+ /**
6
+ * Aggregation modes for combining scores from multiple generators.
7
+ */
8
+ let AggregationMode = /* @__PURE__ */ function(AggregationMode) {
9
+ /** Use the maximum score from any generator */
10
+ AggregationMode["MAX"] = "max";
11
+ /** Average all scores */
12
+ AggregationMode["AVERAGE"] = "average";
13
+ /** Average with frequency boost: avg * (1 + 0.1 * (n-1)) */
14
+ AggregationMode["FREQUENCY_BOOST"] = "frequencyBoost";
15
+ return AggregationMode;
16
+ }({});
17
+ const DEFAULT_AGGREGATION_MODE = AggregationMode.FREQUENCY_BOOST;
18
+ const FREQUENCY_BOOST_FACTOR = .1;
19
+ function mergeHints(allHints) {
20
+ const defined = allHints.filter((h) => h !== void 0);
21
+ if (defined.length === 0) return void 0;
22
+ const merged = {};
23
+ const boostTags = {};
24
+ for (const hints of defined) for (const [pattern, factor] of Object.entries(hints.boostTags ?? {})) boostTags[pattern] = (boostTags[pattern] ?? 1) * factor;
25
+ if (Object.keys(boostTags).length > 0) merged.boostTags = boostTags;
26
+ const boostCards = {};
27
+ for (const hints of defined) for (const [pattern, factor] of Object.entries(hints.boostCards ?? {})) boostCards[pattern] = (boostCards[pattern] ?? 1) * factor;
28
+ if (Object.keys(boostCards).length > 0) merged.boostCards = boostCards;
29
+ const concatUnique = (field) => {
30
+ const values = defined.flatMap((h) => h[field] ?? []);
31
+ if (values.length > 0) merged[field] = [...new Set(values)];
32
+ };
33
+ concatUnique("requireTags");
34
+ concatUnique("requireCards");
35
+ concatUnique("excludeTags");
36
+ concatUnique("excludeCards");
37
+ const labels = defined.map((h) => h._label).filter(Boolean);
38
+ if (labels.length > 0) merged._label = labels.join("; ");
39
+ return Object.keys(merged).length > 0 ? merged : void 0;
40
+ }
41
+ /**
42
+ * Composes multiple generators into a single generator.
43
+ *
44
+ * Implements CardGenerator for use in Pipeline architecture.
45
+ * Also extends ContentNavigator for backward compatibility.
46
+ *
47
+ * Fetches candidates from all generators, deduplicates by cardId,
48
+ * and aggregates scores based on the configured mode.
49
+ */
50
+ var CompositeGenerator = class CompositeGenerator extends ContentNavigator {
51
+ /** Human-readable name for CardGenerator interface */
52
+ name = "Composite Generator";
53
+ generators;
54
+ aggregationMode;
55
+ constructor(generators, aggregationMode = DEFAULT_AGGREGATION_MODE) {
56
+ super();
57
+ this.generators = generators;
58
+ this.aggregationMode = aggregationMode;
59
+ if (generators.length === 0) throw new Error("CompositeGenerator requires at least one generator");
60
+ logger.debug(`[CompositeGenerator] Created with ${generators.length} generators, mode: ${aggregationMode}`);
61
+ }
62
+ /**
63
+ * Creates a CompositeGenerator from strategy data.
64
+ *
65
+ * This is a convenience factory for use by PipelineAssembler.
66
+ */
67
+ static async fromStrategies(user, course, strategies, aggregationMode = DEFAULT_AGGREGATION_MODE) {
68
+ return new CompositeGenerator(await Promise.all(strategies.map((s) => ContentNavigator.create(user, course, s))), aggregationMode);
69
+ }
70
+ /**
71
+ * Get weighted cards from all generators, merge and deduplicate.
72
+ *
73
+ * Cards appearing in multiple generators receive a score boost.
74
+ * Provenance tracks which generators produced each card and how scores were aggregated.
75
+ *
76
+ * This method supports both the legacy signature (limit only) and the
77
+ * CardGenerator interface signature (limit, context).
78
+ *
79
+ * @param limit - Maximum number of cards to return
80
+ * @param context - GeneratorContext passed to child generators (required when called via Pipeline)
81
+ */
82
+ async getWeightedCards(limit, context) {
83
+ if (!context) throw new Error("CompositeGenerator.getWeightedCards requires a GeneratorContext. It should be called via Pipeline, not directly.");
84
+ const results = await Promise.all(this.generators.map((g) => g.getWeightedCards(limit, context)));
85
+ const generatorSummaries = [];
86
+ results.forEach((result, index) => {
87
+ const cards = result.cards;
88
+ const genName = this.generators[index].name || `Generator ${index}`;
89
+ const newCards = cards.filter((c) => c.provenance[0]?.reason?.includes("new card"));
90
+ const reviewCards = cards.filter((c) => c.provenance[0]?.reason?.includes("review"));
91
+ if (cards.length > 0) {
92
+ const topScore = Math.max(...cards.map((c) => c.score)).toFixed(2);
93
+ const parts = [];
94
+ if (newCards.length > 0) parts.push(`${newCards.length} new`);
95
+ if (reviewCards.length > 0) parts.push(`${reviewCards.length} reviews`);
96
+ const breakdown = parts.length > 0 ? parts.join(", ") : `${cards.length} cards`;
97
+ generatorSummaries.push(`${genName}: ${breakdown} (top: ${topScore})`);
98
+ } else generatorSummaries.push(`${genName}: 0 cards`);
99
+ });
100
+ logger.info(`[Composite] Generator breakdown: ${generatorSummaries.join(" | ")}`);
101
+ const byCardId = /* @__PURE__ */ new Map();
102
+ results.forEach((result, index) => {
103
+ const cards = result.cards;
104
+ const gen = this.generators[index];
105
+ let weight = gen.learnable?.weight ?? 1;
106
+ let deviation;
107
+ if (gen.learnable && !gen.staticWeight && context.orchestration) {
108
+ const strategyId = gen.strategyId;
109
+ if (strategyId) {
110
+ weight = context.orchestration.getEffectiveWeight(strategyId, gen.learnable);
111
+ deviation = context.orchestration.getDeviation(strategyId);
112
+ }
113
+ }
114
+ for (const card of cards) {
115
+ if (card.provenance.length > 0) {
116
+ card.provenance[0].effectiveWeight = weight;
117
+ card.provenance[0].deviation = deviation;
118
+ }
119
+ const existing = byCardId.get(card.cardId) || [];
120
+ existing.push({
121
+ card,
122
+ weight
123
+ });
124
+ byCardId.set(card.cardId, existing);
125
+ }
126
+ });
127
+ const merged = [];
128
+ for (const [, items] of byCardId) {
129
+ const cards = items.map((i) => i.card);
130
+ const aggregatedScore = this.aggregateScores(items);
131
+ const finalScore = Math.max(0, aggregatedScore);
132
+ const mergedProvenance = cards.flatMap((c) => c.provenance);
133
+ const initialScore = cards[0].score;
134
+ const action = finalScore > initialScore ? "boosted" : finalScore < initialScore ? "penalized" : "passed";
135
+ const reason = this.buildAggregationReason(items, finalScore);
136
+ merged.push({
137
+ ...cards[0],
138
+ score: finalScore,
139
+ provenance: [...mergedProvenance, {
140
+ strategy: "composite",
141
+ strategyName: "Composite Generator",
142
+ strategyId: "COMPOSITE_GENERATOR",
143
+ action,
144
+ score: finalScore,
145
+ reason
146
+ }]
147
+ });
148
+ }
149
+ return {
150
+ cards: merged.sort((a, b) => b.score - a.score).slice(0, limit),
151
+ hints: mergeHints(results.map((result) => result.hints))
152
+ };
153
+ }
154
+ /**
155
+ * Build human-readable reason for score aggregation.
156
+ */
157
+ buildAggregationReason(items, finalScore) {
158
+ const cards = items.map((i) => i.card);
159
+ const count = cards.length;
160
+ const scores = cards.map((c) => c.score.toFixed(2)).join(", ");
161
+ if (count === 1) {
162
+ const weightMsg = Math.abs(items[0].weight - 1) > .001 ? ` (w=${items[0].weight.toFixed(2)})` : "";
163
+ return `Single generator, score ${finalScore.toFixed(2)}${weightMsg}`;
164
+ }
165
+ const strategies = cards.map((c) => c.provenance[0]?.strategy || "unknown").join(", ");
166
+ switch (this.aggregationMode) {
167
+ case AggregationMode.MAX: return `Max of ${count} generators (${strategies}): scores [${scores}] → ${finalScore.toFixed(2)}`;
168
+ case AggregationMode.AVERAGE: return `Weighted Avg of ${count} generators (${strategies}): scores [${scores}] → ${finalScore.toFixed(2)}`;
169
+ case AggregationMode.FREQUENCY_BOOST: {
170
+ const totalWeight = items.reduce((sum, i) => sum + i.weight, 0);
171
+ const weightedSum = items.reduce((sum, i) => sum + i.card.score * i.weight, 0);
172
+ const avg = totalWeight > 0 ? weightedSum / totalWeight : 0;
173
+ const boost = 1 + FREQUENCY_BOOST_FACTOR * (count - 1);
174
+ return `Frequency boost from ${count} generators (${strategies}): w-avg ${avg.toFixed(2)} × ${boost.toFixed(2)} → ${finalScore.toFixed(2)}`;
175
+ }
176
+ default: return `Aggregated from ${count} generators: ${finalScore.toFixed(2)}`;
177
+ }
178
+ }
179
+ /**
180
+ * Aggregate scores from multiple generators for the same card.
181
+ */
182
+ aggregateScores(items) {
183
+ const scores = items.map((i) => i.card.score);
184
+ switch (this.aggregationMode) {
185
+ case AggregationMode.MAX: return Math.max(...scores);
186
+ case AggregationMode.AVERAGE: {
187
+ const totalWeight = items.reduce((sum, i) => sum + i.weight, 0);
188
+ if (totalWeight === 0) return 0;
189
+ return items.reduce((sum, i) => sum + i.card.score * i.weight, 0) / totalWeight;
190
+ }
191
+ case AggregationMode.FREQUENCY_BOOST: {
192
+ const totalWeight = items.reduce((sum, i) => sum + i.weight, 0);
193
+ const weightedSum = items.reduce((sum, i) => sum + i.card.score * i.weight, 0);
194
+ return (totalWeight > 0 ? weightedSum / totalWeight : 0) * (1 + FREQUENCY_BOOST_FACTOR * (items.length - 1));
195
+ }
196
+ default: return scores[0];
197
+ }
198
+ }
199
+ };
200
+ //#endregion
201
+ export { CompositeGenerator as default };
202
+
203
+ //# sourceMappingURL=CompositeGenerator.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"CompositeGenerator.mjs","names":[],"sources":["../../../../src/core/navigators/generators/CompositeGenerator.ts"],"sourcesContent":["import { ContentNavigator } from '../index';\nimport type { WeightedCard } from '../index';\nimport type { ContentNavigationStrategyData } from '../../types/contentNavigationStrategy';\nimport type { CourseDBInterface } from '../../interfaces/courseDB';\nimport type { UserDBInterface } from '../../interfaces/userDB';\nimport type { CardGenerator, GeneratorContext, GeneratorResult, ReplanHints } from './types';\nimport { logger } from '../../../util/logger';\n\n// ============================================================================\n// COMPOSITE GENERATOR\n// ============================================================================\n//\n// Composes multiple generator strategies into a single generator.\n//\n// Use case: When a course has multiple generators (e.g., ELO + SRS), this\n// class merges their outputs into a unified candidate list.\n//\n// Aggregation strategy:\n// - Cards appearing in multiple generators get a frequency boost\n// - Score = average(scores) * (1 + 0.1 * (appearances - 1))\n// - This rewards cards that multiple generators agree on\n//\n// ============================================================================\n\n/**\n * Aggregation modes for combining scores from multiple generators.\n */\nexport enum AggregationMode {\n /** Use the maximum score from any generator */\n MAX = 'max',\n /** Average all scores */\n AVERAGE = 'average',\n /** Average with frequency boost: avg * (1 + 0.1 * (n-1)) */\n FREQUENCY_BOOST = 'frequencyBoost',\n}\n\nconst DEFAULT_AGGREGATION_MODE = AggregationMode.FREQUENCY_BOOST;\nconst FREQUENCY_BOOST_FACTOR = 0.1;\n\nfunction mergeHints(allHints: Array<ReplanHints | undefined>): ReplanHints | undefined {\n const defined = allHints.filter((h): h is ReplanHints => h !== undefined);\n if (defined.length === 0) return undefined;\n\n const merged: ReplanHints = {};\n\n const boostTags: Record<string, number> = {};\n for (const hints of defined) {\n for (const [pattern, factor] of Object.entries(hints.boostTags ?? {})) {\n boostTags[pattern] = (boostTags[pattern] ?? 1) * factor;\n }\n }\n if (Object.keys(boostTags).length > 0) {\n merged.boostTags = boostTags;\n }\n\n const boostCards: Record<string, number> = {};\n for (const hints of defined) {\n for (const [pattern, factor] of Object.entries(hints.boostCards ?? {})) {\n boostCards[pattern] = (boostCards[pattern] ?? 1) * factor;\n }\n }\n if (Object.keys(boostCards).length > 0) {\n merged.boostCards = boostCards;\n }\n\n const concatUnique = (\n field: 'requireTags' | 'requireCards' | 'excludeTags' | 'excludeCards'\n ): void => {\n const values = defined.flatMap((h) => h[field] ?? []);\n if (values.length > 0) {\n merged[field] = [...new Set(values)];\n }\n };\n\n concatUnique('requireTags');\n concatUnique('requireCards');\n concatUnique('excludeTags');\n concatUnique('excludeCards');\n\n const labels = defined.map((h) => h._label).filter(Boolean);\n if (labels.length > 0) {\n merged._label = labels.join('; ');\n }\n\n return Object.keys(merged).length > 0 ? merged : undefined;\n}\n\n/**\n * Composes multiple generators into a single generator.\n *\n * Implements CardGenerator for use in Pipeline architecture.\n * Also extends ContentNavigator for backward compatibility.\n *\n * Fetches candidates from all generators, deduplicates by cardId,\n * and aggregates scores based on the configured mode.\n */\nexport default class CompositeGenerator extends ContentNavigator implements CardGenerator {\n /** Human-readable name for CardGenerator interface */\n name: string = 'Composite Generator';\n\n private generators: CardGenerator[];\n private aggregationMode: AggregationMode;\n\n constructor(\n generators: CardGenerator[],\n aggregationMode: AggregationMode = DEFAULT_AGGREGATION_MODE\n ) {\n super();\n this.generators = generators;\n this.aggregationMode = aggregationMode;\n\n if (generators.length === 0) {\n throw new Error('CompositeGenerator requires at least one generator');\n }\n\n logger.debug(\n `[CompositeGenerator] Created with ${generators.length} generators, mode: ${aggregationMode}`\n );\n }\n\n /**\n * Creates a CompositeGenerator from strategy data.\n *\n * This is a convenience factory for use by PipelineAssembler.\n */\n static async fromStrategies(\n user: UserDBInterface,\n course: CourseDBInterface,\n strategies: ContentNavigationStrategyData[],\n aggregationMode: AggregationMode = DEFAULT_AGGREGATION_MODE\n ): Promise<CompositeGenerator> {\n const generators = await Promise.all(\n strategies.map((s) => ContentNavigator.create(user, course, s))\n );\n // Cast is safe because we know these are generators\n return new CompositeGenerator(generators as unknown as CardGenerator[], aggregationMode);\n }\n\n /**\n * Get weighted cards from all generators, merge and deduplicate.\n *\n * Cards appearing in multiple generators receive a score boost.\n * Provenance tracks which generators produced each card and how scores were aggregated.\n *\n * This method supports both the legacy signature (limit only) and the\n * CardGenerator interface signature (limit, context).\n *\n * @param limit - Maximum number of cards to return\n * @param context - GeneratorContext passed to child generators (required when called via Pipeline)\n */\n async getWeightedCards(limit: number, context?: GeneratorContext): Promise<GeneratorResult> {\n if (!context) {\n throw new Error(\n 'CompositeGenerator.getWeightedCards requires a GeneratorContext. ' +\n 'It should be called via Pipeline, not directly.'\n );\n }\n\n // Fetch from all generators in parallel\n const results = await Promise.all(\n this.generators.map((g) => g.getWeightedCards(limit, context))\n );\n\n // Log per-generator breakdown for transparency\n const generatorSummaries: string[] = [];\n results.forEach((result, index) => {\n const cards = result.cards;\n const gen = this.generators[index];\n const genName = gen.name || `Generator ${index}`;\n const newCards = cards.filter((c) => c.provenance[0]?.reason?.includes('new card'));\n const reviewCards = cards.filter((c) => c.provenance[0]?.reason?.includes('review'));\n \n if (cards.length > 0) {\n const topScore = Math.max(...cards.map((c) => c.score)).toFixed(2);\n const parts: string[] = [];\n if (newCards.length > 0) parts.push(`${newCards.length} new`);\n if (reviewCards.length > 0) parts.push(`${reviewCards.length} reviews`);\n const breakdown = parts.length > 0 ? parts.join(', ') : `${cards.length} cards`;\n generatorSummaries.push(`${genName}: ${breakdown} (top: ${topScore})`);\n } else {\n generatorSummaries.push(`${genName}: 0 cards`);\n }\n });\n logger.info(`[Composite] Generator breakdown: ${generatorSummaries.join(' | ')}`);\n\n // Group by cardId, tracking the weight of the generator that produced each instance\n type WeightedResult = { card: WeightedCard; weight: number };\n const byCardId = new Map<string, WeightedResult[]>();\n\n results.forEach((result, index) => {\n const cards = result.cards;\n // Access learnable weight if available\n const gen = this.generators[index] as unknown as ContentNavigator;\n\n // Determine effective weight\n let weight = gen.learnable?.weight ?? 1.0;\n let deviation: number | undefined;\n\n if (gen.learnable && !gen.staticWeight && context.orchestration) {\n // Access strategyId (protected field) via type assertion\n const strategyId = (gen as any).strategyId;\n if (strategyId) {\n weight = context.orchestration.getEffectiveWeight(strategyId, gen.learnable);\n deviation = context.orchestration.getDeviation(strategyId);\n }\n }\n\n for (const card of cards) {\n // Record effective weight in provenance for transparency\n if (card.provenance.length > 0) {\n card.provenance[0].effectiveWeight = weight;\n card.provenance[0].deviation = deviation;\n }\n\n const existing = byCardId.get(card.cardId) || [];\n existing.push({ card, weight });\n byCardId.set(card.cardId, existing);\n }\n });\n\n // Aggregate scores\n const merged: WeightedCard[] = [];\n for (const [, items] of byCardId) {\n const cards = items.map((i) => i.card);\n const aggregatedScore = this.aggregateScores(items);\n // Allow scores above 1.0 to pass through — generators like prescribed\n // intentionally use high scores to express curriculum priority.\n // Only clamp negative scores.\n const finalScore = Math.max(0, aggregatedScore);\n\n // Merge provenance from all generators that produced this card\n const mergedProvenance = cards.flatMap((c) => c.provenance);\n\n // Determine action based on whether score changed\n const initialScore = cards[0].score;\n const action =\n finalScore > initialScore ? 'boosted' : finalScore < initialScore ? 'penalized' : 'passed';\n\n // Build reason explaining the aggregation\n const reason = this.buildAggregationReason(items, finalScore);\n\n // Append composite provenance entry\n merged.push({\n ...cards[0],\n score: finalScore,\n provenance: [\n ...mergedProvenance,\n {\n strategy: 'composite',\n strategyName: 'Composite Generator',\n strategyId: 'COMPOSITE_GENERATOR',\n action,\n score: finalScore,\n reason,\n },\n ],\n });\n }\n\n // Sort by score descending and limit\n const cards = merged.sort((a, b) => b.score - a.score).slice(0, limit);\n const hints = mergeHints(results.map((result) => result.hints));\n\n return { cards, hints };\n }\n\n /**\n * Build human-readable reason for score aggregation.\n */\n private buildAggregationReason(\n items: { card: WeightedCard; weight: number }[],\n finalScore: number\n ): string {\n const cards = items.map((i) => i.card);\n const count = cards.length;\n const scores = cards.map((c) => c.score.toFixed(2)).join(', ');\n\n if (count === 1) {\n const weightMsg =\n Math.abs(items[0].weight - 1.0) > 0.001 ? ` (w=${items[0].weight.toFixed(2)})` : '';\n return `Single generator, score ${finalScore.toFixed(2)}${weightMsg}`;\n }\n\n const strategies = cards.map((c) => c.provenance[0]?.strategy || 'unknown').join(', ');\n\n switch (this.aggregationMode) {\n case AggregationMode.MAX:\n return `Max of ${count} generators (${strategies}): scores [${scores}] → ${finalScore.toFixed(2)}`;\n\n case AggregationMode.AVERAGE:\n return `Weighted Avg of ${count} generators (${strategies}): scores [${scores}] → ${finalScore.toFixed(2)}`;\n\n case AggregationMode.FREQUENCY_BOOST: {\n // Recalculate basic weighted avg for display\n const totalWeight = items.reduce((sum, i) => sum + i.weight, 0);\n const weightedSum = items.reduce((sum, i) => sum + i.card.score * i.weight, 0);\n const avg = totalWeight > 0 ? weightedSum / totalWeight : 0;\n\n const boost = 1 + FREQUENCY_BOOST_FACTOR * (count - 1);\n return `Frequency boost from ${count} generators (${strategies}): w-avg ${avg.toFixed(2)} × ${boost.toFixed(2)} → ${finalScore.toFixed(2)}`;\n }\n\n default:\n return `Aggregated from ${count} generators: ${finalScore.toFixed(2)}`;\n }\n }\n\n /**\n * Aggregate scores from multiple generators for the same card.\n */\n private aggregateScores(items: { card: WeightedCard; weight: number }[]): number {\n const scores = items.map((i) => i.card.score);\n\n switch (this.aggregationMode) {\n case AggregationMode.MAX:\n return Math.max(...scores);\n\n case AggregationMode.AVERAGE: {\n const totalWeight = items.reduce((sum, i) => sum + i.weight, 0);\n if (totalWeight === 0) return 0;\n const weightedSum = items.reduce((sum, i) => sum + i.card.score * i.weight, 0);\n return weightedSum / totalWeight;\n }\n\n case AggregationMode.FREQUENCY_BOOST: {\n const totalWeight = items.reduce((sum, i) => sum + i.weight, 0);\n const weightedSum = items.reduce((sum, i) => sum + i.card.score * i.weight, 0);\n const avg = totalWeight > 0 ? weightedSum / totalWeight : 0;\n\n const frequencyBoost = 1 + FREQUENCY_BOOST_FACTOR * (items.length - 1);\n return avg * frequencyBoost;\n }\n\n default:\n return scores[0];\n }\n }\n}\n"],"mappings":"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"}
@@ -0,0 +1,77 @@
1
+ import "../../../_virtual/_rolldown/runtime.mjs";
2
+ import { logger } from "../../../util/logger.mjs";
3
+ import { ContentNavigator } from "../index.mjs";
4
+ import { toCourseElo } from "@vue-skuilder/common";
5
+ //#region src/core/navigators/generators/elo.ts
6
+ /**
7
+ * A navigation strategy that retrieves new cards near the learner's ELO.
8
+ *
9
+ * Implements CardGenerator for use in Pipeline architecture.
10
+ * Also extends ContentNavigator for backward compatibility with legacy code.
11
+ *
12
+ * Only returns new cards - use SRSNavigator for reviews.
13
+ */
14
+ var ELONavigator = class extends ContentNavigator {
15
+ /** Human-readable name for CardGenerator interface */
16
+ name;
17
+ constructor(user, course, strategyData) {
18
+ super(user, course, strategyData);
19
+ this.name = strategyData?.name || "ELO";
20
+ }
21
+ /**
22
+ * Get the new cards nearest the learner's ELO, each scored with a flat
23
+ * jitter in [0.5, 1]. Carries each card's ELO for the ELO distance filter.
24
+ *
25
+ * NOTE: This generator only handles NEW cards. Reviews are handled by
26
+ * SRSNavigator. Use CompositeGenerator to combine both.
27
+ *
28
+ * This method supports both the legacy signature (limit only) and the
29
+ * CardGenerator interface signature (limit, context).
30
+ *
31
+ * @param limit - Maximum number of cards to return
32
+ * @param context - Optional GeneratorContext (used when called via Pipeline)
33
+ */
34
+ async getWeightedCards(limit, context) {
35
+ let userGlobalElo;
36
+ if (context?.userElo !== void 0) userGlobalElo = context.userElo;
37
+ else userGlobalElo = toCourseElo((await this.user.getCourseRegDoc(this.course.getCourseID())).elo).global.score;
38
+ const [activeCards, seenCards] = await Promise.all([this.user.getActiveCards(), this.user.getSeenCards(this.course.getCourseID()).catch(() => [])]);
39
+ const notNew = new Set([...activeCards.map((ac) => ac.cardID), ...seenCards]);
40
+ const scored = (await this.course.getCardsCenteredAtELO({
41
+ limit,
42
+ elo: userGlobalElo
43
+ }, (c) => !notNew.has(c.cardID))).map((c) => ({
44
+ ...c,
45
+ status: "new"
46
+ })).map((c) => {
47
+ const cardElo = c.elo ?? 1e3;
48
+ const distance = Math.abs(cardElo - userGlobalElo);
49
+ const jitter = .5 + .5 * Math.random();
50
+ return {
51
+ cardId: c.cardID,
52
+ courseId: c.courseID,
53
+ score: jitter,
54
+ cardElo,
55
+ provenance: [{
56
+ strategy: "elo",
57
+ strategyName: this.strategyName || this.name,
58
+ strategyId: this.strategyId || "NAVIGATION_STRATEGY-ELO-default",
59
+ action: "generated",
60
+ score: jitter,
61
+ reason: `new card near learner ELO: distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userGlobalElo)}), jitter ${jitter.toFixed(3)}`
62
+ }]
63
+ };
64
+ });
65
+ scored.sort((a, b) => b.score - a.score);
66
+ const cards = scored.slice(0, limit);
67
+ if (cards.length > 0) {
68
+ const topScores = cards.slice(0, 3).map((c) => c.score.toFixed(2)).join(", ");
69
+ logger.info(`[ELO] Course ${this.course.getCourseID()}: ${cards.length} new cards (top scores: ${topScores})`);
70
+ } else logger.info(`[ELO] Course ${this.course.getCourseID()}: No new cards available`);
71
+ return { cards };
72
+ }
73
+ };
74
+ //#endregion
75
+ export { ELONavigator as default };
76
+
77
+ //# sourceMappingURL=elo.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"elo.mjs","names":[],"sources":["../../../../src/core/navigators/generators/elo.ts"],"sourcesContent":["import type { CourseDBInterface } from '../../interfaces/courseDB';\nimport type { UserDBInterface } from '../../interfaces/userDB';\nimport { ContentNavigator } from '../index';\nimport type { WeightedCard } from '../index';\nimport { toCourseElo } from '@vue-skuilder/common';\nimport type { QualifiedCardID } from '../..';\nimport type { CardGenerator, GeneratorContext, GeneratorResult } from './types';\nimport { logger } from '@db/util/logger';\n\n// ============================================================================\n// ELO NAVIGATOR\n// ============================================================================\n//\n// A generator strategy that retrieves new cards near the learner's ELO.\n//\n// It retrieves; it doesn't rank by distance. Scores are a flat jitter in\n// [0.5, 1] for session-to-session variety. ELO distance is scored once, for\n// new cards and reviews alike, by the ELO distance filter (filters/eloDistance),\n// which the assembler adds to every pipeline. Scoring it here too counted it\n// twice for new cards and once for reviews.\n//\n// NOTE: This generator only handles NEW cards. Reviews are handled by\n// SRSNavigator. Use CompositeGenerator to combine both.\n//\n// ============================================================================\n\n/**\n * A navigation strategy that retrieves new cards near the learner's ELO.\n *\n * Implements CardGenerator for use in Pipeline architecture.\n * Also extends ContentNavigator for backward compatibility with legacy code.\n *\n * Only returns new cards - use SRSNavigator for reviews.\n */\nexport default class ELONavigator extends ContentNavigator implements CardGenerator {\n /** Human-readable name for CardGenerator interface */\n name: string;\n\n constructor(\n user: UserDBInterface,\n course: CourseDBInterface,\n strategyData?: { name: string; _id: string }\n // The ELO strategy is non-parameterized.\n //\n // It instead relies on existing meta data from the course and user with respect to\n // ELO scores - it uses those to select cards matched to user skill level.\n ) {\n super(user, course, strategyData as any);\n this.name = strategyData?.name || 'ELO';\n }\n\n /**\n * Get the new cards nearest the learner's ELO, each scored with a flat\n * jitter in [0.5, 1]. Carries each card's ELO for the ELO distance filter.\n *\n * NOTE: This generator only handles NEW cards. Reviews are handled by\n * SRSNavigator. Use CompositeGenerator to combine both.\n *\n * This method supports both the legacy signature (limit only) and the\n * CardGenerator interface signature (limit, context).\n *\n * @param limit - Maximum number of cards to return\n * @param context - Optional GeneratorContext (used when called via Pipeline)\n */\n async getWeightedCards(limit: number, context?: GeneratorContext): Promise<GeneratorResult> {\n // const tElo0 = performance.now(); // [perf] parked\n // Determine user ELO - from context if available, otherwise fetch\n let userGlobalElo: number;\n if (context?.userElo !== undefined) {\n userGlobalElo = context.userElo;\n } else {\n const courseReg = await this.user.getCourseRegDoc(this.course.getCourseID());\n const userElo = toCourseElo(courseReg.elo);\n userGlobalElo = userElo.global.score;\n }\n // const tUser = performance.now(); // [perf] parked\n\n // Not new: cards with a pending review, and cards seen without one (e.g.\n // `srs:skip` intros, which must not resurface). As the prescribed generator.\n const [activeCards, seenCards] = await Promise.all([\n this.user.getActiveCards(),\n this.user.getSeenCards(this.course.getCourseID()).catch(() => [] as string[]),\n ]);\n const notNew = new Set([...activeCards.map((ac) => ac.cardID), ...seenCards]);\n // const tActive = performance.now(); // [perf] parked\n // Centre the window on this generator's user's ELO, passed explicitly:\n // `elo: 'user'` would have the course DB resolve its own notion of the\n // current user, which isn't necessarily the user this pipeline runs for\n // (e.g. an admin running a learner's pipeline read-only).\n const newCards = (\n await this.course.getCardsCenteredAtELO(\n { limit, elo: userGlobalElo },\n (c: QualifiedCardID) => !notNew.has(c.cardID)\n )\n ).map((c) => ({ ...c, status: 'new' as const }));\n // const tCentered = performance.now(); // [perf] parked\n // [perf] parked 2026-05 (pipeline-docs-workup) — uncomment to re-measure\n // logger.info(\n // `[perf][ELOgen] total=${(tCentered - tElo0).toFixed(0)}ms ` +\n // `(userElo=${(tUser - tElo0).toFixed(0)} ` +\n // `activeCards=${(tActive - tUser).toFixed(0)} ` +\n // `centeredAtELO=${(tCentered - tActive).toFixed(0)}) ` +\n // `[active=${activeCards.length} candidates=${newCards.length}]`\n // );\n\n // Retrieval is by ELO (the window above); scoring isn't. Each card gets a\n // jitter in [0.5, 1] so near-equal cards shuffle between sessions instead of\n // looping. Distance is scored by the ELO distance filter, on the Gaussian\n // this generator used to apply itself (sigma 300, never zero, so a\n // downstream boost can always lift a low-ELO target; see filters/eloDistance\n // and packages/db/docs/todo-intro-concept-emphasis-and-retrieval.md).\n //\n // Card ELO is read from the pooled `.elo` carried on each candidate by\n // getCardsCenteredAtELO, and passed on as `cardElo` so the filter needn't\n // fetch it again.\n const scored: WeightedCard[] = newCards.map((c) => {\n const cardElo = c.elo ?? 1000;\n const distance = Math.abs(cardElo - userGlobalElo);\n const jitter = 0.5 + 0.5 * Math.random();\n\n return {\n cardId: c.cardID,\n courseId: c.courseID,\n score: jitter,\n cardElo,\n provenance: [\n {\n strategy: 'elo',\n strategyName: this.strategyName || this.name,\n strategyId: this.strategyId || 'NAVIGATION_STRATEGY-ELO-default',\n action: 'generated',\n score: jitter,\n reason: `new card near learner ELO: distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userGlobalElo)}), jitter ${jitter.toFixed(3)}`,\n },\n ],\n };\n });\n\n // Sort by jitter descending (a uniform random sample of the window)\n scored.sort((a, b) => b.score - a.score);\n\n const cards = scored.slice(0, limit);\n\n // Log summary for transparency\n if (cards.length > 0) {\n const topScores = cards.slice(0, 3).map((c) => c.score.toFixed(2)).join(', ');\n logger.info(\n `[ELO] Course ${this.course.getCourseID()}: ${cards.length} new cards (top scores: ${topScores})`\n );\n } else {\n logger.info(`[ELO] Course ${this.course.getCourseID()}: No new cards available`);\n }\n\n return { cards };\n }\n}\n"],"mappings":";;;;;;;;;;;;;AAkCA,IAAqB,eAArB,cAA0C,iBAA0C;;CAElF;CAEA,YACE,MACA,QACA,cAKA;AACA,QAAM,MAAM,QAAQ,aAAoB;AACxC,OAAK,OAAO,cAAc,QAAQ;;;;;;;;;;;;;;;CAgBpC,MAAM,iBAAiB,OAAe,SAAsD;EAG1F,IAAI;AACJ,MAAI,SAAS,YAAY,KAAA,EACvB,iBAAgB,QAAQ;MAIxB,iBADgB,aADE,MAAM,KAAK,KAAK,gBAAgB,KAAK,OAAO,aAAa,CAAC,EACtC,IAAI,CAClB,OAAO;EAMjC,MAAM,CAAC,aAAa,aAAa,MAAM,QAAQ,IAAI,CACjD,KAAK,KAAK,gBAAgB,EAC1B,KAAK,KAAK,aAAa,KAAK,OAAO,aAAa,CAAC,CAAC,YAAY,EAAE,CAAa,CAC9E,CAAC;EACF,MAAM,SAAS,IAAI,IAAI,CAAC,GAAG,YAAY,KAAK,OAAO,GAAG,OAAO,EAAE,GAAG,UAAU,CAAC;EAgC7E,MAAM,UAzBJ,MAAM,KAAK,OAAO,sBAChB;GAAE;GAAO,KAAK;GAAe,GAC5B,MAAuB,CAAC,OAAO,IAAI,EAAE,OAAO,CAC9C,EACD,KAAK,OAAO;GAAE,GAAG;GAAG,QAAQ;GAAgB,EAAE,CAqBR,KAAK,MAAM;GACjD,MAAM,UAAU,EAAE,OAAO;GACzB,MAAM,WAAW,KAAK,IAAI,UAAU,cAAc;GAClD,MAAM,SAAS,KAAM,KAAM,KAAK,QAAQ;AAExC,UAAO;IACL,QAAQ,EAAE;IACV,UAAU,EAAE;IACZ,OAAO;IACP;IACA,YAAY,CACV;KACE,UAAU;KACV,cAAc,KAAK,gBAAgB,KAAK;KACxC,YAAY,KAAK,cAAc;KAC/B,QAAQ;KACR,OAAO;KACP,QAAQ,uCAAuC,KAAK,MAAM,SAAS,CAAC,UAAU,KAAK,MAAM,QAAQ,CAAC,UAAU,KAAK,MAAM,cAAc,CAAC,YAAY,OAAO,QAAQ,EAAE;KACpK,CACF;IACF;IACD;AAGF,SAAO,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,MAAM;EAExC,MAAM,QAAQ,OAAO,MAAM,GAAG,MAAM;AAGpC,MAAI,MAAM,SAAS,GAAG;GACpB,MAAM,YAAY,MAAM,MAAM,GAAG,EAAE,CAAC,KAAK,MAAM,EAAE,MAAM,QAAQ,EAAE,CAAC,CAAC,KAAK,KAAK;AAC7E,UAAO,KACL,gBAAgB,KAAK,OAAO,aAAa,CAAC,IAAI,MAAM,OAAO,0BAA0B,UAAU,GAChG;QAED,QAAO,KAAK,gBAAgB,KAAK,OAAO,aAAa,CAAC,0BAA0B;AAGlF,SAAO,EAAE,OAAO"}