@vue-skuilder/db 0.3.1 → 0.3.3

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 (53) hide show
  1. package/dist/{contentSource-2zVmcjKA.d.ts → contentSource-CSI0pJ2D.d.ts} +10 -0
  2. package/dist/core/index.cjs +62 -14
  3. package/dist/core/index.cjs.map +1 -1
  4. package/dist/core/index.d.ts +3 -3
  5. package/dist/core/interfaces/contentSource.mjs.map +1 -1
  6. package/dist/core/navigators/Pipeline.mjs +7 -1
  7. package/dist/core/navigators/Pipeline.mjs.map +1 -1
  8. package/dist/core/navigators/filters/eloDistance.mjs +17 -2
  9. package/dist/core/navigators/filters/eloDistance.mjs.map +1 -1
  10. package/dist/core/navigators/generators/prescribed.mjs +20 -10
  11. package/dist/core/navigators/generators/prescribed.mjs.map +1 -1
  12. package/dist/core/navigators/index.mjs +2 -0
  13. package/dist/core/navigators/index.mjs.map +1 -1
  14. package/dist/core/versionStamps.mjs +1 -1
  15. package/dist/{dataLayerProvider-rGyLQ93v.d.ts → dataLayerProvider-D5n1gGc_.d.ts} +1 -1
  16. package/dist/diagnostics/derive.mjs.map +1 -1
  17. package/dist/diagnostics/index.cjs +16 -3
  18. package/dist/diagnostics/index.cjs.map +1 -1
  19. package/dist/diagnostics/index.d.ts +29 -6
  20. package/dist/diagnostics/tagElo.mjs +20 -4
  21. package/dist/diagnostics/tagElo.mjs.map +1 -1
  22. package/dist/impl/couch/courseDB.mjs +5 -0
  23. package/dist/impl/couch/courseDB.mjs.map +1 -1
  24. package/dist/impl/couch/index.cjs +37 -2
  25. package/dist/impl/couch/index.cjs.map +1 -1
  26. package/dist/impl/couch/index.d.ts +4 -2
  27. package/dist/impl/static/courseDB.mjs +5 -0
  28. package/dist/impl/static/courseDB.mjs.map +1 -1
  29. package/dist/impl/static/index.cjs +37 -2
  30. package/dist/impl/static/index.cjs.map +1 -1
  31. package/dist/impl/static/index.d.ts +4 -2
  32. package/dist/index.cjs +80 -16
  33. package/dist/index.cjs.map +1 -1
  34. package/dist/index.d.ts +3 -3
  35. package/dist/study/SessionController.mjs +1 -0
  36. package/dist/study/SessionController.mjs.map +1 -1
  37. package/dist/study/services/tagRecent.mjs +2 -1
  38. package/dist/study/services/tagRecent.mjs.map +1 -1
  39. package/package.json +3 -3
  40. package/src/core/interfaces/contentSource.ts +7 -0
  41. package/src/core/navigators/Pipeline.ts +7 -0
  42. package/src/core/navigators/filters/eloDistance.ts +31 -2
  43. package/src/core/navigators/generators/prescribed.ts +55 -11
  44. package/src/core/navigators/generators/types.ts +3 -0
  45. package/src/core/navigators/index.ts +5 -0
  46. package/src/diagnostics/derive.ts +6 -1
  47. package/src/diagnostics/tagElo.ts +43 -3
  48. package/src/impl/couch/courseDB.ts +13 -0
  49. package/src/impl/static/courseDB.ts +13 -0
  50. package/src/study/SessionController.ts +3 -0
  51. package/src/study/services/tagRecent.test.ts +57 -3
  52. package/src/study/services/tagRecent.ts +8 -1
  53. package/tests/core/navigators/eloDistanceFilter.test.ts +15 -0
