@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,61 +0,0 @@
1
- import { U as UserDBInterface, C as CourseDBInterface, a as CoursesDBInterface } from './contentSource-FQZcZopC.cjs';
2
- import { C as ClassroomDBInterface, A as AdminDBInterface } from './classroomDB-DLTtLZct.cjs';
3
-
4
- /**
5
- * Main factory interface for data access
6
- */
7
- interface DataLayerProvider {
8
- /**
9
- * Get the user database interface
10
- */
11
- getUserDB(): UserDBInterface;
12
- /**
13
- * Get a course database interface
14
- */
15
- getCourseDB(courseId: string): CourseDBInterface;
16
- /**
17
- * Get the courses-lookup interface
18
- */
19
- getCoursesDB(): CoursesDBInterface;
20
- /**
21
- * Get a classroom database interface
22
- */
23
- getClassroomDB(classId: string, type: 'student' | 'teacher'): Promise<ClassroomDBInterface>;
24
- /**
25
- * Get the admin database interface
26
- */
27
- getAdminDB(): AdminDBInterface;
28
- /**
29
- * Initialize the data layer
30
- */
31
- initialize(): Promise<void>;
32
- /**
33
- * Teardown the data layer
34
- */
35
- teardown(): Promise<void>;
36
- /**
37
- * Check if this data layer is read-only
38
- */
39
- isReadOnly(): boolean;
40
- /**
41
- * Trigger local replication of a course database.
42
- *
43
- * When a course opts in via `CourseConfig.localSync.enabled`, this method
44
- * replicates the remote course DB to a local PouchDB instance. Subsequent
45
- * `getCourseDB()` calls for that course will return a CourseDB that reads
46
- * from the local replica (fast, no network) and writes to the remote
47
- * (ELO updates, admin ops).
48
- *
49
- * Safe to call multiple times — concurrent calls coalesce. Returns when
50
- * sync is complete (or immediately if already synced / disabled).
51
- *
52
- * Implementations that don't support local sync may no-op.
53
- *
54
- * @param courseId - The course to sync locally
55
- * @param forceEnabled - Skip CourseConfig check and sync regardless.
56
- * Use when the caller already knows local sync is desired.
57
- */
58
- ensureCourseSynced?(courseId: string, forceEnabled?: boolean): Promise<void>;
59
- }
60
-
61
- export type { DataLayerProvider as D };
@@ -1,561 +0,0 @@
1
- import { C as CardData, b as DisplayableData, a as Tag, c as CardRecord, d as QuestionRecord, e as CardHistory } from '../types-legacy-DdVjg81H.cjs';
2
- import { c as ContentNavigationStrategyData, e as StudySessionDoc, f as ScheduledCard, g as CourseRegistrationDoc, h as SessionStateSnapshot, i as StudySessionRunSummary, j as RegulatorReading, k as StudySessionRunCard, F as FilterKind, l as RegulatorName } from '../contentSource-FQZcZopC.cjs';
3
- export { m as SessionEloEvent, n as StudySessionRunCardTrail } from '../contentSource-FQZcZopC.cjs';
4
- import { TagRole, TagPresentation, EloRank, CourseElo } from '@vue-skuilder/common';
5
- import 'moment';
6
-
7
- type RawDoc = {
8
- _id: string;
9
- [key: string]: unknown;
10
- };
11
- /**
12
- * A learner's raw records, as fetched. This is the on-disk dump format: the
13
- * `dump-user` CLI writes it, an admin UI can load it from a file, and every
14
- * loader produces it. Readers must tolerate every past version.
15
- *
16
- * - v0 (LP `scripts/dump-user-db.ts` before 2026-09-30): no `formatVersion`,
17
- * `courseId`, `tombstones`, or `course`.
18
- * - v1: adds all four. Later v1 dumps also carry `course.strategies` (optional).
19
- */
20
- interface LearnerDump {
21
- formatVersion?: 1;
22
- username: string;
23
- dbName: string;
24
- /** The couch base URL the records came from. */
25
- source: string;
26
- fetchedAt: string;
27
- courseId?: string;
28
- /** The couch `GET /{db}` response. */
29
- info?: unknown;
30
- /** Every user-DB doc, raw (`_id`/`_rev` kept, `_design` docs included). */
31
- docs: RawDoc[];
32
- /**
33
- * Deleted user-DB docs. Completed reviews are deleted, so deleted
34
- * `card_review_<reviewTime>` ids are the only record of past due times.
35
- * `seq` is the numeric prefix of the couch seq: order, not time.
36
- */
37
- tombstones?: Array<{
38
- id: string;
39
- rev?: string;
40
- seq: number;
41
- }>;
42
- course?: CourseSlice;
43
- }
44
- interface CourseSlice {
45
- courseId: string;
46
- source?: string;
47
- /** `touched`: cards the user has history, schedule, or ELO events for. `all`: every card. */
48
- scope: 'touched' | 'all';
49
- cards: Array<CardData & {
50
- _id: string;
51
- }>;
52
- displayableData: Array<DisplayableData & {
53
- _id: string;
54
- }>;
55
- /**
56
- * TAG docs. Under `touched`, `taggedCards` is narrowed to the included cards
57
- * and `taggedCount` keeps the full length.
58
- */
59
- tags: Array<Tag & {
60
- _id: string;
61
- taggedCount: number;
62
- }>;
63
- /**
64
- * The course's NAVIGATION_STRATEGY docs, as they stood when the dump was
65
- * taken (current state, not as of any session). Absent in older dumps.
66
- */
67
- strategies?: ContentNavigationStrategyData[];
68
- }
69
- /** A card-history record with an ISO `timeStamp`. Question fields exist on question records only. */
70
- type DatasetRecord = Omit<CardRecord, 'timeStamp'> & Partial<Omit<QuestionRecord, keyof CardRecord>> & {
71
- timeStamp: string;
72
- };
73
- /** A `CardHistory` whose records carry ISO timestamps. */
74
- type DatasetCardHistory = Omit<CardHistory<CardRecord>, 'records'> & {
75
- records: DatasetRecord[];
76
- };
77
- /** What a view or detector needs to know about a card, joined from the course slice. */
78
- interface CardSummary {
79
- cardId: string;
80
- /** The question type's name, from `id_view` ("Course.question.Spelling.SpellingView" → "Spelling"). */
81
- questionType?: string;
82
- elo?: CardData['elo'];
83
- /** Applied tags, from the course's TAG docs. */
84
- tags: string[];
85
- /** The card's displayable-data fields by name (the word, the answer, etc). */
86
- data: Record<string, unknown>;
87
- }
88
- /** One learner in one course, indexed for reading. Built from a {@link LearnerDump} by {@link fromDump}. */
89
- interface LearnerDataset {
90
- username: string;
91
- courseId: string;
92
- /** When the records were read. Derivations take "now" from here, never the wall clock. */
93
- asOf: string;
94
- /** Oldest first. */
95
- sessions: StudySessionDoc[];
96
- /** Records oldest first, timestamps normalized to ISO. */
97
- cardHistories: DatasetCardHistory[];
98
- /** Pending reviews, soonest first. */
99
- scheduled: ScheduledCard[];
100
- registration?: CourseRegistrationDoc;
101
- /** `STRATEGY_STATE` docs' `data`, by strategy key. */
102
- strategyState: Record<string, unknown>;
103
- tombstones: Array<{
104
- id: string;
105
- seq: number;
106
- }>;
107
- /** Absent when the dump carried no course slice. */
108
- cards?: Map<string, CardSummary>;
109
- /** The course's strategy docs at dump time. Absent when the dump didn't carry them. */
110
- strategies?: ContentNavigationStrategyData[];
111
- }
112
- /**
113
- * Normalize a stored timestamp to ISO. Card-history `timeStamp`s persist as
114
- * `Moment.toString()` ("Sat Jul 18 2026 23:26:16 GMT+0000"), which sorts by
115
- * weekday name, not time. Returns the input unchanged if it doesn't parse.
116
- */
117
- declare function toIsoTimestamp(value: unknown): string;
118
- /** `userdb-<username>-2026-09-30T1412Z.json`: sortable and filename-safe. */
119
- declare function dumpFileName(dump: Pick<LearnerDump, 'username' | 'fetchedAt'>): string;
120
- /** Parse and minimally validate a dump file's text. */
121
- declare function parseLearnerDump(text: string): LearnerDump;
122
- /**
123
- * Index a dump for one course. Records for other courses in the same user DB
124
- * (retired or sibling courses) are left out.
125
- */
126
- declare function fromDump(dump: LearnerDump, courseId?: string): LearnerDataset;
127
-
128
- type CouchAuth = {
129
- kind: 'basic';
130
- username: string;
131
- password: string;
132
- }
133
- /** Browser: the signed-in admin's couch session cookie. */
134
- | {
135
- kind: 'cookie';
136
- };
137
- interface FetchLearnerDumpOptions {
138
- /** Couch base URL, e.g. `https://example.com/couch`. */
139
- couchUrl: string;
140
- username: string;
141
- courseId: string;
142
- auth: CouchAuth;
143
- /** Course-DB slice to include. Default `touched`. */
144
- cards?: 'touched' | 'all' | 'none';
145
- /** Inline user-DB attachments as base64. Default false. */
146
- attachments?: boolean;
147
- /** Defaults to the global `fetch`. */
148
- fetchImpl?: typeof fetch;
149
- }
150
- /** couch_peruser convention: `userdb-` + lowercase hex of the username's UTF-8 bytes. */
151
- declare function userDbName(username: string): string;
152
- /**
153
- * Read one learner's records for one course into a {@link LearnerDump}: the
154
- * whole user DB, its tombstones, and (by default) the course cards the user
155
- * has touched, with their displayable data and tags, plus the course's strategy
156
- * docs. Needs admin rights on the couch, via basic auth or the browser's
157
- * session cookie.
158
- */
159
- declare function fetchLearnerDump(opts: FetchLearnerDumpOptions): Promise<LearnerDump>;
160
-
161
- /**
162
- * A learner's per-tag ELO, read for display: one row per tag on their course
163
- * registration, the batches a view filters those rows by, and each rating's
164
- * trajectory through the dataset's sessions.
165
- *
166
- * The source is the learner's `CourseElo` (global + per-tag `{score, count,
167
- * recent}`). Session `eloEvents` add trajectories (per-tag before → after,
168
- * from when sessions began recording them); card-history records add when a
169
- * tag was first and last named by a response.
170
- */
171
-
172
- /**
173
- * A set of tags to view together, as data: every criterion given must hold.
174
- *
175
- * Plain data on purpose. Choosing which tags count is the same question the
176
- * tag-aware ELO distance filter has open (`tagAwareGap` in
177
- * `filters/eloDistance.ts`); a serializable batch can later move into a
178
- * strategy config and serve both.
179
- */
180
- interface TagBatch {
181
- id: string;
182
- label: string;
183
- /** Tag namespaces (see {@link tagNamespace}); `''` is tags with none. */
184
- namespaces?: string[];
185
- /** Tag roles; `'none'` is tags without one. */
186
- roles?: Array<TagRole | 'none'>;
187
- /** Tags starting with any of these. */
188
- prefixes?: string[];
189
- /** Tags starting with any of these are left out. */
190
- excludePrefixes?: string[];
191
- }
192
- /**
193
- * The colon-delimited segments that scope a tag: what comes before its role
194
- * (`gpc:exercise:x` → `gpc`), else its first segment (`concept:match:x` →
195
- * `concept`). `''` for a tag with neither (`femur`, `expose:x`).
196
- */
197
- declare function tagNamespace(tag: string): string;
198
- declare function matchesTagBatch(tag: string, batch: TagBatch, role?: "intro" | "exercise" | "expose" | null): boolean;
199
- /** The namespace × role batch a tag falls in, e.g. `gpc:exercise`, `concept`, or `(no namespace)`. */
200
- declare function tagGroupBatch(tag: string): TagBatch;
201
- interface TagEloRow {
202
- tag: string;
203
- role: TagRole | null;
204
- namespace: string;
205
- /** Id of the tag's {@link tagGroupBatch}. */
206
- group: string;
207
- /**
208
- * The learner's rating on the tag. Null for a count-only tag: a bookkeeping
209
- * role (`intro`, `expose`), or the count-only sentinel.
210
- */
211
- score: number | null;
212
- /**
213
- * A real score stored on a bookkeeping-role tag, from before roles were
214
- * count-only. Not a rating: the framework ignores it.
215
- */
216
- staleScore?: number;
217
- count: number;
218
- /** `score − global`; null when score is. */
219
- vsGlobal: number | null;
220
- /** The rating's ring buffer of recent first attempts, oldest first. */
221
- recent: TagPresentation[];
222
- /** First-attempt correct entries in `recent`. */
223
- recentOk: number;
224
- /** First and last response whose per-tag performance named the tag, or a recent entry. */
225
- firstSeen: string | null;
226
- lastSeen: string | null;
227
- /** ELO events on the tag in the dataset's sessions. */
228
- events: number;
229
- }
230
- interface EloPoint {
231
- at: string;
232
- score: number;
233
- }
234
- interface TagEloView {
235
- global: EloRank;
236
- /** Every tag on the registration, highest score first, count-only tags last. */
237
- rows: TagEloRow[];
238
- /** The namespace × role batches present, graded ones first. */
239
- groups: TagBatch[];
240
- /**
241
- * Ratings through the dataset's ELO events: each series starts at its first
242
- * event's `before`, has a point per event, and ends at the current score at
243
- * `asOf`. A move between recorded events (a session that didn't save its
244
- * events) shows as a step at the next event, or at `asOf`. Tags with no
245
- * events have no series; count-only tags have none.
246
- */
247
- series: {
248
- global: EloPoint[];
249
- tags: Record<string, EloPoint[]>;
250
- };
251
- /** The first ELO event, or null: trajectories start here. */
252
- seriesFrom: string | null;
253
- }
254
- /** The learner's `CourseElo` for the dataset's course, or null if not registered. */
255
- declare function learnerCourseElo(ds: LearnerDataset): CourseElo | null;
256
- /** The learner's per-tag ELO for display. Null if the dataset has no registration for its course. */
257
- declare function tagEloView(ds: LearnerDataset): TagEloView | null;
258
-
259
- /**
260
- * Derivations over a `LearnerDataset`: pure functions that views, text
261
- * exports, and (later) detectors share. Ported from LettersPractice's admin
262
- * service, with LP's domain knowledge moved behind `DiagnosticsInterpreters`.
263
- *
264
- * "Now" is always `dataset.asOf`, never the wall clock, so a dump reads the
265
- * same tomorrow as today.
266
- */
267
-
268
- /**
269
- * Course-supplied meaning for the generic views. Every member is optional and
270
- * has a neutral default.
271
- */
272
- interface DiagnosticsInterpreters {
273
- /** Tags that name what a card exercises: shown inline and sorted first. Default: none. */
274
- isSkillTag?(tag: string): boolean;
275
- /** Compact display form of a tag. Default: unchanged. */
276
- shortTag?(tag: string): string;
277
- /**
278
- * Numbers to read off a session's state snapshot, by display label.
279
- * Default: every numeric field up to two levels deep, labelled by its path.
280
- */
281
- snapshotMetrics?(snapshot: SessionStateSnapshot): Record<string, number>;
282
- /** Which `snapshotMetrics` labels count as progress (for `stalled`). Default: none. */
283
- progressMetrics?: string[];
284
- /**
285
- * Named tag batches for the ELO view, offered beside the namespace × role
286
- * batches it finds on its own. Default: none.
287
- */
288
- tagBatches?: TagBatch[];
289
- }
290
- declare const isSkillTag: (i: DiagnosticsInterpreters | undefined, tag: string) => boolean;
291
- declare const shortTag: (i: DiagnosticsInterpreters | undefined, tag: string) => string;
292
- /**
293
- * Ways a session failed to do its job. `out-of-content` is LP's `starved`,
294
- * renamed so it isn't confused with intake starvation (no new cards chosen).
295
- */
296
- type SessionFlag = 'churned' | 'out-of-content' | 'walked' | 'stalled' | 'grinding';
297
- declare const SESSION_FLAGS: Record<SessionFlag, {
298
- label: string;
299
- help: string;
300
- }>;
301
- /** First guesses, not measurements: nothing yet records whether a flag was right. */
302
- declare const SESSION_FLAG_THRESHOLDS: {
303
- /** Runs per card above which a session counts as churned. */
304
- churnRunsPerCard: number;
305
- /** Minimum cards before churn is meaningful. */
306
- churnMinCards: number;
307
- /** Leftover clock (s) that counts as running out of content. */
308
- outOfContentSeconds: number;
309
- /** Cards below which an abandon reads as a mis-click, not a walk-out. */
310
- walkMinCards: number;
311
- /** |ELO change| below which movement is flat. */
312
- stallEloEpsilon: number;
313
- /** Accuracy below which a session is grinding. */
314
- grindAccuracy: number;
315
- };
316
- interface SessionStateRow {
317
- label: string;
318
- from: number | null;
319
- to: number | null;
320
- delta: number | null;
321
- }
322
- interface SessionSummary {
323
- doc: StudySessionDoc;
324
- /** Null while a session is `open`. */
325
- durationSeconds: number | null;
326
- accuracy: number | null;
327
- /** Net learner global-ELO change over the session's ELO events. Null when it has none. */
328
- eloNet: number | null;
329
- /** Snapshot metrics at start and end. */
330
- state: SessionStateRow[];
331
- flags: SessionFlag[];
332
- }
333
- declare function summarizeSession(doc: StudySessionDoc, interp?: DiagnosticsInterpreters): SessionSummary;
334
- /** Every session in the dataset, newest first. */
335
- declare function summarizeSessions(ds: LearnerDataset, interp?: DiagnosticsInterpreters): SessionSummary[];
336
- /** A `SessionEloEvent` reshaped for one response row: deltas precomputed, tags as a sorted array. */
337
- interface ResponseEloDelta {
338
- userScore: number;
339
- global: {
340
- before: number;
341
- after: number;
342
- delta: number;
343
- };
344
- card?: {
345
- before: number;
346
- after: number;
347
- delta: number;
348
- };
349
- /** `score: null` is a count-only exposure that moves count, not ELO. */
350
- tags: Array<{
351
- tag: string;
352
- before: number;
353
- after: number;
354
- delta: number;
355
- score: number | null;
356
- }>;
357
- }
358
- interface TimelineResponse {
359
- kind: 'response';
360
- at: string;
361
- cardId: string;
362
- /** Absent when the dataset has no course slice. */
363
- card?: CardSummary;
364
- tags: string[];
365
- questionType?: string;
366
- isCorrect: boolean | null;
367
- timeSpentMs: number;
368
- priorAttempts: number | null;
369
- userAnswer: unknown;
370
- /**
371
- * The ELO exchange this response produced, joined from `eloEvents` by card
372
- * and nearest time. Absent on retries (only first attempts move ELO), on
373
- * events in flight at close, and on sessions predating ELO events.
374
- */
375
- elo?: ResponseEloDelta;
376
- }
377
- interface TimelineRun {
378
- kind: 'run';
379
- at: string;
380
- run: StudySessionRunSummary;
381
- }
382
- /**
383
- * Responses and pipeline runs in one time-ordered stream: a replan firing
384
- * between two failures is the thing worth seeing, and a per-card pivot can't
385
- * show sequence.
386
- */
387
- type TimelineEntry = TimelineResponse | TimelineRun;
388
- interface SessionDetail {
389
- summary: SessionSummary;
390
- timeline: TimelineEntry[];
391
- /** The tally claims more responses than records stamped with this session were found. */
392
- responsesMissing: boolean;
393
- }
394
- /** One session's summary and interleaved timeline, or null if the dataset has no such session. */
395
- declare function sessionDetail(ds: LearnerDataset, sessionId: string, interp?: DiagnosticsInterpreters): SessionDetail | null;
396
- /** Per-tag rollup of what a session served. */
397
- interface ServedTagStat {
398
- tag: string;
399
- /** Responses carrying this tag (a response with several tags counts toward each). */
400
- responses: number;
401
- correct: number;
402
- incorrect: number;
403
- /** correct / graded; null when nothing gradeable was served. */
404
- accuracy: number | null;
405
- totalTimeMs: number;
406
- /** Distinct cards carrying this tag. */
407
- cards: number;
408
- }
409
- /** Skill tags first, then most-served. */
410
- declare function servedTags(timeline: TimelineEntry[], interp?: DiagnosticsInterpreters): ServedTagStat[];
411
- /**
412
- * A session's net global-ELO move split into wins and losses, so an
413
- * accuracy/ELO mismatch (many small wins, a few big losses) is legible.
414
- */
415
- interface EloLedger {
416
- count: number;
417
- net: number;
418
- gained: number;
419
- lost: number;
420
- wins: number;
421
- losses: number;
422
- }
423
- declare function eloLedger(timeline: TimelineEntry[]): EloLedger | null;
424
- /** Everything recorded about one card for one learner. */
425
- interface CardDossier {
426
- cardId: string;
427
- /** Absent when the dataset has no course slice. */
428
- card?: CardSummary;
429
- records: DatasetRecord[];
430
- lapses: number;
431
- streak: number;
432
- bestIntervalSeconds: number;
433
- attempts: number;
434
- fails: number;
435
- firstSeen: string | null;
436
- lastSeen: string | null;
437
- totalTimeMs: number;
438
- /** Earliest pending review; `overdue` is as of `dataset.asOf`. */
439
- pendingReview: {
440
- reviewTime: string;
441
- overdue: boolean;
442
- } | null;
443
- cardElo: number | null;
444
- cardEloCount: number | null;
445
- /** Failed, and holding an overdue review. */
446
- stuck: boolean;
447
- /** Failed repeatedly, yet the card's ELO has fewer updates than failures. */
448
- frozenElo: boolean;
449
- /** Time sunk × (fails + 1): grind-heavy, low-payoff cards first. For sorting only. */
450
- painScore: number;
451
- }
452
- /** One dossier per card the learner has history with, most painful first. */
453
- declare function cardDossiers(ds: LearnerDataset): CardDossier[];
454
- /** A record's global performance, whether stored as a number or a per-tag map. */
455
- declare function recordPerformance(r: DatasetRecord): number | null;
456
-
457
- /**
458
- * Plain-text renderings of derivations, for pasting into an LLM or a note.
459
- * Every admin view that shows something should be able to hand it out as
460
- * text; these are those texts. Also the shared number formatting.
461
- */
462
-
463
- /** Signed, at most one decimal; `—` for null. */
464
- declare function fmtDelta(d: number | null): string;
465
- /** 45s, 3m20s, 1.5h. */
466
- declare function fmtDuration(seconds: number): string;
467
- declare function fmtAnswer(a: unknown, max?: number): string;
468
- /** Two decimals, or one significant figure when tiny; `∞` for a required card's score (persisted as null). */
469
- declare function fmtScore(n: number | null): string;
470
- /** One regulator reading as a line: its urgency, inputs, and multiplier. */
471
- declare function regulatorText(r: RegulatorReading): string;
472
- /** One run as a compact text block. */
473
- declare function runText(run: StudySessionRunSummary): string;
474
- /** Per-tag ELO deltas worth showing inline: scored, non-zero, at most four. */
475
- declare function scoredTagDeltas(elo: ResponseEloDelta): ResponseEloDelta['tags'];
476
- /**
477
- * A whole session as plain text, led by a legend so the numbers read without
478
- * the UI.
479
- */
480
- declare function sessionText(username: string, detail: SessionDetail, extras?: {
481
- servedTags?: ServedTagStat[];
482
- eloLedger?: EloLedger | null;
483
- }, interp?: DiagnosticsInterpreters): string;
484
-
485
- /**
486
- * What put a run's card in the queue: the hint that required it, else the
487
- * generator that produced it. Its `origin` says what it is (review or new).
488
- */
489
- declare function runCardSource(card: Pick<StudySessionRunCard, 'generator' | 'required'>): string;
490
- /**
491
- * A run's selected cards counted by source, most first. Empty for runs that
492
- * don't persist their cards (before 0.2.28).
493
- */
494
- declare function selectedBySource(run: Pick<StudySessionRunSummary, 'cards'>): Array<{
495
- source: string;
496
- count: number;
497
- }>;
498
- /** One generator across persisted runs. */
499
- interface GeneratorRunStat {
500
- /** The name runs report it under (its strategy doc's name). */
501
- name: string;
502
- /** Runs it emitted at least one candidate in. */
503
- runs: number;
504
- /** Mean candidates per run, over the runs it appeared in. */
505
- meanCards: number;
506
- meanNew: number;
507
- meanReview: number;
508
- topScoreMax: number;
509
- /** Top score in the most recent run it appeared in. */
510
- topScoreLast: number;
511
- /** Selected cards it originated (first provenance entry), over runs that persist selection. */
512
- selected: number;
513
- /** First attempts at those cards in the same session. */
514
- firstAttempts: number;
515
- firstAttemptsCorrect: number;
516
- }
517
- /** One filter across persisted runs: candidate counts summed over runs. */
518
- interface FilterRunStat {
519
- name: string;
520
- /** As recorded by the most recent run that recorded it (0.2.29+). */
521
- kind?: FilterKind;
522
- runs: number;
523
- boosted: number;
524
- penalized: number;
525
- passed: number;
526
- removed: number;
527
- }
528
- /** One regulator across persisted runs (0.2.29+). */
529
- interface RegulatorRunStat {
530
- name: RegulatorName;
531
- class: RegulatorReading['class'];
532
- runs: number;
533
- meanMultiplier: number;
534
- maxMultiplier: number;
535
- /** Runs where the multiplier was above 1. */
536
- runsActive: number;
537
- /** The most recent reading. */
538
- last: RegulatorReading;
539
- }
540
- interface PipelineRunStats {
541
- sessions: number;
542
- runs: number;
543
- /** Runs that persist their selected cards. Selection and outcome counts cover only these. */
544
- runsWithSelection: number;
545
- firstRunAt?: string;
546
- lastRunAt?: string;
547
- /** Busiest first. */
548
- generators: GeneratorRunStat[];
549
- /** By name. */
550
- filters: FilterRunStat[];
551
- /** Empty before 0.2.29. */
552
- regulators: RegulatorRunStat[];
553
- /** Selected cards with no originating generator: cards forced in by `requireCards`. */
554
- selectedUnattributed: number;
555
- }
556
- /** Aggregate a learner's persisted pipeline runs, optionally only sessions started at or after `since` (ISO). */
557
- declare function pipelineRunStats(ds: LearnerDataset, opts?: {
558
- since?: string;
559
- }): PipelineRunStats;
560
-
561
- export { type CardDossier, type CardSummary, type CouchAuth, type CourseSlice, type DatasetCardHistory, type DatasetRecord, type DiagnosticsInterpreters, type EloLedger, type EloPoint, type FetchLearnerDumpOptions, FilterKind, type FilterRunStat, type GeneratorRunStat, type LearnerDataset, type LearnerDump, type PipelineRunStats, RegulatorName, RegulatorReading, type RegulatorRunStat, type ResponseEloDelta, SESSION_FLAGS, SESSION_FLAG_THRESHOLDS, type ServedTagStat, type SessionDetail, type SessionFlag, type SessionStateRow, SessionStateSnapshot, type SessionSummary, StudySessionDoc, StudySessionRunCard, StudySessionRunSummary, type TagBatch, type TagEloRow, type TagEloView, type TimelineEntry, type TimelineResponse, type TimelineRun, cardDossiers, dumpFileName, eloLedger, fetchLearnerDump, fmtAnswer, fmtDelta, fmtDuration, fmtScore, fromDump, isSkillTag, learnerCourseElo, matchesTagBatch, parseLearnerDump, pipelineRunStats, recordPerformance, regulatorText, runCardSource, runText, scoredTagDeltas, selectedBySource, servedTags, sessionDetail, sessionText, shortTag, summarizeSession, summarizeSessions, tagEloView, tagGroupBatch, tagNamespace, toIsoTimestamp, userDbName };