@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
@@ -7,11 +7,11 @@
7
7
  > the former `agent/session-pipeline-perf` assessment and should be trimmed
8
8
  > before this ships as public framework documentation.
9
9
  >
10
- > **Perf work is parked (2026-05).** The felt mid-session jank (the synchronous
11
- > wedge-breaker firing when the queue bottomed out) is resolved by the cache work
12
- > recorded below. The `[perf]` timing instrumentation is commented out in place
13
- > (search `[perf] parked` in the source); uncomment to re-measure. Remaining
14
- > threads (cold spin-up, possibly-remote reads) are documented but not pursued.
10
+ > **Perf status (2026-11).** The 2026-05 mid-session jank is resolved (cache
11
+ > work, below). The 2026-11 runtime-perf work resolved the course-DB side of
12
+ > session start: sessions bind to the local replica when one exists, and far
13
+ > fewer remote calls when one doesn't. Open: user-DB reads and main-thread work
14
+ > during replans (see *Open threads*).
15
15
 
16
16
  This document maps how `SessionController` drives content selection through the
17
17
  navigation `Pipeline` during a study session: what runs at session start, when
@@ -334,51 +334,51 @@ sits on one of two clocks:
334
334
 
335
335
  The cache work above optimized the *least* time-sensitive stage (background
336
336
  replan) — correctly, since that is what keeps us out of the wedge. The *most*
