@vue-skuilder/db 0.2.27 → 0.2.28

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 (59) hide show
  1. package/dist/classroomDB-DLTtLZct.d.cts +86 -0
  2. package/dist/classroomDB-DLTtLZct.d.ts +86 -0
  3. package/dist/{contentSource-LPf044hY.d.ts → contentSource-BoFBwvYa.d.ts} +65 -98
  4. package/dist/{contentSource-D3c1fMAk.d.cts → contentSource-DpQqTG3m.d.cts} +65 -98
  5. package/dist/core/index.d.cts +6 -5
  6. package/dist/core/index.d.ts +6 -5
  7. package/dist/core/index.js +22 -2
  8. package/dist/core/index.js.map +1 -1
  9. package/dist/core/index.mjs +22 -2
  10. package/dist/core/index.mjs.map +1 -1
  11. package/dist/{dataLayerProvider-DaAootVV.d.ts → dataLayerProvider-D_LJT3F4.d.ts} +2 -8
  12. package/dist/{dataLayerProvider-CeLiFbHv.d.cts → dataLayerProvider-Dl3cAAvQ.d.cts} +2 -8
  13. package/dist/diagnostics/index.d.cts +370 -0
  14. package/dist/diagnostics/index.d.ts +370 -0
  15. package/dist/diagnostics/index.js +778 -0
  16. package/dist/diagnostics/index.js.map +1 -0
  17. package/dist/diagnostics/index.mjs +729 -0
  18. package/dist/diagnostics/index.mjs.map +1 -0
  19. package/dist/impl/couch/index.d.cts +4 -3
  20. package/dist/impl/couch/index.d.ts +4 -3
  21. package/dist/impl/couch/index.js +22 -2
  22. package/dist/impl/couch/index.js.map +1 -1
  23. package/dist/impl/couch/index.mjs +22 -2
  24. package/dist/impl/couch/index.mjs.map +1 -1
  25. package/dist/impl/static/index.d.cts +5 -5
  26. package/dist/impl/static/index.d.ts +5 -5
  27. package/dist/impl/static/index.js +22 -8
  28. package/dist/impl/static/index.js.map +1 -1
  29. package/dist/impl/static/index.mjs +22 -8
  30. package/dist/impl/static/index.mjs.map +1 -1
  31. package/dist/{index-BkBJlGDX.d.ts → index-CVGehe_t.d.ts} +1 -1
  32. package/dist/{index-D7WdMDAs.d.cts → index-Ktg72jKb.d.cts} +1 -1
  33. package/dist/index.d.cts +10 -9
  34. package/dist/index.d.ts +10 -9
  35. package/dist/index.js +64 -23
  36. package/dist/index.js.map +1 -1
  37. package/dist/index.mjs +64 -23
  38. package/dist/index.mjs.map +1 -1
  39. package/dist/{types-DjiFOZxJ.d.cts → types-D0oQeJAi.d.cts} +1 -1
  40. package/dist/{types-uJ2Xn3_X.d.ts → types-dXWfyz9B.d.ts} +1 -1
  41. package/dist/{types-legacy-CrwyZIvI.d.cts → types-legacy-BkOYOR6U.d.cts} +1 -1
  42. package/dist/{types-legacy-CrwyZIvI.d.ts → types-legacy-BkOYOR6U.d.ts} +1 -1
  43. package/dist/util/packer/index.d.cts +3 -3
  44. package/dist/util/packer/index.d.ts +3 -3
  45. package/package.json +15 -3
  46. package/src/core/interfaces/dataLayerProvider.ts +3 -8
  47. package/src/core/navigators/Pipeline.ts +5 -2
  48. package/src/core/navigators/PipelineDebugger.ts +64 -16
  49. package/src/core/navigators/index.ts +1 -0
  50. package/src/core/types/studySession.ts +37 -0
  51. package/src/diagnostics/dataset.ts +231 -0
  52. package/src/diagnostics/derive.ts +555 -0
  53. package/src/diagnostics/index.ts +24 -0
  54. package/src/diagnostics/loader.ts +191 -0
  55. package/src/diagnostics/text.ts +242 -0
  56. package/src/impl/couch/PouchDataLayerProvider.ts +0 -23
  57. package/src/impl/static/StaticDataLayerProvider.ts +0 -11
  58. package/src/study/SessionController.ts +56 -2
  59. package/tsup.config.ts +1 -0
