@vue-skuilder/db 0.2.30 → 0.2.32
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/{contentSource-B6FrSihy.d.cts → contentSource-CTQ4kWhR.d.cts} +41 -4
- package/dist/{contentSource-CqJmbOZN.d.ts → contentSource-JmWYu8IK.d.ts} +41 -4
- package/dist/core/index.d.cts +3 -3
- package/dist/core/index.d.ts +3 -3
- package/dist/core/index.js +138 -79
- package/dist/core/index.js.map +1 -1
- package/dist/core/index.mjs +90 -30
- package/dist/core/index.mjs.map +1 -1
- package/dist/{dataLayerProvider-DUxDqMtZ.d.cts → dataLayerProvider-DfI_KYAe.d.cts} +1 -1
- package/dist/{dataLayerProvider-B9_UCvkR.d.ts → dataLayerProvider-rlLE2Mf-.d.ts} +1 -1
- package/dist/diagnostics/index.d.cts +18 -3
- package/dist/diagnostics/index.d.ts +18 -3
- package/dist/diagnostics/index.js +171 -135
- package/dist/diagnostics/index.js.map +1 -1
- package/dist/diagnostics/index.mjs +168 -135
- package/dist/diagnostics/index.mjs.map +1 -1
- package/dist/impl/couch/index.d.cts +8 -2
- package/dist/impl/couch/index.d.ts +8 -2
- package/dist/impl/couch/index.js +142 -83
- package/dist/impl/couch/index.js.map +1 -1
- package/dist/impl/couch/index.mjs +90 -30
- package/dist/impl/couch/index.mjs.map +1 -1
- package/dist/impl/static/index.d.cts +2 -2
- package/dist/impl/static/index.d.ts +2 -2
- package/dist/impl/static/index.js +129 -70
- package/dist/impl/static/index.js.map +1 -1
- package/dist/impl/static/index.mjs +90 -30
- package/dist/impl/static/index.mjs.map +1 -1
- package/dist/index.d.cts +5 -3
- package/dist/index.d.ts +5 -3
- package/dist/index.js +204 -114
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +128 -37
- package/dist/index.mjs.map +1 -1
- package/package.json +3 -3
- package/src/core/navigators/Pipeline.ts +13 -2
- package/src/core/navigators/PipelineAssembler.ts +2 -0
- package/src/core/navigators/PipelineDebugger.ts +54 -23
- package/src/core/navigators/defaults.ts +4 -1
- package/src/core/navigators/filters/eloDistance.ts +7 -8
- package/src/core/navigators/generators/elo.ts +8 -2
- package/src/core/navigators/generators/prescribed.ts +7 -5
- package/src/core/types/studySession.ts +23 -2
- package/src/core/versionStamps.ts +66 -0
- package/src/diagnostics/derive.ts +5 -2
- package/src/diagnostics/pipeline.ts +28 -0
- package/src/diagnostics/text.ts +24 -4
- package/src/factory.ts +6 -0
- package/src/study/SessionController.ts +6 -1
- package/src/study/services/EloService.ts +33 -6
- package/tsup.config.ts +5 -0
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.32",
|
|
8
8
|
"description": "Database layer for vue-skuilder",
|
|
9
9
|
"main": "dist/index.js",
|
|
10
10
|
"module": "dist/index.mjs",
|
|
@@ -60,7 +60,7 @@
|
|
|
60
60
|
},
|
|
61
61
|
"dependencies": {
|
|
62
62
|
"@nilock2/pouchdb-authentication": "^1.0.2",
|
|
63
|
-
"@vue-skuilder/common": "0.2.
|
|
63
|
+
"@vue-skuilder/common": "0.2.32",
|
|
64
64
|
"cross-fetch": "^4.1.0",
|
|
65
65
|
"moment": "^2.29.4",
|
|
66
66
|
"pouchdb": "^9.0.0",
|
|
@@ -75,5 +75,5 @@
|
|
|
75
75
|
"vite": "^8.0.0",
|
|
76
76
|
"vitest": "^4.1.0"
|
|
77
77
|
},
|
|
78
|
-
"stableVersion": "0.2.
|
|
78
|
+
"stableVersion": "0.2.32"
|
|
79
79
|
}
|
|
@@ -295,6 +295,12 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
|
|
|
295
295
|
*/
|
|
296
296
|
private _cachedOrchestration: OrchestrationContext | null = null;
|
|
297
297
|
|
|
298
|
+
/**
|
|
299
|
+
* Hash of the strategy docs this pipeline was assembled from (see
|
|
300
|
+
* versionStamps.ts), set by whoever builds it. Stamped on every run.
|
|
301
|
+
*/
|
|
302
|
+
strategyHash?: string;
|
|
303
|
+
|
|
298
304
|
/**
|
|
299
305
|
* Persistent tag cache. Maps cardId → tag names.
|
|
300
306
|
*
|
|
@@ -586,7 +592,8 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
|
|
|
586
592
|
|
|
587
593
|
// Capture run for debug API
|
|
588
594
|
try {
|
|
589
|
-
const
|
|
595
|
+
const courseConfig = await this.course?.getCourseConfig().catch(() => undefined);
|
|
596
|
+
const courseName = courseConfig?.name;
|
|
590
597
|
// Pass the full post-filter sorted array; buildRunReport retains all
|
|
591
598
|
// selected cards plus the top-N highest-scoring near-misses and
|
|
592
599
|
// summarizes the discarded tail (see DISCARDED_KEEP_TOP). This keeps
|
|
@@ -607,7 +614,11 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
|
|
|
607
614
|
scoredCards,
|
|
608
615
|
regulators
|
|
609
616
|
);
|
|
610
|
-
|
|
617
|
+
const versions = {
|
|
618
|
+
...(this.strategyHash ? { strategies: this.strategyHash } : {}),
|
|
619
|
+
...(courseConfig?.contentVersion ? { content: courseConfig.contentVersion } : {}),
|
|
620
|
+
};
|
|
621
|
+
captureRun({ ...report, ...(Object.keys(versions).length ? { versions } : {}) });
|
|
611
622
|
} catch (e) {
|
|
612
623
|
logger.debug(`[Pipeline] Failed to capture debug run: ${e}`);
|
|
613
624
|
}
|
|
@@ -9,6 +9,7 @@ import type { CourseDBInterface } from '../interfaces/courseDB';
|
|
|
9
9
|
import type { UserDBInterface } from '../interfaces/userDB';
|
|
10
10
|
import CompositeGenerator from './generators/CompositeGenerator';
|
|
11
11
|
import { planPipeline } from './pipelinePlan';
|
|
12
|
+
import { strategyHash } from '../versionStamps';
|
|
12
13
|
|
|
13
14
|
// ============================================================================
|
|
14
15
|
// PIPELINE ASSEMBLER
|
|
@@ -162,6 +163,7 @@ export class PipelineAssembler {
|
|
|
162
163
|
|
|
163
164
|
// Build pipeline
|
|
164
165
|
const pipeline = new Pipeline(generator, filters, user, course);
|
|
166
|
+
pipeline.strategyHash = strategyHash(strategies);
|
|
165
167
|
|
|
166
168
|
logger.debug(
|
|
167
169
|
`[PipelineAssembler] Assembled pipeline with ${generatorStrategies.length} generator(s) and ${filters.length} filter(s)`
|
|
@@ -78,12 +78,22 @@ export interface FilterImpact {
|
|
|
78
78
|
removed: number;
|
|
79
79
|
}
|
|
80
80
|
|
|
81
|
+
/** A run's version stamps. Either may be absent: no strategy hash, or no content version set. */
|
|
82
|
+
export interface RunVersions {
|
|
83
|
+
strategies?: string;
|
|
84
|
+
content?: string;
|
|
85
|
+
}
|
|
86
|
+
|
|
81
87
|
/** One card as retained in a {@link PipelineRunReport}. */
|
|
82
88
|
export interface RunReportCard {
|
|
83
89
|
cardId: string;
|
|
84
90
|
courseId: string;
|
|
85
|
-
|
|
91
|
+
/** `'review'`: a scheduled review. `'new'`: anything else. */
|
|
92
|
+
origin: 'new' | 'review';
|
|
93
|
+
/** The strategy that produced the card (first provenance entry). Absent if a hint injected it. */
|
|
86
94
|
generator?: string;
|
|
95
|
+
/** The hint that made the card mandatory, if one did. Its source, over `generator`. */
|
|
96
|
+
required?: string;
|
|
87
97
|
finalScore: number;
|
|
88
98
|
/** Card's ELO (parsed from ELO generator provenance, if available) */
|
|
89
99
|
cardElo?: number;
|
|
@@ -140,7 +150,7 @@ export interface PipelineRunReport {
|
|
|
140
150
|
/**
|
|
141
151
|
* The two unselected non-review cards most worth explaining when a run
|
|
142
152
|
* picks no new content. Non-review means no `reviewID`, so prescribed and
|
|
143
|
-
* required cards count
|
|
153
|
+
* required cards count.
|
|
144
154
|
*
|
|
145
155
|
* - `nextInLine`: highest final score. How close new content came.
|
|
146
156
|
* - `topGenerated`: highest generator score, zero-scored cards included.
|
|
@@ -155,6 +165,12 @@ export interface PipelineRunReport {
|
|
|
155
165
|
/** The regulator stage's readings: each class's pressure and the multiplier it got. */
|
|
156
166
|
regulators?: RegulatorReading[];
|
|
157
167
|
|
|
168
|
+
/**
|
|
169
|
+
* What this run ran on (see versionStamps.ts): the hash of the strategy docs
|
|
170
|
+
* the pipeline was assembled from, and the course's content version.
|
|
171
|
+
*/
|
|
172
|
+
versions?: RunVersions;
|
|
173
|
+
|
|
158
174
|
/**
|
|
159
175
|
* Summary of the discarded tail of the candidate pool — cards that were
|
|
160
176
|
* generated and scored but neither selected nor retained in `cards`.
|
|
@@ -240,17 +256,24 @@ export function clearRunHistory(): void {
|
|
|
240
256
|
}
|
|
241
257
|
|
|
242
258
|
/**
|
|
243
|
-
*
|
|
259
|
+
* What a card is to the learner's queue: a scheduled review (it carries a
|
|
260
|
+
* `reviewID`) or new. The same test as the generator counts and
|
|
261
|
+
* `unselectedNew`. What put it in the queue is {@link RunReportCard.generator}
|
|
262
|
+
* and {@link RunReportCard.required}.
|
|
244
263
|
*/
|
|
245
|
-
function getOrigin(card: WeightedCard): 'new' | 'review'
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
264
|
+
function getOrigin(card: WeightedCard): 'new' | 'review' {
|
|
265
|
+
return card.reviewID ? 'review' : 'new';
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
/**
|
|
269
|
+
* The hint that made a card mandatory (its provenance name), if one did.
|
|
270
|
+
* applyHints marks a requireCards/requireTags requirement with an infinite
|
|
271
|
+
* score, and nothing else scores a card infinite.
|
|
272
|
+
*/
|
|
273
|
+
function requiredBy(card: WeightedCard): string | undefined {
|
|
274
|
+
return card.provenance.find(
|
|
275
|
+
(p) => p.strategy === 'ephemeralHint' && p.score === Number.POSITIVE_INFINITY
|
|
276
|
+
)?.strategyName;
|
|
254
277
|
}
|
|
255
278
|
|
|
256
279
|
/**
|
|
@@ -309,17 +332,25 @@ export function buildRunReport(
|
|
|
309
332
|
// into selected vs not-selected, then retain only the top-N of the
|
|
310
333
|
// non-selected group to bound memory. The remaining low-score tail is
|
|
311
334
|
// summarized rather than kept (see discardedTail).
|
|
312
|
-
const toReport = (card: WeightedCard): RunReportCard =>
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
generator
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
335
|
+
const toReport = (card: WeightedCard): RunReportCard => {
|
|
336
|
+
const required = requiredBy(card);
|
|
337
|
+
// A required card no generator produced starts at its hint: no generator.
|
|
338
|
+
const first = card.provenance[0];
|
|
339
|
+
const generator =
|
|
340
|
+
first && first.strategy !== 'ephemeralHint' ? first.strategyName || first.strategy : undefined;
|
|
341
|
+
return {
|
|
342
|
+
cardId: card.cardId,
|
|
343
|
+
courseId: card.courseId,
|
|
344
|
+
origin: getOrigin(card),
|
|
345
|
+
...(generator ? { generator } : {}),
|
|
346
|
+
...(required ? { required } : {}),
|
|
347
|
+
finalScore: card.score,
|
|
348
|
+
cardElo: card.cardElo ?? parseCardElo(card.provenance),
|
|
349
|
+
provenance: card.provenance,
|
|
350
|
+
tags: card.tags,
|
|
351
|
+
selected: selectedIds.has(card.cardId),
|
|
352
|
+
};
|
|
353
|
+
};
|
|
323
354
|
|
|
324
355
|
const selectedReported: RunReportCard[] = [];
|
|
325
356
|
const nearMissReported: RunReportCard[] = [];
|
|
@@ -6,6 +6,7 @@ import SRSNavigator from './generators/srs';
|
|
|
6
6
|
import EloDistanceFilter, { DEFAULT_ELO_DISTANCE_CONFIG } from './filters/eloDistance';
|
|
7
7
|
import type { ContentNavigationStrategyData } from '../types/contentNavigationStrategy';
|
|
8
8
|
import { DocType } from '../types/types-legacy';
|
|
9
|
+
import { DEFAULT_STRATEGY_HASH } from '../versionStamps';
|
|
9
10
|
import type { CourseDBInterface, UserDBInterface } from '../interfaces';
|
|
10
11
|
|
|
11
12
|
/**
|
|
@@ -104,5 +105,7 @@ export function createDefaultPipeline(
|
|
|
104
105
|
createDefaultEloDistanceStrategy(courseId)
|
|
105
106
|
);
|
|
106
107
|
|
|
107
|
-
|
|
108
|
+
const pipeline = new Pipeline(compositeGenerator, [eloDistanceFilter], user, course);
|
|
109
|
+
pipeline.strategyHash = DEFAULT_STRATEGY_HASH;
|
|
110
|
+
return pipeline;
|
|
108
111
|
}
|
|
@@ -5,7 +5,7 @@ import { ContentNavigator } from '../index';
|
|
|
5
5
|
import type { WeightedCard } from '../index';
|
|
6
6
|
import type { GeneratorResult } from '../generators/types';
|
|
7
7
|
import type { CardFilter, FilterContext, FilterKind } from './types';
|
|
8
|
-
import type
|
|
8
|
+
import { COUNT_ONLY_SCORE, isCountOnlyTag, type CourseElo } from '@vue-skuilder/common';
|
|
9
9
|
import { logger } from '../../../util/logger';
|
|
10
10
|
|
|
11
11
|
// ============================================================================
|
|
@@ -99,9 +99,6 @@ export const DEFAULT_ELO_DISTANCE_CONFIG: Required<EloDistanceConfig> = {
|
|
|
99
99
|
*/
|
|
100
100
|
const TAG_CONFIDENCE_HALF = 10;
|
|
101
101
|
|
|
102
|
-
/** Count-only tag ratings (exposure tracking) carry this sentinel score. */
|
|
103
|
-
const COUNT_ONLY_SENTINEL = -1;
|
|
104
|
-
|
|
105
102
|
/** Fallback card ELO when a card has none recorded. */
|
|
106
103
|
const DEFAULT_CARD_ELO = 1000;
|
|
107
104
|
|
|
@@ -186,9 +183,9 @@ interface TagGap {
|
|
|
186
183
|
* read on the tags they share.
|
|
187
184
|
*
|
|
188
185
|
* - Shared tags: the card's tags on which the learner has a real rating
|
|
189
|
-
* (not the count-only sentinel) resting on at least
|
|
190
|
-
* responses. A card with no rating of its own on a tag
|
|
191
|
-
* the ELO update does when it first grades that tag.
|
|
186
|
+
* (not a bookkeeping role, nor the count-only sentinel) resting on at least
|
|
187
|
+
* `minTagCount` graded responses. A card with no rating of its own on a tag
|
|
188
|
+
* uses its global, as the ELO update does when it first grades that tag.
|
|
192
189
|
* - Each tag's gap is weighted by the learner's evidence on it,
|
|
193
190
|
* n / (n + TAG_CONFIDENCE_HALF).
|
|
194
191
|
* - The weighted mean of the tag gaps is blended with the global gap by the
|
|
@@ -232,7 +229,9 @@ export function tagAwareGap(
|
|
|
232
229
|
const tags: TagGap[] = [];
|
|
233
230
|
for (const tag of cardTags) {
|
|
234
231
|
const user = userElo.tags[tag];
|
|
235
|
-
if (!user || user.score ===
|
|
232
|
+
if (isCountOnlyTag(tag) || !user || user.score === COUNT_ONLY_SCORE || user.count < minTagCount) {
|
|
233
|
+
continue;
|
|
234
|
+
}
|
|
236
235
|
const card = cardElo.tags[tag]?.score ?? cardElo.global.score;
|
|
237
236
|
tags.push({
|
|
238
237
|
tag,
|
|
@@ -75,12 +75,18 @@ export default class ELONavigator extends ContentNavigator implements CardGenera
|
|
|
75
75
|
}
|
|
76
76
|
// const tUser = performance.now(); // [perf] parked
|
|
77
77
|
|
|
78
|
-
|
|
78
|
+
// Not new: cards with a pending review, and cards seen without one (e.g.
|
|
79
|
+
// `srs:skip` intros, which must not resurface). As the prescribed generator.
|
|
80
|
+
const [activeCards, seenCards] = await Promise.all([
|
|
81
|
+
this.user.getActiveCards(),
|
|
82
|
+
this.user.getSeenCards(this.course.getCourseID()).catch(() => [] as string[]),
|
|
83
|
+
]);
|
|
84
|
+
const notNew = new Set([...activeCards.map((ac) => ac.cardID), ...seenCards]);
|
|
79
85
|
// const tActive = performance.now(); // [perf] parked
|
|
80
86
|
const newCards = (
|
|
81
87
|
await this.course.getCardsCenteredAtELO(
|
|
82
88
|
{ limit, elo: 'user' },
|
|
83
|
-
(c: QualifiedCardID) => !
|
|
89
|
+
(c: QualifiedCardID) => !notNew.has(c.cardID)
|
|
84
90
|
)
|
|
85
91
|
).map((c) => ({ ...c, status: 'new' as const }));
|
|
86
92
|
// const tCentered = performance.now(); // [perf] parked
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { tagRole, withTagRole } from '@vue-skuilder/common';
|
|
1
2
|
import type { CourseDBInterface } from '../../interfaces/courseDB';
|
|
2
3
|
import type { UserDBInterface } from '../../interfaces/userDB';
|
|
3
4
|
import { ContentNavigator } from '../index';
|
|
@@ -234,7 +235,8 @@ function formatAge(ms: number): string {
|
|
|
234
235
|
|
|
235
236
|
/**
|
|
236
237
|
* The exposure tags an intro target still lacks before it may surface: its own
|
|
237
|
-
* `
|
|
238
|
+
* `expose` tags plus the `expose` counterpart of each `intro` tag (tag roles,
|
|
239
|
+
* see common's tagRoles.ts: `gpc:intro:X` → `gpc:expose:X`), each needing
|
|
238
240
|
* `minCount` attempts. A `minCount` of 0 requires nothing — not even an entry
|
|
239
241
|
* in `userTagElo`.
|
|
240
242
|
*/
|
|
@@ -245,11 +247,11 @@ export function unmetIntroExposeTags(
|
|
|
245
247
|
): string[] {
|
|
246
248
|
if (minCount <= 0) return [];
|
|
247
249
|
|
|
248
|
-
const exposeTags = new Set(tags.filter((tag) => tag
|
|
250
|
+
const exposeTags = new Set(tags.filter((tag) => tagRole(tag) === 'expose'));
|
|
249
251
|
for (const tag of tags) {
|
|
250
|
-
if (
|
|
251
|
-
const
|
|
252
|
-
if (
|
|
252
|
+
if (tagRole(tag) !== 'intro') continue;
|
|
253
|
+
const expose = withTagRole(tag, 'expose');
|
|
254
|
+
if (expose) exposeTags.add(expose);
|
|
253
255
|
}
|
|
254
256
|
|
|
255
257
|
return [...exposeTags].filter((tag) => {
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { DocType, DocTypePrefixes } from './types-legacy';
|
|
2
2
|
import type { ReplanHints } from '../navigators/generators/types';
|
|
3
|
-
import type { GeneratorSummary, FilterImpact } from '../navigators/PipelineDebugger';
|
|
3
|
+
import type { GeneratorSummary, FilterImpact, RunVersions } from '../navigators/PipelineDebugger';
|
|
4
4
|
import type { RegulatorReading } from '../navigators/regulators';
|
|
5
5
|
import type { StrategyContribution } from '../navigators';
|
|
6
6
|
|
|
@@ -38,6 +38,14 @@ export interface StudySessionDoc {
|
|
|
38
38
|
initHints?: ReplanHints | null;
|
|
39
39
|
};
|
|
40
40
|
|
|
41
|
+
/**
|
|
42
|
+
* The code this session ran on: the framework's version (`'dev'` when run
|
|
43
|
+
* from source) and the host app's, if it reported one (`appVersion` in the
|
|
44
|
+
* data-layer config). Strategy and content versions are stamped per run.
|
|
45
|
+
* Absent on sessions recorded before this shipped.
|
|
46
|
+
*/
|
|
47
|
+
versions?: { framework: string; app?: string };
|
|
48
|
+
|
|
41
49
|
/** Queue depths after the bootstrap run, before the first draw. */
|
|
42
50
|
initialQueues: { supplyQ: number; failedQ: number };
|
|
43
51
|
|
|
@@ -122,14 +130,27 @@ export interface StudySessionRunSummary {
|
|
|
122
130
|
};
|
|
123
131
|
/** The regulator stage's readings: review mass and intake, each with its multiplier (0.2.29+). */
|
|
124
132
|
regulators?: RegulatorReading[];
|
|
133
|
+
/** What the run ran on: the strategy docs' hash and the course's content version. */
|
|
134
|
+
versions?: RunVersions;
|
|
125
135
|
}
|
|
126
136
|
|
|
127
137
|
/** A card as persisted on a run. `origin` is as counted in `newSelected`/`reviewsSelected`. */
|
|
128
138
|
export interface StudySessionRunCard {
|
|
129
139
|
cardId: string;
|
|
140
|
+
/**
|
|
141
|
+
* `'review'`: a scheduled review. `'new'`: anything else. `'unknown'` only on
|
|
142
|
+
* older runs, which counted prescribed and hint-required cards as neither.
|
|
143
|
+
*/
|
|
130
144
|
origin: 'new' | 'review' | 'unknown';
|
|
145
|
+
/**
|
|
146
|
+
* The strategy that produced the card. Absent if a hint injected it (older
|
|
147
|
+
* runs name the hint here instead).
|
|
148
|
+
*/
|
|
131
149
|
generator?: string;
|
|
132
|
-
|
|
150
|
+
/** The hint that made the card mandatory, if one did. Its source, over `generator`. */
|
|
151
|
+
required?: string;
|
|
152
|
+
/** Final score; null for a mandatory (required) card, whose score is infinite. */
|
|
153
|
+
score: number | null;
|
|
133
154
|
selected: boolean;
|
|
134
155
|
}
|
|
135
156
|
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
import type { ContentNavigationStrategyData } from './types/contentNavigationStrategy';
|
|
2
|
+
|
|
3
|
+
// ============================================================================
|
|
4
|
+
// VERSION STAMPS
|
|
5
|
+
// ============================================================================
|
|
6
|
+
//
|
|
7
|
+
// What a study session ran on, written into its records so a change shows up
|
|
8
|
+
// in them: framework and app releases on the session doc, the strategy docs
|
|
9
|
+
// and the content version on each pipeline run (either can change mid-session).
|
|
10
|
+
//
|
|
11
|
+
// ============================================================================
|
|
12
|
+
|
|
13
|
+
declare const __SKUILDER_DB_VERSION__: string | undefined;
|
|
14
|
+
|
|
15
|
+
/** This build's @vue-skuilder/db version, set at build time; `'dev'` when run from source. */
|
|
16
|
+
export const FRAMEWORK_VERSION: string =
|
|
17
|
+
typeof __SKUILDER_DB_VERSION__ === 'string' ? __SKUILDER_DB_VERSION__ : 'dev';
|
|
18
|
+
|
|
19
|
+
let hostAppVersion: string | undefined;
|
|
20
|
+
|
|
21
|
+
/** Record the host app's version (the data layer's `appVersion` option). */
|
|
22
|
+
export function setAppVersion(version: string): void {
|
|
23
|
+
hostAppVersion = version;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/** What a session stamps: the framework's version, and the app's if it reported one. */
|
|
27
|
+
export function sessionVersions(): { framework: string; app?: string } {
|
|
28
|
+
return { framework: FRAMEWORK_VERSION, ...(hostAppVersion ? { app: hostAppVersion } : {}) };
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/** Stamp for a pipeline built without strategy docs (the built-in default). */
|
|
32
|
+
export const DEFAULT_STRATEGY_HASH = 'default';
|
|
33
|
+
|
|
34
|
+
/** JSON with object keys sorted, so equal docs stringify equally. */
|
|
35
|
+
function stableStringify(value: unknown): string {
|
|
36
|
+
if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
|
|
37
|
+
if (value && typeof value === 'object') {
|
|
38
|
+
const entries = Object.entries(value as Record<string, unknown>)
|
|
39
|
+
.filter(([, v]) => v !== undefined)
|
|
40
|
+
.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
|
|
41
|
+
return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(',')}}`;
|
|
42
|
+
}
|
|
43
|
+
return JSON.stringify(value);
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* A short hash of a course's strategy docs: 8 hex chars, FNV-1a over their
|
|
48
|
+
* content (not `_rev`, which a redeploy of the same content also changes).
|
|
49
|
+
* Equal for equal strategy sets, whatever order they load in.
|
|
50
|
+
*/
|
|
51
|
+
export function strategyHash(strategies: readonly ContentNavigationStrategyData[]): string {
|
|
52
|
+
if (strategies.length === 0) return DEFAULT_STRATEGY_HASH;
|
|
53
|
+
const text = strategies
|
|
54
|
+
.map((s) => {
|
|
55
|
+
const { _rev: _ignored, ...rest } = s as ContentNavigationStrategyData & { _rev?: string };
|
|
56
|
+
return stableStringify(rest);
|
|
57
|
+
})
|
|
58
|
+
.sort()
|
|
59
|
+
.join('\n');
|
|
60
|
+
let h = 0x811c9dc5;
|
|
61
|
+
for (let i = 0; i < text.length; i++) {
|
|
62
|
+
h ^= text.charCodeAt(i);
|
|
63
|
+
h = Math.imul(h, 0x01000193);
|
|
64
|
+
}
|
|
65
|
+
return (h >>> 0).toString(16).padStart(8, '0');
|
|
66
|
+
}
|
|
@@ -298,7 +298,10 @@ function toResponseEloDelta(
|
|
|
298
298
|
|
|
299
299
|
/**
|
|
300
300
|
* Attach each ELO event to its response. The event carries no record id, so
|
|
301
|
-
* join by card and nearest time, using each response at most once.
|
|
301
|
+
* join by card and nearest time, using each response at most once. A record
|
|
302
|
+
* is stamped when the card is shown and an event when the answer is
|
|
303
|
+
* submitted, so the join is on the response's end (shown + time spent):
|
|
304
|
+
* joined on the start, a long response's event lands on the next attempt.
|
|
302
305
|
*/
|
|
303
306
|
function attachEloEvents(
|
|
304
307
|
responses: TimelineResponse[],
|
|
@@ -312,7 +315,7 @@ function attachEloEvents(
|
|
|
312
315
|
let bestGap = Infinity;
|
|
313
316
|
responses.forEach((r, i) => {
|
|
314
317
|
if (used.has(i) || r.cardId !== ev.cardId) return;
|
|
315
|
-
const gap = Math.abs(Date.parse(r.at) - evT);
|
|
318
|
+
const gap = Math.abs(Date.parse(r.at) + r.timeSpentMs - evT);
|
|
316
319
|
if (gap < bestGap) {
|
|
317
320
|
bestGap = gap;
|
|
318
321
|
best = i;
|
|
@@ -1,6 +1,34 @@
|
|
|
1
1
|
import type { DatasetRecord, LearnerDataset } from './dataset';
|
|
2
2
|
import type { FilterKind } from '../core/navigators/filters/types';
|
|
3
3
|
import type { RegulatorName, RegulatorReading } from '../core/navigators/regulators';
|
|
4
|
+
import type { StudySessionRunCard, StudySessionRunSummary } from '../core/types/studySession';
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* What put a run's card in the queue: the hint that required it, else the
|
|
8
|
+
* generator that produced it. Its `origin` says what it is (review or new).
|
|
9
|
+
*/
|
|
10
|
+
export function runCardSource(card: Pick<StudySessionRunCard, 'generator' | 'required'>): string {
|
|
11
|
+
if (card.required) return `required: ${card.required}`;
|
|
12
|
+
return card.generator ?? 'unknown';
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* A run's selected cards counted by source, most first. Empty for runs that
|
|
17
|
+
* don't persist their cards (before 0.2.28).
|
|
18
|
+
*/
|
|
19
|
+
export function selectedBySource(
|
|
20
|
+
run: Pick<StudySessionRunSummary, 'cards'>
|
|
21
|
+
): Array<{ source: string; count: number }> {
|
|
22
|
+
const counts = new Map<string, number>();
|
|
23
|
+
for (const c of run.cards ?? []) {
|
|
24
|
+
if (!c.selected) continue;
|
|
25
|
+
const source = runCardSource(c);
|
|
26
|
+
counts.set(source, (counts.get(source) ?? 0) + 1);
|
|
27
|
+
}
|
|
28
|
+
return [...counts]
|
|
29
|
+
.map(([source, count]) => ({ source, count }))
|
|
30
|
+
.sort((a, b) => b.count - a.count);
|
|
31
|
+
}
|
|
4
32
|
|
|
5
33
|
// ============================================================================
|
|
6
34
|
// Pipeline run stats
|
package/src/diagnostics/text.ts
CHANGED
|
@@ -5,6 +5,7 @@
|
|
|
5
5
|
*/
|
|
6
6
|
import type { StudySessionRunCardTrail, StudySessionRunSummary } from '../core/types/studySession';
|
|
7
7
|
import type { RegulatorReading } from '../core/navigators/regulators';
|
|
8
|
+
import { runCardSource, selectedBySource } from './pipeline';
|
|
8
9
|
import {
|
|
9
10
|
shortTag,
|
|
10
11
|
type DiagnosticsInterpreters,
|
|
@@ -42,13 +43,15 @@ export function fmtAnswer(a: unknown, max = 40): string {
|
|
|
42
43
|
}
|
|
43
44
|
}
|
|
44
45
|
|
|
45
|
-
|
|
46
|
+
/** Two decimals, or one significant figure when tiny; `∞` for a required card's score (persisted as null). */
|
|
47
|
+
export function fmtScore(n: number | null): string {
|
|
48
|
+
if (n === null || !Number.isFinite(n)) return '∞';
|
|
46
49
|
return Math.abs(n) >= 0.01 || n === 0 ? n.toFixed(2) : n.toExponential(1);
|
|
47
50
|
}
|
|
48
51
|
|
|
49
52
|
function trailText(label: string, t: StudySessionRunCardTrail): string[] {
|
|
50
53
|
const lines = [
|
|
51
|
-
` ${label}: ${t.cardId} (${t.origin}, ${t
|
|
54
|
+
` ${label}: ${t.cardId} (${t.origin}, ${runCardSource(t)}) final ${fmtScore(t.score)}`,
|
|
52
55
|
];
|
|
53
56
|
for (const p of t.trail) {
|
|
54
57
|
lines.push(` ${p.action} ${p.strategyName} → ${fmtScore(p.score)}: ${p.reason}`);
|
|
@@ -82,6 +85,11 @@ export function runText(run: StudySessionRunSummary): string {
|
|
|
82
85
|
(run.generatedCount > 0 && run.finalCount === 0 ? ' ⚠ nothing survived' : '')
|
|
83
86
|
);
|
|
84
87
|
if (typeof run.userElo === 'number') L.push(` userElo: ${Math.round(run.userElo)}`);
|
|
88
|
+
if (run.versions) {
|
|
89
|
+
L.push(
|
|
90
|
+
` versions: strategies ${run.versions.strategies ?? '—'} · content ${run.versions.content ?? '—'}`
|
|
91
|
+
);
|
|
92
|
+
}
|
|
85
93
|
if (run.generators?.length) {
|
|
86
94
|
L.push(' generators:');
|
|
87
95
|
for (const g of run.generators) {
|
|
@@ -106,10 +114,12 @@ export function runText(run: StudySessionRunSummary): string {
|
|
|
106
114
|
}
|
|
107
115
|
if (run.hints) L.push(` hints: ${JSON.stringify(run.hints)}`);
|
|
108
116
|
if (run.cards?.length) {
|
|
117
|
+
const sources = selectedBySource(run).map((s) => `${s.source} ${s.count}`);
|
|
118
|
+
if (sources.length) L.push(` selected by source: ${sources.join(' · ')}`);
|
|
109
119
|
L.push(' selection (✓ selected, · runner-up):');
|
|
110
120
|
for (const c of run.cards) {
|
|
111
121
|
L.push(
|
|
112
|
-
` ${c.selected ? '✓' : '·'} ${c.cardId} (${c.origin}, ${c
|
|
122
|
+
` ${c.selected ? '✓' : '·'} ${c.cardId} (${c.origin}, ${runCardSource(c)}) ${fmtScore(c.score)}`
|
|
113
123
|
);
|
|
114
124
|
}
|
|
115
125
|
}
|
|
@@ -176,9 +186,13 @@ export function sessionText(
|
|
|
176
186
|
L.push(' (gate: not ready yet; signal: preference). regulators: the pressure on each class,');
|
|
177
187
|
L.push(' review mass (due reviews by value) and intake (hours since a new card).');
|
|
178
188
|
L.push(' hints: the ReplanHints the navigator was told (_label = replan reason).');
|
|
189
|
+
L.push(" versions: the strategy docs' hash and the content version the run ran on; the");
|
|
190
|
+
L.push(" headline's are the framework and app versions. A change between runs marks a deploy.");
|
|
179
191
|
L.push(' selection: the chosen cards and top runners-up. "next new in line" / "top-generated');
|
|
180
192
|
L.push(' new (sunk)": the unselected new cards worth explaining, with each score change.');
|
|
181
|
-
L.push('
|
|
193
|
+
L.push(' Each card reads (origin, source). origin: review = a scheduled review, new = anything');
|
|
194
|
+
L.push(' else. source: the generator that produced it, or "required: <hint>" when a hint forced');
|
|
195
|
+
L.push(' it. Older runs show origin "unknown" for prescribed and hint-required cards.');
|
|
182
196
|
L.push('- RESP "✓/✗ type <cardId> [tags] Ts (attempt k) \'answer\'": one presentation and');
|
|
183
197
|
L.push(' its outcome. A trailing "ELO g:before→after (Δ) | tag:Δ …" is the exchange it');
|
|
184
198
|
L.push(' produced. Only first attempts move ELO.');
|
|
@@ -187,6 +201,12 @@ export function sessionText(
|
|
|
187
201
|
L.push('## Headline');
|
|
188
202
|
L.push(`- status: ${doc.status}`);
|
|
189
203
|
L.push(`- start: ${doc.startTime}${doc.endTime ? ` · end: ${doc.endTime}` : ''}`);
|
|
204
|
+
if (doc.versions) {
|
|
205
|
+
L.push(
|
|
206
|
+
`- versions: framework ${doc.versions.framework}` +
|
|
207
|
+
(doc.versions.app ? ` · app ${doc.versions.app}` : '')
|
|
208
|
+
);
|
|
209
|
+
}
|
|
190
210
|
L.push(
|
|
191
211
|
`- clock: ${s.durationSeconds ?? '—'}s of ${doc.plannedSeconds}s planned` +
|
|
192
212
|
(doc.tally ? ` · ${doc.tally.secondsRemaining}s remaining` : '')
|
package/src/factory.ts
CHANGED
|
@@ -5,6 +5,7 @@ import { BaseUser } from './impl/common';
|
|
|
5
5
|
import { logger } from './util/logger';
|
|
6
6
|
import { StaticCourseManifest } from './util/packer/types';
|
|
7
7
|
import { initializeNavigatorRegistry } from './core/navigators';
|
|
8
|
+
import { setAppVersion } from './core/versionStamps';
|
|
8
9
|
|
|
9
10
|
const NOT_SET = 'NOT_SET' as const;
|
|
10
11
|
|
|
@@ -30,6 +31,8 @@ export interface DataLayerConfig {
|
|
|
30
31
|
options: {
|
|
31
32
|
staticContentPath?: string; // Path to static content JSON files
|
|
32
33
|
localStoragePrefix?: string; // Prefix for IndexedDB storage names
|
|
34
|
+
/** The host app's version (e.g. a git SHA), stamped on every study session it records. */
|
|
35
|
+
appVersion?: string;
|
|
33
36
|
manifests?: Record<string, StaticCourseManifest>; // Course manifests for static mode
|
|
34
37
|
COUCHDB_SERVER_URL?: string;
|
|
35
38
|
COUCHDB_SERVER_PROTOCOL?: string;
|
|
@@ -71,6 +74,9 @@ export async function initializeDataLayer(config: DataLayerConfig): Promise<Data
|
|
|
71
74
|
if (config.options.localStoragePrefix) {
|
|
72
75
|
ENV.LOCAL_STORAGE_PREFIX = config.options.localStoragePrefix;
|
|
73
76
|
}
|
|
77
|
+
if (config.options.appVersion) {
|
|
78
|
+
setAppVersion(config.options.appVersion);
|
|
79
|
+
}
|
|
74
80
|
|
|
75
81
|
if (config.type === 'couch') {
|
|
76
82
|
if (!config.options.COUCHDB_SERVER_URL || !config.options.COUCHDB_SERVER_PROTOCOL) {
|
|
@@ -39,6 +39,7 @@ import type { PipelineRunReport, RunReportCard } from '@db/core/navigators';
|
|
|
39
39
|
import { ReplanHints } from '@db/core/navigators/generators/types';
|
|
40
40
|
import { mergeHints } from '@db/core/navigators/Pipeline';
|
|
41
41
|
import type { RegulatorReading } from '@db/core/navigators/regulators';
|
|
42
|
+
import { sessionVersions } from '@db/core/versionStamps';
|
|
42
43
|
import { SourceMixer, QuotaRoundRobinMixer, SourceBatch } from './SourceMixer';
|
|
43
44
|
import { captureMixerRun } from './MixerDebugger';
|
|
44
45
|
import { startSessionTracking, recordCardPresentation, snapshotQueues, endSessionTracking, clearStaleSessionDebugState } from './SessionDebugger';
|
|
@@ -239,7 +240,9 @@ function toRunCard(c: RunReportCard): StudySessionRunCard {
|
|
|
239
240
|
cardId: c.cardId,
|
|
240
241
|
origin: c.origin,
|
|
241
242
|
...(c.generator ? { generator: c.generator } : {}),
|
|
242
|
-
|
|
243
|
+
...(c.required ? { required: c.required } : {}),
|
|
244
|
+
// A required card's score is infinite, which JSON can't hold: say so with null.
|
|
245
|
+
score: Number.isFinite(c.finalScore) ? sig4(c.finalScore) : null,
|
|
243
246
|
selected: c.selected,
|
|
244
247
|
};
|
|
245
248
|
}
|
|
@@ -647,6 +650,7 @@ export class SessionController<TView = unknown> extends Loggable {
|
|
|
647
650
|
cards: persistedRunCards(run),
|
|
648
651
|
...(run.unselectedNew ? { unselectedNew: persistedUnselectedNew(run.unselectedNew) } : {}),
|
|
649
652
|
...(run.regulators ? { regulators: run.regulators.map(persistedReading) } : {}),
|
|
653
|
+
...(run.versions ? { versions: run.versions } : {}),
|
|
650
654
|
});
|
|
651
655
|
}
|
|
652
656
|
}
|
|
@@ -687,6 +691,7 @@ export class SessionController<TView = unknown> extends Loggable {
|
|
|
687
691
|
sourceCount: this.sources.length,
|
|
688
692
|
initHints: this._sessionHints,
|
|
689
693
|
},
|
|
694
|
+
versions: sessionVersions(),
|
|
690
695
|
initialQueues: { supplyQ: this.supplyQ.length, failedQ: this.failedQ.length },
|
|
691
696
|
runs: [...this._runLog],
|
|
692
697
|
stateAtStart: await this._captureState('start'),
|