@vue-skuilder/db 0.2.26 → 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.
- package/dist/classroomDB-DLTtLZct.d.cts +86 -0
- package/dist/classroomDB-DLTtLZct.d.ts +86 -0
- package/dist/{contentSource-LPf044hY.d.ts → contentSource-BoFBwvYa.d.ts} +65 -98
- package/dist/{contentSource-D3c1fMAk.d.cts → contentSource-DpQqTG3m.d.cts} +65 -98
- package/dist/core/index.d.cts +6 -5
- package/dist/core/index.d.ts +6 -5
- package/dist/core/index.js +43 -15
- package/dist/core/index.js.map +1 -1
- package/dist/core/index.mjs +43 -15
- package/dist/core/index.mjs.map +1 -1
- package/dist/{dataLayerProvider-DaAootVV.d.ts → dataLayerProvider-D_LJT3F4.d.ts} +2 -8
- package/dist/{dataLayerProvider-CeLiFbHv.d.cts → dataLayerProvider-Dl3cAAvQ.d.cts} +2 -8
- package/dist/diagnostics/index.d.cts +370 -0
- package/dist/diagnostics/index.d.ts +370 -0
- package/dist/diagnostics/index.js +778 -0
- package/dist/diagnostics/index.js.map +1 -0
- package/dist/diagnostics/index.mjs +729 -0
- package/dist/diagnostics/index.mjs.map +1 -0
- package/dist/impl/couch/index.d.cts +4 -3
- package/dist/impl/couch/index.d.ts +4 -3
- package/dist/impl/couch/index.js +43 -15
- package/dist/impl/couch/index.js.map +1 -1
- package/dist/impl/couch/index.mjs +43 -15
- package/dist/impl/couch/index.mjs.map +1 -1
- package/dist/impl/static/index.d.cts +5 -5
- package/dist/impl/static/index.d.ts +5 -5
- package/dist/impl/static/index.js +43 -21
- package/dist/impl/static/index.js.map +1 -1
- package/dist/impl/static/index.mjs +43 -21
- package/dist/impl/static/index.mjs.map +1 -1
- package/dist/{index-BkBJlGDX.d.ts → index-CVGehe_t.d.ts} +1 -1
- package/dist/{index-D7WdMDAs.d.cts → index-Ktg72jKb.d.cts} +1 -1
- package/dist/index.d.cts +10 -9
- package/dist/index.d.ts +10 -9
- package/dist/index.js +85 -36
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +85 -36
- package/dist/index.mjs.map +1 -1
- package/dist/{types-DjiFOZxJ.d.cts → types-D0oQeJAi.d.cts} +1 -1
- package/dist/{types-uJ2Xn3_X.d.ts → types-dXWfyz9B.d.ts} +1 -1
- package/dist/{types-legacy-CrwyZIvI.d.cts → types-legacy-BkOYOR6U.d.cts} +1 -1
- package/dist/{types-legacy-CrwyZIvI.d.ts → types-legacy-BkOYOR6U.d.ts} +1 -1
- package/dist/util/packer/index.d.cts +3 -3
- package/dist/util/packer/index.d.ts +3 -3
- package/package.json +15 -3
- package/src/core/interfaces/dataLayerProvider.ts +3 -8
- package/src/core/navigators/Pipeline.ts +5 -2
- package/src/core/navigators/PipelineDebugger.ts +64 -16
- package/src/core/navigators/generators/prescribed.ts +43 -14
- package/src/core/navigators/index.ts +1 -0
- package/src/core/types/studySession.ts +37 -0
- package/src/diagnostics/dataset.ts +231 -0
- package/src/diagnostics/derive.ts +555 -0
- package/src/diagnostics/index.ts +24 -0
- package/src/diagnostics/loader.ts +191 -0
- package/src/diagnostics/text.ts +242 -0
- package/src/impl/couch/PouchDataLayerProvider.ts +0 -23
- package/src/impl/static/StaticDataLayerProvider.ts +0 -11
- package/src/study/SessionController.ts +56 -2
- package/tests/core/navigators/prescribedIntroExposure.test.ts +29 -0
- package/tsup.config.ts +1 -0
|
@@ -165,4 +165,4 @@ interface QuestionRecord extends CardRecord, Evaluation {
|
|
|
165
165
|
priorAttemps: number;
|
|
166
166
|
}
|
|
167
167
|
|
|
168
|
-
export { type
|
|
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
|
|
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-
|
|
2
|
-
export { C as CouchDBToStaticPacker } from '../../index-
|
|
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-
|
|
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-
|
|
2
|
-
export { C as CouchDBToStaticPacker } from '../../index-
|
|
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-
|
|
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.
|
|
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.
|
|
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.
|
|
78
|
+
"stableVersion": "0.2.28"
|
|
67
79
|
}
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
// db/src/core/interfaces.ts
|
|
2
2
|
|
|
3
|
-
import { UserDBInterface
|
|
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
|
-
|
|
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:
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
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:
|
|
297
|
-
const nearMissReported:
|
|
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
|
}
|
|
@@ -48,6 +48,16 @@ interface PrescribedGroupConfig {
|
|
|
48
48
|
maxDirectTargetsPerRun?: number;
|
|
49
49
|
maxSupportCardsPerRun?: number;
|
|
50
50
|
hierarchyWalk?: HierarchyWalkConfig;
|
|
51
|
+
/**
|
|
52
|
+
* Exposure an intro target needs before it may surface. Each target is held
|
|
53
|
+
* back — and cards bearing its missing exposure tags are emitted as support —
|
|
54
|
+
* until every exposure tag it implies (its own `gpc:expose:*` tags, plus
|
|
55
|
+
* `gpc:expose:X` for each `gpc:intro:X`) reaches this count. Default 3: a
|
|
56
|
+
* letter is met incidentally inside other words before it is introduced.
|
|
57
|
+
* Set 0 for targets that must be introduced *before* any exposure — e.g.
|
|
58
|
+
* irregular words, which only ever appear in their own cards.
|
|
59
|
+
*/
|
|
60
|
+
introExposeMinCount?: number;
|
|
51
61
|
retireOnEncounter?: boolean;
|
|
52
62
|
/**
|
|
53
63
|
* Tag patterns identifying *practice* skills to drill once unlocked. For each
|
|
@@ -222,6 +232,32 @@ function formatAge(ms: number): string {
|
|
|
222
232
|
return `${Math.round(hours / 24)}d`;
|
|
223
233
|
}
|
|
224
234
|
|
|
235
|
+
/**
|
|
236
|
+
* The exposure tags an intro target still lacks before it may surface: its own
|
|
237
|
+
* `gpc:expose:*` tags plus `gpc:expose:X` for each `gpc:intro:X`, each needing
|
|
238
|
+
* `minCount` attempts. A `minCount` of 0 requires nothing — not even an entry
|
|
239
|
+
* in `userTagElo`.
|
|
240
|
+
*/
|
|
241
|
+
export function unmetIntroExposeTags(
|
|
242
|
+
tags: string[],
|
|
243
|
+
userTagElo: Record<string, { count: number }>,
|
|
244
|
+
minCount: number
|
|
245
|
+
): string[] {
|
|
246
|
+
if (minCount <= 0) return [];
|
|
247
|
+
|
|
248
|
+
const exposeTags = new Set(tags.filter((tag) => tag.startsWith('gpc:expose:')));
|
|
249
|
+
for (const tag of tags) {
|
|
250
|
+
if (!tag.startsWith('gpc:intro:')) continue;
|
|
251
|
+
const suffix = tag.slice('gpc:intro:'.length);
|
|
252
|
+
if (suffix) exposeTags.add(`gpc:expose:${suffix}`);
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
return [...exposeTags].filter((tag) => {
|
|
256
|
+
const tagElo = userTagElo[tag];
|
|
257
|
+
return !tagElo || tagElo.count < minCount;
|
|
258
|
+
});
|
|
259
|
+
}
|
|
260
|
+
|
|
225
261
|
function pickTopByScore(cards: WeightedCard[], limit: number): WeightedCard[] {
|
|
226
262
|
return [...cards]
|
|
227
263
|
.sort((a, b) => b.score - a.score || a.cardId.localeCompare(b.cardId))
|
|
@@ -609,6 +645,8 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
|
|
|
609
645
|
typeof raw.maxDirectTargetsPerRun === 'number' ? raw.maxDirectTargetsPerRun : DEFAULT_MAX_DIRECT_PER_RUN,
|
|
610
646
|
maxSupportCardsPerRun:
|
|
611
647
|
typeof raw.maxSupportCardsPerRun === 'number' ? raw.maxSupportCardsPerRun : DEFAULT_MAX_SUPPORT_PER_RUN,
|
|
648
|
+
introExposeMinCount:
|
|
649
|
+
typeof raw.introExposeMinCount === 'number' ? raw.introExposeMinCount : DEFAULT_MIN_COUNT,
|
|
612
650
|
hierarchyWalk: {
|
|
613
651
|
enabled: raw.hierarchyWalk?.enabled !== false,
|
|
614
652
|
maxDepth:
|
|
@@ -715,20 +753,11 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
|
|
|
715
753
|
group.hierarchyWalk?.maxDepth ?? DEFAULT_HIERARCHY_DEPTH
|
|
716
754
|
);
|
|
717
755
|
|
|
718
|
-
const
|
|
719
|
-
|
|
720
|
-
|
|
721
|
-
|
|
722
|
-
|
|
723
|
-
if (suffix) {
|
|
724
|
-
exposeTags.add(`gpc:expose:${suffix}`);
|
|
725
|
-
}
|
|
726
|
-
}
|
|
727
|
-
|
|
728
|
-
const unmetExposeTags = [...exposeTags].filter((tag) => {
|
|
729
|
-
const tagElo = userTagElo[tag];
|
|
730
|
-
return !tagElo || tagElo.count < DEFAULT_MIN_COUNT;
|
|
731
|
-
});
|
|
756
|
+
const unmetExposeTags = unmetIntroExposeTags(
|
|
757
|
+
tags,
|
|
758
|
+
userTagElo,
|
|
759
|
+
group.introExposeMinCount ?? DEFAULT_MIN_COUNT
|
|
760
|
+
);
|
|
732
761
|
|
|
733
762
|
if (unmetExposeTags.length > 0) {
|
|
734
763
|
unmetExposeTags.forEach((tag) => supportTags.add(tag));
|
|
@@ -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
|
+
}
|