@vue-skuilder/db 0.3.3 → 0.3.4

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/index.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  export { A as AdminDBInterface, d as AssignedCard, a as AssignedContent, c as AssignedCourse, b as AssignedTag, C as ClassroomDBInterface, S as StudentClassroomDBInterface, T as TeacherClassroomDBInterface } from './classroomDB-DLTtLZct.js';
2
- import { U as UserDBInterface, g as CourseRegistrationDoc, m as SessionEloEvent, S as StudySessionItem, W as WeightedCard, R as ReplanHints, o as StudyContentSource, x as SessionStateSnapshotProvider, G as GeneratorResult, N as NavigatorRole, c as ContentNavigationStrategyData, F as FilterKind, y as RegulatorConfig, C as CourseDBInterface } from './contentSource-CSI0pJ2D.js';
3
- export { P as ActivityRecord, ae as CardFilter, ag as CardFilterFactory, ah as CardGenerator, aj as CardGeneratorFactory, K as ClassroomRegistration, J as ClassroomRegistrationDesignation, L as ClassroomRegistrationDoc, d as ContentNavigator, v as ContentSourceID, b as CourseInfo, Q as CourseRegistration, a as CoursesDBInterface, aB as DEFAULT_REGULATOR_CONFIG, aM as DocumentUpdater, af as FilterContext, at as FilterImpact, ai as GeneratorContext, as as GeneratorSummary, _ as HYDRATION_MARKER_ID, $ as HydrationMarker, aF as INTAKE_CLOCK_KEY, aE as IntakeClockState, av as LearnableWeight, a0 as NavigatorConstructor, ab as NavigatorRoles, aa as Navigators, aw as OrchestrationContext, au as PipelineForecaster, aq as PipelineRunReport, l as RegulatorName, j as RegulatorReading, ar as RunReportCard, f as ScheduledCard, h as SessionStateSnapshot, M as SessionTrackingData, a8 as StrategyContribution, e as StudySessionDoc, p as StudySessionFailedItem, q as StudySessionFailedNewItem, r as StudySessionFailedReviewItem, s as StudySessionNewItem, t as StudySessionReviewItem, k as StudySessionRunCard, n as StudySessionRunCardTrail, i as StudySessionRunSummary, O as UserConfig, H as UserCourseSetting, E as UserCourseSettings, B as UserDBAuthenticator, z as UserDBReader, A as UserDBWriter, Y as UserHydrationState, Z as UserHydrationStatus, T as UserOutcomeRecord, I as UsrCrsDataInterface, aL as applyReading, ax as computeDeviation, az as computeEffectiveWeight, ay as computeSpread, aA as createOrchestrationContext, ap as drainCapturedRuns, aH as frozenMsAt, am as getActivePipeline, a9 as getCardOrigin, aP as getLapses, a5 as getRegisteredFilterKind, a2 as getRegisteredNavigator, a6 as getRegisteredNavigatorNames, a4 as getRegisteredNavigatorRole, ao as getRunsForSession, aO as getStreak, w as getStudySource, a3 as hasRegisteredNavigator, a7 as initializeNavigatorRegistry, aI as intakeHours, aK as intakeReading, ad as isFilter, ac as isGenerator, u as isReview, V as makeStudySessionId, al as mountPipelineDebugger, aN as newInterval, X as newSessionId, ak as pipelineDebugAPI, a1 as registerNavigator, aG as resetIntakeClock, aD as reviewMassReading, aC as reviewWeight, an as setDebugSessionId, aJ as stepIntakeClock } from './contentSource-CSI0pJ2D.js';
4
- import { D as DataLayerProvider } from './dataLayerProvider-D5n1gGc_.js';
2
+ import { U as UserDBInterface, g as CourseRegistrationDoc, m as SessionEloEvent, S as StudySessionItem, W as WeightedCard, R as ReplanHints, o as StudyContentSource, x as SessionStateSnapshotProvider, G as GeneratorResult, N as NavigatorRole, c as ContentNavigationStrategyData, F as FilterKind, y as RegulatorConfig, C as CourseDBInterface } from './contentSource-CPM872yn.js';
3
+ export { P as ActivityRecord, ae as CardFilter, ag as CardFilterFactory, ah as CardGenerator, aj as CardGeneratorFactory, K as ClassroomRegistration, J as ClassroomRegistrationDesignation, L as ClassroomRegistrationDoc, d as ContentNavigator, v as ContentSourceID, b as CourseInfo, Q as CourseRegistration, a as CoursesDBInterface, aB as DEFAULT_REGULATOR_CONFIG, aM as DocumentUpdater, af as FilterContext, at as FilterImpact, ai as GeneratorContext, as as GeneratorSummary, _ as HYDRATION_MARKER_ID, $ as HydrationMarker, aF as INTAKE_CLOCK_KEY, aE as IntakeClockState, av as LearnableWeight, a0 as NavigatorConstructor, ab as NavigatorRoles, aa as Navigators, aw as OrchestrationContext, au as PipelineForecaster, aq as PipelineRunReport, l as RegulatorName, j as RegulatorReading, ar as RunReportCard, f as ScheduledCard, h as SessionStateSnapshot, M as SessionTrackingData, a8 as StrategyContribution, e as StudySessionDoc, p as StudySessionFailedItem, q as StudySessionFailedNewItem, r as StudySessionFailedReviewItem, s as StudySessionNewItem, t as StudySessionReviewItem, k as StudySessionRunCard, n as StudySessionRunCardTrail, i as StudySessionRunSummary, O as UserConfig, H as UserCourseSetting, E as UserCourseSettings, B as UserDBAuthenticator, z as UserDBReader, A as UserDBWriter, Y as UserHydrationState, Z as UserHydrationStatus, T as UserOutcomeRecord, I as UsrCrsDataInterface, aL as applyReading, ax as computeDeviation, az as computeEffectiveWeight, ay as computeSpread, aA as createOrchestrationContext, ap as drainCapturedRuns, aH as frozenMsAt, am as getActivePipeline, a9 as getCardOrigin, aP as getLapses, a5 as getRegisteredFilterKind, a2 as getRegisteredNavigator, a6 as getRegisteredNavigatorNames, a4 as getRegisteredNavigatorRole, ao as getRunsForSession, aO as getStreak, w as getStudySource, a3 as hasRegisteredNavigator, a7 as initializeNavigatorRegistry, aI as intakeHours, aK as intakeReading, ad as isFilter, ac as isGenerator, u as isReview, V as makeStudySessionId, al as mountPipelineDebugger, aN as newInterval, X as newSessionId, ak as pipelineDebugAPI, a1 as registerNavigator, aG as resetIntakeClock, aD as reviewMassReading, aC as reviewWeight, an as setDebugSessionId, aJ as stepIntakeClock } from './contentSource-CPM872yn.js';
4
+ import { D as DataLayerProvider } from './dataLayerProvider-CaNgzRCz.js';
5
5
  import { e as CardHistory, c as CardRecord, d as QuestionRecord } from './types-legacy-DdVjg81H.js';
