@vue-skuilder/db 0.3.1 → 0.3.2

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 (42) 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/index.d.ts +2 -2
  17. package/dist/impl/couch/courseDB.mjs +5 -0
  18. package/dist/impl/couch/courseDB.mjs.map +1 -1
  19. package/dist/impl/couch/index.cjs +37 -2
  20. package/dist/impl/couch/index.cjs.map +1 -1
  21. package/dist/impl/couch/index.d.ts +4 -2
  22. package/dist/impl/static/courseDB.mjs +5 -0
  23. package/dist/impl/static/courseDB.mjs.map +1 -1
  24. package/dist/impl/static/index.cjs +37 -2
  25. package/dist/impl/static/index.cjs.map +1 -1
  26. package/dist/impl/static/index.d.ts +4 -2
  27. package/dist/index.cjs +73 -15
  28. package/dist/index.cjs.map +1 -1
  29. package/dist/index.d.ts +3 -3
  30. package/dist/study/SessionController.mjs +1 -0
  31. package/dist/study/SessionController.mjs.map +1 -1
  32. package/package.json +3 -3
  33. package/src/core/interfaces/contentSource.ts +7 -0
  34. package/src/core/navigators/Pipeline.ts +7 -0
  35. package/src/core/navigators/filters/eloDistance.ts +31 -2
  36. package/src/core/navigators/generators/prescribed.ts +56 -11
  37. package/src/core/navigators/generators/types.ts +3 -0
  38. package/src/core/navigators/index.ts +5 -0
  39. package/src/impl/couch/courseDB.ts +13 -0
  40. package/src/impl/static/courseDB.ts +13 -0
  41. package/src/study/SessionController.ts +3 -0
  42. package/tests/core/navigators/eloDistanceFilter.test.ts +15 -0
@@ -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 starved established learners of every intro (an LP learner
39
+ // at ~1600 saw sight-word intros at 1000 scored ×0.05 for six weeks).
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,19 @@ 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 (LP:
39
+ // intro-core's ck-K / wh-W and their doubled-consonant support, behind a
40
+ // deferred lesson, cut to ~x0.002). Harmless while every such card stays
41
+ // gated; but staleness escalates the support boost hint to x4 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. LP tracking: agent/curriculum-log/concerns.md
47
+ // (Watch: "Prescribed targets gated cards").
48
+ //
36
49
  // ============================================================================
37
50
 
38
51
  interface HierarchyWalkConfig {
@@ -102,6 +115,12 @@ interface PrescribedProgressState {
102
115
  * map self-prunes and "staleness" is measured from first-owed, not last-seen.
103
116
  */
104
117
  practiceDebt?: Record<string, string>;
118
+ /**
119
+ * The study session of the last run. `sessionsSinceSurfaced` advances once
120
+ * per new session, not once per run (a session replans several times).
121
+ * Absent when the caller set no session id; then each run counts.
122
+ */
123
+ lastSessionId?: string;
105
124
  }
106
125
 
107
126
  interface TagPrerequisite {
@@ -334,9 +353,15 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
334
353
 
335
354
  const cardsByTag = await this.loadCardsByTag();
336
355
 
356
+ const sessionId = context?.sessionId;
357
+ // A run with no session id counts as its own session (the old behaviour).
358
+ const newSession = sessionId === undefined || sessionId !== progress.lastSessionId;
337
359
  const nextState: PrescribedProgressState = {
338
360
  updatedAt: isoNow(),
339
361
  groups: {},
362
+ ...(sessionId || progress.lastSessionId
363
+ ? { lastSessionId: sessionId ?? progress.lastSessionId }
364
+ : {}),
340
365
  };
341
366
 
342
367
  const emitted: WeightedCard[] = [];
@@ -395,7 +420,11 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
395
420
  }
396
421
  }
397
422
 
398
- nextState.groups[group.id] = this.buildNextGroupState(runtime, progress.groups[group.id]);
423
+ nextState.groups[group.id] = this.buildNextGroupState(
424
+ runtime,
425
+ progress.groups[group.id],
426
+ newSession
427
+ );
399
428
 
400
429
  const directCards = this.buildDirectTargetCards(
401
430
  runtime,
@@ -490,15 +519,15 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
490
519
  surfacedByGroup.get(groupId)![mode].push(card.cardId);
491
520
  }
492
521
 
522
+ // Emission is not surfacing. A card emitted here can still lose to the rest
523
+ // of the heap and never be shown, so it does not reset the staleness clock;
524
+ // only a target reaching the learner does (buildNextGroupState). Support
525
+ // emission is still recorded, as bookkeeping.
493
526
  for (const group of this.config.groups) {
494
527
  const groupState = nextState.groups[group.id];
495
528
  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
- }
529
+ if (surfaced && surfaced.supportIds.length > 0) {
530
+ groupState.lastSupportAt = isoNow();
502
531
  }
503
532
  }
504
533
 
@@ -859,15 +888,31 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
859
888
  };
860
889
  }
861
890
 
862
- private buildNextGroupState(runtime: GroupRuntimeState, prior?: GroupCardState): GroupCardState {
891
+ /**
892
+ * The group's state after this run. The staleness clock resets only when a
893
+ * target has reached the learner since the last run: it is newly in
894
+ * `encounteredTargets`, which reads card history and scheduled reviews, so
895
+ * the card was shown and answered. Emitting a target does not count; it may
896
+ * lose to the rest of the heap. (Before 2026-11, emission reset the clock,
897
+ * and a group that emitted every run never escalated.) The clock advances
898
+ * once per study session, not per run.
899
+ */
900
+ private buildNextGroupState(
901
+ runtime: GroupRuntimeState,
902
+ prior: GroupCardState | undefined,
903
+ newSession: boolean
904
+ ): GroupCardState {
863
905
  const carriedSessions = prior?.sessionsSinceSurfaced ?? 0;
864
- const surfacedThisRun = false;
906
+ const previouslyEncountered = new Set(prior?.encounteredCardIds ?? []);
907
+ const surfacedThisRun =
908
+ prior !== undefined &&
909
+ [...runtime.encounteredTargets].some((id) => !previouslyEncountered.has(id));
865
910
 
866
911
  return {
867
912
  encounteredCardIds: [...runtime.encounteredTargets].sort(),
868
913
  pendingTargetIds: [...runtime.pendingTargets].sort(),
869
- lastSurfacedAt: prior?.lastSurfacedAt ?? null,
870
- sessionsSinceSurfaced: surfacedThisRun ? 0 : carriedSessions + 1,
914
+ lastSurfacedAt: surfacedThisRun ? isoNow() : (prior?.lastSurfacedAt ?? null),
915
+ sessionsSinceSurfaced: surfacedThisRun ? 0 : carriedSessions + (newSession ? 1 : 0),
871
916
  lastSupportAt: prior?.lastSupportAt ?? null,
872
917
  blockedTargetIds: [...runtime.blockedTargets].sort(),
873
918
  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
  }
@@ -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);
@@ -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();