@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.
- package/dist/{contentSource-2zVmcjKA.d.ts → contentSource-CSI0pJ2D.d.ts} +10 -0
- package/dist/core/index.cjs +105 -36
- package/dist/core/index.cjs.map +1 -1
- package/dist/core/index.d.ts +3 -3
- package/dist/core/interfaces/contentSource.mjs.map +1 -1
- package/dist/core/navigators/Pipeline.mjs +7 -1
- package/dist/core/navigators/Pipeline.mjs.map +1 -1
- package/dist/core/navigators/filters/eloDistance.mjs +17 -2
- package/dist/core/navigators/filters/eloDistance.mjs.map +1 -1
- package/dist/core/navigators/generators/prescribed.mjs +20 -10
- package/dist/core/navigators/generators/prescribed.mjs.map +1 -1
- package/dist/core/navigators/index.mjs +2 -0
- package/dist/core/navigators/index.mjs.map +1 -1
- package/dist/core/versionStamps.mjs +1 -1
- package/dist/{dataLayerProvider-rGyLQ93v.d.ts → dataLayerProvider-D5n1gGc_.d.ts} +1 -1
- package/dist/diagnostics/index.d.ts +2 -2
- package/dist/impl/common/BaseUserDB.mjs +43 -21
- package/dist/impl/common/BaseUserDB.mjs.map +1 -1
- package/dist/impl/couch/courseDB.mjs +5 -0
- package/dist/impl/couch/courseDB.mjs.map +1 -1
- package/dist/impl/couch/index.cjs +80 -24
- package/dist/impl/couch/index.cjs.map +1 -1
- package/dist/impl/couch/index.d.ts +4 -2
- package/dist/impl/static/courseDB.mjs +5 -0
- package/dist/impl/static/courseDB.mjs.map +1 -1
- package/dist/impl/static/index.cjs +80 -24
- package/dist/impl/static/index.cjs.map +1 -1
- package/dist/impl/static/index.d.ts +4 -2
- package/dist/index.cjs +116 -37
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.ts +3 -3
- package/dist/study/SessionController.mjs +1 -0
- package/dist/study/SessionController.mjs.map +1 -1
- package/docs/session-lifecycle-and-replan.md +71 -58
- package/package.json +3 -3
- package/src/core/interfaces/contentSource.ts +7 -0
- package/src/core/navigators/Pipeline.ts +7 -0
- package/src/core/navigators/filters/eloDistance.ts +31 -2
- package/src/core/navigators/generators/prescribed.ts +56 -11
- package/src/core/navigators/generators/types.ts +3 -0
- package/src/core/navigators/index.ts +5 -0
- package/src/impl/common/BaseUserDB.ts +47 -25
- package/src/impl/couch/courseDB.ts +13 -0
- package/src/impl/static/courseDB.ts +13 -0
- package/src/study/SessionController.ts +3 -0
- 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
|
|
11
|
-
>
|
|
12
|
-
>
|
|
13
|
-
>
|
|
14
|
-
>
|
|
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
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
###
|
|
341
|
-
|
|
342
|
-
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
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
|
|
396
|
+
### Instrumentation
|
|
397
397
|
|
|
398
|
-
|
|
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
|
|
401
|
-
`[Pipeline:timing]` summary line
|
|
402
|
-
|
|
403
|
-
|
|
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`
|
|
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.
|
|
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.
|
|
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.
|
|
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
|
|
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(
|
|
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 &&
|
|
497
|
-
groupState.
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
447
|
+
return (await this.scanScheduledCards()).map((doc) => ({
|
|
448
|
+
courseID: doc.courseId,
|
|
449
|
+
cardID: doc.cardId,
|
|
450
|
+
}));
|
|
451
|
+
}
|
|
445
452
|
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
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
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
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
|
|
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
|
|
558
|
-
.filter((
|
|
559
|
-
if (
|
|
576
|
+
return reviews
|
|
577
|
+
.filter((doc) => {
|
|
578
|
+
if (doc._id.startsWith(DocTypePrefixes[DocType.SCHEDULED_CARD])) {
|
|
560
579
|
const date = moment.utc(
|
|
561
|
-
|
|
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 ||
|
|
584
|
+
if (course_id === undefined || doc.courseId === course_id) {
|
|
566
585
|
return true;
|
|
567
586
|
}
|
|
568
587
|
}
|
|
569
588
|
}
|
|
570
589
|
})
|
|
571
|
-
.map((
|
|
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);
|