6
6
  export { C as CardData, g as CourseListData, h as DataShapeData, b as DisplayableData, D as DocType, f as DocTypePrefixes, F as Field, G as GuestUsername, Q as QualifiedCardID, i as QuestionData, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from './types-legacy-DdVjg81H.js';
7
7
  import { SrsBacklogDebug, StrategyPressureDebug, Loggable } from './core/index.js';
package/package.json CHANGED
@@ -13,7 +13,7 @@
13
13
  "publishConfig": {
14
14
  "access": "public"
15
15
  },
16
- "version": "0.3.3",
16
+ "version": "0.3.4",
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.3",
72
+ "@vue-skuilder/common": "0.3.4",
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.3"
90
+ "stableVersion": "0.3.4"
91
91
  }
@@ -5,5 +5,8 @@ export type { CardFilter, FilterContext, CardFilterFactory, FilterKind } from '.
5
5
  export { createEloDistanceFilter, default as EloDistanceFilter } from './eloDistance';
6
6
  export type { EloDistanceConfig } from './eloDistance';
7
7
 
8
+ export { default as SkillPressureFilter, skillPressures } from './skillPressure';
9
+ export type { SkillPressureConfig } from './skillPressure';
10
+
8
11
  export { default as UserTagPreferenceFilter } from './userTagPreference';