@@ -1 +1 @@
1
- {"version":3,"file":"tagRecent.mjs","names":[],"sources":["../../../src/study/services/tagRecent.ts"],"sourcesContent":["import {\n CourseElo,\n EloRank,\n TaggedPerformance,\n TagPresentation,\n pushTagPresentation,\n} from '@vue-skuilder/common';\nimport { CardRecord } from '@db/core';\n\n/**\n * Mastery signal: per-tag ring buffer of recent presentations.\n *\n * Written on the same path as the per-tag ELO update, one entry per\n * *presentation* of a card. Retries within a presentation (a record with\n * `priorAttemps > 0`, or any record after the first on the current card)\n * are not evidence and add nothing — including the \"dismiss-failed\" final\n * penalty, which reaches the ELO path on a retry record.\n *\n * Only tags the question actually graded (numeric perf) get an entry;\n * count-only exposure tags (`null`) carry no correctness signal.\n */\n\n/** The record for the presentation being graded, or null if none is visible. */\nfunction currentRecord(records: readonly CardRecord[]): CardRecord | null {\n return records.length ? records[records.length - 1] : null;\n}\n\n/**\n * Whether the record under grading is the first attempt of its presentation.\n *\n * `priorAttemps` is the authoritative marker (written by the question view).\n * When it is absent (non-question records, or a caller that did not push the\n * record onto `currentCard.records`), fall back to the presentation's record\n * count. With no record visible at all we cannot tell, and say no.\n */\nexport function isFirstAttempt(records: readonly CardRecord[]): boolean {\n const rec = currentRecord(records);\n if (!rec) return false;\n const prior = (rec as { priorAttemps?: unknown }).priorAttemps;\n if (typeof prior === 'number') return prior === 0;\n return records.length === 1;\n}\n\n/**\n * Append a presentation entry to every scored tag in `perf`, mutating\n * `userElo.tags[tag]` in place (each rank object is replaced, not mutated).\n * No-op for retries. Returns the tags that received an entry.\n */\nexport function recordTagPresentations(\n userElo: CourseElo,\n perf: TaggedPerformance,\n records: readonly CardRecord[],\n cardId: string,\n at: string\n): string[] {\n if (!isFirstAttempt(records)) return [];\n const rec = currentRecord(records) as { isCorrect?: unknown } | null;\n const ok = rec?.isCorrect === true;\n\n const written: string[] = [];\n for (const [tag, score] of Object.entries(perf)) {\n if (tag === '_global') continue;\n if (typeof score !== 'number') continue; // count-only exposure tag\n const rank: EloRank = userElo.tags[tag] ?? { score: userElo.global.score, count: 0 };\n const entry: TagPresentation = { at, ok, perf: score, card: cardId };\n userElo.tags[tag] = pushTagPresentation(rank, entry);\n written.push(tag);\n }\n return written;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAuBA,SAAS,cAAc,SAAmD;AACxE,QAAO,QAAQ,SAAS,QAAQ,QAAQ,SAAS,KAAK;;;;;;;;;;AAWxD,SAAgB,eAAe,SAAyC;CACtE,MAAM,MAAM,cAAc,QAAQ;AAClC,KAAI,CAAC,IAAK,QAAO;CACjB,MAAM,QAAS,IAAmC;AAClD,KAAI,OAAO,UAAU,SAAU,QAAO,UAAU;AAChD,QAAO,QAAQ,WAAW;;;;;;;AAQ5B,SAAgB,uBACd,SACA,MACA,SACA,QACA,IACU;AACV,KAAI,CAAC,eAAe,QAAQ,CAAE,QAAO,EAAE;CAEvC,MAAM,KADM,cAAc,QAAQ,EAClB,cAAc;CAE9B,MAAM,UAAoB,EAAE;AAC5B,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,KAAK,EAAE;AAC/C,MAAI,QAAQ,UAAW;AACvB,MAAI,OAAO,UAAU,SAAU;EAC/B,MAAM,OAAgB,QAAQ,KAAK,QAAQ;GAAE,OAAO,QAAQ,OAAO;GAAO,OAAO;GAAG;EACpF,MAAM,QAAyB;GAAE;GAAI;GAAI,MAAM;GAAO,MAAM;GAAQ;AACpE,UAAQ,KAAK,OAAO,oBAAoB,MAAM,MAAM;AACpD,UAAQ,KAAK,IAAI;;AAEnB,QAAO"}
1
+ {"version":3,"file":"tagRecent.mjs","names":[],"sources":["../../../src/study/services/tagRecent.ts"],"sourcesContent":["import {\n CourseElo,\n EloRank,\n TAG_OK_MIN_PERF,\n TaggedPerformance,\n TagPresentation,\n pushTagPresentation,\n} from '@vue-skuilder/common';\nimport { CardRecord } from '@db/core';\n\n/**\n * Mastery signal: per-tag ring buffer of recent presentations.\n *\n * Written on the same path as the per-tag ELO update, one entry per\n * *presentation* of a card. Retries within a presentation (a record with\n * `priorAttemps > 0`, or any record after the first on the current card)\n * are not evidence and add nothing — including the \"dismiss-failed\" final\n * penalty, which reaches the ELO path on a retry record.\n *\n * Only tags the question actually graded (numeric perf) get an entry;\n * count-only exposure tags (`null`) carry no correctness signal.\n */\n\n/** The record for the presentation being graded, or null if none is visible. */\nfunction currentRecord(records: readonly CardRecord[]): CardRecord | null {\n return records.length ? records[records.length - 1] : null;\n}\n\n/**\n * Whether the record under grading is the first attempt of its presentation.\n *\n * `priorAttemps` is the authoritative marker (written by the question view).\n * When it is absent (non-question records, or a caller that did not push the\n * record onto `currentCard.records`), fall back to the presentation's record\n * count. With no record visible at all we cannot tell, and say no.\n */\nexport function isFirstAttempt(records: readonly CardRecord[]): boolean {\n const rec = currentRecord(records);\n if (!rec) return false;\n const prior = (rec as { priorAttemps?: unknown }).priorAttemps;\n if (typeof prior === 'number') return prior === 0;\n return records.length === 1;\n}\n\n/**\n * Append a presentation entry to every scored tag in `perf`, mutating\n * `userElo.tags[tag]` in place (each rank object is replaced, not mutated).\n * No-op for retries. Returns the tags that received an entry.\n */\nexport function recordTagPresentations(\n userElo: CourseElo,\n perf: TaggedPerformance,\n records: readonly CardRecord[],\n cardId: string,\n at: string\n): string[] {\n if (!isFirstAttempt(records)) return [];\n const rec = currentRecord(records) as { isCorrect?: unknown } | null;\n const ok = rec?.isCorrect === true;\n\n const written: string[] = [];\n for (const [tag, score] of Object.entries(perf)) {\n if (tag === '_global') continue;\n if (typeof score !== 'number') continue; // count-only exposure tag\n const rank: EloRank = userElo.tags[tag] ?? { score: userElo.global.score, count: 0 };\n const entry: TagPresentation = {\n at,\n ok,\n tagOk: score > TAG_OK_MIN_PERF,\n perf: score,\n card: cardId,\n };\n userElo.tags[tag] = pushTagPresentation(rank, entry);\n written.push(tag);\n }\n return written;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAwBA,SAAS,cAAc,SAAmD;AACxE,QAAO,QAAQ,SAAS,QAAQ,QAAQ,SAAS,KAAK;;;;;;;;;;AAWxD,SAAgB,eAAe,SAAyC;CACtE,MAAM,MAAM,cAAc,QAAQ;AAClC,KAAI,CAAC,IAAK,QAAO;CACjB,MAAM,QAAS,IAAmC;AAClD,KAAI,OAAO,UAAU,SAAU,QAAO,UAAU;AAChD,QAAO,QAAQ,WAAW;;;;;;;AAQ5B,SAAgB,uBACd,SACA,MACA,SACA,QACA,IACU;AACV,KAAI,CAAC,eAAe,QAAQ,CAAE,QAAO,EAAE;CAEvC,MAAM,KADM,cAAc,QAAQ,EAClB,cAAc;CAE9B,MAAM,UAAoB,EAAE;AAC5B,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,KAAK,EAAE;AAC/C,MAAI,QAAQ,UAAW;AACvB,MAAI,OAAO,UAAU,SAAU;EAC/B,MAAM,OAAgB,QAAQ,KAAK,QAAQ;GAAE,OAAO,QAAQ,OAAO;GAAO,OAAO;GAAG;EACpF,MAAM,QAAyB;GAC7B;GACA;GACA,OAAO,QAAQ;GACf,MAAM;GACN,MAAM;GACP;AACD,UAAQ,KAAK,OAAO,oBAAoB,MAAM,MAAM;AACpD,UAAQ,KAAK,IAAI;;AAEnB,QAAO"}
package/package.json CHANGED
@@ -13,7 +13,7 @@
13
13
  "publishConfig": {
14
14
  "access": "public"
15
15
  },
16
- "version": "0.3.1",
16
+ "version": "0.3.3",
17
17
  "description": "Database layer for vue-skuilder",
18
18
  "main": "dist/index.cjs",
19
19
  "module": "dist/index.mjs",
@@ -69,7 +69,7 @@
69
69
  },
70
70
  "dependencies": {
71
71
  "@nilock2/pouchdb-authentication": "^1.0.2",
72
- "@vue-skuilder/common": "0.3.1",
72
+ "@vue-skuilder/common": "0.3.3",
73
73
  "cross-fetch": "^4.1.0",
74
74
  "moment": "^2.29.4",
75
75
  "pouchdb": "^9.0.0",
@@ -87,5 +87,5 @@
87
87
  "vite": "^8.0.0",
88
88
  "vitest": "^4.1.0"
89
89
  },
90
- "stableVersion": "0.3.1"
90
+ "stableVersion": "0.3.3"
91
91
  }