337
- time-sensitive stage (cold spin-up, dominated by the ELO view reindex) is
338
- essentially untouched.
339
-
340
- ### Open / parked threads (running notes)
341
-
342
- - **Cold spin-up (~4.6s, blocking)** dominated by the first `elo` view reindex
343
- (`getCardsByELO below~2490ms`). Most time-sensitive, least touched. A cheap
344
- micro-fix worth trying: fire a throwaway `db.query('elo', {limit:1})` early
345
- (e.g. on the study-hub view) to keep the IndexedDB index warm before
346
- `/study/practice`.
347
- - **Reads may be hitting REMOTE CouchDB, not the local replica** — the leading
348
- hypothesis for the remaining costs (see next subsection). If true, this is one
349
- root cause behind spin-up + per-card hydration + `regDoc`, not three.
350
- - **Per-card hydration `cardDoc+tags` = 0.8-2.1s each**, a persistent band (not
351
- just at startup). Entirely `getCourseDoc` + `getAppliedTagsBatch`. On a *local*
352
- PouchDB these should be tens of ms — hence the remote-reads suspicion.
353
- - **`getPendingReviews` ~ 768ms**, recomputed fresh on every replan (SRSgen).
354
- Candidate to incrementalize, but reviews mutate as cards are answered, so
355
- correctness needs care.
356
- - **`regDoc ~ 444ms`** — a single registration-doc read inside
357
- `getCardsCenteredAtELO`. Same "reads may be remote" smell.
358
-
359
- ### The likely root cause: reads may not be local
360
-
361
- `CourseDB` picks local-vs-remote **once, at construction**: `this.db = localDB ??
362
- remoteDB`, where `localDB` is non-null only if `CourseSyncService` sync state is
363
- exactly `'ready'` at that instant. Miss that window (cold first visit:
364
- replication + view-warming takes seconds) and the whole session's pipeline reads
365
- go to the remote handle and **never re-bind** after sync finishes.
366
-
367
- The "remote" CouchDB in dev is `localhost:5984`, so the cost is *not* network
368
- latency — it is **per-request work the CouchDB server does**: MapReduce view-index
369
- maintenance. The log fingerprints it: the same `elo` view queried back-to-back
370
- reads `below=2490ms` then `above=111ms` — cold reindex then warm, not latency
371
- (which would tax both equally). What invalidates the index? *This session's own
372
- ELO writes* — every answered card writes a card-ELO doc, bumping `update_seq`. A
373
- local sync replica is one-shot, read-only and pre-warmed, so local reads never
374
- trigger a reindex.
375
-
376
- To confirm: add a one-line `CourseDB` constructor log (`db=local|remote`); split
377
- the hydration timer into `cardDoc` (`.get`, no view) vs `tags`
378
- (`getAppliedTagsBatch`, a view query) — if `tags` carries the 1-2s it's the
379
- reindex story. The fix is then *not* micro-optimizing reads but guaranteeing the
380
- session runs against a ready local replica (await `'ready'`; re-bind or
381
- lazy-resolve `this.db`; reuse hydration handles).
337
+ time-sensitive stage, cold spin-up, was the 2026-11 work's target (next
338
+ section); the figures in this table are 2026-05's.
339
+
340
+ ### Course-DB reads: local vs remote (resolved 2026-11)
341
+
342
+ The 2026-05 notes suspected session reads were going to remote CouchDB instead of
343
+ the synced replica. Confirmed, and fixed for the course DB (fw #1197, 0.2.37):
344
+
345
+ - **Replica ready at load.** `CourseSyncService` writes `_local/sync-complete`
346
+ when a sync finishes; on later page loads `ensureSynced` hands out the on-disk
347
+ replica at once from that marker and refreshes it in the background (an
348
+ epoch mismatch only drops the marker; the next load rebuilds).
349
+ - **Rebinding between sessions.** `PouchDataLayerProvider` keeps one `CourseDB`
350
+ per course and replaces it when the replica becomes ready, so the *next*
351
+ session on the same page reads locally. A running session keeps the handle it
352
+ was built with (`CourseDB` still binds at construction).
353
+ - **Fewer remote calls without a replica:** one memoized remote handle per
354
+ course with `skip_setup`, `CourseConfig` cached, tag stubs and applied tags
355
+ read through `CourseDB.db` (local when available), strategy docs fetched once.
356
+ Cold preparation went from ~21 requests to 10; with a replica, 2.
357
+
358
+ Production (2026-11-06): cold guest preparation 8.7 s → 3.6 s (remote, mobile
359
+ network); returning device 2.5 s, bound local. Whether a session ran local is
360
+ now visible: `sk:pipeline-run`'s `binding` (below).
361
+
362
+ ### Open threads
363
+
364
+ - **User-DB reads.** A replan's generators used to scan the user's scheduled
365
+ cards three times (`getActiveCards` from ELO and Prescribed,
366
+ `getReviewstoDate` from SRS); they now share one in-flight scan
367
+ (`BaseUserDB.scanScheduledCards`, 2026-11). It still reads the remote handle
368
+ for a logged-in user: scheduled reviews are written to the server and reach
369
+ the local mirror by live sync, so a local read could return a review that was
370
+ just completed. Reading locally would need writes to land locally first. The
371
+ remote range also accumulates tombstones (one per completed review), which
372
+ the scan walks until compaction.
373
+ - **Main-thread work during replans** (filters, tag hydration, scoring) on
374
+ slower devices. Yield points between stages are the cheap first step;
375
+ attribute with a real-device trace first.
376
+ - **A session can't start before its first plan.** Preparation (~2.5–4 s)
377
+ starts when `StudySession.vue` mounts. Consumers with a lead-in (a lesson, a
378
+ hub) could prepare a `SessionController` earlier and hand it in; no seam for
379
+ that yet.
380
+ - **First sync on a new device** (download, IndexedDB writes, view warming)
381
+ runs on the main thread, alongside whatever session starts meanwhile.
382
382
 
383
383
  ### Still-true structural notes
384
384
 
@@ -393,22 +393,35 @@ lazy-resolve `this.db`; reuse hydration handles).
393
393
  3. **Initial fetch is inflated to ~220** (`defaultBatchLimit + initialReviewCap`),
394
394
  compounding (2) at spin-up.
395
395
 
396
- ### Instrumentation (parked)
396
+ ### Instrumentation
397
397
 
