@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
@@ -1,2007 +0,0 @@
1
- import { Status, CourseConfig, SkuilderCourseData as SkuilderCourseData$1, CourseElo, DataShape, TagFilter } from '@vue-skuilder/common';
2
- import { Moment } from 'moment';
3
- import { S as SkuilderCourseData, f as DocTypePrefixes, D as DocType, Q as QualifiedCardID, T as TagStub, a as Tag, e as CardHistory, c as CardRecord, d as QuestionRecord } from './types-legacy-DdVjg81H.cjs';
4
-
5
- interface DataLayerResult {
6
- status: Status;
7
- message: string;
8
- id?: string;
9
- }
10
-
11
- /**
12
- * Configuration for an evolutionarily-weighted strategy.
13
- *
14
- * This structure tracks the "learned" weight of a strategy, representing the
15
- * system's confidence in its utility.
16
- *
17
- * - weight: The best-known multiplier (peak of the bell curve)
18
- * - confidence: How certain we are (inverse of variance / spread)
19
- * - sampleSize: How many data points informed this weight
20
- */
21
- interface LearnableWeight {
22
- /** The current best estimate of optimal weight (multiplier) */
23
- weight: number;
24
- /** Confidence in this weight (0-1). Higher = narrower exploration spread. */
25
- confidence: number;
26
- /** Number of outcome observations that contributed to this weight */
27
- sampleSize: number;
28
- }
29
- /**
30
- *
31
- */
32
- interface ContentNavigationStrategyData extends SkuilderCourseData {
33
- _id: `${typeof DocTypePrefixes[DocType.NAVIGATION_STRATEGY]}-${string}`;
34
- docType: DocType.NAVIGATION_STRATEGY;
35
- name: string;
36
- description: string;
37
- /**
38
- The name of the class that implements the navigation strategy at runtime.
39
- */
40
- implementingClass: string;
41
- /**
42
- A representation of the strategy's parameterization - to be deserialized
43
- by the implementing class's constructor at runtime.
44
- */
45
- serializedData: string;
46
- /**
47
- * Evolutionary weighting configuration.
48
- * If present, the strategy's influence is scaled by this weight.
49
- * If omitted, weight defaults to 1.0.
50
- */
51
- learnable?: LearnableWeight;
52
- /**
53
- * If true, the weight is applied exactly as configured, without
54
- * per-user deviation. Used for manual tuning or A/B testing.
55
- */
56
- staticWeight?: boolean;
57
- }
58
-
59
- /**
60
- * A NavigationStrategyManager is an entity which may contain multiple strategies.
61
- *
62
- * This interface defines strategy CRUD.
63
- */
64
- interface NavigationStrategyManager {
65
- /**
66
- * Get the navigation strategy for a given course
67
- * @returns The navigation strategy for the course
68
- */
69
- getNavigationStrategy(id: string): Promise<ContentNavigationStrategyData>;
70
- /**
71
- * Get all available navigation strategies
72
- * @returns An array of all available navigation strategies
73
- */
74
- getAllNavigationStrategies(): Promise<ContentNavigationStrategyData[]>;
75
- /**
76
- * Add a new navigation strategy
77
- * @param data The data for the new navigation strategy
78
- * @returns A promise that resolves when the strategy has been added
79
- */
80
- addNavigationStrategy(data: ContentNavigationStrategyData): Promise<void>;
81
- /**
82
- * Update an existing navigation strategy
83
- * @param id The ID of the navigation strategy to update
84
- * @param data The new data for the navigation strategy
85
- * @returns A promise that resolves when the update is complete
86
- */
87
- updateNavigationStrategy(id: string, data: ContentNavigationStrategyData): Promise<void>;
88
- }
89
-
90
- /**
91
- * Course content and management
92
- */
93
- interface CoursesDBInterface {
94
- /**
95
- * Get course config
96
- */
97
- getCourseConfig(courseId: string): Promise<CourseConfig>;
98
- /**
99
- * Get a list of all courses
100
- */
101
- getCourseList(): Promise<CourseConfig[]>;
102
- disambiguateCourse(courseId: string, disambiguator: string): Promise<void>;
103
- }
104
- interface CourseInfo {
105
- cardCount: number;
106
- registeredUsers: number;
107
- }
108
- interface CourseDBInterface extends NavigationStrategyManager, StudyContentSource {
109
- /**
110
- * Get course config
111
- */
112
- getCourseConfig(): Promise<CourseConfig>;
113
- getCourseID(): string;
114
- /**
115
- * Set course config
116
- */
117
- updateCourseConfig(cfg: CourseConfig): Promise<PouchDB.Core.Response>;
118
- getCourseInfo(): Promise<CourseInfo>;
119
- getCourseDoc<T extends SkuilderCourseData$1>(id: string, options?: PouchDB.Core.GetOptions): Promise<T>;
120
- getCourseDocs<T extends SkuilderCourseData$1>(ids: string[], options?: PouchDB.Core.AllDocsOptions): Promise<PouchDB.Core.AllDocsWithKeysResponse<{} & T>>;
121
- /**
122
- * Get cards sorted by ELO rating
123
- */
124
- getCardsByELO(elo: number, limit?: number): Promise<{
125
- courseID: string;
126
- cardID: string;
127
- elo?: number;
128
- }[]>;
129
- /**
130
- * Get ELO data for specific cards
131
- */
132
- getCardEloData(cardIds: string[]): Promise<CourseElo[]>;
133
- /**
134
- * Update card ELO rating
135
- */
136
- updateCardElo(cardId: string, elo: CourseElo): Promise<PouchDB.Core.Response>;
137
- /**
138
- * Get cards centered at a particular ELO rating
139
- */
140
- getCardsCenteredAtELO(options: {
141
- limit: number;
142
- elo: 'user' | 'random' | number;
143
- }, filter?: (card: QualifiedCardID) => boolean): Promise<StudySessionItem[]>;
144
- /**
145
- * Get tags for a card
146
- */
147
- getAppliedTags(cardId: string): Promise<PouchDB.Query.Response<TagStub>>;
148
- /**
149
- * Get tags for multiple cards in a single batch query.
150
- * More efficient than calling getAppliedTags() for each card.
151
- *
152
- * This method reduces redundant database operations when multiple filters
153
- * need tag data for the same cards. The Pipeline uses this to pre-hydrate
154
- * tags on WeightedCard objects before filters run.
155
- *
156
- * @param cardIds - Array of card IDs to fetch tags for
157
- * @returns Map from cardId to array of tag names
158
- */
159
- getAppliedTagsBatch(cardIds: string[]): Promise<Map<string, string[]>>;
160
- /**
161
- * Get all card IDs in the course.
162
- * Used by diagnostics to scan the full card space.
163
- */
164
- getAllCardIds(): Promise<string[]>;
165
- /**
166
- * Add a tag to a card
167
- */
168
- addTagToCard(cardId: string, tagId: string, updateELO?: boolean): Promise<PouchDB.Core.Response>;
169
- /**
170
- * Remove a tag from a card
171
- */
172
- removeTagFromCard(cardId: string, tagId: string): Promise<PouchDB.Core.Response>;
173
- /**
174
- * Create a new tag
175
- */
176
- createTag(tagName: string, author: string): Promise<PouchDB.Core.Response>;
177
- /**
178
- * Get a tag by name
179
- */
180
- getTag(tagName: string): Promise<Tag>;
181
- /**
182
- * Update a tag
183
- */
184
- updateTag(tag: Tag): Promise<PouchDB.Core.Response>;
185
- /**
186
- * Get all tag stubs for a course
187
- */
188
- getCourseTagStubs(): Promise<PouchDB.Core.AllDocsResponse<Tag>>;
189
- /**
190
- * Add a note to the course
191
- */
192
- addNote(codeCourse: string, shape: DataShape, data: unknown, author: string, tags: string[], uploads?: {
193
- [key: string]: PouchDB.Core.FullAttachment;
194
- }, elo?: CourseElo): Promise<DataLayerResult>;
195
- removeCard(cardId: string): Promise<PouchDB.Core.Response>;
196
- getInexperiencedCards(): Promise<{
197
- courseId: string;
198
- cardId: string;
199
- count: number;
200
- elo: CourseElo;
201
- }[]>;
202
- /**
203
- * Search for cards by text content
204
- * @param query Text to search for
205
- * @returns Array of matching card data
206
- */
207
- searchCards(query: string): Promise<any[]>;
208
- /**
209
- * Find documents using PouchDB query syntax
210
- * @param request PouchDB find request
211
- * @returns Query response
212
- */
213
- find(request: PouchDB.Find.FindRequest<any>): Promise<PouchDB.Find.FindResponse<any>>;
214
- }
215
-
216
- interface SessionTrackingData {
217
- peekSessionCount: number;
218
- studySessionCount: number;
219
- sessionCount: number;
220
- firstSessionDate: string;
221
- lastSessionDate: string;
222
- signupPrompted: boolean;
223
- promptDismissalCount: number;
224
- studyModeAcknowledged: boolean;
225
- }
226
- interface UserConfig {
227
- darkMode: boolean;
228
- likesConfetti: boolean;
229
- sessionTimeLimit: number;
230
- /**
231
- * @deprecated Retired in favour of the _users-doc email (the single source of
232
- * truth, written by /auth/send-verification and read by /auth/status). No
233
- * live code writes or reads this field; it may linger on older CONFIG docs.
234
- */
235
- email?: string;
236
- sessionTracking?: Record<string, SessionTrackingData>;
237
- }
238
- interface ActivityRecord {
239
- timeStamp: number | string;
240
- [key: string]: any;
241
- }
242
- interface CourseRegistration {
243
- status?: 'active' | 'dropped' | 'maintenance-mode' | 'preview';
244
- courseID: string;
245
- admin: boolean;
246
- moderator: boolean;
247
- user: boolean;
248
- settings?: {
249
- [setting: string]: string | number | boolean;
250
- };
251
- elo: number | CourseElo;
252
- }
253
- interface StudyWeights {
254
- [courseID: string]: number;
255
- }
256
- interface CourseRegistrationDoc {
257
- courses: CourseRegistration[];
258
- studyWeight: StudyWeights;
259
- }
260
- interface ScheduledCard {
261
- _id: PouchDB.Core.DocumentId;
262
- /**
263
- * The docID of the card to be reviewed
264
- */
265
- cardId: PouchDB.Core.DocumentId;
266
- /**
267
- * The ID of the course
268
- */
269
- courseId: string;
270
- /**
271
- * The time at which the card becomes eligible for review.
272
- *
273
- * (Should probably be UTC adjusted so that performance is
274
- * not wonky across time zones)
275
- *
276
- * Note: Stored as ISO string for PouchDB serialization compatibility,
277
- * but can be consumed as Moment objects via moment.utc(reviewTime)
278
- */
279
- reviewTime: string | Moment;
280
- /**
281
- * The time at which this scheduled event was created.
282
- *
283
- * Note: Stored as ISO string for PouchDB serialization compatibility,
284
- * but can be consumed as Moment objects via moment.utc(scheduledAt)
285
- */
286
- scheduledAt: string | Moment;
287
- /**
288
- * Classifying whether this card is scheduled on behalf of a
289
- * user-registered course or by as assigned content from a
290
- * user-registered classroom
291
- */
292
- scheduledFor: 'course' | 'classroom';
293
- /**
294
- * The ID of the course or classroom that requested this card
295
- */
296
- schedulingAgentId: string;
297
- }
298
-
299
- /**
300
- * Record of a user's learning outcome over a specific period.
301
- *
302
- * Used by the evolutionary orchestration system to correlate strategy
303
- * deviations with learning success.
304
- *
305
- * Stored in the UserDB.
306
- */
307
- interface UserOutcomeRecord {
308
- /**
309
- * Unique ID: "USER_OUTCOME::{courseId}::{userId}::{timestamp}"
310
- * Timestamp corresponds to periodEnd.
311
- */
312
- _id: string;
313
- docType: DocType.USER_OUTCOME;
314
- courseId: string;
315
- userId: string;
316
- /** Start of the measurement period (ISO timestamp) */
317
- periodStart: string;
318
- /** End of the measurement period (ISO timestamp) */
319
- periodEnd: string;
320
- /**
321
- * The computed signal value (e.g., 0.85 for 85% accuracy).
322
- * This is the 'Y' in the regression analysis.
323
- *
324
- * Higher values indicate better learning outcomes.
325
- */
326
- outcomeValue: number;
327
- /**
328
- * Snapshot of active deviations during this period.
329
- * Maps strategyId -> deviation value used [-1.0, 1.0].
330
- * This provides the 'X' values for regression analysis.
331
- */
332
- deviations: Record<string, number>;
333
- metadata: {
334
- sessionsCount: number;
335
- cardsSeen: number;
336
- eloStart: number;
337
- eloEnd: number;
338
- /** The algorithm used to compute outcomeValue (e.g. "accuracy_in_zone") */
339
- signalType: string;
340
- };
341
- }
342
-
343
- /**
344
- * Context for orchestration decisions during a session.
345
- *
346
- * Provides access to user/course data and helper methods for determining
347
- * effective strategy weights based on the user's cohort assignment.
348
- */
349
- interface OrchestrationContext {
350
- user: UserDBInterface;
351
- course: CourseDBInterface;
352
- userId: string;
353
- courseConfig: CourseConfig;
354
- /**
355
- * Calculate the effective weight for a strategy for this user.
356
- *
357
- * Applies deviation based on the user's cohort assignment (derived from
358
- * userId, strategyId, and course salt).
359
- *
360
- * @param strategyId - Unique ID of the strategy
361
- * @param learnable - The strategy's learning configuration
362
- * @returns Effective weight multiplier (typically 0.1 - 3.0)
363
- */
364
- getEffectiveWeight(strategyId: string, learnable: LearnableWeight): number;
365
- /**
366
- * Get the deviation factor for this user/strategy.
367
- * Range [-1.0, 1.0].
368
- */
369
- getDeviation(strategyId: string): number;
370
- }
371
- /**
372
- * Compute a user's deviation for a specific strategy.
373
- *
374
- * Returns a value in [-1, 1] that is:
375
- * 1. Deterministic for the same (user, strategy, salt) tuple
376
- * 2. Uniformly distributed across users
377
- * 3. Uncorrelated between different strategies (due to strategyId in hash)
378
- * 4. Rotatable by changing the salt
379
- *
380
- * @param userId - ID of the user
381
- * @param strategyId - ID of the strategy
382
- * @param salt - Random seed from course config
383
- * @returns Deviation factor between -1.0 and 1.0
384
- */
385
- declare function computeDeviation(userId: string, strategyId: string, salt: string): number;
386
- /**
387
- * Compute the exploration spread based on confidence.
388
- *
389
- * - Low confidence (0.0) -> Max spread (Explore broadly)
390
- * - High confidence (1.0) -> Min spread (Exploit known good weight)
391
- *
392
- * @param confidence - Confidence level 0-1
393
- * @returns Spread magnitude (half-width of the distribution)
394
- */
395
- declare function computeSpread(confidence: number): number;
396
- /**
397
- * Calculate the effective weight for a strategy instance.
398
- *
399
- * Combines the learnable weight (peak) with the user's deviation and the
400
- * allowed spread (based on confidence).
401
- *
402
- * @param learnable - Strategy learning config
403
- * @param userId - User ID
404
- * @param strategyId - Strategy ID
405
- * @param salt - Course salt
406
- * @returns Effective weight multiplier
407
- */
408
- declare function computeEffectiveWeight(learnable: LearnableWeight, userId: string, strategyId: string, salt: string): number;
409
- /**
410
- * Create an orchestration context for a study session.
411
- *
412
- * Fetches necessary configuration to enable deterministic weight calculation.
413
- *
414
- * @param user - User DB interface
415
- * @param course - Course DB interface
416
- * @returns Initialized orchestration context
417
- */
418
- declare function createOrchestrationContext(user: UserDBInterface, course: CourseDBInterface): Promise<OrchestrationContext>;
419
-
420
- /**
421
- * A navigation pipeline that runs a generator and applies filters sequentially.
422
- *
423
- * Implements StudyContentSource for backward compatibility with SessionController.
424
- *
425
- * ## Usage
426
- *
427
- * ```typescript
428
- * const pipeline = new Pipeline(
429
- * compositeGenerator, // or single generator
430
- * [eloDistanceFilter, interferenceFilter],
431
- * user,
432
- * course
433
- * );
434
- *
435
- * const cards = await pipeline.getWeightedCards(20);
436
- * ```
437
- */
438
- /**
439
- * Narrow capability surface for out-of-band, commit-free reads against a live
440
- * pipeline (see {@link getActivePipeline}). Kept minimal on purpose — consumers
441
- * get the forecast capability, not the whole `Pipeline` class.
442
- */
443
- interface PipelineForecaster {
444
- forecast(opts?: {
445
- hints?: ReplanHints;
446
- unseenOnly?: boolean;
447
- threshold?: number;
448
- limit?: number;
449
- }): Promise<WeightedCard[]>;
450
- }
451
- /**
452
- * Diagnosis of the full card space for the current user.
453
- */
454
- interface CardSpaceDiagnosis {
455
- totalCards: number;
456
- threshold: number;
457
- wellIndicated: number;
458
- encountered: number;
459
- wellIndicatedNew: number;
460
- byType: Record<string, {
461
- total: number;
462
- wellIndicated: number;
463
- new: number;
464
- }>;
465
- filterBreakdown: Array<{
466
- name: string;
467
- wellIndicated: number;
468
- }>;
469
- elapsedMs: number;
470
- }
471
-
472
- type RegulatorName = 'review-mass' | 'intake';
473
- /** One regulator's reading for one pipeline run. Persisted on run summaries. */
474
- interface RegulatorReading {
475
- name: RegulatorName;
476
- /** The class the multiplier applies to. */
477
- class: 'review' | 'new';
478
- /** The valve's urgency: review mass (card-equivalents) or intake hours. */
479
- urgency: number;
480
- multiplier: number;
481
- /** Candidates the multiplier applied to. */
482
- applied: number;
483
- inputs: Record<string, number>;
484
- }
485
- interface RegulatorConfig {
486
- reviewMass: {
487
- /**
488
- * Unit of mass for reviews without an SRS urgency (from another
489
- * generator): a filtered score this high weighs 1.
490
- */
491
- referenceScore: number;
492
- /** Mass (card-equivalents) at or below which there's no pressure. */
493
- healthyMass: number;
494
- /** Multiplier growth per multiple of `healthyMass` in excess. */
495
- rate: number;
496
- };
497
- intake: {
498
- /** Multiplier growth per `scaleHours` without a new card. */
499
- rate: number;
500
- scaleHours: number;
501
- };
502
- }
503
- /**
504
- * Defaults. Review mass keeps the SRS generator's former healthy threshold and
505
- * growth rate (20, ×2), now applied to mass instead of count. Intake doubles
506
- * per day of servable time without a new card.
507
- */
508
- declare const DEFAULT_REGULATOR_CONFIG: RegulatorConfig;
509
- /**
510
- * One due review's weight in the mass, in [0, 1]: its SRS urgency times the
511
- * filters' net effect on it (filtered score ÷ the score it was generated
512
- * with), so every course signal discounts it. A review without an urgency
513
- * weighs its filtered score against the reference.
514
- */
515
- declare function reviewWeight(card: WeightedCard, generatedScore: number | undefined, referenceScore: number): number;
516
- /**
517
- * @param reviews - Due reviews, after filters
518
- * @param generatedScores - Each card's score as generated, before filters
519
- */
520
- declare function reviewMassReading(reviews: WeightedCard[], generatedScores: ReadonlyMap<string, number>, config?: RegulatorConfig['reviewMass']): RegulatorReading;
521
- /** The intake valve's clock, persisted per user and course (strategy state). */
522
- interface IntakeClockState {
523
- /** When a new card was last presented (ISO). */
524
- lastNewAt: string;
525
- /** Closed stretches since then during which no eligible new card existed (ms). */
526
- frozenMs: number;
527
- /** Start of the current stretch with no eligible new card (ISO), or null. */
528
- unservableSince: string | null;
529
- }
530
- /** Strategy-state key for the intake clock. */
531
- declare const INTAKE_CLOCK_KEY = "IntakeClock";
532
- /** A fresh clock: a new card was just presented (or the clock is starting). */
533
- declare function resetIntakeClock(nowMs: number): IntakeClockState;
534
- /** Frozen time so far, including an open unservable stretch. */
535
- declare function frozenMsAt(state: IntakeClockState, nowMs: number): number;
536
- /** Servable hours since a new card was last presented. */
537
- declare function intakeHours(state: IntakeClockState, nowMs: number): number;
538
- /**
539
- * Advance the clock's freeze bookkeeping for a run that found `eligibleNew`
540
- * eligible new candidates. The clock freezes while there are none (exhaustion
541
- * isn't starvation) and resumes when some appear. Returns the same object when
542
- * nothing changed, so callers persist only on transitions.
543
- */
544
- declare function stepIntakeClock(state: IntakeClockState, nowMs: number, eligibleNew: number): IntakeClockState;
545
- declare function intakeReading(state: IntakeClockState, nowMs: number, counts: {
546
- eligibleNew: number;
547
- newCandidates: number;
548
- }, config?: RegulatorConfig['intake']): RegulatorReading;
549
- /** Multiply `cards` (in place) by a reading's multiplier, with a provenance entry when it changes them. */
550
- declare function applyReading(cards: WeightedCard[], reading: RegulatorReading): void;
551
-
552
- /**
553
- * The most recently constructed pipeline for the current session, or null if
554
- * none has been built yet. This is the supported, non-debug accessor for
555
- * out-of-band reads against the live pipeline (e.g. a commit-free
556
- * `forecast()`), replacing reach-ins through `window.skuilder.pipeline`.
557
- */
558
- declare function getActivePipeline(): PipelineForecaster | null;
559
- /**
560
- * Summary of a single generator's contribution.
561
- */
562
- interface GeneratorSummary {
563
- name: string;
564
- cardCount: number;
565
- newCount: number;
566
- reviewCount: number;
567
- topScore: number;
568
- }
569
- /**
570
- * Summary of a filter's impact on scores.
571
- */
572
- interface FilterImpact {
573
- name: string;
574
- /** Effective kind: undeclared filters count as gates. Absent on runs before 0.2.29. */
575
- kind?: FilterKind;
576
- boosted: number;
577
- penalized: number;
578
- passed: number;
579
- removed: number;
580
- }
581
- /** A run's version stamps. Either may be absent: no strategy hash, or no content version set. */
582
- interface RunVersions {
583
- strategies?: string;
584
- content?: string;
585
- }
586
- /** One card as retained in a {@link PipelineRunReport}. */
587
- interface RunReportCard {
588
- cardId: string;
589
- courseId: string;
590
- /** `'review'`: a scheduled review. `'new'`: anything else. */
591
- origin: 'new' | 'review';
592
- /** The strategy that produced the card (first provenance entry). Absent if a hint injected it. */
593
- generator?: string;
594
- /** The hint that made the card mandatory, if one did. Its source, over `generator`. */
595
- required?: string;
596
- finalScore: number;
597
- /** Card's ELO (parsed from ELO generator provenance, if available) */
598
- cardElo?: number;
599
- provenance: StrategyContribution[];
600
- tags?: string[];
601
- selected: boolean;
602
- }
603
- /**
604
- * Complete record of a single pipeline execution.
605
- */
606
- interface PipelineRunReport {
607
- runId: string;
608
- /** Absent for runs fired outside a session (forecasts, editor probes). */
609
- sessionId?: string;
610
- timestamp: Date;
611
- courseId: string;
612
- courseName?: string;
613
- /** User's global ELO at the time of this pipeline run */
614
- userElo?: number;
615
- generatorName: string;
616
- generators?: GeneratorSummary[];
617
- generatedCount: number;
618
- filters: FilterImpact[];
619
- /** Ephemeral hints applied during this run */
620
- hints?: ReplanHints;
621
- finalCount: number;
622
- reviewsSelected: number;
623
- newSelected: number;
624
- /**
625
- * Card data for inspection.
626
- *
627
- * To keep the in-memory ring buffer small, this contains:
628
- * - All selected cards (the actual session output).
629
- * - The top-N highest-scoring non-selected cards (see DISCARDED_KEEP_TOP),
630
- * useful for understanding "near misses" and filter behavior.
631
- *
632
- * The remaining low-score tail of the candidate pool (mostly ELO-window
633
- * pull remnants that filters scored down) is summarized in `discardedTail`
634
- * rather than retained verbatim — each retained card carries a multi-KB
635
- * provenance trail, and the tail is typically hundreds of cards per run.
636
- */
637
- cards: RunReportCard[];
638
- /**
639
- * The two unselected non-review cards most worth explaining when a run
640
- * picks no new content. Non-review means no `reviewID`, so prescribed and
641
- * required cards count.
642
- *
643
- * - `nextInLine`: highest final score. How close new content came.
644
- * - `topGenerated`: highest generator score, zero-scored cards included.
645
- * Its provenance shows which filter sank it. Omitted when it is the same
646
- * card as `nextInLine`.
647
- */
648
- unselectedNew?: {
649
- nextInLine?: RunReportCard;
650
- topGenerated?: RunReportCard;
651
- };
652
- /** The regulator stage's readings: each class's pressure and the multiplier it got. */
653
- regulators?: RegulatorReading[];
654
- /**
655
- * What this run ran on (see versionStamps.ts): the hash of the strategy docs
656
- * the pipeline was assembled from, and the course's content version.
657
- */
658
- versions?: RunVersions;
659
- /**
660
- * Summary of the discarded tail of the candidate pool — cards that were
661
- * generated and scored but neither selected nor retained in `cards`.
662
- *
663
- * Provides breadcrumbs for "where did card X go?" investigations without
664
- * the memory cost of keeping every dropped candidate's provenance.
665
- *
666
- * Future: may carry a bloom filter of discarded cardIds so callers can
667
- * ask "was X in this run's discard tail?" with bounded memory cost.
668
- */
669
- discardedTail?: {
670
- count: number;
671
- /** [min, max] finalScore across the discarded tail. */
672
- scoreRange?: [number, number];
673
- /** [min, max] cardElo across the discarded tail (where parseable). */
674
- eloRange?: [number, number];
675
- /** Human-readable note for console display. */
676
- note: string;
677
- };
678
- }
679
- declare function setDebugSessionId(sessionId: string | undefined): void;
680
- /** Take and clear the runs captured since the previous call, in execution order. */
681
- declare function drainCapturedRuns(): PipelineRunReport[];
682
- /**
683
- * Runs for `sessionId`, oldest first. Bounded by {@link MAX_RUNS} — the
684
- * complete record is `StudySessionDoc.runs`.
685
- */
686
- declare function getRunsForSession(sessionId: string): PipelineRunReport[];
687
- /**
688
- * Console API object exposed on window.skuilder.pipeline
689
- */
690
- declare const pipelineDebugAPI: {
691
- /**
692
- * Get raw run history for programmatic access.
693
- */
694
- readonly runs: PipelineRunReport[];
695
- /**
696
- * Show summary of a specific pipeline run.
697
- */
698
- showRun(idOrIndex?: string | number): void;
699
- /**
700
- * Show summary of the last pipeline run.
701
- */
702
- showLastRun(): void;
703
- /**
704
- * Show detailed provenance for a specific card.
705
- */
706
- showCard(cardId: string): void;
707
- /**
708
- * Explain why reviews may or may not have been selected.
709
- */
710
- explainReviews(): void;
711
- /**
712
- * Show prescribed-related cards from the most recent run.
713
- *
714
- * Highlights:
715
- * - cards directly generated by the prescribed strategy
716
- * - blocked prescribed targets mentioned in provenance
717
- * - support tags resolved for blocked targets
718
- *
719
- * @param groupId - Optional prescribed group ID filter (e.g. 'intro-core')
720
- */
721
- showPrescribed(groupId?: string): void;
722
- /**
723
- * Show all runs in compact format.
724
- */
725
- listRuns(): void;
726
- /**
727
- * Export run history as JSON for bug reports.
728
- */
729
- export(): string;
730
- /**
731
- * Clear run history.
732
- */
733
- clear(): void;
734
- /**
735
- * Show the navigator registry: all registered classes and their roles.
736
- *
737
- * Useful for verifying that consumer-defined navigators were registered
738
- * before pipeline assembly.
739
- */
740
- showRegistry(): void;
741
- /**
742
- * Show strategy documents from the last pipeline run and how they mapped
743
- * to the registry.
744
- *
745
- * If no runs are captured yet, falls back to showing just the registry.
746
- */
747
- showStrategies(): void;
748
- /**
749
- * Scan the full card space through the filter chain for the current user.
750
- *
751
- * Reports how many cards are well-indicated and how many are new.
752
- * Use this to understand how the search space grows during onboarding.
753
- *
754
- * @param threshold - Score threshold for "well indicated" (default 0.10)
755
- */
756
- diagnoseCardSpace(threshold?: number): Promise<CardSpaceDiagnosis | null>;
757
- /**
758
- * Show user's per-tag ELO data. Useful for diagnosing hierarchy gate status.
759
- *
760
- * @param tagFilter - Optional glob pattern(s) to filter tags.
761
- * Examples: 'gpc:expose:*', 'gpc:intro:t-T', ['gpc:expose:t-*', 'gpc:intro:t-*']
762
- */
763
- showTagElo(tagFilter?: string | string[]): Promise<void>;
764
- /**
765
- * Toggle the full-screen UI debugger.
766
- */
767
- ui(): void;
768
- /**
769
- * Internal UI helpers
770
- * @internal
771
- */
772
- _selectRun(index: number): void;
773
- /**
774
- * Internal UI helpers
775
- * @internal
776
- */
777
- _setSearch(query: string): void;
778
- /**
779
- * Internal UI helpers
780
- * @internal
781
- */
782
- _copyConfig(runId: string, btn?: HTMLElement): void;
783
- /**
784
- * Internal UI helpers
785
- * @internal
786
- *
787
- * Copies an "abridged" view of results: just the selected cards with their
788
- * generator, origin, final score, and the top provenance reason. Designed
789
- * for pasting into bug reports without flooding with full provenance.
790
- */
791
- _copyResults(runId: string, btn?: HTMLElement): void;
792
- /**
793
- * Show help.
794
- */
795
- help(): void;
796
- };
797
- /**
798
- * Mount the debug API on window.skuilder.pipeline
799
- */
800
- declare function mountPipelineDebugger(): void;
801
-
802
- /**
803
- * Durable per-sitting record. Join target for `CardRecord.sessionId`.
804
- *
805
- * Written twice: `open` at `prepareSession()`, overwritten at termination.
806
- */
807
- interface StudySessionDoc {
808
- /** `SESSION::{courseId}::{userId}::{sessionId}` */
809
- _id: string;
810
- _rev?: string;
811
- docType: DocType.STUDY_SESSION;
812
- sessionId: string;
813
- courseId: string;
814
- userId: string;
815
- /** Session construction time, not first-card time. */
816
- startTime: string;
817
- endTime?: string;
818
- /**
819
- * `closed` — ran to natural termination.
820
- * `abandoned` — host tore the study view down mid-session.
821
- * `open` — never closed: tab closed, reload, crash. No tally or end state.
822
- */
823
- status: 'open' | 'closed' | 'abandoned';
824
- plannedSeconds: number;
825
- config: {
826
- defaultBatchLimit: number;
827
- sourceCount: number;
828
- initHints?: ReplanHints | null;
829
- };
830
- /**
831
- * The code this session ran on: the framework's version (`'dev'` when run
832
- * from source) and the host app's, if it reported one (`appVersion` in the
833
- * data-layer config). Strategy and content versions are stamped per run.
834
- * Absent on sessions recorded before this shipped.
835
- */
836
- versions?: {
837
- framework: string;
838
- app?: string;
839
- };
840
- /** Queue depths after the bootstrap run, before the first draw. */
841
- initialQueues: {
842
- supplyQ: number;
843
- failedQ: number;
844
- };
845
- tally?: {
846
- /** Distinct cards; a re-presented failed card counts once. */
847
- cardsPresented: number;
848
- /** Total responses, including repeat attempts on one card. */
849
- responses: number;
850
- correct: number;
851
- incorrect: number;
852
- failedQRemaining: number;
853
- secondsRemaining: number;
854
- };
855
- /** Bootstrap run plus every replan, in execution order. */
856
- runs?: StudySessionRunSummary[];
857
- /**
858
- * Per-response ELO exchanges, in the order they resolved. One entry per
859
- * ELO-updating response (first attempt of a presentation; retries don't
860
- * move ELO). Flushed at close from an in-memory log — so `open`/`abandoned`
861
- * sessions that never reached the close write carry none, and a same-card
862
- * event still in flight at close may be missing. Absent on sessions
863
- * recorded before this shipped.
864
- */
865
- eloEvents?: SessionEloEvent[];
866
- finalHints?: ReplanHints | null;
867
- stateAtStart?: SessionStateSnapshot;
868
- stateAtEnd?: SessionStateSnapshot;
869
- }
870
- interface StudySessionRunSummary {
871
- /** Joins to `PipelineRunReport.runId` while that run is still in memory. */
872
- runId: string;
873
- at: string;
874
- /** `'bootstrap'`, a replan's label, or `'(auto)'`. */
875
- label: string;
876
- mode?: string;
877
- generatedCount: number;
878
- finalCount: number;
879
- reviewsSelected: number;
880
- newSelected: number;
881
- /** User's global ELO at the moment this run's pipeline executed. */
882
- userElo?: number;
883
- /** Per-generator contribution (name, card/new/review counts, top score). */
884
- generators?: GeneratorSummary[];
885
- /** Per-filter impact (boosted / penalized / passed / removed). */
886
- filters?: FilterImpact[];
887
- /** Ephemeral replan hints in force for this run (what the navigator was told). */
888
- hints?: ReplanHints;
889
- /** Compact summary of the scored-but-dropped candidate tail. */
890
- discardedTail?: {
891
- count: number;
892
- scoreRange?: [number, number];
893
- eloRange?: [number, number];
894
- note: string;
895
- };
896
- /**
897
- * The selected cards, then the top few unselected ones, each in score
898
- * order. The lowest selected score against the first runner-up is this
899
- * run's cutoff.
900
- */
901
- cards?: StudySessionRunCard[];
902
- /**
903
- * The unselected non-review cards most worth explaining, with their
904
- * score-changing provenance. See `PipelineRunReport.unselectedNew`.
905
- */
906
- unselectedNew?: {
907
- nextInLine?: StudySessionRunCardTrail;
908
- topGenerated?: StudySessionRunCardTrail;
909
- };
910
- /** The regulator stage's readings: review mass and intake, each with its multiplier (0.2.29+). */
911
- regulators?: RegulatorReading[];
912
- /** What the run ran on: the strategy docs' hash and the course's content version. */
913
- versions?: RunVersions;
914
- }
915
- /** A card as persisted on a run. `origin` is as counted in `newSelected`/`reviewsSelected`. */
916
- interface StudySessionRunCard {
917
- cardId: string;
918
- /**
919
- * `'review'`: a scheduled review. `'new'`: anything else. `'unknown'` only on
920
- * older runs, which counted prescribed and hint-required cards as neither.
921
- */
922
- origin: 'new' | 'review' | 'unknown';
923
- /**
924
- * The strategy that produced the card. Absent if a hint injected it (older
925
- * runs name the hint here instead).
926
- */
927
- generator?: string;
928
- /** The hint that made the card mandatory, if one did. Its source, over `generator`. */
929
- required?: string;
930
- /** Final score; null for a mandatory (required) card, whose score is infinite. */
931
- score: number | null;
932
- selected: boolean;
933
- }
934
- /**
935
- * A card plus the provenance entries that changed its score, in order.
936
- * `'passed'` entries are dropped. Strategy ids are dropped (the name is kept).
937
- */
938
- interface StudySessionRunCardTrail extends StudySessionRunCard {
939
- trail: Array<{
940
- strategyName: string;
941
- action: StrategyContribution['action'];
942
- score: number;
943
- reason: string;
944
- }>;
945
- }
946
- /**
947
- * One learner↔card ELO exchange, captured at the moment it resolved so a
948
- * session can be read as an ELO ledger (why did 88% accuracy net -1?). The
949
- * exchange is otherwise write-once-and-discard: only the updated aggregates
950
- * survive on the user/card docs, and ELO is path-dependent, so a response's
951
- * move can't be reconstructed after the fact. Joins to a `CardRecord` by
952
- * `cardId` + nearest `at`.
953
- */
954
- interface SessionEloEvent {
955
- /** Card this exchange was for. */
956
- cardId: string;
957
- /** ISO time the exchange resolved (fires just after the response record). */
958
- at: string;
959
- /**
960
- * Global performance in [0,1] that drove the update. Note this is the ELO
961
- * `userScore`, not raw correctness: the numeric path maps a correct answer
962
- * to `0.5 + performance/2` (so a plain correct is 1.0, a graded-correct
963
- * less) and a miss to 0; the tagged path uses `_global`.
964
- */
965
- userScore: number;
966
- /** Learner global ELO before → after this response. */
967
- global: {
968
- before: number;
969
- after: number;
970
- };
971
- /** Card global ELO before → after (absent if the card ELO was unreadable). */
972
- card?: {
973
- before: number;
974
- after: number;
975
- };
976
- /**
977
- * Per-tag learner ELO before → after, for every tag the exchange touched.
978
- * `score` is the per-tag performance applied, or null for a count-only
979
- * exposure tag (`gpc:expose:*`) that increments count without moving ELO.
980
- */
981
- tags?: Record<string, {
982
- before: number;
983
- after: number;
984
- score: number | null;
985
- }>;
986
- }
987
- /**
988
- * Host-defined learner state at a session boundary. Keep it thin — this is
989
- * written on every session, and the deltas between consecutive snapshots are
990
- * what it's read for.
991
- */
992
- type SessionStateSnapshot = Record<string, unknown>;
993
- /**
994
- * Invoked at session open and close. Errors and slow calls are absorbed by
995
- * the controller.
996
- */
997
- type SessionStateSnapshotProvider = (phase: 'start' | 'end') => SessionStateSnapshot | Promise<SessionStateSnapshot>;
998
- /** Stable across the open and close writes, unlike a timestamp-keyed id. */
999
- declare function makeStudySessionId(courseId: string, userId: string, sessionId: string): string;
1000
- declare function newSessionId(): string;
1001
-
1002
- /**
1003
- * User database hydration.
1004
- *
1005
- * A logged-in user's data lives in a remote CouchDB `userdb-<hex>` and is
1006
- * mirrored into a browser-local PouchDB. On a device that has never synced
1007
- * that account, the local mirror starts EMPTY — and every local read
1008
- * (`getStrategyState`, `getConfig`, `getCourseRegistrationsDoc`, ...) answers
1009
- * "no such document", which is indistinguishable from "brand new user".
1010
- *
1011
- * Consumers acting on that answer render a new-user experience to an existing
1012
- * user, and — worse — compute writes from empty state that then lose to the
1013
- * real remote document at replication time. Hydration closes that window by
1014
- * pulling the account's documents down BEFORE the user object is handed out.
1015
- */
1016
- /**
1017
- * Where a user's local database stands relative to its remote counterpart.
1018
- *
1019
- * Only `failed` is a blocking condition. `stale` explicitly is not: it means a
1020
- * full pull completed on this device previously, so local data is real and
1021
- * merely possibly-behind — live sync closes the gap in the background. That is
1022
- * the ordinary offline case and it must keep working.
1023
- */
1024
- type UserHydrationState =
1025
- /** Guest, or a data layer with no remote. There is nothing to hydrate from. */
1026
- 'not-required'
1027
- /** Initial pull in flight. */
1028
- | 'hydrating'
1029
- /** Initial pull completed this session. Local is a faithful mirror. */
1030
- | 'hydrated'
1031
- /**
1032
- * A previous session completed a full pull on this device (recorded by the
1033
- * `_local/hydration` marker). Local data is real; live sync is catching up.
1034
- */
1035
- | 'stale'
1036
- /**
1037
- * No pull has ever completed on this device and one could not be completed
1038
- * now. Local reads CANNOT be trusted to mean "no data" — callers must not
1039
- * present a new-user experience or compute writes from what they read.
1040
- */
1041
- | 'failed';
1042
- /**
1043
- * Hydration state plus observability detail.
1044
- *
1045
- * Shaped to mirror `CourseSyncStatus` in CourseSyncService, which solves the
1046
- * same problem for course databases.
1047
- */
1048
- interface UserHydrationStatus {
1049
- state: UserHydrationState;
1050
- /** Documents pulled by the initial replication (set when state is `hydrated`). */
1051
- docsWritten?: number;
1052
- /** Wall-clock duration of the initial pull attempt, successful or not. */
1053
- durationMs?: number;
1054
- /** Failure detail, set when state is `failed`. */
1055
- error?: string;
1056
- }
1057
- /**
1058
- * ID of the per-device marker recording that a full pull once completed.
1059
- *
1060
- * `_local/*` documents are deliberately excluded from replication by CouchDB
1061
- * and PouchDB alike, which is exactly the semantics wanted here: the marker
1062
- * describes THIS device's mirror, and must never travel to another one.
1063
- */
1064
- declare const HYDRATION_MARKER_ID = "_local/hydration";
1065
- /**
1066
- * Payload of {@link HYDRATION_MARKER_ID}.
1067
- */
1068
- interface HydrationMarker {
1069
- _id: typeof HYDRATION_MARKER_ID;
1070
- _rev?: string;
1071
- /** Account the mirror was hydrated for — guards against a stale marker after an account switch. */
1072
- username: string;
1073
- /** ISO timestamp of the most recent successful full pull. */
1074
- hydratedAt: string;
1075
- }
1076
-
1077
- type Update<T> = Partial<T> | ((x: T) => T);
1078
-
1079
- interface DocumentUpdater {
1080
- update<T extends PouchDB.Core.Document<object>>(id: string, update: Update<T>): Promise<T>;
1081
- }
1082
- /**
1083
- * Returns the minimum number of seconds that should pass before a
1084
- * card is redisplayed for review / practice.
1085
- *
1086
- * @param cardHistory The user's history working with the given card
1087
- */
1088
- declare function newInterval(user: DocumentUpdater, cardHistory: CardHistory<CardRecord>): number;
1089
- /**
1090
- * Number of trailing consecutive correct records (retries within a single
1091
- * presentation count as separate records). Exported so the persisted
1092
- * `CardHistory.streak` can be kept in step with this derivation.
1093
- */
1094
- declare function getStreak(records: QuestionRecord[]): number;
1095
- /**
1096
- * Total number of incorrect records on the card. Exported so the persisted
1097
- * `CardHistory.lapses` can be kept in step with this derivation.
1098
- */
1099
- declare function getLapses(records: QuestionRecord[]): number;
1100
-
1101
- /**
1102
- * Read-only user data operations
1103
- */
1104
- interface UserDBReader {
1105
- get<T>(id: string): Promise<T & PouchDB.Core.RevisionIdMeta>;
1106
- getUsername(): string;
1107
- isLoggedIn(): boolean;
1108
- /**
1109
- * How far this device's local mirror of the user's data can be trusted,
1110
- * as of right now.
1111
- *
1112
- * Reads answer from the local mirror, so on a device that has never synced
1113
- * this account "document not found" does not mean "no such data". Anything
1114
- * that would otherwise interpret an empty read as a new user should check
1115
- * for `failed` first. See {@link UserHydrationStatus}.
1116
- *
1117
- * Can return `hydrating`; use {@link awaitHydration} to decide on a settled
1118
- * answer instead of a snapshot.
1119
- */
1120
- hydrationStatus(): UserHydrationStatus;
1121
- /**
1122
- * The hydration status once settled — never `hydrating`.
1123
- *
1124
- * Resolves immediately unless a pull is in flight. Prefer this over
1125
- * hydrationStatus() wherever the answer gates behaviour, such as a route
1126
- * guard that may run while a login is still completing.
1127
- */
1128
- awaitHydration(): Promise<UserHydrationStatus>;
1129
- /**
1130
- * Get user configuration
1131
- */
1132
- getConfig(): Promise<UserConfig>;
1133
- /**
1134
- * Get cards that the user has seen
1135
- */
1136
- getSeenCards(courseId?: string): Promise<string[]>;
1137
- /**
1138
- * Get cards that are actively scheduled for review
1139
- */
1140
- getActiveCards(): Promise<QualifiedCardID[]>;
1141
- /**
1142
- * Get user's course registrations
1143
- */
1144
- getCourseRegistrationsDoc(): Promise<CourseRegistrationDoc>;
1145
- /**
1146
- * Get the registration doc for a specific course.
1147
- * @param courseId
1148
- */
1149
- getCourseRegDoc(courseId: string): Promise<CourseRegistration>;
1150
- /**
1151
- * Get user's active courses
1152
- */
1153
- getActiveCourses(): Promise<CourseRegistration[]>;
1154
- /**
1155
- * Get user's pending reviews
1156
- */
1157
- getPendingReviews(courseId?: string): Promise<ScheduledCard[]>;
1158
- /** Study-session records for a course, newest session-start first. */
1159
- getStudySessions(courseId?: string): Promise<StudySessionDoc[]>;
1160
- /**
1161
- * Get all scheduled reviews due within the next `daysCount` days —
1162
- * including ones not yet due. `getPendingReviews` is the `daysCount = 0`
1163
- * special case: it returns only reviews already due, so a review scheduled
1164
- * moments ago (necessarily in the future) will never appear in it.
1165
- */
1166
- getReviewsForcast(daysCount: number, courseId?: string): Promise<ScheduledCard[]>;
1167
- getActivityRecords(): Promise<ActivityRecord[]>;
1168
- /**
1169
- * Get strategy-specific state for a course.
1170
- *
1171
- * Strategies use this to persist preferences, learned patterns, or temporal
1172
- * tracking data across sessions. Each strategy owns its own namespace.
1173
- *
1174
- * @deprecated Use `getCourseInterface(courseId).getStrategyState(strategyKey)` instead.
1175
- * Direct use bypasses course-scoping safety — the courseId parameter is unguarded,
1176
- * allowing accidental cross-course data access. The course-scoped interface binds
1177
- * courseId once at construction.
1178
- *
1179
- * @param courseId - The course this state applies to
1180
- * @param strategyKey - Unique key identifying the strategy (typically class name)
1181
- * @returns The strategy's data payload, or null if no state exists
1182
- */
1183
- getStrategyState<T>(courseId: string, strategyKey: string): Promise<T | null>;
1184
- /**
1185
- * Get user's classroom registrations
1186
- */
1187
- getUserClassrooms(): Promise<ClassroomRegistrationDoc>;
1188
- /**
1189
- * Get user's active classes
1190
- */
1191
- getActiveClasses(): Promise<string[]>;
1192
- getCourseInterface(courseId: string): Promise<UsrCrsDataInterface>;
1193
- }
1194
- /**
1195
- * User data mutation operations
1196
- */
1197
- interface UserDBWriter extends DocumentUpdater {
1198
- /**
1199
- * Update user configuration
1200
- */
1201
- setConfig(config: Partial<UserConfig>): Promise<void>;
1202
- /**
1203
- * Record a user's interaction with a card
1204
- */
1205
- putCardRecord<T extends CardRecord>(record: T): Promise<CardHistory<CardRecord>>;
1206
- /**
1207
- * Register user for a course
1208
- */
1209
- registerForCourse(courseId: string, previewMode?: boolean): Promise<PouchDB.Core.Response>;
1210
- /**
1211
- * Drop a course registration
1212
- */
1213
- dropCourse(courseId: string, dropStatus?: string): Promise<PouchDB.Core.Response>;
1214
- /**
1215
- * Schedule a card for review
1216
- */
1217
- scheduleCardReview(review: {
1218
- user: string;
1219
- course_id: string;
1220
- card_id: string;
1221
- time: Moment;
1222
- scheduledFor: 'course' | 'classroom';
1223
- schedulingAgentId: string;
1224
- }): Promise<void>;
1225
- /**
1226
- * Remove a scheduled card review
1227
- */
1228
- removeScheduledCardReview(reviewId: string): Promise<void>;
1229
- /**
1230
- * Register user for a classroom
1231
- */
1232
- registerForClassroom(classId: string, registerAs: 'student' | 'teacher' | 'aide' | 'admin'): Promise<PouchDB.Core.Response>;
1233
- /**
1234
- * Drop user from classroom
1235
- */
1236
- dropFromClassroom(classId: string): Promise<PouchDB.Core.Response>;
1237
- /**
1238
- * Update user's ELO rating for a course
1239
- */
1240
- updateUserElo(courseId: string, elo: CourseElo): Promise<PouchDB.Core.Response>;
1241
- /**
1242
- * Reset all user data (progress, registrations, etc.) while preserving authentication
1243
- */
1244
- resetUserData(): Promise<{
1245
- status: Status;
1246
- error?: string;
1247
- }>;
1248
- /**
1249
- * Store strategy-specific state for a course.
1250
- *
1251
- * Strategies use this to persist preferences, learned patterns, or temporal
1252
- * tracking data across sessions. Each strategy owns its own namespace.
1253
- *
1254
- * @deprecated Use `getCourseInterface(courseId).putStrategyState(strategyKey, data)` instead.
1255
- * Direct use bypasses course-scoping safety — the courseId parameter is unguarded,
1256
- * allowing accidental cross-course data writes. The course-scoped interface binds
1257
- * courseId once at construction.
1258
- *
1259
- * @param courseId - The course this state applies to
1260
- * @param strategyKey - Unique key identifying the strategy (typically class name)
1261
- * @param data - The strategy's data payload to store
1262
- */
1263
- putStrategyState<T>(courseId: string, strategyKey: string, data: T): Promise<void>;
1264
- /**
1265
- * Delete strategy-specific state for a course.
1266
- *
1267
- * @deprecated Use `getCourseInterface(courseId).deleteStrategyState(strategyKey)` instead.
1268
- * Direct use bypasses course-scoping safety.
1269
- *
1270
- * @param courseId - The course this state applies to
1271
- * @param strategyKey - Unique key identifying the strategy (typically class name)
1272
- */
1273
- deleteStrategyState(courseId: string, strategyKey: string): Promise<void>;
1274
- /**
1275
- * Record a user learning outcome for evolutionary orchestration.
1276
- */
1277
- putUserOutcome(record: UserOutcomeRecord): Promise<void>;
1278
- /** Write or overwrite a study-session record. */
1279
- putStudySession(doc: StudySessionDoc): Promise<void>;
1280
- }
1281
- /**
1282
- * Authentication and account management operations
1283
- */
1284
- interface UserDBAuthenticator {
1285
- /**
1286
- * Create a new user account
1287
- */
1288
- createAccount(username: string, password: string): Promise<{
1289
- status: Status;
1290
- error: string;
1291
- }>;
1292
- /**
1293
- * Log in as a user
1294
- */
1295
- login(username: string, password: string): Promise<{
1296
- ok: boolean;
1297
- name?: string;
1298
- roles?: string[];
1299
- }>;
1300
- /**
1301
- * Log out the current user
1302
- */
1303
- logout(): Promise<{
1304
- ok: boolean;
1305
- }>;
1306
- /**
1307
- * Adopt a session established outside this client (e.g. third-party
1308
- * sign-in completed server-side), optionally migrating guest data.
1309
- */
1310
- adoptSession(opts: {
1311
- migrateGuestData: boolean;
1312
- }): Promise<{
1313
- ok: boolean;
1314
- error?: string;
1315
- username?: string;
1316
- }>;
1317
- }
1318
- /**
1319
- * Complete user database interface - combines all user operations
1320
- * This maintains backward compatibility with existing code
1321
- */
1322
- interface UserDBInterface extends UserDBReader, UserDBWriter, UserDBAuthenticator {
1323
- }
1324
- interface UserCourseSettings {
1325
- [setting: string]: string | number | boolean;
1326
- }
1327
- interface UserCourseSetting {
1328
- key: string;
1329
- value: string | number | boolean;
1330
- }
1331
- interface UsrCrsDataInterface {
1332
- getScheduledReviewCount(): Promise<number>;
1333
- getCourseSettings(): Promise<UserCourseSettings>;
1334
- updateCourseSettings(updates: UserCourseSetting[]): void;
1335
- /**
1336
- * Get strategy-specific state for this course.
1337
- *
1338
- * Course-scoped alternative to `UserDBInterface.getStrategyState()`.
1339
- * The courseId is bound at construction via `getCourseInterface(courseId)`,
1340
- * so callers cannot accidentally access another course's state.
1341
- *
1342
- * @param strategyKey - Unique key identifying the state document
1343
- * @returns The state payload, or null if no state exists
1344
- */
1345
- getStrategyState<T>(strategyKey: string): Promise<T | null>;
1346
- /**
1347
- * Store strategy-specific state for this course.
1348
- *
1349
- * Course-scoped alternative to `UserDBInterface.putStrategyState()`.
1350
- *
1351
- * @param strategyKey - Unique key identifying the state document
1352
- * @param data - The state payload to store
1353
- */
1354
- putStrategyState<T>(strategyKey: string, data: T): Promise<void>;
1355
- /**
1356
- * Delete strategy-specific state for this course.
1357
- *
1358
- * Course-scoped alternative to `UserDBInterface.deleteStrategyState()`.
1359
- *
1360
- * @param strategyKey - Unique key identifying the state document
1361
- */
1362
- deleteStrategyState(strategyKey: string): Promise<void>;
1363
- }
1364
- type ClassroomRegistrationDesignation = 'student' | 'teacher' | 'aide' | 'admin';
1365
- interface ClassroomRegistration {
1366
- classID: string;
1367
- registeredAs: ClassroomRegistrationDesignation;
1368
- }
1369
- interface ClassroomRegistrationDoc {
1370
- registrations: ClassroomRegistration[];
1371
- }
1372
-
1373
- /**
1374
- * Shared context available to all filters in a pipeline.
1375
- *
1376
- * Built once per getWeightedCards() call and passed to each filter.
1377
- * This avoids repeated lookups for common data like user ELO.
1378
- */
1379
- interface FilterContext {
1380
- /** User database interface */
1381
- user: UserDBInterface;
1382
- /** Course database interface */
1383
- course: CourseDBInterface;
1384
- /** User's global ELO score for this course */
1385
- userElo: number;
1386
- /** User's full ELO for this course: global and per tag. Absent if it couldn't be read. */
1387
- userCourseElo?: CourseElo;
1388
- /** Orchestration context for evolutionary weighting */
1389
- orchestration?: OrchestrationContext;
1390
- }
1391
- /**
1392
- * A filter that transforms a list of weighted cards.
1393
- *
1394
- * Filters are pure transforms - they receive cards and context,
1395
- * and return a modified list of cards. No delegate wrapping,
1396
- * no side effects beyond provenance tracking.
1397
- *
1398
- * ## Implementation Guidelines
1399
- *
1400
- * 1. **Append provenance**: Every filter should add a StrategyContribution
1401
- * entry documenting its decision for each card.
1402
- *
1403
- * 2. **Use multipliers**: Adjust scores by multiplying, not replacing.
1404
- * This ensures filter order doesn't matter.
1405
- *
1406
- * 3. **Score 0 for exclusion**: To exclude a card, set score to 0.
1407
- * Don't filter it out - let provenance show why it was excluded.
1408
- *
1409
- * 4. **Don't sort**: The Pipeline handles final sorting.
1410
- * Filters just transform scores.
1411
- *
1412
- * ## Example Implementation
1413
- *
1414
- * ```typescript
1415
- * const myFilter: CardFilter = {
1416
- * name: 'My Filter',
1417
- * async transform(cards, context) {
1418
- * return cards.map(card => {
1419
- * const multiplier = computeMultiplier(card, context);
1420
- * const newScore = card.score * multiplier;
1421
- * return {
1422
- * ...card,
1423
- * score: newScore,
1424
- * provenance: [...card.provenance, {
1425
- * strategy: 'myFilter',
1426
- * strategyName: 'My Filter',
1427
- * strategyId: 'MY_FILTER',
1428
- * action: multiplier < 1 ? 'penalized' : 'passed',
1429
- * score: newScore,
1430
- * reason: 'Explanation of decision'
1431
- * }]
1432
- * };
1433
- * });
1434
- * }
1435
- * };
1436
- * ```
1437
- */
1438
- /**
1439
- * What a filter's penalties mean. A `gate` says a card isn't ready yet
1440
- * (prerequisites, lessons, unlocks); a `signal` expresses preference
1441
- * (priority, interference, ELO distance).
1442
- */
1443
- type FilterKind = 'gate' | 'signal';
1444
- interface CardFilter {
1445
- /** Human-readable name for this filter */
1446
- name: string;
1447
- /**
1448
- * Regulators lift only new cards that no gate penalized, so pressure can't
1449
- * override "not ready". Undeclared filters count as gates: a penalty of
1450
- * unknown meaning shouldn't be overridden by pressure.
1451
- */
1452
- kind?: FilterKind;
1453
- /**
1454
- * Applies to live runs only. `forecast` and `diagnoseCardSpace` start every
1455
- * card at 1.0 without a generator, and skip these filters.
1456
- */
1457
- liveOnly?: boolean;
1458
- /**
1459
- * Transform a list of weighted cards.
1460
- *
1461
- * @param cards - Cards to transform (already scored by generator)
1462
- * @param context - Shared context (user, course, userElo, etc.)
1463
- * @returns Transformed cards with updated scores and provenance
1464
- */
1465
- transform(cards: WeightedCard[], context: FilterContext): Promise<WeightedCard[]>;
1466
- }
1467
- /**
1468
- * Factory function type for creating filters from configuration.
1469
- *
1470
- * Used by PipelineAssembler to instantiate filters from strategy documents.
1471
- */
1472
- type CardFilterFactory<TConfig = unknown> = (config: TConfig) => CardFilter;
1473
-
1474
- /**
1475
- * Type for navigator constructor functions.
1476
- */
1477
- type NavigatorConstructor = new (user: UserDBInterface, course: CourseDBInterface, strategyData: ContentNavigationStrategyData) => ContentNavigator;
1478
- /**
1479
- * Register a navigator implementation.
1480
- *
1481
- * Call this to make a navigator available for instantiation by
1482
- * ContentNavigator.create() without relying on dynamic imports.
1483
- *
1484
- * Passing a `role` is optional for built-in navigators (whose roles are in
1485
- * the hardcoded `NavigatorRoles` record), but **required** for consumer-
1486
- * defined navigators that need to participate in pipeline assembly.
1487
- *
1488
- * @param implementingClass - The class name (e.g., 'elo', 'letterGatingFilter')
1489
- * @param constructor - The navigator class constructor
1490
- * @param role - Optional pipeline role (GENERATOR or FILTER)
1491
- */
1492
- declare function registerNavigator(implementingClass: string, constructor: NavigatorConstructor, role?: NavigatorRole): void;
1493
- /**
1494
- * Get a navigator constructor from the registry.
1495
- *
1496
- * @param implementingClass - The class name to look up
1497
- * @returns The constructor, or undefined if not registered
1498
- */
1499
- declare function getRegisteredNavigator(implementingClass: string): NavigatorConstructor | undefined;
1500
- /**
1501
- * Check if a navigator is registered.
1502
- *
1503
- * @param implementingClass - The class name to check
1504
- * @returns true if registered, false otherwise
1505
- */
1506
- declare function hasRegisteredNavigator(implementingClass: string): boolean;
1507
- /**
1508
- * Get the registered role for a navigator, if one was provided at registration.
1509
- *
1510
- * @param implementingClass - The class name to look up
1511
- * @returns The role, or undefined if not registered or no role was specified
1512
- */
1513
- declare function getRegisteredNavigatorRole(implementingClass: string): NavigatorRole | undefined;
1514
- /**
1515
- * A registered filter's declared kind (see `CardFilter.kind`): the static
1516
- * `kind` on its class. Undefined if unregistered or undeclared; undeclared
1517
- * filters count as gates at run time.
1518
- * @param implementingClass - The class name to look up
1519
- */
1520
- declare function getRegisteredFilterKind(implementingClass: string): FilterKind | undefined;
1521
- /**
1522
- * Get all registered navigator names.
1523
- * Useful for debugging and testing.
1524
- */
1525
- declare function getRegisteredNavigatorNames(): string[];
1526
- /**
1527
- * Initialize the navigator registry with all built-in navigators.
1528
- *
1529
- * This function dynamically imports all standard navigator implementations
1530
- * and registers them. Call this once at application startup to ensure
1531
- * all navigators are available.
1532
- *
1533
- * In test environments, this may need to be called explicitly before
1534
- * using ContentNavigator.create().
1535
- */
1536
- declare function initializeNavigatorRegistry(): Promise<void>;
1537
- /**
1538
- * Tracks a single strategy's contribution to a card's final score.
1539
- *
1540
- * Each strategy in the pipeline adds a StrategyContribution entry to the
1541
- * card's provenance array, creating an audit trail of scoring decisions.
1542
- */
1543
- interface StrategyContribution {
1544
- /**
1545
- * Strategy type (implementing class name).
1546
- * Examples: 'elo', 'hierarchyDefinition', 'interferenceMitigator'
1547
- */
1548
- strategy: string;
1549
- /**
1550
- * Human-readable name identifying this specific strategy instance.
1551
- * Extracted from ContentNavigationStrategyData.name.
1552
- * Courses may have multiple instances of the same strategy type with
1553
- * different configurations.
1554
- *
1555
- * Examples:
1556
- * - "ELO (default)"
1557
- * - "Interference: b/d/p confusion"
1558
- * - "Interference: phonetic confusables"
1559
- * - "Priority: Common letters first"
1560
- */
1561
- strategyName: string;
1562
- /**
1563
- * Unique database document ID for this strategy instance.
1564
- * Extracted from ContentNavigationStrategyData._id.
1565
- * Use this to fetch the full strategy configuration document.
1566
- *
1567
- * Examples:
1568
- * - "NAVIGATION_STRATEGY-ELO-default"
1569
- * - "NAVIGATION_STRATEGY-interference-bdp"
1570
- * - "NAVIGATION_STRATEGY-priority-common-letters"
1571
- */
1572
- strategyId: string;
1573
- /**
1574
- * What the strategy did:
1575
- * - 'generated': Strategy produced this card (generators only)
1576
- * - 'passed': Strategy evaluated but didn't change score (transparent pass-through)
1577
- * - 'boosted': Strategy increased the score
1578
- * - 'penalized': Strategy decreased the score
1579
- */
1580
- action: 'generated' | 'passed' | 'boosted' | 'penalized';
1581
- /** Score after this strategy's processing */
1582
- score: number;
1583
- /**
1584
- * The effective weight applied for this strategy instance.
1585
- * If using evolutionary orchestration, this includes deviation.
1586
- * If omitted, implies weight 1.0 (legacy behavior).
1587
- */
1588
- effectiveWeight?: number;
1589
- /**
1590
- * The deviation factor applied to this user's cohort for this strategy.
1591
- * Range [-1.0, 1.0].
1592
- */
1593
- deviation?: number;
1594
- /**
1595
- * Human-readable explanation of the strategy's decision.
1596
- *
1597
- * Examples:
1598
- * - "ELO distance 75, new card"
1599
- * - "Prerequisites met: letter-sounds"
1600
- * - "Interferes with immature tag 'd' (decay 0.8)"
1601
- * - "High-priority tag 's' (0.95) → boost 1.15x"
1602
- *
1603
- * Required for transparency - silent adjusters are anti-patterns.
1604
- */
1605
- reason: string;
1606
- }
1607
- /**
1608
- * A card with a suitability score and provenance trail.
1609
- *
1610
- * Scores range from 0-1:
1611
- * - 1.0 = fully suitable
1612
- * - 0.0 = hard filter (e.g., prerequisite not met)
1613
- * - 0.5 = neutral
1614
- * - Intermediate values = soft preference
1615
- *
1616
- * Provenance tracks the scoring pipeline:
1617
- * - First entry: Generator that produced the card
1618
- * - Subsequent entries: Filters that transformed the score
1619
- * - Each entry includes action and human-readable reason
1620
- */
1621
- interface WeightedCard {
1622
- cardId: string;
1623
- courseId: string;
1624
- /** Suitability score from 0-1 */
1625
- score: number;
1626
- /**
1627
- * Audit trail of strategy contributions.
1628
- * First entry is from the generator, subsequent entries from filters.
1629
- */
1630
- provenance: StrategyContribution[];
1631
- /**
1632
- * Pre-fetched tags. Populated by Pipeline before filters run.
1633
- * Filters should use this instead of querying getAppliedTags() individually.
1634
- */
1635
- tags?: string[];
1636
- /**
1637
- * Review document ID (_id from ScheduledCard).
1638
- * Present when this card originated from SRS review scheduling.
1639
- * Used by SessionController to track review outcomes and maintain review state.
1640
- */
1641
- reviewID?: string;
1642
- /**
1643
- * The card's global ELO, when the generator already knows it (the ELO
1644
- * generator reads it during retrieval). Lets the ELO distance filter skip a
1645
- * fetch.
1646
- */
1647
- cardElo?: number;
1648
- /**
1649
- * A review's SRS urgency in [0, 1] (overdueness and interval recency), set by
1650
- * the SRS generator. The review-mass regulator weighs the backlog by it.
1651
- */
1652
- reviewUrgency?: number;
1653
- }
1654
- /**
1655
- * Extract card origin from provenance trail.
1656
- *
1657
- * The first provenance entry (from the generator) indicates whether
1658
- * this is a new card, review, or failed card. We parse the reason
1659
- * string to extract this information.
1660
- *
1661
- * @param card - Card with provenance trail
1662
- * @returns Card origin ('new', 'review', or 'failed')
1663
- */
1664
- declare function getCardOrigin(card: WeightedCard): 'new' | 'review' | 'failed';
1665
- declare enum Navigators {
1666
- ELO = "elo",
1667
- SRS = "srs",
1668
- PRESCRIBED = "prescribed",
1669
- HIERARCHY = "hierarchyDefinition",
1670
- INTERFERENCE = "interferenceMitigator",
1671
- RELATIVE_PRIORITY = "relativePriority",
1672
- USER_TAG_PREFERENCE = "userTagPreference",
1673
- ELO_DISTANCE = "eloDistance"
1674
- }
1675
- /**
1676
- * Role classification for navigation strategies.
1677
- *
1678
- * - GENERATOR: Produces candidate cards with initial scores
1679
- * - FILTER: Transforms cards with score multipliers
1680
- */
1681
- declare enum NavigatorRole {
1682
- GENERATOR = "generator",
1683
- FILTER = "filter"
1684
- }
1685
- /**
1686
- * Registry mapping navigator implementations to their roles.
1687
- */
1688
- declare const NavigatorRoles: Record<Navigators, NavigatorRole>;
1689
- /**
1690
- * Check if a navigator implementation is a generator.
1691
- *
1692
- * @param impl - Navigator implementation name (e.g., 'elo', 'hierarchyDefinition')
1693
- * @returns true if the navigator is a generator, false otherwise
1694
- */
1695
- declare function isGenerator(impl: string): boolean;
1696
- /**
1697
- * Check if a navigator implementation is a filter.
1698
- *
1699
- * Checks the built-in NavigatorRoles enum first, then falls back to the
1700
- * navigator registry for consumer-registered navigators.
1701
- *
1702
- * @param impl - Navigator implementation name (e.g., 'elo', 'letterGatingFilter')
1703
- * @returns true if the navigator is a filter, false otherwise
1704
- */
1705
- declare function isFilter(impl: string): boolean;
1706
- /**
1707
- * Abstract base class for navigation strategies.
1708
- *
1709
- * This class exists primarily for backward compatibility with legacy code.
1710
- * New code should use CardGenerator or CardFilter interfaces directly.
1711
- *
1712
- * The class implements StudyContentSource for compatibility with SessionController.
1713
- * Once SessionController migrates to use getWeightedCards() exclusively,
1714
- * the legacy methods can be removed.
1715
- */
1716
- declare abstract class ContentNavigator implements StudyContentSource {
1717
- /** User interface for this navigation session */
1718
- protected user: UserDBInterface;
1719
- /** Course interface for this navigation session */
1720
- protected course: CourseDBInterface;
1721
- /** Human-readable name for this strategy instance (from ContentNavigationStrategyData.name) */
1722
- protected strategyName?: string;
1723
- /** Unique document ID for this strategy instance (from ContentNavigationStrategyData._id) */
1724
- protected strategyId?: string;
1725
- /** Evolutionary weighting configuration */
1726
- learnable?: LearnableWeight;
1727
- /** Whether to bypass deviation (manual/static weighting) */
1728
- staticWeight?: boolean;
1729
- /**
1730
- * Constructor for standard navigators.
1731
- * Call this from subclass constructors to initialize common fields.
1732
- *
1733
- * Note: CompositeGenerator and Pipeline call super() without args, then set
1734
- * user/course fields directly if needed.
1735
- */
1736
- constructor(user?: UserDBInterface, course?: CourseDBInterface, strategyData?: ContentNavigationStrategyData);
1737
- /**
1738
- * Unique key identifying this strategy for state storage.
1739
- *
1740
- * Defaults to the constructor name (e.g., "UserTagPreferenceFilter").
1741
- * Override in subclasses if multiple instances of the same strategy type
1742
- * need separate state storage.
1743
- */
1744
- protected get strategyKey(): string;
1745
- /**
1746
- * Get this strategy's persisted state for the current course.
1747
- *
1748
- * @returns The strategy's data payload, or null if no state exists
1749
- * @throws Error if user or course is not initialized
1750
- */
1751
- protected getStrategyState<T>(): Promise<T | null>;
1752
- /**
1753
- * Persist this strategy's state for the current course.
1754
- *
1755
- * @param data - The strategy's data payload to store
1756
- * @throws Error if user or course is not initialized
1757
- */
1758
- protected putStrategyState<T>(data: T): Promise<void>;
1759
- /**
1760
- * Factory method to create navigator instances.
1761
- *
1762
- * First checks the navigator registry for a pre-registered constructor.
1763
- * If not found, falls back to dynamic import (for custom navigators).
1764
- *
1765
- * For reliable operation in test environments, call initializeNavigatorRegistry()
1766
- * before using this method.
1767
- *
1768
- * @param user - User interface
1769
- * @param course - Course interface
1770
- * @param strategyData - Strategy configuration document
1771
- * @returns the runtime object used to steer a study session.
1772
- */
1773
- static create(user: UserDBInterface, course: CourseDBInterface, strategyData: ContentNavigationStrategyData): Promise<ContentNavigator>;
1774
- /**
1775
- * Get cards with suitability scores and provenance trails.
1776
- *
1777
- * **This is the PRIMARY API for navigation strategies.**
1778
- *
1779
- * Returns cards ranked by suitability score (0-1). Higher scores indicate
1780
- * better candidates for presentation. Each card includes a provenance trail
1781
- * documenting how strategies contributed to the final score.
1782
- *
1783
- * ## Implementation Required
1784
- * All navigation strategies MUST override this method. The base class does
1785
- * not provide a default implementation.
1786
- *
1787
- * ## For Generators
1788
- * Override this method to generate candidates and compute scores based on
1789
- * your strategy's logic (e.g., ELO proximity, review urgency). Create the
1790
- * initial provenance entry with action='generated'.
1791
- *
1792
- * ## For Filters
1793
- * Filters should implement the CardFilter interface instead and be composed
1794
- * via Pipeline. Filters do not directly implement getWeightedCards().
1795
- *
1796
- * @param limit - Maximum cards to return
1797
- * @returns Cards sorted by score descending, with provenance trails
1798
- */
1799
- getWeightedCards(_limit: number): Promise<GeneratorResult>;
1800
- /**
1801
- * Set ephemeral hints for the next pipeline run.
1802
- * No-op for non-Pipeline navigators. Pipeline overrides this.
1803
- */
1804
- setEphemeralHints(_hints: ReplanHints): void;
1805
- }
1806
-
1807
- /**
1808
- * Typed ephemeral pipeline hints for a single run.
1809
- * All fields are optional. Tag/card patterns support `*` wildcards.
1810
- */
1811
- interface ReplanHints {
1812
- /** Multiply scores for cards matching these tag patterns. */
1813
- boostTags?: Record<string, number>;
1814
- /** Multiply scores for these specific card IDs (glob patterns). */
1815
- boostCards?: Record<string, number>;
1816
- /** Cards matching these tag patterns MUST appear in results. */
1817
- requireTags?: string[];
1818
- /** These specific card IDs MUST appear in results. */
1819
- requireCards?: string[];
1820
- /** Remove cards matching these tag patterns from results. */
1821
- excludeTags?: string[];
1822
- /** Remove these specific card IDs from results. */
1823
- excludeCards?: string[];
1824
- /**
1825
- * Debugging label threaded from the replan requester.
1826
- * Prefixed with `_` to signal it's metadata, not a scoring hint.
1827
- */
1828
- _label?: string;
1829
- }
1830
- /**
1831
- * Context available to generators when producing candidates.
1832
- *
1833
- * Built once per getWeightedCards() call by the Pipeline.
1834
- */
1835
- interface GeneratorContext {
1836
- /** User database interface */
1837
- user: UserDBInterface;
1838
- /** Course database interface */
1839
- course: CourseDBInterface;
1840
- /** User's global ELO score for this course */
1841
- userElo: number;
1842
- /** Orchestration context for evolutionary weighting */
1843
- orchestration?: OrchestrationContext;
1844
- }
1845
- /**
1846
- * Structured generator result.
1847
- *
1848
- * Generators may optionally emit one-shot replan hints alongside their
1849
- * candidate cards. This allows a generator to shape the broader pipeline
1850
- * without having to enumerate every affected support card directly.
1851
- */
1852
- interface GeneratorResult {
1853
- /** Candidate cards produced by the generator */
1854
- cards: WeightedCard[];
1855
- /** Optional one-shot hints to apply after the filter chain */
1856
- hints?: ReplanHints;
1857
- }
1858
- /**
1859
- * A generator that produces candidate cards with initial scores.
1860
- *
1861
- * Generators are the "source" stage of a navigation pipeline.
1862
- * They query the database for eligible cards and assign initial
1863
- * suitability scores based on their strategy (ELO proximity,
1864
- * review urgency, fixed order, etc.).
1865
- *
1866
- * ## Implementation Guidelines
1867
- *
1868
- * 1. **Create provenance**: Each card should have a provenance entry
1869
- * with action='generated' documenting why it was selected.
1870
- *
1871
- * 2. **Score semantics**: Higher scores = more suitable for presentation.
1872
- * Scores should be in [0, 1] range for composability.
1873
- *
1874
- * 3. **Limit handling**: Respect the limit parameter, but may over-fetch
1875
- * internally if needed for scoring accuracy.
1876
- *
1877
- * 4. **Sort before returning**: Return cards sorted by score descending.
1878
- *
1879
- * 5. **Hints are optional**: Generators may return structured results with
1880
- * `hints` when they need to apply pipeline-wide ephemeral pressure.
1881
- *
1882
- * ## Example Implementation
1883
- *
1884
- * ```typescript
1885
- * const myGenerator: CardGenerator = {
1886
- * name: 'My Generator',
1887
- * async getWeightedCards(limit, context) {
1888
- * const candidates = await fetchCandidates(context.course, limit);
1889
- * return candidates.map(c => ({
1890
- * cardId: c.id,
1891
- * courseId: context.course.getCourseID(),
1892
- * score: computeScore(c, context),
1893
- * provenance: [{
1894
- * strategy: 'myGenerator',
1895
- * strategyName: 'My Generator',
1896
- * strategyId: 'MY_GENERATOR',
1897
- * action: 'generated',
1898
- * score: computeScore(c, context),
1899
- * reason: 'Explanation of selection'
1900
- * }]
1901
- * }));
1902
- * }
1903
- * };
1904
- * ```
1905
- */
1906
- interface CardGenerator {
1907
- /** Human-readable name for this generator */
1908
- name: string;
1909
- /**
1910
- * Produce candidate cards with initial scores.
1911
- *
1912
- * @param limit - Maximum number of cards to return
1913
- * @param context - Shared context (user, course, userElo, etc.)
1914
- * @returns Cards sorted by score descending, with provenance, optionally
1915
- * accompanied by one-shot replan hints
1916
- */
1917
- getWeightedCards(limit: number, context: GeneratorContext): Promise<GeneratorResult>;
1918
- }
1919
- /**
1920
- * Factory function type for creating generators from configuration.
1921
- *
1922
- * Used by PipelineAssembler to instantiate generators from strategy documents.
1923
- */
1924
- type CardGeneratorFactory<TConfig = unknown> = (config: TConfig) => CardGenerator;
1925
-
1926
- type StudySessionFailedItem = StudySessionFailedNewItem | StudySessionFailedReviewItem;
1927
- interface StudySessionFailedNewItem extends StudySessionItem {
1928
- status: 'failed-new';
1929
- }
1930
- interface StudySessionFailedReviewItem extends StudySessionReviewItem {
1931
- status: 'failed-review';
1932
- }
1933
- interface StudySessionNewItem extends StudySessionItem {
1934
- status: 'new';
1935
- }
1936
- interface StudySessionReviewItem extends StudySessionItem {
1937
- reviewID: string;
1938
- status: 'review' | 'failed-review';
1939
- }
1940
- declare function isReview(item: StudySessionItem): item is StudySessionReviewItem;
1941
- interface StudySessionItem {
1942
- status: 'new' | 'review' | 'failed-new' | 'failed-review';
1943
- contentSourceType: 'course' | 'classroom';
1944
- contentSourceID: string;
1945
- cardID: string;
1946
- courseID: string;
1947
- elo?: number;
1948
- /**
1949
- * Pipeline suitability score at queue-build time, carried for observability
1950
- * (the debug overlay renders the now-load-bearing supply ranking). `+INF`
1951
- * marks a mandatory required card. Not used for any draw decision — the
1952
- * supplyQ is already ordered, so the controller draws front-to-back.
1953
- */
1954
- score?: number;
1955
- }
1956
- interface ContentSourceID {
1957
- type: 'course' | 'classroom';
1958
- id: string;
1959
- /**
1960
- * Optional tag filter for scoped study sessions.
1961
- * When present, creates a TagFilteredContentSource instead of a regular course source.
1962
- */
1963
- tagFilter?: TagFilter;
1964
- }
1965
- /**
1966
- * Interface for sources that provide study content to SessionController.
1967
- *
1968
- * Content sources return scored candidates via getWeightedCards(), which
1969
- * SessionController uses to populate study queues.
1970
- *
1971
- * See: packages/db/docs/navigators-architecture.md
1972
- */
1973
- interface StudyContentSource {
1974
- /**
1975
- * Get cards with suitability scores for presentation.
1976
- *
1977
- * Returns unified scored candidates that can be sorted and selected by SessionController.
1978
- * The card origin ('new' | 'review' | 'failed') is determined by provenance metadata.
1979
- *
1980
- * @param limit - Maximum number of cards to return
1981
- * @returns Cards sorted by score descending
1982
- */
1983
- getWeightedCards(limit: number): Promise<GeneratorResult>;
1984
- /**
1985
- * Get the orchestration context for this source.
1986
- * Used for recording learning outcomes.
1987
- */
1988
- getOrchestrationContext?(): Promise<OrchestrationContext>;
1989
- /**
1990
- * Set ephemeral hints for the next pipeline run.
1991
- * No-op for sources that don't support hints.
1992
- */
1993
- setEphemeralHints?(hints: ReplanHints): void;
1994
- /**
1995
- * A card was just presented. `status` is the session item's (`'new'`,
1996
- * `'review'`, `'failed-new'`, ...). Pipelines use a new card's first
1997
- * presentation to restart their intake valve's clock.
1998
- */
1999
- notePresented?(card: {
2000
- cardId: string;
2001
- courseId: string;
2002
- status: string;
2003
- }): void;
2004
- }
2005
- declare function getStudySource(source: ContentSourceID, user: UserDBInterface): Promise<StudyContentSource>;
2006
-
2007
- export { type HydrationMarker as $, type UserDBWriter as A, type UserDBAuthenticator as B, type CourseDBInterface as C, type DataLayerResult as D, type UserCourseSettings as E, type FilterKind as F, type GeneratorResult as G, type UserCourseSetting as H, type UsrCrsDataInterface as I, type ClassroomRegistrationDesignation as J, type ClassroomRegistration as K, type ClassroomRegistrationDoc as L, type SessionTrackingData as M, NavigatorRole as N, type UserConfig as O, type ActivityRecord as P, type CourseRegistration as Q, type ReplanHints as R, type StudySessionItem as S, type UserOutcomeRecord as T, type UserDBInterface as U, makeStudySessionId as V, type WeightedCard as W, newSessionId as X, type UserHydrationState as Y, type UserHydrationStatus as Z, HYDRATION_MARKER_ID as _, type CoursesDBInterface as a, type NavigatorConstructor as a0, registerNavigator as a1, getRegisteredNavigator as a2, hasRegisteredNavigator as a3, getRegisteredNavigatorRole as a4, getRegisteredFilterKind as a5, getRegisteredNavigatorNames as a6, initializeNavigatorRegistry as a7, type StrategyContribution as a8, getCardOrigin as a9, createOrchestrationContext as aA, DEFAULT_REGULATOR_CONFIG as aB, reviewWeight as aC, reviewMassReading as aD, type IntakeClockState as aE, INTAKE_CLOCK_KEY as aF, resetIntakeClock as aG, frozenMsAt as aH, intakeHours as aI, stepIntakeClock as aJ, intakeReading as aK, applyReading as aL, type DocumentUpdater as aM, newInterval as aN, getStreak as aO, getLapses as aP, Navigators as aa, NavigatorRoles as ab, isGenerator as ac, isFilter as ad, type CardFilter as ae, type FilterContext as af, type CardFilterFactory as ag, type CardGenerator as ah, type GeneratorContext as ai, type CardGeneratorFactory as aj, pipelineDebugAPI as ak, mountPipelineDebugger as al, getActivePipeline as am, setDebugSessionId as an, getRunsForSession as ao, drainCapturedRuns as ap, type PipelineRunReport as aq, type RunReportCard as ar, type GeneratorSummary as as, type FilterImpact as at, type PipelineForecaster as au, type LearnableWeight as av, type OrchestrationContext as aw, computeDeviation as ax, computeSpread as ay, computeEffectiveWeight as az, type CourseInfo as b, type ContentNavigationStrategyData as c, ContentNavigator as d, type StudySessionDoc as e, type ScheduledCard as f, type CourseRegistrationDoc as g, type SessionStateSnapshot as h, type StudySessionRunSummary as i, type RegulatorReading as j, type StudySessionRunCard as k, type RegulatorName as l, type SessionEloEvent as m, type StudySessionRunCardTrail as n, type StudyContentSource as o, type StudySessionFailedItem as p, type StudySessionFailedNewItem as q, type StudySessionFailedReviewItem as r, type StudySessionNewItem as s, type StudySessionReviewItem as t, isReview as u, type ContentSourceID as v, getStudySource as w, type SessionStateSnapshotProvider as x, type RegulatorConfig as y, type UserDBReader as z };