@vue-skuilder/db 0.2.29 → 0.2.30

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/package.json CHANGED
@@ -4,7 +4,7 @@
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
7
- "version": "0.2.29",
7
+ "version": "0.2.30",
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.29",
63
+ "@vue-skuilder/common": "0.2.30",
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.29"
78
+ "stableVersion": "0.2.30"
79
79
  }
@@ -6,6 +6,7 @@ import type { WeightedCard } from '../index';
6
6
  import type { GeneratorResult } from '../generators/types';
7
7
  import type { CardFilter, FilterContext, FilterKind } from './types';
8
8
  import type { CourseElo } from '@vue-skuilder/common';
9
+ import { logger } from '../../../util/logger';
9
10
 
10
11
  // ============================================================================
11
12
  // ELO DISTANCE FILTER
@@ -23,12 +24,14 @@ import type { CourseElo } from '@vue-skuilder/common';
23
24
  // - new cards far from the learner's level rank low (this used to live in the
24
25
  // ELO generator's own score, which double-counted alongside this filter).
25
26
  //
26
- // Tag-aware (default): a card's difficulty for this learner is read on the
27
- // skills they share, not only on global ELO. Card and learner keep paired
28
- // ratings per tag (each graded response adjusts both), so a tag's gap
27
+ // Tag-aware (opt-in, experimental): a card's difficulty for this learner is
28
+ // read on the skills they share, not only on global ELO. Card and learner keep
29
+ // paired ratings per tag (each graded response adjusts both), so a tag's gap
29
30
  // (card − learner) is as meaningful as the global one, and often more: a card
30
31
  // can sit at the learner's global level while testing their weakest skill.
31
- // See tagAwareGap for the combination.
32
+ // See tagAwareGap for the combination. Global distance is the default; a course
33
+ // opts in with `tagAware`, a browser with `window.skuilder.multiDimElo = true`
34
+ // (see the toggle below), for side-by-side testing.
32
35
  //
33
36
  // A `signal`, not a gate: it expresses preference, not readiness. `liveOnly`:
34
37
  // forecasts and card-space scans start every card at 1.0 without a generator,
@@ -67,7 +70,7 @@ export interface EloDistanceConfig {
67
70
  /**
68
71
  * Measure distance on the tags the card and learner share (see
69
72
  * tagAwareGap), falling back to global ELO where they share none.
70
- * Default true.
73
+ * Default false. `window.skuilder.multiDimElo` turns it on in one browser.
71
74
  */
72
75
  tagAware?: boolean;
73
76
 
@@ -86,7 +89,7 @@ export const DEFAULT_ELO_DISTANCE_CONFIG: Required<EloDistanceConfig> = {
86
89
  halfLife: 300,
87
90
  minMultiplier: 0.05,
88
91
  maxMultiplier: 1.0,
89
- tagAware: true,
92
+ tagAware: false,
90
93
  minTagCount: 3,
91
94
  };
92
95
 
@@ -117,6 +120,59 @@ function resolveConfig(config?: EloDistanceConfig): Required<EloDistanceConfig>
117
120
  return { ...DEFAULT_ELO_DISTANCE_CONFIG, ...config };
118
121
  }
119
122
 
