@vue-skuilder/db 0.3.0 → 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 (46) hide show
  1. package/dist/{contentSource-2zVmcjKA.d.ts → contentSource-CSI0pJ2D.d.ts} +10 -0
  2. package/dist/core/index.cjs +105 -36
  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/common/BaseUserDB.mjs +43 -21
  18. package/dist/impl/common/BaseUserDB.mjs.map +1 -1
  19. package/dist/impl/couch/courseDB.mjs +5 -0
  20. package/dist/impl/couch/courseDB.mjs.map +1 -1
  21. package/dist/impl/couch/index.cjs +80 -24
  22. package/dist/impl/couch/index.cjs.map +1 -1
  23. package/dist/impl/couch/index.d.ts +4 -2
  24. package/dist/impl/static/courseDB.mjs +5 -0
  25. package/dist/impl/static/courseDB.mjs.map +1 -1
  26. package/dist/impl/static/index.cjs +80 -24
  27. package/dist/impl/static/index.cjs.map +1 -1
  28. package/dist/impl/static/index.d.ts +4 -2
  29. package/dist/index.cjs +116 -37
  30. package/dist/index.cjs.map +1 -1
  31. package/dist/index.d.ts +3 -3
  32. package/dist/study/SessionController.mjs +1 -0
  33. package/dist/study/SessionController.mjs.map +1 -1
  34. package/docs/session-lifecycle-and-replan.md +71 -58
  35. package/package.json +3 -3
  36. package/src/core/interfaces/contentSource.ts +7 -0
  37. package/src/core/navigators/Pipeline.ts +7 -0
  38. package/src/core/navigators/filters/eloDistance.ts +31 -2
  39. package/src/core/navigators/generators/prescribed.ts +56 -11
  40. package/src/core/navigators/generators/types.ts +3 -0
  41. package/src/core/navigators/index.ts +5 -0
  42. package/src/impl/common/BaseUserDB.ts +47 -25
  43. package/src/impl/couch/courseDB.ts +13 -0
  44. package/src/impl/static/courseDB.ts +13 -0
  45. package/src/study/SessionController.ts +3 -0
  46. package/tests/core/navigators/eloDistanceFilter.test.ts +15 -0
@@ -1,6 +1,6 @@
1
1
  import { C as ClassroomDBInterface, A as AdminDBInterface } from '../../classroomDB-DLTtLZct.js';
2
- import { U as UserDBInterface, C as CourseDBInterface, a as CoursesDBInterface, b as CourseInfo, S as StudySessionItem, D as DataLayerResult, c as ContentNavigationStrategyData, d as ContentNavigator, R as ReplanHints, G as GeneratorResult } from '../../contentSource-2zVmcjKA.js';
3
- import { D as DataLayerProvider } from '../../dataLayerProvider-rGyLQ93v.js';
2
+ import { U as UserDBInterface, C as CourseDBInterface, a as CoursesDBInterface, b as CourseInfo, S as StudySessionItem, D as DataLayerResult, c as ContentNavigationStrategyData, d as ContentNavigator, R as ReplanHints, G as GeneratorResult } from '../../contentSource-CSI0pJ2D.js';
3
+ import { D as DataLayerProvider } from '../../dataLayerProvider-D5n1gGc_.js';
4
4
  import { S as StaticCourseManifest } from '../../types-DF0JuPbs.js';
5
5
  import { CourseConfig, CourseElo, DataShape } from '@vue-skuilder/common';
6
6
  import { S as SkuilderCourseData, Q as QualifiedCardID, T as TagStub, a as Tag } from '../../types-legacy-DdVjg81H.js';