398
- The `[perf]` timing logs across `Pipeline`, `SessionController`,
398
+ **Timing marks (stable, shipped; fw #1198).** User Timing entries that tools
399
+ read with `performance.getEntriesByType('mark' | 'measure')` or Lighthouse's
400
+ `user-timings`:
401
+
402
+ | Name | Where | Detail |
403
+ |------|-------|--------|
404
+ | `sk:session-prepare-start`, `sk:session-prepared`, measure `sk:session-prepare` | `SessionController.prepareSession` | — |
405
+ | measure `sk:pipeline-run` (every run) | `Pipeline.getWeightedCards` | stage ms; `binding`: `local` / `remote` / `unknown` (`CourseDBInterface.readsLocal`) |
406
+ | `sk:course-sync-replicated`, `sk:course-sync-ready`, `sk:course-sync-refreshed` | `CourseSyncService` | `ready`'s `from`: `marker` / `sync` |
407
+ | `sk:first-card` | common-ui `StudySession` | card ID |
408
+
409
+ Helpers: `perfMark` / `perfMeasure` (`db/src/util/perfMarks.ts`), which never
410
+ throw.
411
+
412
+ **Parked logs.** The `[perf]` timing logs across `Pipeline`, `SessionController`,
399
413
  `CardHydrationService`, `elo`/`srs` generators, and `courseDB` are commented out
400
- in place — search **`[perf] parked`**. Uncomment to re-measure. The pre-existing
401
- `[Pipeline:timing]` summary line is kept (it predates this effort). Two
402
- provenance fields added during the dig — `awaitedReplan` and `wedgeRuns` on the
403
- `nextCard` log — are the instruments to re-enable first if the wedge question is
404
- revisited.
414
+ in place — search **`[perf] parked`**. Uncomment to re-measure. The
415
+ `[Pipeline:timing]` summary line stays. Two provenance fields on the `nextCard`
416
+ log — `awaitedReplan` and `wedgeRuns` — are the instruments to re-enable first if
417
+ the wedge question is revisited.
405
418
 
406
419
  ## File reference
407
420
 
408
421
  | File | Relevant region |
409
422
  |------|-----------------|
410
423
  | `db/src/study/SessionController.ts` | queues, `requestReplan`, `_runReplan`, `nextCard` triggers, wedge-breaker |
411
- | `db/src/impl/couch/courseDB.ts` | `getWeightedCards`, `setEphemeralHints`, `createNavigator` (no cache) |
424
+ | `db/src/impl/couch/courseDB.ts` | `getWeightedCards`, `setEphemeralHints`, `createNavigator`, `readsLocal` |
412
425
  | `db/src/core/navigators/Pipeline.ts` | `getWeightedCards` (fetchLimit=500), `applyHints`, `hydrateTags`, `buildContext` |
413
426
  | `db/src/core/navigators/generators/types.ts` | `ReplanHints`, `GeneratorResult` |
414
427
  | `db/src/study/SourceMixer.ts` | `QuotaRoundRobinMixer` |
package/package.json CHANGED
@@ -13,7 +13,7 @@
13
13
  "publishConfig": {
14
14
  "access": "public"
15
15
  },
16
- "version": "0.3.0",
16
+ "version": "0.3.2",
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.0",
72
+ "@vue-skuilder/common": "0.3.2",
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.0"
90
+ "stableVersion": "0.3.2"
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 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
  }