9
12
  export type { UserTagPreferenceState } from './userTagPreference';
@@ -0,0 +1,194 @@
1
+ import {
2
+ courseSecurity,
3
+ skillNeed,
4
+ type CourseElo,
5
+ type SkillNeedConfig,
6
+ type TagSecurityConfig,
7
+ type TagSecurityStatus,
8
+ } from '@vue-skuilder/common';
9
+ import type { CourseDBInterface } from '../../interfaces/courseDB';
10
+ import type { UserDBInterface } from '../../interfaces/userDB';
11
+ import type { ContentNavigationStrategyData } from '../../types/contentNavigationStrategy';
12
+ import { ContentNavigator } from '../index';
13
+ import type { WeightedCard } from '../index';
14
+ import type { GeneratorResult } from '../generators/types';
15
+ import type { CardFilter, FilterContext, FilterKind } from './types';
16
+
17
+ // ============================================================================
18
+ // SKILL PRESSURE FILTER
19
+ // ============================================================================
20
+ //
21
+ // Leans selection toward the learner's weakest skills: a card exercising a
22
+ // skill under pressure gets a small, bounded boost. "Which skill", kept
23
+ // separate from ELO distance's "what difficulty", so each is its own line in
24
+ // a card's provenance.
25
+ //
26
+ // A skill's pressure (0–1) is the larger of:
27
+ // - need (common/skillNeed): how far its rating sits below the median of the
28
+ // learner's skills;
29
+ // - insecurity (common/tagSecurity), when enabled: a fixed weight for a met
30
+ // skill that is shaky (right too rarely lately) or unproven (too little
31
+ // recent evidence). This is what works down the insecure count a course may
32
+ // gate new material on; need alone misses skills rated near the median but
33
+ // missed lately, and skills with too few responses to rate.
34
+ //
35
+ // multiplier = 1 + gain · (the card's highest skill pressure). The max over a
36
+ // card's tags, never the product, so a card naming several weak skills isn't
37
+ // boosted several times.
38
+ //
39
+ // Acts on the whole heap, reviews included: its first effect under a review
40
+ // backlog is on *which* reviews are served. A boost can't bring a card that no
41
+ // generator retrieved; retrieval of a weak skill's unseen cards is a
42
+ // generator's job.
43
+ //
44
+ // A `signal`. Not added by default: it re-weights every candidate, so a course
45
+ // opts in with a `skillPressure` strategy doc (serializedData: a
46
+ // SkillPressureConfig as JSON, or empty for the defaults).
47
+ //
48
+ // ============================================================================
49
+
50
+ export interface SkillPressureConfig extends SkillNeedConfig {
51
+ /** Boost at pressure 1: multiplier = 1 + gain · pressure. Default 0.5 (cap ×1.5). */
52
+ gain?: number;
53
+ /**
54
+ * Insecurity as pressure. `false` turns it off (need only). Weights are
55
+ * need-equivalents, 0–1. Default: shaky 0.8, unproven 0.5. Uses the same
56
+ * tag selector as need.
57
+ */
58
+ security?:
59
+ | false
60
+ | {
61
+ shaky?: number;
62
+ unproven?: number;
63
+ /** Thresholds for secure / shaky / unproven. Default: the framework's. */
64
+ config?: TagSecurityConfig;
65
+ };
66
+ }
67
+
68
+ const DEFAULT_GAIN = 0.5;
69
+ const DEFAULT_SECURITY_WEIGHTS: Record<Exclude<TagSecurityStatus, 'secure'>, number> = {
70
+ shaky: 0.8,
71
+ unproven: 0.5,
72
+ };
73
+
74
+ interface SkillPressureEntry {
75
+ pressure: number;
76
+ why: string;
77
+ }
78
+
79
+ /** Pressure per skill tag for this learner; tags under no pressure are absent. */
80
+ export function skillPressures(
81
+ elo: CourseElo,
82
+ config: SkillPressureConfig = {}
83
+ ): Map<string, SkillPressureEntry> {
84
+ const out = new Map<string, SkillPressureEntry>();
85
+ const raise = (tag: string, pressure: number, why: string): void => {
86
+ if (pressure <= 0) return;
87
+ const prev = out.get(tag);
88
+ if (!prev || pressure > prev.pressure) out.set(tag, { pressure, why });
89
+ };
90
+
91
+ for (const s of skillNeed(elo, config).skills) {
92
+ raise(s.tag, s.need, `need ${s.need.toFixed(2)} (${Math.round(s.deficit)} below the skill median)`);
93
+ }
94
+
95
+ if (config.security !== false) {
96
+ const weights = { ...DEFAULT_SECURITY_WEIGHTS, ...(config.security ?? {}) };
97
+ const { include, exclude, roles } = config;
98
+ const security = courseSecurity(elo, {
99
+ selector: { include, exclude, roles },
100
+ config: config.security ? config.security.config : undefined,
101
+ });
102
+ for (const s of security.tags) {
103
+ if (s.status === 'secure') continue;
104
+ const n = Math.min(s.attempts, 12);
105
+ raise(
106
+ s.tag,
107
+ weights[s.status],
108
+ s.status === 'shaky' ? `shaky (${s.right}/${n} right)` : `unproven (${s.attempts} recent attempts)`
109
+ );
110
+ }
111
+ }
112
+ return out;
113
+ }
114
+
115
+ async function applySkillPressure(
116
+ cards: WeightedCard[],
117
+ context: FilterContext,
118
+ config: SkillPressureConfig,
119
+ source: { name: string; strategyId: string }
120
+ ): Promise<WeightedCard[]> {
121
+ if (!context.userCourseElo) return cards;
122
+ const pressures = skillPressures(context.userCourseElo, config);
123
+ if (pressures.size === 0) return cards;
124
+ const gain = config.gain ?? DEFAULT_GAIN;
125
+
126
+ return cards.map((card) => {
127
+ let top: { tag: string; entry: SkillPressureEntry } | null = null;
128
+ for (const tag of card.tags ?? []) {
129
+ const entry = pressures.get(tag);
130
+ if (entry && (!top || entry.pressure > top.entry.pressure)) top = { tag, entry };
131
+ }
132
+ if (!top) return card;
133
+
134
+ const multiplier = 1 + gain * top.entry.pressure;
135
+ const score = card.score * multiplier;
136
+ return {
137
+ ...card,
138
+ score,
139
+ provenance: [
140
+ ...card.provenance,
141
+ {
142
+ strategy: 'skillPressure',
143
+ strategyName: source.name,
144
+ strategyId: source.strategyId,
145
+ action: 'boosted',
146
+ score,
147
+ reason: `skill pressure: ${top.tag} ${top.entry.why} → ×${multiplier.toFixed(2)}`,
148
+ },
149
+ ],
150
+ };
151
+ });
152
+ }
153
+
154
+ /**
155
+ * The skill pressure filter as a strategy-doc navigator (`implementingClass:
156
+ * 'skillPressure'`, serializedData: a SkillPressureConfig as JSON, or empty).
157
+ */
158
+ export default class SkillPressureFilter extends ContentNavigator implements CardFilter {
159
+ name: string;
160
+ /** See CardFilter.kind. Static, so the pipeline plan can read it without an instance. */
161
+ static readonly kind: FilterKind = 'signal';
162
+ readonly kind = SkillPressureFilter.kind;
163
+ private config: SkillPressureConfig;
164
+
165
+ constructor(
166
+ user: UserDBInterface,
167
+ course: CourseDBInterface,
168
+ strategyData: ContentNavigationStrategyData
169
+ ) {
170
+ super(user, course, strategyData);
171
+ this.name = strategyData.name || 'Skill Pressure';
172
+ let parsed: SkillPressureConfig = {};
173
+ try {
174
+ parsed = strategyData.serializedData ? JSON.parse(strategyData.serializedData) : {};
175
+ } catch {
176
+ parsed = {};
177
+ }
178
+ this.config = parsed;
179
+ }
180
+
181
+ transform(cards: WeightedCard[], context: FilterContext): Promise<WeightedCard[]> {
182
+ return applySkillPressure(cards, context, this.config, {
183
+ name: this.name,
184
+ strategyId: this.strategyId || 'NAVIGATION_STRATEGY-skillPressure',
185
+ });
186
+ }
187
+
188
+ async getWeightedCards(_limit: number): Promise<GeneratorResult> {
189
+ throw new Error(
190
+ 'SkillPressureFilter is a filter and should not be used as a generator. ' +
191
+ 'Use Pipeline with a generator and this filter via transform().'
192
+ );
193
+ }
194
+ }
@@ -200,18 +200,21 @@ export async function initializeNavigatorRegistry(): Promise<void> {
200
200
  relativePriorityModule,
201
201
  userTagPreferenceModule,
202
202
  eloDistanceModule,
203
+ skillPressureModule,
203
204
  ] = await Promise.all([
204
205
  import('./filters/hierarchyDefinition'),
205
206
  import('./filters/interferenceMitigator'),
206
207
  import('./filters/relativePriority'),
207
208
  import('./filters/userTagPreference'),
208
209
  import('./filters/eloDistance'),
210
+ import('./filters/skillPressure'),
209
211
  ]);