@@ -93,6 +93,13 @@ export interface StudyContentSource {
93
93
  */
94
94
  setEphemeralHints?(hints: ReplanHints): void;
95
95
 
96
+ /**
97
+ * The study session the following runs belong to. Persists until replaced
98
+ * (unlike hints). Generators read it from their context, e.g. to count
99
+ * sessions rather than runs.
100
+ */
101
+ setSessionId?(sessionId: string): void;
102
+
96
103
  /**
97
104
  * A card was just presented. `status` is the session item's (`'new'`,
98
105
  * `'review'`, `'failed-new'`, ...). Pipelines use a new card's first
@@ -316,6 +316,7 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
316
316
  * getWeightedCards() call, then cleared.
317
317
  */
318
318
  private _ephemeralHints: ReplanHints | null = null;
319
+ private _sessionId: string | undefined;
319
320
 
320
321
  /**
321
322
  * The intake valve's clock (see regulators.ts), loaded from strategy state on
@@ -366,6 +367,11 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
366
367
  *
367
368
  * Overrides ContentNavigator.setEphemeralHints() no-op.
368
369
  */
370
+ /** See StudyContentSource.setSessionId. Carried into every run's context. */
371
+ override setSessionId(sessionId: string): void {
372
+ this._sessionId = sessionId;
373
+ }
374
+
369
375
  override setEphemeralHints(hints: ReplanHints): void {
370
376
  this._ephemeralHints = hints;
371
377
  logger.info(`[Pipeline] Ephemeral hints set: ${JSON.stringify(hints)}`);
@@ -959,6 +965,7 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
959
965
  userElo,
960
966
  ...(userCourseElo ? { userCourseElo } : {}),
961
967
  orchestration,
968
+ ...(this._sessionId ? { sessionId: this._sessionId } : {}),
962
969
  };
963
970
  }
964
971
 
@@ -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 { COUNT_ONLY_SCORE, isCountOnlyTag, type CourseElo } from '@vue-skuilder/common';
8
+ import { COUNT_ONLY_SCORE, isCountOnlyTag, tagRole, type CourseElo } from '@vue-skuilder/common';
9
9
  import { logger } from '../../../util/logger';