@@ -1,5 +1,5 @@
1
1
  import { CourseConfig } from '@vue-skuilder/common';
2
- import { D as DocType } from './types-legacy-CrwyZIvI.cjs';
2
+ import { D as DocType } from './types-legacy-BkOYOR6U.cjs';
3
3
 
4
4
  interface StaticCourseManifest {
5
5
  version: string;
@@ -1,5 +1,5 @@
1
1
  import { CourseConfig } from '@vue-skuilder/common';
2
- import { D as DocType } from './types-legacy-CrwyZIvI.js';
2
+ import { D as DocType } from './types-legacy-BkOYOR6U.js';
3
3
 
4
4
  interface StaticCourseManifest {
5
5
  version: string;
@@ -165,4 +165,4 @@ interface QuestionRecord extends CardRecord, Evaluation {
165
165
  priorAttemps: number;
166
166
  }
167
167
 
168
- export { type CardHistory as C, DocType as D, type Field as F, GuestUsername as G, type QualifiedCardID as Q, type SkuilderCourseData as S, type TagStub as T, type Tag as a, type CardRecord as b, type QuestionRecord as c, type CardData as d, type CourseListData as e, type DisplayableData as f, type DataShapeData as g, type QuestionData as h, DocTypePrefixes as i, log as l };
168
+ export { type CardData as C, DocType as D, type Field as F, GuestUsername as G, type QuestionRecord as Q, type SkuilderCourseData as S, type Tag as T, type DisplayableData as a, type CardRecord as b, type CardHistory as c, type QualifiedCardID as d, type TagStub as e, DocTypePrefixes as f, type CourseListData as g, type DataShapeData as h, type QuestionData as i, log as l };
@@ -165,4 +165,4 @@ interface QuestionRecord extends CardRecord, Evaluation {
165
165
  priorAttemps: number;
166
166
  }
167
167
 
168
- export { type CardHistory as C, DocType as D, type Field as F, GuestUsername as G, type QualifiedCardID as Q, type SkuilderCourseData as S, type TagStub as T, type Tag as a, type CardRecord as b, type QuestionRecord as c, type CardData as d, type CourseListData as e, type DisplayableData as f, type DataShapeData as g, type QuestionData as h, DocTypePrefixes as i, log as l };
168
+ export { type CardData as C, DocType as D, type Field as F, GuestUsername as G, type QuestionRecord as Q, type SkuilderCourseData as S, type Tag as T, type DisplayableData as a, type CardRecord as b, type CardHistory as c, type QualifiedCardID as d, type TagStub as e, DocTypePrefixes as f, type CourseListData as g, type DataShapeData as h, type QuestionData as i, log as l };
@@ -1,5 +1,5 @@
1
- export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-DjiFOZxJ.cjs';
2
- export { C as CouchDBToStaticPacker } from '../../index-D7WdMDAs.cjs';
1
+ export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-D0oQeJAi.cjs';
2
+ export { C as CouchDBToStaticPacker } from '../../index-Ktg72jKb.cjs';
3
3
  import '@vue-skuilder/common';
4
- import '../../types-legacy-CrwyZIvI.cjs';
4
+ import '../../types-legacy-BkOYOR6U.cjs';
5
5
  import 'moment';
@@ -1,5 +1,5 @@
1
- export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-uJ2Xn3_X.js';
2
- export { C as CouchDBToStaticPacker } from '../../index-BkBJlGDX.js';
1
+ export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-dXWfyz9B.js';
2
+ export { C as CouchDBToStaticPacker } from '../../index-CVGehe_t.js';
3
3
  import '@vue-skuilder/common';
4
- import '../../types-legacy-CrwyZIvI.js';
4
+ import '../../types-legacy-BkOYOR6U.js';
5
5
  import 'moment';
package/package.json CHANGED
@@ -4,7 +4,7 @@
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
7
- "version": "0.2.27",
7
+ "version": "0.2.28",
8
8
  "description": "Database layer for vue-skuilder",
9
9
  "main": "dist/index.js",
10
10
  "module": "dist/index.mjs",
@@ -34,6 +34,18 @@
34
34
  "types": "./dist/impl/static/index.d.ts",
35
35
  "import": "./dist/impl/static/index.mjs",
36
36
  "require": "./dist/impl/static/index.js"
37
+ },
38
+ "./diagnostics": {
39
+ "types": "./dist/diagnostics/index.d.ts",
40
+ "import": "./dist/diagnostics/index.mjs",
41
+ "require": "./dist/diagnostics/index.js"
42
+ }
43
+ },
44
+ "typesVersions": {
45
+ "*": {
46
+ "diagnostics": [
47
+ "./dist/diagnostics/index.d.ts"
48
+ ]
37
49
  }
38
50
  },