@@ -127,6 +127,9 @@ export class BaseUser implements UserDBInterface, DocumentUpdater {
127
127
  private updateQueue!: UpdateQueue;
128
128
 
129
129
  private _hydration: UserHydrationStatus = { state: 'not-required' };
130
+ /** See scanScheduledCards. Bumped by every write to scheduled reviews. */
131
+ private _scheduledScan: { generation: number; scan: Promise<ScheduledCard[]> } | null = null;
132
+ private _scheduledGeneration = 0;
130
133
  /** In-flight hydration, so concurrent callers can wait for a real answer. */
131
134
  private _hydrationPromise: Promise<void> | null = null;
132
135
  /**
@@ -441,20 +444,42 @@ Currently logged-in as ${this._username}.`
441
444
  *
442
445
  */
443
446
  public async getActiveCards() {
444
- const keys = getStartAndEndKeys(DocTypePrefixes[DocType.SCHEDULED_CARD]);
447
+ return (await this.scanScheduledCards()).map((doc) => ({
448
+ courseID: doc.courseId,
449
+ cardID: doc.cardId,
450
+ }));
451
+ }
445
452
 
446
- const reviews = await this.remoteDB.allDocs<ScheduledCard>({
447
- startkey: keys.startkey,
448
- endkey: keys.endkey,
449
- include_docs: true,
450
- });
453
+ /**
454
+ * The user's scheduled reviews (`card_review_*`), all of them: one `allDocs`
455
+ * scan shared by concurrent readers. A pipeline run's generators start
456
+ * together (`CompositeGenerator`), and each used to scan the range itself
457
+ * (`getActiveCards` from ELO and Prescribed, `getReviewstoDate` from SRS).
458
+ * Sharing only an in-flight scan keeps reads as fresh as before; a schedule
459
+ * or removal of a review starts a new scan for anyone reading after it.
460
+ * Docs are shared between callers: copy before mutating.
461
+ */
462
+ private scanScheduledCards(): Promise<ScheduledCard[]> {
463
+ const inFlight = this._scheduledScan;
464
+ if (inFlight && inFlight.generation === this._scheduledGeneration) return inFlight.scan;
451
465
 
452
- return reviews.rows.map((r) => {
453
- return {
454
- courseID: r.doc!.courseId,
455
- cardID: r.doc!.cardId,
456
- };
457
- });
466
+ const keys = getStartAndEndKeys(DocTypePrefixes[DocType.SCHEDULED_CARD]);
467
+ const entry = {
468
+ generation: this._scheduledGeneration,
469
+ scan: this.remoteDB
470
+ .allDocs<ScheduledCard>({
471
+ startkey: keys.startkey,
472
+ endkey: keys.endkey,
473
+ include_docs: true,
474
+ })
475
+ .then((res) => res.rows.map((row) => row.doc!)),
476
+ };
477
+ this._scheduledScan = entry;
478
+ const done = () => {
479
+ if (this._scheduledScan === entry) this._scheduledScan = null;
480
+ };
481
+ entry.scan.then(done, done);
482
+ return entry.scan;
458
483
  }
459
484
 
460
485
  public async getActivityRecords(): Promise<ActivityRecord[]> {
@@ -541,34 +566,28 @@ Currently logged-in as ${this._username}.`
541
566
  }
542
567
 
543
568
  private async getReviewstoDate(targetDate: Moment, course_id?: string) {
544
- const keys = getStartAndEndKeys(DocTypePrefixes[DocType.SCHEDULED_CARD]);
545
-
546
- const reviews = await this.remoteDB.allDocs<ScheduledCard>({
547
- startkey: keys.startkey,
548
- endkey: keys.endkey,
549
- include_docs: true,
550
- });
569
+ const reviews = await this.scanScheduledCards();
551
570
 
552
571
  log(
553
572
  `Fetching ${this._username}'s scheduled reviews${
554
573
  course_id ? ` for course ${course_id}` : ''
555
574
  }.`
556
575
  );
557
- return reviews.rows
558
- .filter((r) => {
559
- if (r.id.startsWith(DocTypePrefixes[DocType.SCHEDULED_CARD])) {
576
+ return reviews
577
+ .filter((doc) => {
578
+ if (doc._id.startsWith(DocTypePrefixes[DocType.SCHEDULED_CARD])) {
560
579
  const date = moment.utc(
561
- r.id.substr(DocTypePrefixes[DocType.SCHEDULED_CARD].length),
580
+ doc._id.substr(DocTypePrefixes[DocType.SCHEDULED_CARD].length),
562
581
  REVIEW_TIME_FORMAT
563
582
  );
564
583
  if (targetDate.isAfter(date)) {
565
- if (course_id === undefined || r.doc!.courseId === course_id) {
584
+ if (course_id === undefined || doc.courseId === course_id) {
566
585
  return true;
567
586
  }
568
587
  }
569
588
  }
570
589
  })
571
- .map((r) => r.doc!);
590
+ .map((doc) => ({ ...doc }));
572
591
  }
573
592
 
574
593
  public async getReviewsForcast(daysCount: number, course_id?: string) {
@@ -1180,6 +1199,7 @@ Currently logged-in as ${this._username}.`
1180
1199
  const deletePromises = duplicateDocIds.map(async (docId) => {
1181
1200
  try {
1182
1201
  const doc = await this.remoteDB.get(docId);
1202
+ this._scheduledGeneration++;
1183
1203
  await this.writeDB.remove(doc);
1184
1204
  log(`Successfully removed duplicate review: ${docId}`);
1185
1205
  } catch (error) {
@@ -1357,9 +1377,11 @@ Currently logged-in as ${this._username}.`
1357
1377
  scheduledFor: ScheduledCard['scheduledFor'];
1358
1378
  schedulingAgentId: ScheduledCard['schedulingAgentId'];
1359
1379
  }) {
1380
+ this._scheduledGeneration++;
1360
1381
  return scheduleCardReviewLocal(this.writeDB, review);
1361
1382
  }
1362
1383
  public async removeScheduledCardReview(reviewId: string): Promise<void> {
1384
+ this._scheduledGeneration++;
1363
1385
  return removeScheduledCardReviewLocal(this.writeDB, reviewId);
1364
1386
  }
1365
1387
 
@@ -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);