@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.
Files changed (51) hide show
  1. package/dist/{contentSource-B6FrSihy.d.cts → contentSource-CTQ4kWhR.d.cts} +41 -4
  2. package/dist/{contentSource-CqJmbOZN.d.ts → contentSource-JmWYu8IK.d.ts} +41 -4
  3. package/dist/core/index.d.cts +3 -3
  4. package/dist/core/index.d.ts +3 -3
  5. package/dist/core/index.js +138 -79
  6. package/dist/core/index.js.map +1 -1
  7. package/dist/core/index.mjs +90 -30
  8. package/dist/core/index.mjs.map +1 -1
  9. package/dist/{dataLayerProvider-DUxDqMtZ.d.cts → dataLayerProvider-DfI_KYAe.d.cts} +1 -1
  10. package/dist/{dataLayerProvider-B9_UCvkR.d.ts → dataLayerProvider-rlLE2Mf-.d.ts} +1 -1
  11. package/dist/diagnostics/index.d.cts +18 -3
  12. package/dist/diagnostics/index.d.ts +18 -3
  13. package/dist/diagnostics/index.js +171 -135
  14. package/dist/diagnostics/index.js.map +1 -1
  15. package/dist/diagnostics/index.mjs +168 -135
  16. package/dist/diagnostics/index.mjs.map +1 -1
  17. package/dist/impl/couch/index.d.cts +8 -2
  18. package/dist/impl/couch/index.d.ts +8 -2
  19. package/dist/impl/couch/index.js +142 -83
  20. package/dist/impl/couch/index.js.map +1 -1
  21. package/dist/impl/couch/index.mjs +90 -30
  22. package/dist/impl/couch/index.mjs.map +1 -1
  23. package/dist/impl/static/index.d.cts +2 -2
  24. package/dist/impl/static/index.d.ts +2 -2
  25. package/dist/impl/static/index.js +129 -70
  26. package/dist/impl/static/index.js.map +1 -1
  27. package/dist/impl/static/index.mjs +90 -30
  28. package/dist/impl/static/index.mjs.map +1 -1
  29. package/dist/index.d.cts +5 -3
  30. package/dist/index.d.ts +5 -3
  31. package/dist/index.js +204 -114
  32. package/dist/index.js.map +1 -1
  33. package/dist/index.mjs +128 -37
  34. package/dist/index.mjs.map +1 -1
  35. package/package.json +3 -3
  36. package/src/core/navigators/Pipeline.ts +13 -2
  37. package/src/core/navigators/PipelineAssembler.ts +2 -0
  38. package/src/core/navigators/PipelineDebugger.ts +54 -23
  39. package/src/core/navigators/defaults.ts +4 -1
  40. package/src/core/navigators/filters/eloDistance.ts +7 -8
  41. package/src/core/navigators/generators/elo.ts +8 -2
  42. package/src/core/navigators/generators/prescribed.ts +7 -5
  43. package/src/core/types/studySession.ts +23 -2
  44. package/src/core/versionStamps.ts +66 -0
  45. package/src/diagnostics/derive.ts +5 -2
  46. package/src/diagnostics/pipeline.ts +28 -0
  47. package/src/diagnostics/text.ts +24 -4
  48. package/src/factory.ts +6 -0
  49. package/src/study/SessionController.ts +6 -1
  50. package/src/study/services/EloService.ts +33 -6
  51. 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.30",
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.30",
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.30"
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 courseName = await this.course?.getCourseConfig().then((c) => c.name).catch(() => undefined);
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
- captureRun(report);
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
- origin: 'new' | 'review' | 'unknown';
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 (their `origin` reads `'unknown'`).
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
- * Determine card origin from provenance trail.
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' | 'unknown' {
246
- const firstEntry = card.provenance[0];
247
- if (!firstEntry) return 'unknown';
248
- const reason = firstEntry.reason?.toLowerCase() || '';
249
- const strategy = firstEntry.strategy?.toLowerCase() || '';
250
-
251
- if (reason.includes('new card') || strategy.includes('elo')) return 'new';
252
- if (reason.includes('review') || strategy.includes('srs')) return 'review';
253
- return 'unknown';
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
- cardId: card.cardId,
314
- courseId: card.courseId,
315
- origin: getOrigin(card),
316
- generator: card.provenance[0]?.strategyName || card.provenance[0]?.strategy,
317
- finalScore: card.score,
318
- cardElo: card.cardElo ?? parseCardElo(card.provenance),
319
- provenance: card.provenance,
320
- tags: card.tags,
321
- selected: selectedIds.has(card.cardId),
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
- return new Pipeline(compositeGenerator, [eloDistanceFilter], user, course);
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 { CourseElo } from '@vue-skuilder/common';
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 `minTagCount` graded
190
- * responses. A card with no rating of its own on a tag uses its global, as
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 === COUNT_ONLY_SENTINEL || user.count < minTagCount) continue;
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
- const activeCards = await this.user.getActiveCards();
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) => !activeCards.some((ac) => c.cardID === ac.cardID)
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
- * `gpc:expose:*` tags plus `gpc:expose:X` for each `gpc:intro:X`, each needing
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.startsWith('gpc:expose:')));
250
+ const exposeTags = new Set(tags.filter((tag) => tagRole(tag) === 'expose'));
249
251
  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}`);
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
- score: number;
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
@@ -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
- function fmtScore(n: number): string {
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.generator ?? '?'}) final ${fmtScore(t.score)}`,
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.generator ?? '?'}) ${fmtScore(c.score)}`
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(' Prescribed and hint-required cards count as origin "unknown" (known miscount).');
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
- score: sig4(c.finalScore),
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'),