39
51
  "scripts": {
@@ -48,7 +60,7 @@
48
60
  },
49
61
  "dependencies": {
50
62
  "@nilock2/pouchdb-authentication": "^1.0.2",
51
- "@vue-skuilder/common": "0.2.27",
63
+ "@vue-skuilder/common": "0.2.28",
52
64
  "cross-fetch": "^4.1.0",
53
65
  "moment": "^2.29.4",
54
66
  "pouchdb": "^9.0.0",
@@ -63,5 +75,5 @@
63
75
  "vite": "^8.0.0",
64
76
  "vitest": "^4.1.0"
65
77
  },
66
- "stableVersion": "0.2.27"
78
+ "stableVersion": "0.2.28"
67
79
  }
@@ -1,6 +1,6 @@
1
1
  // db/src/core/interfaces.ts
2
2
 
3
- import { UserDBInterface, UserDBReader } from './userDB';
3
+ import { UserDBInterface } from './userDB';
4
4
  import { CourseDBInterface, CoursesDBInterface } from './courseDB';
5
5
  import { ClassroomDBInterface } from './classroomDB';
6
6
  import { AdminDBInterface } from './adminDB';
@@ -14,13 +14,8 @@ export interface DataLayerProvider {
14
14
  */
15
15
  getUserDB(): UserDBInterface;
16
16
 
17
- /**
18
- * Create a UserDBReader for a specific user (admin access required)
19
- * Uses session authentication to verify requesting user is admin
20
- * @param targetUsername - The username to create a reader for
21
- * @throws Error if requesting user is not 'admin'
22
- */
23
- createUserReaderForUser(targetUsername: string): Promise<UserDBReader>;
17
+ // Reading another learner's records (admin): see `@vue-skuilder/db/diagnostics`
18
+ // (`fetchLearnerDump`). A second UserDB would replace the logged-in one.
24
19
 
25
20
  /**
26
21
  * Get a course database interface
@@ -501,7 +501,9 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
501
501
  logger.debug(`[Pipeline] Filter '${filter.name}': ${beforeScores.size} → ${cards.length} cards (↑${boosted} ↓${penalized} =${passed})`);
502
502
  }
503
503
 
504
- // Remove zero-score cards (hard filtered)
504
+ // Remove zero-score cards (hard filtered). The debug report still wants
505
+ // them: they're the answer to "which filter sank this card?"
506
+ const scoredCards = cards;
505
507
  cards = cards.filter((c) => c.score > 0);
506
508
 
507
509
  // Apply ephemeral hints (one-shot, post-filter)
@@ -568,7 +570,8 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
568
570
  cards,
569
571
  result,
570
572
  context.userElo,
571
- hints?? undefined
573
+ hints?? undefined,
574
+ scoredCards
572
575
  );
573
576
  captureRun(report);
574
577
  } catch (e) {
@@ -74,6 +74,20 @@ export interface FilterImpact {
74
74
  removed: number;
75
75
  }
76
76
 
77
+ /** One card as retained in a {@link PipelineRunReport}. */
78
+ export interface RunReportCard {
79
+ cardId: string;
80
+ courseId: string;
81
+ origin: 'new' | 'review' | 'unknown';
82
+ generator?: string;
83
+ finalScore: number;
84
+ /** Card's ELO (parsed from ELO generator provenance, if available) */
85
+ cardElo?: number;
86
+ provenance: StrategyContribution[];
87
+ tags?: string[];
88
+ selected: boolean;
89
+ }
90
+
77
91
  /**
78
92
  * Complete record of a single pipeline execution.
79
93
  */
@@ -117,18 +131,22 @@ export interface PipelineRunReport {
117
131
  * rather than retained verbatim — each retained card carries a multi-KB
118
132
  * provenance trail, and the tail is typically hundreds of cards per run.
119
133
  */
120
- cards: Array<{
121
- cardId: string;
122
- courseId: string;
123
- origin: 'new' | 'review' | 'unknown';
124
- generator?: string;
125
- finalScore: number;
126
- /** Card's ELO (parsed from ELO generator provenance, if available) */
127
- cardElo?: number;
128
- provenance: StrategyContribution[];
129
- tags?: string[];
130
- selected: boolean;
131
- }>;
134
+ cards: RunReportCard[];
135
+
136
+ /**
137
+ * The two unselected non-review cards most worth explaining when a run
138
+ * picks no new content. Non-review means no `reviewID`, so prescribed and
139
+ * required cards count (their `origin` reads `'unknown'`).
140
+ *
141
+ * - `nextInLine`: highest final score. How close new content came.
142
+ * - `topGenerated`: highest generator score, zero-scored cards included.
143
+ * Its provenance shows which filter sank it. Omitted when it is the same
144
+ * card as `nextInLine`.
145
+ */
146
+ unselectedNew?: {
147
+ nextInLine?: RunReportCard;
148
+ topGenerated?: RunReportCard;
149
+ };
132
150
 
133
151
  /**
134
152
  * Summary of the discarded tail of the candidate pool — cards that were
@@ -273,7 +291,9 @@ export function buildRunReport(
273
291
  allCards: WeightedCard[],
274
292
  selectedCards: WeightedCard[],
275
293
  userElo?: number,
276
- hints?: ReplanHints
294
+ hints?: ReplanHints,
295
+ /** Post-filter cards before zero-scored ones are dropped. Defaults to `allCards`. */
296
+ scoredCards?: WeightedCard[]
277
297
  ): Omit<PipelineRunReport, 'runId' | 'timestamp'> {
278
298
  const selectedIds = new Set(selectedCards.map((c) => c.cardId));
279
299
 
@@ -281,7 +301,7 @@ export function buildRunReport(
281
301
  // into selected vs not-selected, then retain only the top-N of the
282
302
  // non-selected group to bound memory. The remaining low-score tail is
283
303
  // summarized rather than kept (see discardedTail).
284
- const toReport = (card: WeightedCard) => ({
304
+ const toReport = (card: WeightedCard): RunReportCard => ({
285
305
  cardId: card.cardId,
286
306
  courseId: card.courseId,
287
307
  origin: getOrigin(card),
@@ -293,8 +313,8 @@ export function buildRunReport(
293
313
  selected: selectedIds.has(card.cardId),
294
314
  });
295
315
 
296
- const selectedReported: ReturnType<typeof toReport>[] = [];
297
- const nearMissReported: ReturnType<typeof toReport>[] = [];
316
+ const selectedReported: RunReportCard[] = [];
317
+ const nearMissReported: RunReportCard[] = [];
298
318
  const discardedTailCards: WeightedCard[] = [];
299
319
 
300
320
  let nonSelectedSeen = 0;
@@ -341,6 +361,33 @@ export function buildRunReport(
341
361
  };
342
362
  }
343
363
 
364
+ // Unselected non-review candidates. `nextInLine` ranks by final score, so it
365
+ // comes from `allCards` (post-hints; zero-scored dropped). `topGenerated`
366
+ // ranks by generator score and must see the zero-scored cards too, but not
367
+ // cards a hint excluded: exclusion leaves no provenance to explain them.
368
+ const isUnselectedNew = (c: WeightedCard) => !c.reviewID && !selectedIds.has(c.cardId);
369
+ const generatorScore = (c: WeightedCard) => c.provenance[0]?.score ?? 0;
370
+ const keptIds = new Set(allCards.map((c) => c.cardId));
371
+ const hintExcluded = (c: WeightedCard) => c.score > 0 && !keptIds.has(c.cardId);
372
+ let nextInLine: WeightedCard | undefined;
373
+ for (const c of allCards) {
374
+ if (isUnselectedNew(c) && (!nextInLine || c.score > nextInLine.score)) nextInLine = c;
375
+ }
376
+ let topGenerated: WeightedCard | undefined;
377
+ for (const c of scoredCards ?? allCards) {
378
+ if (!isUnselectedNew(c) || hintExcluded(c)) continue;
379
+ if (!topGenerated || generatorScore(c) > generatorScore(topGenerated)) topGenerated = c;
380
+ }
381
+ const unselectedNew =
382
+ nextInLine || topGenerated
383
+ ? {
384
+ ...(nextInLine ? { nextInLine: toReport(nextInLine) } : {}),
385
+ ...(topGenerated && topGenerated.cardId !== nextInLine?.cardId
386
+ ? { topGenerated: toReport(topGenerated) }
387
+ : {}),
388
+ }
389
+ : undefined;
390
+
344
391
  const reviewsSelected = selectedCards.filter((c) => getOrigin(c) === 'review').length;
345
392
  const newSelected = selectedCards.filter((c) => getOrigin(c) === 'new').length;
346
393
 
@@ -357,6 +404,7 @@ export function buildRunReport(
357
404
  reviewsSelected,
358
405
  newSelected,
359
406
  cards,
407
+ unselectedNew,
360
408
  discardedTail,
361
409
  };
362
410
  }
@@ -24,6 +24,7 @@ export {
24
24
  getRunsForSession,
25
25
  drainCapturedRuns,
26
26
  type PipelineRunReport,
27
+ type RunReportCard,
27
28
  type GeneratorSummary,
28
29
  type FilterImpact,
29
30
  } from './PipelineDebugger';
@@ -1,6 +1,7 @@
1
1
  import { DocType, DocTypePrefixes } from './types-legacy';
2
2
  import type { ReplanHints } from '../navigators/generators/types';
3
3
  import type { GeneratorSummary, FilterImpact } from '../navigators/PipelineDebugger';
4
+ import type { StrategyContribution } from '../navigators';
4
5
 
5
6
  /**
6
7
  * Durable per-sitting record. Join target for `CardRecord.sessionId`.
@@ -104,6 +105,42 @@ export interface StudySessionRunSummary {
104
105
  eloRange?: [number, number];
105
106
  note: string;
106
107
  };
108
+ /**
109
+ * The selected cards, then the top few unselected ones, each in score
110
+ * order. The lowest selected score against the first runner-up is this
111
+ * run's cutoff.
112
+ */
113
+ cards?: StudySessionRunCard[];
114
+ /**
115
+ * The unselected non-review cards most worth explaining, with their
116
+ * score-changing provenance. See `PipelineRunReport.unselectedNew`.
117
+ */
118
+ unselectedNew?: {
119
+ nextInLine?: StudySessionRunCardTrail;
120
+ topGenerated?: StudySessionRunCardTrail;
121
+ };
122
+ }
123
+
124
+ /** A card as persisted on a run. `origin` is as counted in `newSelected`/`reviewsSelected`. */
125
+ export interface StudySessionRunCard {
126
+ cardId: string;
127
+ origin: 'new' | 'review' | 'unknown';
128
+ generator?: string;
129
+ score: number;
130
+ selected: boolean;
131
+ }
132
+
133
+ /**
134
+ * A card plus the provenance entries that changed its score, in order.
135
+ * `'passed'` entries are dropped. Strategy ids are dropped (the name is kept).
136
+ */
137
+ export interface StudySessionRunCardTrail extends StudySessionRunCard {
138
+ trail: Array<{
139
+ strategyName: string;
140
+ action: StrategyContribution['action'];
141
+ score: number;
142
+ reason: string;
143
+ }>;
107
144
  }
108
145
 
109
146
  /**
@@ -0,0 +1,231 @@
1
+ import type {
2
+ CardData,
3
+ CardHistory,
4
+ CardRecord,
5
+ DisplayableData,
6
+ QuestionRecord,
7
+ Tag,
8
+ } from '../core/types/types-legacy';
9
+ import type { CourseRegistrationDoc, ScheduledCard } from '../core/types/user';
10
+ import type { StudySessionDoc } from '../core/types/studySession';
11
+
12
+ // Literal prefixes rather than `DocTypePrefixes`: this entry stays free of
13
+ // runtime imports from `core`, so it loads in the browser, node, and the CLI
14
+ // without the rest of the db package.
15
+ const PREFIX = {
16
+ cardHistory: 'cardH',
17
+ scheduled: 'card_review_',
18
+ session: 'SESSION::',
19
+ strategyState: 'STRATEGY_STATE::',
20
+ registrations: 'CourseRegistrations',
21
+ } as const;
22
+
23
+ type RawDoc = { _id: string; [key: string]: unknown };
24
+
25
+ /**
26
+ * A learner's raw records, as fetched. This is the on-disk dump format: the
27
+ * `dump-user` CLI writes it, an admin UI can load it from a file, and every
28
+ * loader produces it. Readers must tolerate every past version.
29
+ *
30
+ * - v0 (LP `scripts/dump-user-db.ts` before 2026-09-30): no `formatVersion`,
31
+ * `courseId`, `tombstones`, or `course`.
32
+ * - v1: adds all four.
33
+ */
34
+ export interface LearnerDump {
35
+ formatVersion?: 1;
36
+ username: string;
37
+ dbName: string;
38
+ /** The couch base URL the records came from. */
39
+ source: string;
40
+ fetchedAt: string;
41
+ courseId?: string;
42
+ /** The couch `GET /{db}` response. */
43
+ info?: unknown;
44
+ /** Every user-DB doc, raw (`_id`/`_rev` kept, `_design` docs included). */
45
+ docs: RawDoc[];
46
+ /**
47
+ * Deleted user-DB docs. Completed reviews are deleted, so deleted
48
+ * `card_review_<reviewTime>` ids are the only record of past due times.
49
+ * `seq` is the numeric prefix of the couch seq: order, not time.
50
+ */
51
+ tombstones?: Array<{ id: string; rev?: string; seq: number }>;
52
+ course?: CourseSlice;
53
+ }
54
+
55
+ export interface CourseSlice {
56
+ courseId: string;
57
+ source?: string;
58
+ /** `touched`: cards the user has history, schedule, or ELO events for. `all`: every card. */
59
+ scope: 'touched' | 'all';
60
+ cards: Array<CardData & { _id: string }>;
61
+ displayableData: Array<DisplayableData & { _id: string }>;
62
+ /**
63
+ * TAG docs. Under `touched`, `taggedCards` is narrowed to the included cards
64
+ * and `taggedCount` keeps the full length.
65
+ */
66
+ tags: Array<Tag & { _id: string; taggedCount: number }>;
67
+ }
68
+
69
+ /** A card-history record with an ISO `timeStamp`. Question fields exist on question records only. */
70
+ export type DatasetRecord = Omit<CardRecord, 'timeStamp'> &
71
+ Partial<Omit<QuestionRecord, keyof CardRecord>> & { timeStamp: string };
72
+
73
+ /** A `CardHistory` whose records carry ISO timestamps. */
74
+ export type DatasetCardHistory = Omit<CardHistory<CardRecord>, 'records'> & {
75
+ records: DatasetRecord[];
76
+ };
77
+
78
+ /** What a view or detector needs to know about a card, joined from the course slice. */
79
+ export interface CardSummary {
80
+ cardId: string;
81
+ /** The question type's name, from `id_view` ("Course.question.Spelling.SpellingView" → "Spelling"). */
82
+ questionType?: string;
83
+ elo?: CardData['elo'];
84
+ /** Applied tags, from the course's TAG docs. */
85
+ tags: string[];
86
+ /** The card's displayable-data fields by name (the word, the answer, etc). */
87
+ data: Record<string, unknown>;
88
+ }
89
+
90
+ /** One learner in one course, indexed for reading. Built from a {@link LearnerDump} by {@link fromDump}. */
91
+ export interface LearnerDataset {
92
+ username: string;
93
+ courseId: string;
94
+ /** When the records were read. Derivations take "now" from here, never the wall clock. */
95
+ asOf: string;
96
+ /** Oldest first. */
97
+ sessions: StudySessionDoc[];
98
+ /** Records oldest first, timestamps normalized to ISO. */
99
+ cardHistories: DatasetCardHistory[];
100
+ /** Pending reviews, soonest first. */
101
+ scheduled: ScheduledCard[];
102
+ registration?: CourseRegistrationDoc;
103
+ /** `STRATEGY_STATE` docs' `data`, by strategy key. */
104
+ strategyState: Record<string, unknown>;
105
+ tombstones: Array<{ id: string; seq: number }>;
106
+ /** Absent when the dump carried no course slice. */
107
+ cards?: Map<string, CardSummary>;
108
+ }
109
+
110
+ /**
111
+ * Normalize a stored timestamp to ISO. Card-history `timeStamp`s persist as
112
+ * `Moment.toString()` ("Sat Jul 18 2026 23:26:16 GMT+0000"), which sorts by
113
+ * weekday name, not time. Returns the input unchanged if it doesn't parse.
114
+ */
115
+ export function toIsoTimestamp(value: unknown): string {
116
+ if (typeof value === 'number') return new Date(value).toISOString();
117
+ const s = String(value ?? '');
118
+ const ms = Date.parse(s);
119
+ return Number.isNaN(ms) ? s : new Date(ms).toISOString();
120
+ }
121
+
122
+ /** `userdb-<username>-2026-09-30T1412Z.json`: sortable and filename-safe. */
123
+ export function dumpFileName(dump: Pick<LearnerDump, 'username' | 'fetchedAt'>): string {
124
+ return `userdb-${dump.username}-${dump.fetchedAt.slice(0, 16).replace(':', '')}Z.json`;
125
+ }
126
+
127
+ /** Parse and minimally validate a dump file's text. */
128
+ export function parseLearnerDump(text: string): LearnerDump {
129
+ const dump = JSON.parse(text) as Partial<LearnerDump>;
130
+ if (!dump || typeof dump.username !== 'string' || !Array.isArray(dump.docs)) {
131
+ throw new Error('[diagnostics] Not a learner dump: expected `username` and a `docs` array');
132
+ }
133
+ return dump as LearnerDump;
134
+ }
135
+
136
+ function questionTypeOf(idView: unknown): string | undefined {
137
+ if (typeof idView !== 'string') return undefined;
138
+ const parts = idView.split('.');
139
+ return parts.length >= 2 ? parts[parts.length - 2] : idView;
140
+ }
141
+
142
+ function summarizeCards(slice: CourseSlice): Map<string, CardSummary> {
143
+ const data = new Map(slice.displayableData.map((dd) => [dd._id, dd]));
144
+ const cards = new Map<string, CardSummary>();
145
+ for (const card of slice.cards) {
146
+ const fields: Record<string, unknown> = {};
147
+ for (const f of data.get(card.id_displayable_data?.[0] ?? '')?.data ?? []) {
148
+ fields[f.name] = f.data;
149
+ }
150
+ cards.set(card._id, {
151
+ cardId: card._id,
152
+ questionType: questionTypeOf(card.id_view),
153
+ elo: card.elo,
154
+ tags: [],
155
+ data: fields,
156
+ });
157
+ }
158
+ for (const tag of slice.tags) {
159
+ for (const cardId of tag.taggedCards ?? []) cards.get(cardId)?.tags.push(tag.name);
160
+ }
161
+ return cards;
162
+ }
163
+
164
+ /** The dump's course, else the course most of its sessions belong to. */
165
+ function inferCourseId(dump: LearnerDump): string | undefined {
166
+ if (dump.courseId) return dump.courseId;
167
+ if (dump.course) return dump.course.courseId;
168
+ const counts = new Map<string, number>();
169
+ for (const d of dump.docs) {
170
+ if (d._id.startsWith(PREFIX.session) && typeof d.courseId === 'string') {
171
+ counts.set(d.courseId, (counts.get(d.courseId) ?? 0) + 1);
172
+ }
173
+ }
174
+ return [...counts.entries()].sort((a, b) => b[1] - a[1])[0]?.[0];
175
+ }
176
+
177
+ /**
178
+ * Index a dump for one course. Records for other courses in the same user DB
179
+ * (retired or sibling courses) are left out.
180
+ */
181
+ export function fromDump(dump: LearnerDump, courseId?: string): LearnerDataset {
182
+ const course = courseId ?? inferCourseId(dump);
183
+ if (!course) throw new Error('[diagnostics] No course id given, and none found in the dump');
184
+
185
+ const sessions: StudySessionDoc[] = [];
186
+ const cardHistories: DatasetCardHistory[] = [];
187
+ const scheduled: ScheduledCard[] = [];
188
+ const strategyState: Record<string, unknown> = {};
189
+ let registration: CourseRegistrationDoc | undefined;
190
+
191
+ for (const doc of dump.docs) {
192
+ const id = doc._id;
193
+ if (id.startsWith(PREFIX.session)) {
194
+ if (doc.courseId === course) sessions.push(doc as unknown as StudySessionDoc);
195
+ } else if (id.startsWith(PREFIX.cardHistory)) {
196
+ if (doc.courseID !== course) continue;
197
+ const history = doc as unknown as DatasetCardHistory;
198
+ cardHistories.push({
199
+ ...history,
200
+ records: (history.records ?? [])
201
+ .map((r) => ({ ...r, timeStamp: toIsoTimestamp(r.timeStamp) }))
202
+ .sort((a, b) => a.timeStamp.localeCompare(b.timeStamp)),
203
+ });
204
+ } else if (id.startsWith(PREFIX.scheduled)) {
205
+ if (doc.courseId === course) scheduled.push(doc as unknown as ScheduledCard);
206
+ } else if (id.startsWith(PREFIX.strategyState)) {
207
+ const [, docCourse, key] = id.split('::');
208
+ if (docCourse === course && key) strategyState[key] = doc.data;
209
+ } else if (id === PREFIX.registrations) {
210
+ registration = doc as unknown as CourseRegistrationDoc;
211
+ }
212
+ }
213
+
214
+ sessions.sort((a, b) => a.startTime.localeCompare(b.startTime));
215
+ scheduled.sort((a, b) => String(a.reviewTime).localeCompare(String(b.reviewTime)));
216
+
217
+ return {
218
+ username: dump.username,
219
+ courseId: course,
220
+ asOf: dump.fetchedAt,
221
+ sessions,
222
+ cardHistories,
223
+ scheduled,
224
+ registration,
225
+ strategyState,
226
+ tombstones: (dump.tombstones ?? []).map(({ id, seq }) => ({ id, seq })),
227
+ ...(dump.course && dump.course.courseId === course
228
+ ? { cards: summarizeCards(dump.course) }
229
+ : {}),
230
+ };
231
+ }