10
10
 
11
11
  // ============================================================================
@@ -33,6 +33,11 @@ import { logger } from '../../../util/logger';
33
33
  // opts in with `tagAware`, a browser with `window.skuilder.multiDimElo = true`
34
34
  // (see the toggle below), for side-by-side testing.
35
35
  //
36
+ // Intro cards pass through untouched. They carry an `intro`-role tag, grade
37
+ // nothing, and their ELO is a placeholder, so a distance on it means nothing.
38
+ // Penalising them starves established learners of intros: a learner rated
39
+ // well above the placeholder sees every intro at the curve's floor.
40
+ //
36
41
  // A `signal`, not a gate: it expresses preference, not readiness. `liveOnly`:
37
42
  // forecasts and card-space scans start every card at 1.0 without a generator,
38
43
  // and never applied ELO distance, so they skip it.
@@ -99,6 +104,11 @@ export const DEFAULT_ELO_DISTANCE_CONFIG: Required<EloDistanceConfig> = {
99
104
  */
100
105
  const TAG_CONFIDENCE_HALF = 10;
101
106
 
107
+ /** Whether the card is an intro: any `intro`-role tag. Its ELO is a placeholder. */
108
+ function isIntroCard(card: WeightedCard): boolean {
109
+ return (card.tags ?? []).some((t) => tagRole(t) === 'intro');
110
+ }
111
+
102
112
  /** Fallback card ELO when a card has none recorded. */
103
113
  const DEFAULT_CARD_ELO = 1000;
104
114
 
@@ -279,7 +289,9 @@ async function applyEloDistance(
279
289
 
280
290
  // Tag-aware needs every card's full ratings; otherwise only the ELO of cards
281
291
  // that don't carry it (reviews). One batch either way.
282
- const missing = cards.filter((c) => tagAware || c.cardElo === undefined).map((c) => c.cardId);
292
+ const missing = cards
293
+ .filter((c) => !isIntroCard(c) && (tagAware || c.cardElo === undefined))
294
+ .map((c) => c.cardId);
283
295
  const fetched = new Map<string, CourseElo>();
284
296
  if (missing.length > 0) {
285
297
  const elos = await course.getCardEloData(missing);
@@ -289,6 +301,23 @@ async function applyEloDistance(
289
301
  }
290
302
 
291
303
  return cards.map((card) => {
304
+ if (isIntroCard(card)) {
305
+ return {
306
+ ...card,
307
+ provenance: [
308
+ ...card.provenance,
309
+ {
310
+ strategy: 'eloDistance',
311
+ strategyName: source.name,
312
+ strategyId: source.strategyId,
313
+ action: 'passed',
314
+ score: card.score,
315
+ reason: 'intro card: ELO is a placeholder, distance not applied → 1.00x',
316
+ },
317
+ ],
318
+ };
319
+ }
320
+
292
321
  const full = fetched.get(card.cardId);
293
322
  const cardElo = full?.global?.score ?? card.cardElo ?? DEFAULT_CARD_ELO;
294
323
 
@@ -33,6 +33,18 @@ import { logger } from '@db/util/logger';
33
33
  // lesson gating, letter gating, interference, and priority filters continue to
34
34
  // shape final ordering.
35
35
  //
36
+ // KNOWN LATENT BUG (2026-11-17): this generator decides targets, support,
37
+ // boost hints and pressure *before* the gates run, and knows nothing about
38
+ // them. It will target and support cards a gate is certain to block (e.g. a
39
+ // target whose prerequisites sit behind a course gate that never opens), so
40
+ // the group can never complete. Harmless while every such card stays gated;
41
+ // but staleness escalates the support boost hint to its cap on those tags,
42
+ // so the day one becomes ungated it gets that boost at once (a pressure
43
+ // mania). Proposed fix: Pipeline offers generators the gate-kind filters
44
+ // (e.g. `context.gate(cardIds)`), and prescribed treats gated candidates as
45
+ // blocked: not emitted, not boosted, not escalating. That would also replace
46
+ // this file's own hierarchy walk.
47
+ //
36
48
  // ============================================================================
37
49
 
38
50
  interface HierarchyWalkConfig {
@@ -102,6 +114,12 @@ interface PrescribedProgressState {
102
114
  * map self-prunes and "staleness" is measured from first-owed, not last-seen.
103
115
  */
104
116
  practiceDebt?: Record<string, string>;
117
+ /**
118
+ * The study session of the last run. `sessionsSinceSurfaced` advances once
119
+ * per new session, not once per run (a session replans several times).
120
+ * Absent when the caller set no session id; then each run counts.
121
+ */
122
+ lastSessionId?: string;
105
123
  }
106
124
 
107
125
  interface TagPrerequisite {
@@ -334,9 +352,15 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
334
352
 
335
353
  const cardsByTag = await this.loadCardsByTag();
336
354
 
355
+ const sessionId = context?.sessionId;
356
+ // A run with no session id counts as its own session (the old behaviour).
357
+ const newSession = sessionId === undefined || sessionId !== progress.lastSessionId;
337
358
  const nextState: PrescribedProgressState = {
338
359
  updatedAt: isoNow(),
339
360
  groups: {},
361
+ ...(sessionId || progress.lastSessionId
362
+ ? { lastSessionId: sessionId ?? progress.lastSessionId }
363
+ : {}),
340
364
  };
341
365
 
342
366
  const emitted: WeightedCard[] = [];
@@ -395,7 +419,11 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
395
419
  }
396
420
  }
397
421
 
398
- nextState.groups[group.id] = this.buildNextGroupState(runtime, progress.groups[group.id]);
422
+ nextState.groups[group.id] = this.buildNextGroupState(
423
+ runtime,
424
+ progress.groups[group.id],
425
+ newSession
426
+ );
399
427
 
400
428
  const directCards = this.buildDirectTargetCards(
401
429
  runtime,
@@ -490,15 +518,15 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
490
518
  surfacedByGroup.get(groupId)![mode].push(card.cardId);
491
519
  }
492
520
 
521
+ // Emission is not surfacing. A card emitted here can still lose to the rest
522
+ // of the heap and never be shown, so it does not reset the staleness clock;
523
+ // only a target reaching the learner does (buildNextGroupState). Support
524
+ // emission is still recorded, as bookkeeping.
493
525
  for (const group of this.config.groups) {
494
526
  const groupState = nextState.groups[group.id];
495
527
  const surfaced = surfacedByGroup.get(group.id);
496
- if (surfaced && (surfaced.targetIds.length > 0 || surfaced.supportIds.length > 0)) {
497
- groupState.lastSurfacedAt = isoNow();
498
- groupState.sessionsSinceSurfaced = 0;
499
- if (surfaced.supportIds.length > 0) {
500
- groupState.lastSupportAt = isoNow();
501
- }
528
+ if (surfaced && surfaced.supportIds.length > 0) {
529
+ groupState.lastSupportAt = isoNow();
502
530
  }
503
531
  }
504
532
 
@@ -859,15 +887,31 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
859
887
  };
860
888
  }
861
889
 
862
- private buildNextGroupState(runtime: GroupRuntimeState, prior?: GroupCardState): GroupCardState {
890
+ /**
891
+ * The group's state after this run. The staleness clock resets only when a
892
+ * target has reached the learner since the last run: it is newly in
893
+ * `encounteredTargets`, which reads card history and scheduled reviews, so
894
+ * the card was shown and answered. Emitting a target does not count; it may
895
+ * lose to the rest of the heap. (Before 2026-11, emission reset the clock,
896
+ * and a group that emitted every run never escalated.) The clock advances
897
+ * once per study session, not per run.
898
+ */
899
+ private buildNextGroupState(
900
+ runtime: GroupRuntimeState,
901
+ prior: GroupCardState | undefined,
902
+ newSession: boolean
903
+ ): GroupCardState {
863
904
  const carriedSessions = prior?.sessionsSinceSurfaced ?? 0;
864
- const surfacedThisRun = false;
905
+ const previouslyEncountered = new Set(prior?.encounteredCardIds ?? []);
906
+ const surfacedThisRun =
907
+ prior !== undefined &&
908
+ [...runtime.encounteredTargets].some((id) => !previouslyEncountered.has(id));
865
909
 
866
910
  return {
867
911
  encounteredCardIds: [...runtime.encounteredTargets].sort(),
868
912
  pendingTargetIds: [...runtime.pendingTargets].sort(),
869
- lastSurfacedAt: prior?.lastSurfacedAt ?? null,
870
- sessionsSinceSurfaced: surfacedThisRun ? 0 : carriedSessions + 1,
913
+ lastSurfacedAt: surfacedThisRun ? isoNow() : (prior?.lastSurfacedAt ?? null),
914
+ sessionsSinceSurfaced: surfacedThisRun ? 0 : carriedSessions + (newSession ? 1 : 0),
871
915
  lastSupportAt: prior?.lastSupportAt ?? null,
872
916
  blockedTargetIds: [...runtime.blockedTargets].sort(),
873
917
  lastResolvedSupportTags: [...runtime.supportTags].sort(),
@@ -62,6 +62,9 @@ export interface GeneratorContext {
62
62
  /** Orchestration context for evolutionary weighting */
63
63
  orchestration?: OrchestrationContext;
64
64
 
65
+ /** The study session this run belongs to, when the caller set one. */
66
+ sessionId?: string;
67
+
65
68
  // Future extensions:
66
69
  // - user's tag-level ELO data
67
70
  // - course config
@@ -702,4 +702,9 @@ export abstract class ContentNavigator implements StudyContentSource {
702
702
  setEphemeralHints(_hints: ReplanHints): void {
703
703
  // no-op — only Pipeline implements this
704
704
  }
705
+
706
+ /** See StudyContentSource.setSessionId. No-op for non-Pipeline navigators. */
707
+ setSessionId(_sessionId: string): void {
708
+ // no-op — only Pipeline implements this
709
+ }
705
710
  }
@@ -13,7 +13,7 @@ import type {
13
13
  StudySessionRunSummary,
14
14
  } from '../core/types/studySession';
15
15
  import type { CardSummary, DatasetRecord, LearnerDataset } from './dataset';
16
- import type { TagBatch } from './tagElo';
16
+ import type { TagBatch, TagEloViewOptions } from './tagElo';
17
17
 
18
18
  /**
19
19
  * Course-supplied meaning for the generic views. Every member is optional and
@@ -36,6 +36,11 @@ export interface DiagnosticsInterpreters {
36
36
  * batches it finds on its own. Default: none.
37
37
  */
38
38
  tagBatches?: TagBatch[];
39
+ /**
40
+ * How the ELO view reads skills: which tags security and need consider, and
41
+ * their thresholds. Default: exercise-role tags, framework thresholds.
42
+ */
43
+ tagEloOptions?: TagEloViewOptions;
39
44
  }
40
45
 
41
46
  export const isSkillTag = (i: DiagnosticsInterpreters | undefined, tag: string): boolean =>
@@ -10,9 +10,17 @@
10
10
  */
11
11
  import {
12
12
  COUNT_ONLY_SCORE,
13
+ courseSecurity,
13
14
  isCountOnlyTag,
15
+ presentationOk,
16
+ skillNeed,
14
17
  tagRole,
15
18
  type CourseElo,
19
+ type CourseSecurity,
20
+ type SkillNeedConfig,
21
+ type TagSecurity,
22
+ type TagSecurityConfig,
23
+ type TagSelector,
16
24
  type EloRank,
17
25
  type TagPresentation,
18
26
  type TagRole,
@@ -104,8 +112,14 @@ export interface TagEloRow {
104
112
  vsGlobal: number | null;
105
113
  /** The rating's ring buffer of recent first attempts, oldest first. */
106
114
  recent: TagPresentation[];
107
- /** First-attempt correct entries in `recent`. */
115
+ /** Entries in `recent` right on this tag (per-tag, not the card's ok). */
108
116
  recentOk: number;
117
+ /** Secure / shaky / unproven, for tags the security selector picks (met exercise tags by default). */
118
+ security?: TagSecurity;
119
+ /** 0–1 need from skillNeed; absent for tags that don't qualify as skills. */
120
+ need?: number;
121
+ /** Skill reference − rating; absent with need. */
122
+ deficit?: number;
109
123
  /** First and last response whose per-tag performance named the tag, or a recent entry. */
110
124
  firstSeen: string | null;
111
125
  lastSeen: string | null;
@@ -134,6 +148,16 @@ export interface TagEloView {
134
148
  series: { global: EloPoint[]; tags: Record<string, EloPoint[]> };
135
149
  /** The first ELO event, or null: trajectories start here. */
136
150
  seriesFrom: string | null;
151
+ /** Median rating over the learner's qualifying skills (skillNeed); null if too few. */
152
+ skillReference: number | null;
153
+ /** Security totals over the selected tags. */
154
+ security: Omit<CourseSecurity, 'tags'>;
155
+ }
156
+
157
+ /** How the view reads skills: a course may pass its own selectors and thresholds. */
158
+ export interface TagEloViewOptions {
159
+ security?: { selector?: TagSelector; config?: TagSecurityConfig };
160
+ need?: SkillNeedConfig;
137
161
  }
138
162
 
139
163
  /** The learner's `CourseElo` for the dataset's course, or null if not registered. */
@@ -164,10 +188,15 @@ function step(line: EloPoint[], at: string, before: number, after: number): void
164
188
  }
165
189
 
166
190
  /** The learner's per-tag ELO for display. Null if the dataset has no registration for its course. */
167
- export function tagEloView(ds: LearnerDataset): TagEloView | null {
191
+ export function tagEloView(ds: LearnerDataset, options: TagEloViewOptions = {}): TagEloView | null {
168
192
  const elo = learnerCourseElo(ds);
169
193
  if (!elo) return null;
170
194
 
195
+ const security = courseSecurity(elo, options.security);
196
+ const securityByTag = new Map(security.tags.map((s) => [s.tag, s]));
197
+ const need = skillNeed(elo, options.need);
198
+ const needByTag = new Map(need.skills.map((s) => [s.tag, s]));
199
+
171
200
  // When each tag was named by a response, from card history.
172
201
  const seen = new Map<string, { first: string | null; last: string | null }>();
173
202
  for (const h of ds.cardHistories) {
@@ -220,7 +249,11 @@ export function tagEloView(ds: LearnerDataset): TagEloView | null {
220
249
  count: rank.count,
221
250
  vsGlobal: score === null ? null : score - elo.global.score,
222
251
  recent,
223
- recentOk: recent.filter((p) => p.ok).length,
252
+ recentOk: recent.filter(presentationOk).length,
253
+ ...(securityByTag.has(tag) ? { security: securityByTag.get(tag) } : {}),
254
+ ...(needByTag.has(tag)
255
+ ? { need: needByTag.get(tag)!.need, deficit: needByTag.get(tag)!.deficit }
256
+ : {}),
224
257
  firstSeen: first,
225
258
  lastSeen: last,
226
259
  events: eventCounts.get(tag) ?? 0,
@@ -253,5 +286,12 @@ export function tagEloView(ds: LearnerDataset): TagEloView | null {
253
286
  ),
254
287
  series: { global: globalSeries, tags: tagSeries },
255
288
  seriesFrom: events[0]?.at ?? null,
289
+ skillReference: need.reference,
290
+ security: {
291
+ secure: security.secure,
292
+ shaky: security.shaky,
293
+ unproven: security.unproven,
294
+ debt: security.debt,
295
+ },
256
296
  };
257
297
  }
@@ -729,6 +729,16 @@ above:\n${above.rows.map((r) => `\t${r.id}-${r.key}\n`)}`;
729
729
  this._pendingHints = hints;
730
730
  }
731
731
 
732
+
733
+ private _sessionId: string | null = null;
734
+
735
+
736
+ public setSessionId(sessionId: string): void {
737
+
738
+ this._sessionId = sessionId;
739
+
740
+ }
741
+
732
742
  /**
733
743
  * Forward a presentation to the navigator (a new card restarts its intake
734
744
  * clock). Builds the navigator if the cached one has expired.
@@ -752,6 +762,9 @@ above:\n${above.rows.map((r) => `\t${r.id}-${r.key}\n`)}`;
752
762
  navigator.setEphemeralHints(this._pendingHints);
753
763
  this._pendingHints = null;
754
764
  }
765
+ if (this._sessionId) {
766
+ navigator.setSessionId(this._sessionId);
767
+ }
755
768
  const result = await navigator.getWeightedCards(limit);
756
769
  // const tRun = performance.now(); // [perf] parked
757
770
  // [perf] parked 2026-05 (pipeline-docs-workup) — uncomment to re-measure
@@ -451,6 +451,16 @@ export class StaticCourseDB implements CourseDBInterface {
451
451
  this._pendingHints = hints;
452
452
  }
453
453
 
454
+
455
+ private _sessionId: string | null = null;
456
+
457
+
458
+ setSessionId(sessionId: string): void {
459
+
460
+ this._sessionId = sessionId;
461
+
462
+ }
463
+
454
464
  /** Forward a presentation to the navigator (a new card restarts its intake clock). */
455
465
  notePresented(card: { cardId: string; courseId: string; status: string }): void {
456
466
  if (card.status !== 'new') return;
@@ -467,6 +477,9 @@ export class StaticCourseDB implements CourseDBInterface {
467
477
  navigator.setEphemeralHints(this._pendingHints);
468
478
  this._pendingHints = null;
469
479
  }
480
+ if (this._sessionId) {
481
+ navigator.setSessionId(this._sessionId);
482
+ }
470
483
  return navigator.getWeightedCards(limit);
471
484
  } catch (e) {
472
485
  logger.error(`[static/courseDB] Error getting weighted cards: ${e}`);
@@ -527,6 +527,9 @@ export class SessionController<TView = unknown> extends Loggable {
527
527
  };
528
528
 
529
529
  this.sources = sources;
530
+ for (const source of sources) {
531
+ source.setSessionId?.(this.sessionId);
532
+ }
530
533
  this.startTime = new Date();
531
534
  this._secondsRemaining = time;
532
535
  this.endTime = new Date(this.startTime.valueOf() + 1000 * this._secondsRemaining);
@@ -1,5 +1,12 @@
1
1
  import { describe, it, expect } from 'vitest';
2
- import { TAG_RECENT_MAX, pushTagPresentation, type CourseElo, type EloRank } from '@vue-skuilder/common';
2
+ import {
3
+ TAG_RECENT_MAX,
4
+ courseSecurity,
5
+ pushTagPresentation,
6
+ tagSecurity,
7
+ type CourseElo,
8
+ type EloRank,
9
+ } from '@vue-skuilder/common';
3
10
  import { isFirstAttempt, recordTagPresentations } from './tagRecent';
4
11
  import type { CardRecord } from '@db/core';
5
12
 
@@ -61,7 +68,7 @@ describe('recordTagPresentations', () => {
61
68
  );
62
69
  expect(written).toEqual(['gpc:exercise:th-TH']);
63
70
  expect(elo.tags['gpc:exercise:th-TH'].recent).toEqual([
64
- { at: '2026-09-18T00:00:00.000Z', ok: true, perf: 0.6, card: 'c-ml-worth-3' },
71
+ { at: '2026-09-18T00:00:00.000Z', ok: true, tagOk: true, perf: 0.6, card: 'c-ml-worth-3' },
65
72
  ]);
66
73
  expect(elo.tags['gpc:expose:w-W']).toBeUndefined();
67
74
  });
@@ -69,7 +76,7 @@ describe('recordTagPresentations', () => {
69
76
  it('records a first-attempt miss as ok:false', () => {
70
77
  const elo = blank();
71
78
  recordTagPresentations(elo, { _global: 0, 'gpc:exercise:sh-SH': 0 }, [rec(0, false)], 'c-ml-hush-2', 't');
72
- expect(elo.tags['gpc:exercise:sh-SH'].recent).toEqual([{ at: 't', ok: false, perf: 0, card: 'c-ml-hush-2' }]);
79
+ expect(elo.tags['gpc:exercise:sh-SH'].recent).toEqual([{ at: 't', ok: false, tagOk: false, perf: 0, card: 'c-ml-hush-2' }]);
73
80
  });
74
81
 
75
82
  it('adds nothing for a retry (priorAttemps > 0), even a correct one', () => {
@@ -99,3 +106,50 @@ describe('recordTagPresentations', () => {
99
106
  expect(elo.tags['t'].recent![0].card).toBe('card-3');
100
107
  });
101
108
  });
109
+
110
+ describe('tagSecurity', () => {
111
+ const day = (d: number) => `2026-11-${String(d).padStart(2, '0')}T12:00:00.000Z`;
112
+ const rank = (oks: boolean[], days: number[]): EloRank => ({
113
+ score: 1500,
114
+ count: oks.length,
115
+ recent: oks.map((ok, i) => ({ at: day(days[i]), ok: true, tagOk: ok, perf: ok ? 0.8 : 0, card: `c${i}` })),
116
+ });
117
+ const cfg = { dayOf: (at: string) => at.slice(0, 10) };
118
+
119
+ it('unproven below minAttempts, shaky under 75% of the window, secure otherwise', () => {
120
+ const five = Array(5).fill(true);
121
+ expect(tagSecurity('t', rank(five, [1, 1, 2, 2, 3]), cfg).status).toBe('unproven');
122
+ // 12 attempts, 8 right (67%): shaky; the card-level ok (all true) is ignored
123
+ const eightOfTwelve = [...Array(8).fill(true), ...Array(4).fill(false)];
124
+ expect(tagSecurity('t', rank(eightOfTwelve, Array(12).fill(0).map((_, i) => 1 + (i % 3))), cfg).status).toBe('shaky');
125
+ // 6 of 6 right, all on one day: unproven (needs two days)
126
+ expect(tagSecurity('t', rank(Array(6).fill(true), Array(6).fill(4)), cfg).status).toBe('unproven');
127
+ expect(tagSecurity('t', rank(Array(6).fill(true), [4, 4, 4, 5, 5, 5]), cfg).status).toBe('secure');
128
+ });
129
+
130
+ it('falls back to perf for entries without tagOk (hinted 0.5 is not right)', () => {
131
+ const r: EloRank = {
132
+ score: 1500,
133
+ count: 6,
134
+ recent: [0.6, 0.8, 0.5, 0.8, 0.8, 0.8].map((perf, i) => ({ at: day(1 + (i % 2)), ok: true, perf, card: `c${i}` })),
135
+ };
136
+ const s = tagSecurity('t', r, cfg);
137
+ expect(s.right).toBe(5);
138
+ expect(s.status).toBe('secure');
139
+ });
140
+
141
+ it('courseSecurity counts met exercise tags only; a met tag with no buffer is unproven', () => {
142
+ const elo: CourseElo = {
143
+ global: { score: 1500, count: 100 },
144
+ tags: {
145
+ 'gpc:exercise:a-AE': rank(Array(6).fill(true), [1, 1, 1, 2, 2, 2]),
146
+ 'gpc:exercise:a-EY': { score: 1300, count: 9 },
147
+ 'gpc:expose:a-AE': { score: -1, count: 4 },
148
+ },
149
+ misc: {},
150
+ };
151
+ const c = courseSecurity(elo, { config: cfg });
152
+ expect(c.tags.map((t) => t.tag).sort()).toEqual(['gpc:exercise:a-AE', 'gpc:exercise:a-EY']);
153
+ expect([c.secure, c.shaky, c.unproven, c.debt]).toEqual([1, 0, 1, 1]);
154
+ });
155
+ });
@@ -1,6 +1,7 @@
1
1
  import {
2
2
  CourseElo,
3
3
  EloRank,
4
+ TAG_OK_MIN_PERF,
4
5
  TaggedPerformance,
5
6
  TagPresentation,
6
7
  pushTagPresentation,
@@ -62,7 +63,13 @@ export function recordTagPresentations(
62
63
  if (tag === '_global') continue;
63
64
  if (typeof score !== 'number') continue; // count-only exposure tag
64
65
  const rank: EloRank = userElo.tags[tag] ?? { score: userElo.global.score, count: 0 };
65
- const entry: TagPresentation = { at, ok, perf: score, card: cardId };
66
+ const entry: TagPresentation = {
67
+ at,
68
+ ok,
69
+ tagOk: score > TAG_OK_MIN_PERF,
70
+ perf: score,
71
+ card: cardId,
72
+ };
66
73
  userElo.tags[tag] = pushTagPresentation(rank, entry);
67
74
  written.push(tag);
68
75
  }
@@ -144,6 +144,21 @@ describe('ELO Distance Filter', () => {
144
144
  });
145
145
  });
146
146
 
147
+ describe('intro cards', () => {
148
+ it('passes an intro-role card through untouched, whatever its distance', async () => {
149
+ const filter = createEloDistanceFilter();
150
+ const intro = { ...createCard('intro-1', 2.0), tags: ['gpc:intro:WORD-are', 'srs:skip'] };
151
+ const graded = { ...createCard('card-1', 2.0), tags: ['gpc:exercise:a-AE'] };
152
+ const context = createMockContext(1600, { 'intro-1': 1000, 'card-1': 1000 });
153
+
154
+ const result = await filter.transform([intro, graded], context);
155
+
156
+ expect(result[0].score).toBe(2.0);
157
+ expect(result[0].provenance.at(-1)?.reason).toContain('intro card');
158
+ expect(result[1].score).toBeLessThan(0.2);
159
+ });
160
+ });
161
+
147
162
  describe('provenance tracking', () => {
148
163
  it('should append provenance entry with ELO details', async () => {
149
164
  const filter = createEloDistanceFilter();