123
+ // ----------------------------------------------------------------------------
124
+ // Live toggle: window.skuilder.multiDimElo
125
+ // ----------------------------------------------------------------------------
126
+ //
127
+ // `window.skuilder.multiDimElo = true` turns tag-aware distance on in this
128
+ // browser, whatever the strategy config says; `false` returns it to the
129
+ // config. Read on every run, so it takes effect at the next replan. Kept in
130
+ // localStorage so it survives reloads across a testing stretch. Runs it shapes
131
+ // say so in every card's ELO distance reason ("tag-aware").
132
+
133
+ const MULTI_DIM_ELO_KEY = 'skuilder:multiDimElo';
134
+
135
+ let multiDimElo = readMultiDimElo();
136
+
137
+ function readMultiDimElo(): boolean {
138
+ try {
139
+ return typeof localStorage !== 'undefined' && localStorage.getItem(MULTI_DIM_ELO_KEY) === 'true';
140
+ } catch {
141
+ return false;
142
+ }
143
+ }
144
+
145
+ /**
146
+ * Mount the toggle on window.skuilder.multiDimElo.
147
+ */
148
+ export function mountMultiDimEloToggle(): void {
149
+ if (typeof window === 'undefined') return;
150
+
151
+ const win = window as any;
152
+ win.skuilder = win.skuilder || {};
153
+ Object.defineProperty(win.skuilder, 'multiDimElo', {
154
+ configurable: true,
155
+ enumerable: true,
156
+ get: () => multiDimElo,
157
+ set: (on: unknown) => {
158
+ multiDimElo = on === true;
159
+ try {
160
+ if (multiDimElo) localStorage.setItem(MULTI_DIM_ELO_KEY, 'true');
161
+ else localStorage.removeItem(MULTI_DIM_ELO_KEY);
162
+ } catch (e) {
163
+ logger.warn(`[EloDistance] multiDimElo not persisted (localStorage unavailable): ${e}`);
164
+ }
165
+ logger.info(
166
+ `[EloDistance] multiDimElo ${multiDimElo ? 'on: tag-aware' : 'off: per strategy config'}` +
167
+ ' ELO distance from the next replan'
168
+ );
169
+ },
170
+ });
171
+ }
172
+
173
+ // Auto-mount when module is loaded
174
+ mountMultiDimEloToggle();
175
+
120
176
  /** One shared tag's contribution to a card's tag-aware gap. */
121
177
  interface TagGap {
122
178
  tag: string;
@@ -139,8 +195,9 @@ interface TagGap {
139
195
  * total evidence W: λ = W / (W + 1). One thin tag barely moves it; several
140
196
  * practised tags dominate it.
141
197
  *
142
- * OPEN (draft, 2026-10-01; uncommitted, to sit on). On one LP learner's
143
- * 09-30 dump the effect was modest: every touched card shared a rated tag
198
+ * OPEN (draft, 2026-10-01). Shipped on by default in 0.2.29 by accident (it
199
+ * rode along in the version-bump commit); off by default since, and live only
200
+ * behind the toggle. On one LP learner's 09-30 dump the effect was modest: every touched card shared a rated tag
144
201
  * (median 4); mean multiplier ×0.70 → ×0.75 over 352 touched cards, ×0.84 →
145
202
  * ×0.88 over 42 due reviews. The biggest movers were old who-said-that cards:
146
203
  * ~400 below the learner globally, ~280 below on their own skills.
@@ -209,7 +266,7 @@ async function applyEloDistance(
209
266
  ): Promise<WeightedCard[]> {
210
267
  const { course, userElo, userCourseElo } = context;
211
268
  const { halfLife, minMultiplier, maxMultiplier } = config;
212
- const tagAware = config.tagAware && userCourseElo !== undefined;
269
+ const tagAware = (config.tagAware || multiDimElo) && userCourseElo !== undefined;
213
270
 
214
271
  // Tag-aware needs every card's full ratings; otherwise only the ELO of cards
215
272
  // that don't carry it (reviews). One batch either way.
@@ -228,10 +285,12 @@ async function applyEloDistance(
228
285
 
229
286
  let distance = Math.abs(cardElo - userElo);
230
287
  let how = '';
231
- if (tagAware && full) {
232
- const t = tagAwareGap(card.tags ?? [], full, userCourseElo!, config.minTagCount);
233
- distance = Math.abs(t.gap);
234
- if (t.tags.length > 0) how = tagReason(t.tags, t.globalGap);
288
+ if (tagAware) {
289
+ const t = full ? tagAwareGap(card.tags ?? [], full, userCourseElo!, config.minTagCount) : undefined;
290
+ if (t) distance = Math.abs(t.gap);
291
+ how = t?.tags.length
292
+ ? `, tag-aware${tagReason(t.tags, t.globalGap)}`
293
+ : ', tag-aware: global (no shared tags)';
235
294
  }
236
295
 
237
296
  const multiplier = computeMultiplier(distance, halfLife, minMultiplier, maxMultiplier);