210
212
  registerNavigator('hierarchyDefinition', hierarchyModule.default);
211
213
  registerNavigator('interferenceMitigator', interferenceModule.default);
212
214
  registerNavigator('relativePriority', relativePriorityModule.default);
213
215
  registerNavigator('userTagPreference', userTagPreferenceModule.default);
214
216
  registerNavigator('eloDistance', eloDistanceModule.default);
217
+ registerNavigator('skillPressure', skillPressureModule.default);
215
218
 
216
219
  logger.debug(
217
220
  `[NavigatorRegistry] Initialized ${navigatorRegistry.size} navigators: ${getRegisteredNavigatorNames().join(', ')}`
@@ -412,6 +415,7 @@ export enum Navigators {
412
415
  RELATIVE_PRIORITY = 'relativePriority',
413
416
  USER_TAG_PREFERENCE = 'userTagPreference',
414
417
  ELO_DISTANCE = 'eloDistance',
418
+ SKILL_PRESSURE = 'skillPressure',
415
419
  }
416
420
 
417
421
  // ============================================================================
@@ -452,6 +456,7 @@ export const NavigatorRoles: Record<Navigators, NavigatorRole> = {
452
456
  [Navigators.RELATIVE_PRIORITY]: NavigatorRole.FILTER,
453
457
  [Navigators.USER_TAG_PREFERENCE]: NavigatorRole.FILTER,
454
458
  [Navigators.ELO_DISTANCE]: NavigatorRole.FILTER,
459
+ [Navigators.SKILL_PRESSURE]: NavigatorRole.FILTER,
455
460
  };
456
461
 
457
462
  /**
@@ -0,0 +1,84 @@
1
+ import { describe, it, expect } from 'vitest';
2
+ import type { CourseElo, EloRank } from '@vue-skuilder/common';
3
+ import SkillPressureFilter, { skillPressures } from '../../../src/core/navigators/filters/skillPressure';
4
+ import type { WeightedCard } from '../../../src/core/navigators/index';
5
+ import type { FilterContext } from '../../../src/core/navigators/filters/types';
6
+ import type { CourseDBInterface } from '../../../src/core/interfaces/courseDB';
7
+ import type { UserDBInterface } from '../../../src/core/interfaces/userDB';
8
+ import type { ContentNavigationStrategyData } from '../../../src/core/types/contentNavigationStrategy';
9
+
10
+ /** A rated skill with `n` first attempts, `right` of them right, over two days. */
11
+ function skill(score: number, n = 12, right = n): EloRank {
12
+ return {
13
+ score,
14
+ count: Math.max(n, 10),
15
+ recent: Array.from({ length: n }, (_, i) => ({
16
+ at: `2026-11-0${1 + (i % 2)}T12:00:00.000Z`,
17
+ ok: i < right,
18
+ tagOk: i < right,
19
+ perf: i < right ? 0.8 : 0,
20
+ card: `c${i}`,
21
+ })),
22
+ };
23
+ }
24
+
25
+ const elo: CourseElo = {
26
+ global: { score: 1500, count: 500 },
27
+ tags: {
28
+ 'exercise:a': skill(1500),
29
+ 'exercise:b': skill(1500),
30
+ 'exercise:c': skill(1500),
31
+ 'exercise:d': skill(1500),
32
+ 'exercise:low': skill(1350), // 150 below the median: need 1
33
+ 'exercise:shaky': skill(1500, 12, 6), // at the median, right half the time
34
+ },
35
+ misc: {},
36
+ };
37
+
38
+ const card = (id: string, tags: string[]): WeightedCard => ({
39
+ cardId: id,
40
+ courseId: 'c',
41
+ score: 1,
42
+ tags,
43
+ provenance: [{ strategy: 'test', strategyName: 'T', strategyId: 'T', action: 'generated', score: 1, reason: 't' }],
44
+ });
45
+
46
+ function filter(serializedData = ''): SkillPressureFilter {
47
+ return new SkillPressureFilter({} as UserDBInterface, {} as CourseDBInterface, {
48
+ name: 'Skill Pressure',
49
+ serializedData,
50
+ } as ContentNavigationStrategyData);
51
+ }
52
+
53
+ const ctx = (userCourseElo?: CourseElo): FilterContext => ({
54
+ user: {} as UserDBInterface,
55
+ course: {} as CourseDBInterface,
56
+ userElo: 1500,
57
+ ...(userCourseElo ? { userCourseElo } : {}),
58
+ });
59
+
60
+ describe('skill pressure', () => {
61
+ it('pressures low-rated skills by need, and shaky ones by insecurity', () => {
62
+ const p = skillPressures(elo);
63
+ expect(p.get('exercise:low')?.pressure).toBe(1);
64
+ expect(p.get('exercise:shaky')?.pressure).toBe(0.8);
65
+ expect(p.has('exercise:a')).toBe(false);
66
+ expect(skillPressures(elo, { security: false }).has('exercise:shaky')).toBe(false);
67
+ });
68
+
69
+ it('boosts by the card’s neediest tag (max, not product), up to ×1.5', async () => {
70
+ const out = await filter().transform(
71
+ [card('both', ['exercise:low', 'exercise:shaky']), card('shaky', ['exercise:shaky']), card('fine', ['exercise:a'])],
72
+ ctx(elo)
73
+ );
74
+ expect(out[0].score).toBeCloseTo(1.5);
75
+ expect(out[1].score).toBeCloseTo(1.4);
76
+ expect(out[2].score).toBe(1);
77
+ expect(out[0].provenance.at(-1)?.reason).toContain('exercise:low');
78
+ });
79
+
80
+ it('passes everything through without the learner’s ratings', async () => {
81
+ const cards = [card('x', ['exercise:low'])];
82
+ expect(await filter().transform(cards, ctx())).toEqual(cards);
83
+ });
84
+ });