@@ -176,6 +176,8 @@ declare class StaticCourseDB implements CourseDBInterface {
176
176
  createNavigator(user: UserDBInterface): Promise<ContentNavigator>;
177
177
  private _pendingHints;
178
178
  setEphemeralHints(hints: ReplanHints): void;
179
+ private _sessionId;
180
+ setSessionId(sessionId: string): void;
179
181
  /** Forward a presentation to the navigator (a new card restarts its intake clock). */
180
182
  notePresented(card: {
181
183
  cardId: string;
package/dist/index.cjs CHANGED
@@ -1621,9 +1621,12 @@ var init_prescribed = __esm({
1621
1621
  const allRelevantIds = dedupe([...allTargetIds, ...allSupportIds]);
1622
1622
  const tagsByCard = allRelevantIds.length > 0 ? await this.course.getAppliedTagsBatch(allRelevantIds) : /* @__PURE__ */ new Map();
1623
1623
  const cardsByTag = await this.loadCardsByTag();
1624
+ const sessionId = context?.sessionId;
1625
+ const newSession = sessionId === void 0 || sessionId !== progress.lastSessionId;
1624
1626
  const nextState = {
1625
1627
  updatedAt: isoNow(),
1626
- groups: {}
1628
+ groups: {},
1629
+ ...sessionId || progress.lastSessionId ? { lastSessionId: sessionId ?? progress.lastSessionId } : {}
1627
1630
  };
1628
1631
  const emitted = [];
1629
1632
  const emittedIds = /* @__PURE__ */ new Set();
@@ -1663,7 +1666,11 @@ var init_prescribed = __esm({
1663
1666
  );
1664
1667
  }
1665
1668
  }
1666
- nextState.groups[group.id] = this.buildNextGroupState(runtime, progress.groups[group.id]);
1669
+ nextState.groups[group.id] = this.buildNextGroupState(
1670
+ runtime,
1671
+ progress.groups[group.id],
1672
+ newSession
1673
+ );
1667
1674
  const directCards = this.buildDirectTargetCards(
1668
1675
  runtime,
1669
1676
  courseId,
@@ -1735,12 +1742,8 @@ var init_prescribed = __esm({
1735
1742
  for (const group of this.config.groups) {
1736
1743
  const groupState = nextState.groups[group.id];
1737
1744
  const surfaced = surfacedByGroup.get(group.id);
1738
- if (surfaced && (surfaced.targetIds.length > 0 || surfaced.supportIds.length > 0)) {
1739
- groupState.lastSurfacedAt = isoNow();
1740
- groupState.sessionsSinceSurfaced = 0;
1741
- if (surfaced.supportIds.length > 0) {
1742
- groupState.lastSupportAt = isoNow();
1743
- }
1745
+ if (surfaced && surfaced.supportIds.length > 0) {
1746
+ groupState.lastSupportAt = isoNow();
1744
1747
  }
1745
1748
  }
1746
1749
  await this.putStrategyState(nextState).catch((e) => {
@@ -2006,14 +2009,24 @@ var init_prescribed = __esm({
2006
2009
  debugVersion: PRESCRIBED_DEBUG_VERSION
2007
2010
  };
2008
2011
  }
2009
- buildNextGroupState(runtime, prior) {
2012
+ /**
2013
+ * The group's state after this run. The staleness clock resets only when a
2014
+ * target has reached the learner since the last run: it is newly in
2015
+ * `encounteredTargets`, which reads card history and scheduled reviews, so
2016
+ * the card was shown and answered. Emitting a target does not count; it may
2017
+ * lose to the rest of the heap. (Before 2026-11, emission reset the clock,
2018
+ * and a group that emitted every run never escalated.) The clock advances
2019
+ * once per study session, not per run.
2020
+ */
2021
+ buildNextGroupState(runtime, prior, newSession) {
2010
2022
  const carriedSessions = prior?.sessionsSinceSurfaced ?? 0;
2011
- const surfacedThisRun = false;
2023
+ const previouslyEncountered = new Set(prior?.encounteredCardIds ?? []);
2024
+ const surfacedThisRun = prior !== void 0 && [...runtime.encounteredTargets].some((id) => !previouslyEncountered.has(id));
2012
2025
  return {
2013
2026
  encounteredCardIds: [...runtime.encounteredTargets].sort(),
2014
2027
  pendingTargetIds: [...runtime.pendingTargets].sort(),
2015
- lastSurfacedAt: prior?.lastSurfacedAt ?? null,
2016
- sessionsSinceSurfaced: surfacedThisRun ? 0 : carriedSessions + 1,
2028
+ lastSurfacedAt: surfacedThisRun ? isoNow() : prior?.lastSurfacedAt ?? null,
2029
+ sessionsSinceSurfaced: surfacedThisRun ? 0 : carriedSessions + (newSession ? 1 : 0),
2017
2030
  lastSupportAt: prior?.lastSupportAt ?? null,
2018
2031
  blockedTargetIds: [...runtime.blockedTargets].sort(),
2019
2032
  lastResolvedSupportTags: [...runtime.supportTags].sort()
@@ -3140,6 +3153,9 @@ __export(eloDistance_exports, {
3140
3153
  mountMultiDimEloToggle: () => mountMultiDimEloToggle,
3141
3154
  tagAwareGap: () => tagAwareGap
3142
3155
  });
3156
+ function isIntroCard(card) {
3157
+ return (card.tags ?? []).some((t) => (0, import_common5.tagRole)(t) === "intro");
3158
+ }
3143
3159
  function computeMultiplier(distance, halfLife, minMultiplier, maxMultiplier) {
3144
3160
  const normalizedDistance = distance / halfLife;
3145
3161
  const decay = Math.exp(-(normalizedDistance * normalizedDistance));
@@ -3207,7 +3223,7 @@ async function applyEloDistance(cards, context, config, source) {
3207
3223
  const { course, userElo, userCourseElo } = context;
3208
3224
  const { halfLife, minMultiplier, maxMultiplier } = config;
3209
3225
  const tagAware = (config.tagAware || multiDimElo) && userCourseElo !== void 0;
3210
- const missing = cards.filter((c) => tagAware || c.cardElo === void 0).map((c) => c.cardId);
3226
+ const missing = cards.filter((c) => !isIntroCard(c) && (tagAware || c.cardElo === void 0)).map((c) => c.cardId);
3211
3227
  const fetched = /* @__PURE__ */ new Map();
3212
3228
  if (missing.length > 0) {
3213
3229
  const elos = await course.getCardEloData(missing);
@@ -3216,6 +3232,22 @@ async function applyEloDistance(cards, context, config, source) {
3216
3232
  });
3217
3233
  }
3218
3234
  return cards.map((card) => {
3235
+ if (isIntroCard(card)) {
3236
+ return {
3237
+ ...card,
3238
+ provenance: [
3239
+ ...card.provenance,
3240
+ {
3241
+ strategy: "eloDistance",
3242
+ strategyName: source.name,
3243
+ strategyId: source.strategyId,
3244
+ action: "passed",
3245
+ score: card.score,
3246
+ reason: "intro card: ELO is a placeholder, distance not applied \u2192 1.00x"
3247
+ }
3248
+ ]
3249
+ };
3250
+ }
3219
3251
  const full = fetched.get(card.cardId);
3220
3252
  const cardElo = full?.global?.score ?? card.cardElo ?? DEFAULT_CARD_ELO;
3221
3253
  let distance = Math.abs(cardElo - userElo);
@@ -3588,6 +3620,9 @@ var init_navigators = __esm({
3588
3620
  */
3589
3621
  setEphemeralHints(_hints) {
3590
3622
  }
3623
+ /** See StudyContentSource.setSessionId. No-op for non-Pipeline navigators. */
3624
+ setSessionId(_sessionId) {
3625
+ }
3591
3626
  };
3592
3627
  }
3593
3628
  });
@@ -3624,7 +3659,7 @@ var FRAMEWORK_VERSION, hostAppVersion, DEFAULT_STRATEGY_HASH;
3624
3659
  var init_versionStamps = __esm({
3625
3660
  "src/core/versionStamps.ts"() {
3626
3661
  "use strict";
3627
- FRAMEWORK_VERSION = true ? "0.3.0" : "dev";
3662
+ FRAMEWORK_VERSION = true ? "0.3.2" : "dev";
3628
3663
  DEFAULT_STRATEGY_HASH = "default";
3629
3664
  }
3630
3665
  });
@@ -7069,6 +7104,7 @@ var init_Pipeline = __esm({
7069
7104
  * getWeightedCards() call, then cleared.
7070
7105
  */
7071
7106
  _ephemeralHints = null;
7107
+ _sessionId;
7072
7108
  /**
7073
7109
  * The intake valve's clock (see regulators.ts), loaded from strategy state on
7074
7110
  * first use and kept in memory. Writes are chained so a presentation and a
@@ -7104,6 +7140,10 @@ var init_Pipeline = __esm({
7104
7140
  *
7105
7141
  * Overrides ContentNavigator.setEphemeralHints() no-op.
7106
7142
  */
7143
+ /** See StudyContentSource.setSessionId. Carried into every run's context. */
7144
+ setSessionId(sessionId) {
7145
+ this._sessionId = sessionId;
7146
+ }
7107
7147
  setEphemeralHints(hints) {
7108
7148
  this._ephemeralHints = hints;
7109
7149
  logger.info(`[Pipeline] Ephemeral hints set: ${JSON.stringify(hints)}`);
@@ -7551,7 +7591,8 @@ var init_Pipeline = __esm({
7551
7591
  course: this.course,
7552
7592
  userElo,
7553
7593
  ...userCourseElo ? { userCourseElo } : {},
7554
- orchestration
7594
+ orchestration,
7595
+ ...this._sessionId ? { sessionId: this._sessionId } : {}
7555
7596
  };
7556
7597
  }
7557
7598
  /**
@@ -9100,6 +9141,9 @@ var init_SessionController = __esm({
9100
9141
  )
9101
9142
  };
9102
9143
  this.sources = sources;
9144
+ for (const source of sources) {
9145
+ source.setSessionId?.(this.sessionId);
9146
+ }
9103
9147
  this.startTime = /* @__PURE__ */ new Date();
9104
9148
  this._secondsRemaining = time;
9105
9149
  this.endTime = new Date(this.startTime.valueOf() + 1e3 * this._secondsRemaining);
@@ -10738,6 +10782,9 @@ var init_BaseUserDB = __esm({
10738
10782
  // Database to use for write operations (local-first approach)
10739
10783
  updateQueue;
10740
10784
  _hydration = { state: "not-required" };
10785
+ /** See scanScheduledCards. Bumped by every write to scheduled reviews. */
10786
+ _scheduledScan = null;
10787
+ _scheduledGeneration = 0;
10741
10788
  /** In-flight hydration, so concurrent callers can wait for a real answer. */
10742
10789
  _hydrationPromise = null;
10743
10790
  /**
@@ -10982,18 +11029,38 @@ Currently logged-in as ${this._username}.`
10982
11029
  *
10983
11030
  */
10984
11031
  async getActiveCards() {
11032
+ return (await this.scanScheduledCards()).map((doc) => ({
11033
+ courseID: doc.courseId,
11034
+ cardID: doc.cardId
11035
+ }));
11036
+ }
11037
+ /**
11038
+ * The user's scheduled reviews (`card_review_*`), all of them: one `allDocs`
11039
+ * scan shared by concurrent readers. A pipeline run's generators start
11040
+ * together (`CompositeGenerator`), and each used to scan the range itself
11041
+ * (`getActiveCards` from ELO and Prescribed, `getReviewstoDate` from SRS).
11042
+ * Sharing only an in-flight scan keeps reads as fresh as before; a schedule
11043
+ * or removal of a review starts a new scan for anyone reading after it.
11044
+ * Docs are shared between callers: copy before mutating.
11045
+ */
11046
+ scanScheduledCards() {
11047
+ const inFlight = this._scheduledScan;
11048
+ if (inFlight && inFlight.generation === this._scheduledGeneration) return inFlight.scan;
10985
11049
  const keys = getStartAndEndKeys(DocTypePrefixes["SCHEDULED_CARD" /* SCHEDULED_CARD */]);
10986
- const reviews = await this.remoteDB.allDocs({
10987
- startkey: keys.startkey,
10988
- endkey: keys.endkey,
10989
- include_docs: true
10990
- });
10991
- return reviews.rows.map((r) => {
10992
- return {
10993
- courseID: r.doc.courseId,
10994
- cardID: r.doc.cardId
10995
- };
10996
- });
11050
+ const entry = {
11051
+ generation: this._scheduledGeneration,
11052
+ scan: this.remoteDB.allDocs({
11053
+ startkey: keys.startkey,
11054
+ endkey: keys.endkey,
11055
+ include_docs: true
11056
+ }).then((res) => res.rows.map((row) => row.doc))
11057
+ };
11058
+ this._scheduledScan = entry;
11059
+ const done = () => {
11060
+ if (this._scheduledScan === entry) this._scheduledScan = null;
11061
+ };
11062
+ entry.scan.then(done, done);
11063
+ return entry.scan;
10997
11064
  }
10998
11065
  async getActivityRecords() {
10999
11066
  try {
@@ -11059,28 +11126,23 @@ Currently logged-in as ${this._username}.`
11059
11126
  }
11060
11127
  }
11061
11128
  async getReviewstoDate(targetDate, course_id) {
11062
- const keys = getStartAndEndKeys(DocTypePrefixes["SCHEDULED_CARD" /* SCHEDULED_CARD */]);
11063
- const reviews = await this.remoteDB.allDocs({
11064
- startkey: keys.startkey,
11065
- endkey: keys.endkey,
11066
- include_docs: true
11067
- });
11129
+ const reviews = await this.scanScheduledCards();
11068
11130
  log3(
11069
11131
  `Fetching ${this._username}'s scheduled reviews${course_id ? ` for course ${course_id}` : ""}.`
11070
11132
  );
11071
- return reviews.rows.filter((r) => {
11072
- if (r.id.startsWith(DocTypePrefixes["SCHEDULED_CARD" /* SCHEDULED_CARD */])) {
11133
+ return reviews.filter((doc) => {
11134
+ if (doc._id.startsWith(DocTypePrefixes["SCHEDULED_CARD" /* SCHEDULED_CARD */])) {
11073
11135
  const date = import_moment7.default.utc(
11074
- r.id.substr(DocTypePrefixes["SCHEDULED_CARD" /* SCHEDULED_CARD */].length),
11136
+ doc._id.substr(DocTypePrefixes["SCHEDULED_CARD" /* SCHEDULED_CARD */].length),
11075
11137
  REVIEW_TIME_FORMAT
11076
11138
  );
11077
11139
  if (targetDate.isAfter(date)) {
11078
- if (course_id === void 0 || r.doc.courseId === course_id) {
11140
+ if (course_id === void 0 || doc.courseId === course_id) {
11079
11141
  return true;
11080
11142
  }
11081
11143
  }
11082
11144
  }
11083
- }).map((r) => r.doc);
11145
+ }).map((doc) => ({ ...doc }));
11084
11146
  }
11085
11147
  async getReviewsForcast(daysCount, course_id) {
11086
11148
  const time = import_moment7.default.utc().add(daysCount, "days");
@@ -11551,6 +11613,7 @@ Currently logged-in as ${this._username}.`
11551
11613
  const deletePromises = duplicateDocIds.map(async (docId) => {
11552
11614
  try {
11553
11615
  const doc = await this.remoteDB.get(docId);
11616
+ this._scheduledGeneration++;
11554
11617
  await this.writeDB.remove(doc);
11555
11618
  log3(`Successfully removed duplicate review: ${docId}`);
11556
11619
  } catch (error) {
@@ -11696,9 +11759,11 @@ Currently logged-in as ${this._username}.`
11696
11759
  }
11697
11760
  }
11698
11761
  async scheduleCardReview(review) {
11762
+ this._scheduledGeneration++;
11699
11763
  return scheduleCardReviewLocal(this.writeDB, review);
11700
11764
  }
11701
11765
  async removeScheduledCardReview(reviewId) {
11766
+ this._scheduledGeneration++;
11702
11767
  return removeScheduledCardReviewLocal(this.writeDB, reviewId);
11703
11768
  }
11704
11769
  async registerForClassroom(_classId, _registerAs) {
@@ -13333,6 +13398,10 @@ ${e.stack}` : JSON.stringify(e);
13333
13398
  setEphemeralHints(hints) {
13334
13399
  this._pendingHints = hints;
13335
13400
  }
13401
+ _sessionId = null;
13402
+ setSessionId(sessionId) {
13403
+ this._sessionId = sessionId;
13404
+ }
13336
13405
  /**
13337
13406
  * Forward a presentation to the navigator (a new card restarts its intake
13338
13407
  * clock). Builds the navigator if the cached one has expired.
@@ -13349,6 +13418,9 @@ ${e.stack}` : JSON.stringify(e);
13349
13418
  navigator2.setEphemeralHints(this._pendingHints);
13350
13419
  this._pendingHints = null;
13351
13420
  }
13421
+ if (this._sessionId) {
13422
+ navigator2.setSessionId(this._sessionId);
13423
+ }
13352
13424
  const result = await navigator2.getWeightedCards(limit);
13353
13425
  return result;
13354
13426
  } catch (e) {
@@ -15570,6 +15642,10 @@ var init_courseDB2 = __esm({
15570
15642
  setEphemeralHints(hints) {
15571
15643
  this._pendingHints = hints;
15572
15644
  }
15645
+ _sessionId = null;
15646
+ setSessionId(sessionId) {
15647
+ this._sessionId = sessionId;
15648
+ }
15573
15649
  /** Forward a presentation to the navigator (a new card restarts its intake clock). */
15574
15650
  notePresented(card) {
15575
15651
  if (card.status !== "new") return;
@@ -15582,6 +15658,9 @@ var init_courseDB2 = __esm({
15582
15658
  navigator2.setEphemeralHints(this._pendingHints);
15583
15659
  this._pendingHints = null;
15584
15660
  }
15661
+ if (this._sessionId) {
15662
+ navigator2.setSessionId(this._sessionId);
15663
+ }
15585
15664
  return navigator2.getWeightedCards(limit);
15586
15665
  } catch (e) {
15587
15666
  logger.error(`[static/courseDB] Error getting weighted cards: ${e}`);