@vue-skuilder/db 0.2.34 → 0.2.36
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/CLAUDE.md +15 -4
- package/build.entries.mjs +12 -0
- package/dist/_virtual/_rolldown/runtime.mjs +8 -0
- package/dist/{contentSource-CTQ4kWhR.d.cts → contentSource-D_E7JaxR.d.ts} +2 -2
- package/dist/core/UserDBDebugger.mjs +285 -0
- package/dist/core/UserDBDebugger.mjs.map +1 -0
- package/dist/core/bulkImport/cardProcessor.mjs +106 -0
- package/dist/core/bulkImport/cardProcessor.mjs.map +1 -0
- package/dist/core/{index.js → index.cjs} +6438 -7784
- package/dist/core/index.cjs.map +1 -0
- package/dist/core/index.d.ts +5 -5
- package/dist/core/index.mjs +20 -11368
- package/dist/core/interfaces/contentSource.mjs +20 -0
- package/dist/core/interfaces/contentSource.mjs.map +1 -0
- package/dist/core/navigators/Pipeline.mjs +723 -0
- package/dist/core/navigators/Pipeline.mjs.map +1 -0
- package/dist/core/navigators/PipelineAssembler.mjs +86 -0
- package/dist/core/navigators/PipelineAssembler.mjs.map +1 -0
- package/dist/core/navigators/PipelineDebugger.mjs +771 -0
- package/dist/core/navigators/PipelineDebugger.mjs.map +1 -0
- package/dist/core/navigators/SrsDebugger.mjs +34 -0
- package/dist/core/navigators/SrsDebugger.mjs.map +1 -0
- package/dist/core/navigators/StrategyPressureDebugger.mjs +19 -0
- package/dist/core/navigators/StrategyPressureDebugger.mjs.map +1 -0
- package/dist/core/navigators/defaults.mjs +96 -0
- package/dist/core/navigators/defaults.mjs.map +1 -0
- package/dist/core/navigators/diversityRerank.mjs +85 -0
- package/dist/core/navigators/diversityRerank.mjs.map +1 -0
- package/dist/core/navigators/filters/WeightedFilter.mjs +81 -0
- package/dist/core/navigators/filters/WeightedFilter.mjs.map +1 -0
- package/dist/core/navigators/filters/eloDistance.mjs +244 -0
- package/dist/core/navigators/filters/eloDistance.mjs.map +1 -0
- package/dist/core/navigators/filters/hierarchyDefinition.mjs +235 -0
- package/dist/core/navigators/filters/hierarchyDefinition.mjs.map +1 -0
- package/dist/core/navigators/filters/interferenceMitigator.mjs +201 -0
- package/dist/core/navigators/filters/interferenceMitigator.mjs.map +1 -0
- package/dist/core/navigators/filters/relativePriority.mjs +135 -0
- package/dist/core/navigators/filters/relativePriority.mjs.map +1 -0
- package/dist/core/navigators/filters/userTagPreference.mjs +101 -0
- package/dist/core/navigators/filters/userTagPreference.mjs.map +1 -0
- package/dist/core/navigators/generators/CompositeGenerator.mjs +203 -0
- package/dist/core/navigators/generators/CompositeGenerator.mjs.map +1 -0
- package/dist/core/navigators/generators/elo.mjs +77 -0
- package/dist/core/navigators/generators/elo.mjs.map +1 -0
- package/dist/core/navigators/generators/prescribed.mjs +676 -0
- package/dist/core/navigators/generators/prescribed.mjs.map +1 -0
- package/dist/core/navigators/generators/srs.mjs +158 -0
- package/dist/core/navigators/generators/srs.mjs.map +1 -0
- package/dist/core/navigators/index.mjs +345 -0
- package/dist/core/navigators/index.mjs.map +1 -0
- package/dist/core/navigators/pipelinePlan.mjs +109 -0
- package/dist/core/navigators/pipelinePlan.mjs.map +1 -0
- package/dist/core/navigators/regulators.mjs +128 -0
- package/dist/core/navigators/regulators.mjs.map +1 -0
- package/dist/core/orchestration/gradient.mjs +101 -0
- package/dist/core/orchestration/gradient.mjs.map +1 -0
- package/dist/core/orchestration/index.mjs +115 -0
- package/dist/core/orchestration/index.mjs.map +1 -0
- package/dist/core/orchestration/learning.mjs +140 -0
- package/dist/core/orchestration/learning.mjs.map +1 -0
- package/dist/core/orchestration/recording.mjs +64 -0
- package/dist/core/orchestration/recording.mjs.map +1 -0
- package/dist/core/orchestration/signal.mjs +40 -0
- package/dist/core/orchestration/signal.mjs.map +1 -0
- package/dist/core/types/contentNavigationStrategy.mjs +10 -0
- package/dist/core/types/contentNavigationStrategy.mjs.map +1 -0
- package/dist/core/types/hydration.mjs +13 -0
- package/dist/core/types/hydration.mjs.map +1 -0
- package/dist/core/types/strategyState.mjs +16 -0
- package/dist/core/types/strategyState.mjs.map +1 -0
- package/dist/core/types/studySession.mjs +14 -0
- package/dist/core/types/studySession.mjs.map +1 -0
- package/dist/core/types/types-legacy.mjs +44 -0
- package/dist/core/types/types-legacy.mjs.map +1 -0
- package/dist/core/util/index.mjs +31 -0
- package/dist/core/util/index.mjs.map +1 -0
- package/dist/core/versionStamps.mjs +46 -0
- package/dist/core/versionStamps.mjs.map +1 -0
- package/dist/courseConfigRegistration.mjs +306 -0
- package/dist/courseConfigRegistration.mjs.map +1 -0
- package/dist/{dataLayerProvider-rlLE2Mf-.d.ts → dataLayerProvider-BDshhSp_.d.ts} +1 -1
- package/dist/diagnostics/dataset.mjs +118 -0
- package/dist/diagnostics/dataset.mjs.map +1 -0
- package/dist/diagnostics/derive.mjs +318 -0
- package/dist/diagnostics/derive.mjs.map +1 -0
- package/dist/diagnostics/{index.js → index.cjs} +130 -1
- package/dist/diagnostics/index.cjs.map +1 -0
- package/dist/diagnostics/index.d.ts +108 -5
- package/dist/diagnostics/index.mjs +7 -914
- package/dist/diagnostics/loader.mjs +151 -0
- package/dist/diagnostics/loader.mjs.map +1 -0
- package/dist/diagnostics/pipeline.mjs +161 -0
- package/dist/diagnostics/pipeline.mjs.map +1 -0
- package/dist/diagnostics/tagElo.mjs +177 -0
- package/dist/diagnostics/tagElo.mjs.map +1 -0
- package/dist/diagnostics/text.mjs +174 -0
- package/dist/diagnostics/text.mjs.map +1 -0
- package/dist/factory.mjs +70 -0
- package/dist/factory.mjs.map +1 -0
- package/dist/impl/common/BaseUserDB.mjs +1103 -0
- package/dist/impl/common/BaseUserDB.mjs.map +1 -0
- package/dist/impl/common/userDBHelpers.mjs +49 -0
- package/dist/impl/common/userDBHelpers.mjs.map +1 -0
- package/dist/impl/common/userDBKeys.mjs +45 -0
- package/dist/impl/common/userDBKeys.mjs.map +1 -0
- package/dist/impl/couch/CouchDBSyncStrategy.mjs +272 -0
- package/dist/impl/couch/CouchDBSyncStrategy.mjs.map +1 -0
- package/dist/impl/couch/CourseSyncService.mjs +242 -0
- package/dist/impl/couch/CourseSyncService.mjs.map +1 -0
- package/dist/impl/couch/PouchDataLayerProvider.mjs +74 -0
- package/dist/impl/couch/PouchDataLayerProvider.mjs.map +1 -0
- package/dist/impl/couch/adminDB.mjs +61 -0
- package/dist/impl/couch/adminDB.mjs.map +1 -0
- package/dist/impl/couch/auth.mjs +33 -0
- package/dist/impl/couch/auth.mjs.map +1 -0
- package/dist/impl/couch/classroomDB.mjs +227 -0
- package/dist/impl/couch/classroomDB.mjs.map +1 -0
- package/dist/impl/couch/clientCache.mjs +15 -0
- package/dist/impl/couch/clientCache.mjs.map +1 -0
- package/dist/impl/couch/courseAPI.mjs +183 -0
- package/dist/impl/couch/courseAPI.mjs.map +1 -0
- package/dist/impl/couch/courseDB.mjs +729 -0
- package/dist/impl/couch/courseDB.mjs.map +1 -0
- package/dist/impl/couch/courseLookupDB.mjs +94 -0
- package/dist/impl/couch/courseLookupDB.mjs.map +1 -0
- package/dist/impl/couch/{index.js → index.cjs} +6911 -10367
- package/dist/impl/couch/index.cjs.map +1 -0
- package/dist/impl/couch/index.d.ts +12 -5
- package/dist/impl/couch/index.mjs +134 -12146
- package/dist/impl/couch/index.mjs.map +1 -1
- package/dist/impl/couch/pouchdb-setup.mjs +15 -0
- package/dist/impl/couch/pouchdb-setup.mjs.map +1 -0
- package/dist/impl/couch/updateQueue.mjs +101 -0
- package/dist/impl/couch/updateQueue.mjs.map +1 -0
- package/dist/impl/couch/user-course-relDB.mjs +55 -0
- package/dist/impl/couch/user-course-relDB.mjs.map +1 -0
- package/dist/impl/static/NoOpSyncStrategy.mjs +49 -0
- package/dist/impl/static/NoOpSyncStrategy.mjs.map +1 -0
- package/dist/impl/static/StaticDataLayerProvider.mjs +94 -0
- package/dist/impl/static/StaticDataLayerProvider.mjs.map +1 -0
- package/dist/impl/static/StaticDataUnpacker.mjs +311 -0
- package/dist/impl/static/StaticDataUnpacker.mjs.map +1 -0
- package/dist/impl/static/courseDB.mjs +368 -0
- package/dist/impl/static/courseDB.mjs.map +1 -0
- package/dist/impl/static/coursesDB.mjs +38 -0
- package/dist/impl/static/coursesDB.mjs.map +1 -0
- package/dist/impl/static/{index.js → index.cjs} +2461 -5992
- package/dist/impl/static/index.cjs.map +1 -0
- package/dist/impl/static/index.d.ts +4 -4
- package/dist/impl/static/index.mjs +6 -10741
- package/dist/{index-CVGehe_t.d.ts → index-BLDpFYG3.d.ts} +1 -1
- package/dist/{index.js → index.cjs} +14070 -14239
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.ts +12 -23
- package/dist/index.mjs +38 -16937
- package/dist/pouch/{index.js → index.cjs} +5 -1
- package/dist/pouch/index.cjs.map +1 -0
- package/dist/pouch/index.mjs +2 -19
- package/dist/study/ItemQueue.mjs +95 -0
- package/dist/study/ItemQueue.mjs.map +1 -0
- package/dist/study/MixerDebugger.mjs +303 -0
- package/dist/study/MixerDebugger.mjs.map +1 -0
- package/dist/study/SessionController.mjs +1187 -0
- package/dist/study/SessionController.mjs.map +1 -0
- package/dist/study/SessionDebugger.mjs +271 -0
- package/dist/study/SessionDebugger.mjs.map +1 -0
- package/dist/study/SessionOverlay.mjs +407 -0
- package/dist/study/SessionOverlay.mjs.map +1 -0
- package/dist/study/SourceMixer.mjs +45 -0
- package/dist/study/SourceMixer.mjs.map +1 -0
- package/dist/study/SpacedRepetition.mjs +108 -0
- package/dist/study/SpacedRepetition.mjs.map +1 -0
- package/dist/study/TagFilteredContentSource.mjs +136 -0
- package/dist/study/TagFilteredContentSource.mjs.map +1 -0
- package/dist/study/services/CardHydrationService.mjs +172 -0
- package/dist/study/services/CardHydrationService.mjs.map +1 -0
- package/dist/study/services/EloService.mjs +217 -0
- package/dist/study/services/EloService.mjs.map +1 -0
- package/dist/study/services/ResponseProcessor.mjs +190 -0
- package/dist/study/services/ResponseProcessor.mjs.map +1 -0
- package/dist/study/services/SrsService.mjs +49 -0
- package/dist/study/services/SrsService.mjs.map +1 -0
- package/dist/study/services/tagRecent.mjs +65 -0
- package/dist/study/services/tagRecent.mjs.map +1 -0
- package/dist/{types-dXWfyz9B.d.ts → types-DChCz22D.d.ts} +1 -1
- package/dist/{types-legacy-BkOYOR6U.d.cts → types-legacy-fT5Y1Wuy.d.ts} +1 -1
- package/dist/userDBKeys-ne1g4Xuq.d.ts +16 -0
- package/dist/util/Loggable.mjs +14 -0
- package/dist/util/Loggable.mjs.map +1 -0
- package/dist/util/dataDirectory.mjs +47 -0
- package/dist/util/dataDirectory.mjs.map +1 -0
- package/dist/util/logger.mjs +86 -0
- package/dist/util/logger.mjs.map +1 -0
- package/dist/util/migrator/FileSystemAdapter.mjs +18 -0
- package/dist/util/migrator/FileSystemAdapter.mjs.map +1 -0
- package/dist/util/migrator/StaticToCouchDBMigrator.mjs +428 -0
- package/dist/util/migrator/StaticToCouchDBMigrator.mjs.map +1 -0
- package/dist/util/migrator/types.mjs +11 -0
- package/dist/util/migrator/types.mjs.map +1 -0
- package/dist/util/migrator/validation.mjs +334 -0
- package/dist/util/migrator/validation.mjs.map +1 -0
- package/dist/util/packer/CouchDBToStaticPacker.mjs +438 -0
- package/dist/util/packer/CouchDBToStaticPacker.mjs.map +1 -0
- package/dist/util/packer/{index.js → index.cjs} +73 -9
- package/dist/util/packer/index.cjs.map +1 -0
- package/dist/util/packer/index.d.ts +3 -3
- package/dist/util/packer/index.mjs +2 -537
- package/eslint.config.mjs +9 -1
- package/package.json +25 -13
- package/rolldown.config.mjs +44 -0
- package/src/core/UserDBDebugger.ts +47 -46
- package/src/core/navigators/Pipeline.ts +10 -10
- package/src/core/navigators/PipelineDebugger.ts +55 -55
- package/src/core/navigators/filters/eloDistance.ts +11 -1
- package/src/core/navigators/generators/elo.ts +5 -1
- package/src/core/navigators/index.ts +9 -3
- package/src/diagnostics/derive.ts +6 -0
- package/src/diagnostics/index.ts +1 -0
- package/src/diagnostics/tagElo.ts +257 -0
- package/src/factory.ts +10 -1
- package/src/impl/common/BaseUserDB.ts +1 -3
- package/src/impl/common/index.ts +2 -0
- package/src/impl/common/userDBHelpers.ts +4 -58
- package/src/impl/common/userDBKeys.ts +64 -0
- package/src/impl/couch/courseDB.ts +15 -3
- package/src/impl/couch/index.ts +2 -18
- package/src/impl/couch/pouchdb-setup.ts +8 -0
- package/src/index.ts +1 -1
- package/src/study/MixerDebugger.ts +46 -46
- package/src/study/SessionDebugger.ts +20 -20
- package/src/study/SessionOverlay.ts +4 -4
- package/src/util/logger.ts +112 -13
- package/tests/core/navigators/eloGenerator.test.ts +36 -0
- package/tsup.config.ts +24 -21
- package/dist/SyncStrategy-BXliog1m.d.cts +0 -116
- package/dist/classroomDB-DLTtLZct.d.cts +0 -86
- package/dist/contentSource-JmWYu8IK.d.ts +0 -2007
- package/dist/core/index.d.cts +0 -521
- package/dist/core/index.js.map +0 -1
- package/dist/core/index.mjs.map +0 -1
- package/dist/dataLayerProvider-DfI_KYAe.d.cts +0 -61
- package/dist/diagnostics/index.d.cts +0 -458
- package/dist/diagnostics/index.js.map +0 -1
- package/dist/diagnostics/index.mjs.map +0 -1
- package/dist/impl/couch/index.d.cts +0 -620
- package/dist/impl/couch/index.js.map +0 -1
- package/dist/impl/static/index.d.cts +0 -232
- package/dist/impl/static/index.js.map +0 -1
- package/dist/impl/static/index.mjs.map +0 -1
- package/dist/index-Ktg72jKb.d.cts +0 -137
- package/dist/index.d.cts +0 -1663
- package/dist/index.js.map +0 -1
- package/dist/index.mjs.map +0 -1
- package/dist/pouch/index.d.cts +0 -1
- package/dist/pouch/index.js.map +0 -1
- package/dist/pouch/index.mjs.map +0 -1
- package/dist/types-D0oQeJAi.d.cts +0 -58
- package/dist/types-legacy-BkOYOR6U.d.ts +0 -168
- package/dist/util/packer/index.d.cts +0 -5
- package/dist/util/packer/index.js.map +0 -1
- package/dist/util/packer/index.mjs.map +0 -1
- package/src/study/getCardDataShape.ts +0 -34
|
@@ -1,2007 +0,0 @@
|
|
|
1
|
-
import { Status, CourseConfig, SkuilderCourseData as SkuilderCourseData$1, CourseElo, DataShape, TagFilter } from '@vue-skuilder/common';
|
|
2
|
-
import { Moment } from 'moment';
|
|
3
|
-
import { S as SkuilderCourseData, f as DocTypePrefixes, D as DocType, d as QualifiedCardID, e as TagStub, T as Tag, c as CardHistory, b as CardRecord, Q as QuestionRecord } from './types-legacy-BkOYOR6U.js';
|
|
4
|
-
|
|
5
|
-
interface DataLayerResult {
|
|
6
|
-
status: Status;
|
|
7
|
-
message: string;
|
|
8
|
-
id?: string;
|
|
9
|
-
}
|
|
10
|
-
|
|
11
|
-
/**
|
|
12
|
-
* Configuration for an evolutionarily-weighted strategy.
|
|
13
|
-
*
|
|
14
|
-
* This structure tracks the "learned" weight of a strategy, representing the
|
|
15
|
-
* system's confidence in its utility.
|
|
16
|
-
*
|
|
17
|
-
* - weight: The best-known multiplier (peak of the bell curve)
|
|
18
|
-
* - confidence: How certain we are (inverse of variance / spread)
|
|
19
|
-
* - sampleSize: How many data points informed this weight
|
|
20
|
-
*/
|
|
21
|
-
interface LearnableWeight {
|
|
22
|
-
/** The current best estimate of optimal weight (multiplier) */
|
|
23
|
-
weight: number;
|
|
24
|
-
/** Confidence in this weight (0-1). Higher = narrower exploration spread. */
|
|
25
|
-
confidence: number;
|
|
26
|
-
/** Number of outcome observations that contributed to this weight */
|
|
27
|
-
sampleSize: number;
|
|
28
|
-
}
|
|
29
|
-
/**
|
|
30
|
-
*
|
|
31
|
-
*/
|
|
32
|
-
interface ContentNavigationStrategyData extends SkuilderCourseData {
|
|
33
|
-
_id: `${typeof DocTypePrefixes[DocType.NAVIGATION_STRATEGY]}-${string}`;
|
|
34
|
-
docType: DocType.NAVIGATION_STRATEGY;
|
|
35
|
-
name: string;
|
|
36
|
-
description: string;
|
|
37
|
-
/**
|
|
38
|
-
The name of the class that implements the navigation strategy at runtime.
|
|
39
|
-
*/
|
|
40
|
-
implementingClass: string;
|
|
41
|
-
/**
|
|
42
|
-
A representation of the strategy's parameterization - to be deserialized
|
|
43
|
-
by the implementing class's constructor at runtime.
|
|
44
|
-
*/
|
|
45
|
-
serializedData: string;
|
|
46
|
-
/**
|
|
47
|
-
* Evolutionary weighting configuration.
|
|
48
|
-
* If present, the strategy's influence is scaled by this weight.
|
|
49
|
-
* If omitted, weight defaults to 1.0.
|
|
50
|
-
*/
|
|
51
|
-
learnable?: LearnableWeight;
|
|
52
|
-
/**
|
|
53
|
-
* If true, the weight is applied exactly as configured, without
|
|
54
|
-
* per-user deviation. Used for manual tuning or A/B testing.
|
|
55
|
-
*/
|
|
56
|
-
staticWeight?: boolean;
|
|
57
|
-
}
|
|
58
|
-
|
|
59
|
-
/**
|
|
60
|
-
* A NavigationStrategyManager is an entity which may contain multiple strategies.
|
|
61
|
-
*
|
|
62
|
-
* This interface defines strategy CRUD.
|
|
63
|
-
*/
|
|
64
|
-
interface NavigationStrategyManager {
|
|
65
|
-
/**
|
|
66
|
-
* Get the navigation strategy for a given course
|
|
67
|
-
* @returns The navigation strategy for the course
|
|
68
|
-
*/
|
|
69
|
-
getNavigationStrategy(id: string): Promise<ContentNavigationStrategyData>;
|
|
70
|
-
/**
|
|
71
|
-
* Get all available navigation strategies
|
|
72
|
-
* @returns An array of all available navigation strategies
|
|
73
|
-
*/
|
|
74
|
-
getAllNavigationStrategies(): Promise<ContentNavigationStrategyData[]>;
|
|
75
|
-
/**
|
|
76
|
-
* Add a new navigation strategy
|
|
77
|
-
* @param data The data for the new navigation strategy
|
|
78
|
-
* @returns A promise that resolves when the strategy has been added
|
|
79
|
-
*/
|
|
80
|
-
addNavigationStrategy(data: ContentNavigationStrategyData): Promise<void>;
|
|
81
|
-
/**
|
|
82
|
-
* Update an existing navigation strategy
|
|
83
|
-
* @param id The ID of the navigation strategy to update
|
|
84
|
-
* @param data The new data for the navigation strategy
|
|
85
|
-
* @returns A promise that resolves when the update is complete
|
|
86
|
-
*/
|
|
87
|
-
updateNavigationStrategy(id: string, data: ContentNavigationStrategyData): Promise<void>;
|
|
88
|
-
}
|
|
89
|
-
|
|
90
|
-
/**
|
|
91
|
-
* Course content and management
|
|
92
|
-
*/
|
|
93
|
-
interface CoursesDBInterface {
|
|
94
|
-
/**
|
|
95
|
-
* Get course config
|
|
96
|
-
*/
|
|
97
|
-
getCourseConfig(courseId: string): Promise<CourseConfig>;
|
|
98
|
-
/**
|
|
99
|
-
* Get a list of all courses
|
|
100
|
-
*/
|
|
101
|
-
getCourseList(): Promise<CourseConfig[]>;
|
|
102
|
-
disambiguateCourse(courseId: string, disambiguator: string): Promise<void>;
|
|
103
|
-
}
|
|
104
|
-
interface CourseInfo {
|
|
105
|
-
cardCount: number;
|
|
106
|
-
registeredUsers: number;
|
|
107
|
-
}
|
|
108
|
-
interface CourseDBInterface extends NavigationStrategyManager, StudyContentSource {
|
|
109
|
-
/**
|
|
110
|
-
* Get course config
|
|
111
|
-
*/
|
|
112
|
-
getCourseConfig(): Promise<CourseConfig>;
|
|
113
|
-
getCourseID(): string;
|
|
114
|
-
/**
|
|
115
|
-
* Set course config
|
|
116
|
-
*/
|
|
117
|
-
updateCourseConfig(cfg: CourseConfig): Promise<PouchDB.Core.Response>;
|
|
118
|
-
getCourseInfo(): Promise<CourseInfo>;
|
|
119
|
-
getCourseDoc<T extends SkuilderCourseData$1>(id: string, options?: PouchDB.Core.GetOptions): Promise<T>;
|
|
120
|
-
getCourseDocs<T extends SkuilderCourseData$1>(ids: string[], options?: PouchDB.Core.AllDocsOptions): Promise<PouchDB.Core.AllDocsWithKeysResponse<{} & T>>;
|
|
121
|
-
/**
|
|
122
|
-
* Get cards sorted by ELO rating
|
|
123
|
-
*/
|
|
124
|
-
getCardsByELO(elo: number, limit?: number): Promise<{
|
|
125
|
-
courseID: string;
|
|
126
|
-
cardID: string;
|
|
127
|
-
elo?: number;
|
|
128
|
-
}[]>;
|
|
129
|
-
/**
|
|
130
|
-
* Get ELO data for specific cards
|
|
131
|
-
*/
|
|
132
|
-
getCardEloData(cardIds: string[]): Promise<CourseElo[]>;
|
|
133
|
-
/**
|
|
134
|
-
* Update card ELO rating
|
|
135
|
-
*/
|
|
136
|
-
updateCardElo(cardId: string, elo: CourseElo): Promise<PouchDB.Core.Response>;
|
|
137
|
-
/**
|
|
138
|
-
* Get cards centered at a particular ELO rating
|
|
139
|
-
*/
|
|
140
|
-
getCardsCenteredAtELO(options: {
|
|
141
|
-
limit: number;
|
|
142
|
-
elo: 'user' | 'random' | number;
|
|
143
|
-
}, filter?: (card: QualifiedCardID) => boolean): Promise<StudySessionItem[]>;
|
|
144
|
-
/**
|
|
145
|
-
* Get tags for a card
|
|
146
|
-
*/
|
|
147
|
-
getAppliedTags(cardId: string): Promise<PouchDB.Query.Response<TagStub>>;
|
|
148
|
-
/**
|
|
149
|
-
* Get tags for multiple cards in a single batch query.
|
|
150
|
-
* More efficient than calling getAppliedTags() for each card.
|
|
151
|
-
*
|
|
152
|
-
* This method reduces redundant database operations when multiple filters
|
|
153
|
-
* need tag data for the same cards. The Pipeline uses this to pre-hydrate
|
|
154
|
-
* tags on WeightedCard objects before filters run.
|
|
155
|
-
*
|
|
156
|
-
* @param cardIds - Array of card IDs to fetch tags for
|
|
157
|
-
* @returns Map from cardId to array of tag names
|
|
158
|
-
*/
|
|
159
|
-
getAppliedTagsBatch(cardIds: string[]): Promise<Map<string, string[]>>;
|
|
160
|
-
/**
|
|
161
|
-
* Get all card IDs in the course.
|
|
162
|
-
* Used by diagnostics to scan the full card space.
|
|
163
|
-
*/
|
|
164
|
-
getAllCardIds(): Promise<string[]>;
|
|
165
|
-
/**
|
|
166
|
-
* Add a tag to a card
|
|
167
|
-
*/
|
|
168
|
-
addTagToCard(cardId: string, tagId: string, updateELO?: boolean): Promise<PouchDB.Core.Response>;
|
|
169
|
-
/**
|
|
170
|
-
* Remove a tag from a card
|
|
171
|
-
*/
|
|
172
|
-
removeTagFromCard(cardId: string, tagId: string): Promise<PouchDB.Core.Response>;
|
|
173
|
-
/**
|
|
174
|
-
* Create a new tag
|
|
175
|
-
*/
|
|
176
|
-
createTag(tagName: string, author: string): Promise<PouchDB.Core.Response>;
|
|
177
|
-
/**
|
|
178
|
-
* Get a tag by name
|
|
179
|
-
*/
|
|
180
|
-
getTag(tagName: string): Promise<Tag>;
|
|
181
|
-
/**
|
|
182
|
-
* Update a tag
|
|
183
|
-
*/
|
|
184
|
-
updateTag(tag: Tag): Promise<PouchDB.Core.Response>;
|
|
185
|
-
/**
|
|
186
|
-
* Get all tag stubs for a course
|
|
187
|
-
*/
|
|
188
|
-
getCourseTagStubs(): Promise<PouchDB.Core.AllDocsResponse<Tag>>;
|
|
189
|
-
/**
|
|
190
|
-
* Add a note to the course
|
|
191
|
-
*/
|
|
192
|
-
addNote(codeCourse: string, shape: DataShape, data: unknown, author: string, tags: string[], uploads?: {
|
|
193
|
-
[key: string]: PouchDB.Core.FullAttachment;
|
|
194
|
-
}, elo?: CourseElo): Promise<DataLayerResult>;
|
|
195
|
-
removeCard(cardId: string): Promise<PouchDB.Core.Response>;
|
|
196
|
-
getInexperiencedCards(): Promise<{
|
|
197
|
-
courseId: string;
|
|
198
|
-
cardId: string;
|
|
199
|
-
count: number;
|
|
200
|
-
elo: CourseElo;
|
|
201
|
-
}[]>;
|
|
202
|
-
/**
|
|
203
|
-
* Search for cards by text content
|
|
204
|
-
* @param query Text to search for
|
|
205
|
-
* @returns Array of matching card data
|
|
206
|
-
*/
|
|
207
|
-
searchCards(query: string): Promise<any[]>;
|
|
208
|
-
/**
|
|
209
|
-
* Find documents using PouchDB query syntax
|
|
210
|
-
* @param request PouchDB find request
|
|
211
|
-
* @returns Query response
|
|
212
|
-
*/
|
|
213
|
-
find(request: PouchDB.Find.FindRequest<any>): Promise<PouchDB.Find.FindResponse<any>>;
|
|
214
|
-
}
|
|
215
|
-
|
|
216
|
-
interface SessionTrackingData {
|
|
217
|
-
peekSessionCount: number;
|
|
218
|
-
studySessionCount: number;
|
|
219
|
-
sessionCount: number;
|
|
220
|
-
firstSessionDate: string;
|
|
221
|
-
lastSessionDate: string;
|
|
222
|
-
signupPrompted: boolean;
|
|
223
|
-
promptDismissalCount: number;
|
|
224
|
-
studyModeAcknowledged: boolean;
|
|
225
|
-
}
|
|
226
|
-
interface UserConfig {
|
|
227
|
-
darkMode: boolean;
|
|
228
|
-
likesConfetti: boolean;
|
|
229
|
-
sessionTimeLimit: number;
|
|
230
|
-
/**
|
|
231
|
-
* @deprecated Retired in favour of the _users-doc email (the single source of
|
|
232
|
-
* truth, written by /auth/send-verification and read by /auth/status). No
|
|
233
|
-
* live code writes or reads this field; it may linger on older CONFIG docs.
|
|
234
|
-
*/
|
|
235
|
-
email?: string;
|
|
236
|
-
sessionTracking?: Record<string, SessionTrackingData>;
|
|
237
|
-
}
|
|
238
|
-
interface ActivityRecord {
|
|
239
|
-
timeStamp: number | string;
|
|
240
|
-
[key: string]: any;
|
|
241
|
-
}
|
|
242
|
-
interface CourseRegistration {
|
|
243
|
-
status?: 'active' | 'dropped' | 'maintenance-mode' | 'preview';
|
|
244
|
-
courseID: string;
|
|
245
|
-
admin: boolean;
|
|
246
|
-
moderator: boolean;
|
|
247
|
-
user: boolean;
|
|
248
|
-
settings?: {
|
|
249
|
-
[setting: string]: string | number | boolean;
|
|
250
|
-
};
|
|
251
|
-
elo: number | CourseElo;
|
|
252
|
-
}
|
|
253
|
-
interface StudyWeights {
|
|
254
|
-
[courseID: string]: number;
|
|
255
|
-
}
|
|
256
|
-
interface CourseRegistrationDoc {
|
|
257
|
-
courses: CourseRegistration[];
|
|
258
|
-
studyWeight: StudyWeights;
|
|
259
|
-
}
|
|
260
|
-
interface ScheduledCard {
|
|
261
|
-
_id: PouchDB.Core.DocumentId;
|
|
262
|
-
/**
|
|
263
|
-
* The docID of the card to be reviewed
|
|
264
|
-
*/
|
|
265
|
-
cardId: PouchDB.Core.DocumentId;
|
|
266
|
-
/**
|
|
267
|
-
* The ID of the course
|
|
268
|
-
*/
|
|
269
|
-
courseId: string;
|
|
270
|
-
/**
|
|
271
|
-
* The time at which the card becomes eligible for review.
|
|
272
|
-
*
|
|
273
|
-
* (Should probably be UTC adjusted so that performance is
|
|
274
|
-
* not wonky across time zones)
|
|
275
|
-
*
|
|
276
|
-
* Note: Stored as ISO string for PouchDB serialization compatibility,
|
|
277
|
-
* but can be consumed as Moment objects via moment.utc(reviewTime)
|
|
278
|
-
*/
|
|
279
|
-
reviewTime: string | Moment;
|
|
280
|
-
/**
|
|
281
|
-
* The time at which this scheduled event was created.
|
|
282
|
-
*
|
|
283
|
-
* Note: Stored as ISO string for PouchDB serialization compatibility,
|
|
284
|
-
* but can be consumed as Moment objects via moment.utc(scheduledAt)
|
|
285
|
-
*/
|
|
286
|
-
scheduledAt: string | Moment;
|
|
287
|
-
/**
|
|
288
|
-
* Classifying whether this card is scheduled on behalf of a
|
|
289
|
-
* user-registered course or by as assigned content from a
|
|
290
|
-
* user-registered classroom
|
|
291
|
-
*/
|
|
292
|
-
scheduledFor: 'course' | 'classroom';
|
|
293
|
-
/**
|
|
294
|
-
* The ID of the course or classroom that requested this card
|
|
295
|
-
*/
|
|
296
|
-
schedulingAgentId: string;
|
|
297
|
-
}
|
|
298
|
-
|
|
299
|
-
/**
|
|
300
|
-
* Record of a user's learning outcome over a specific period.
|
|
301
|
-
*
|
|
302
|
-
* Used by the evolutionary orchestration system to correlate strategy
|
|
303
|
-
* deviations with learning success.
|
|
304
|
-
*
|
|
305
|
-
* Stored in the UserDB.
|
|
306
|
-
*/
|
|
307
|
-
interface UserOutcomeRecord {
|
|
308
|
-
/**
|
|
309
|
-
* Unique ID: "USER_OUTCOME::{courseId}::{userId}::{timestamp}"
|
|
310
|
-
* Timestamp corresponds to periodEnd.
|
|
311
|
-
*/
|
|
312
|
-
_id: string;
|
|
313
|
-
docType: DocType.USER_OUTCOME;
|
|
314
|
-
courseId: string;
|
|
315
|
-
userId: string;
|
|
316
|
-
/** Start of the measurement period (ISO timestamp) */
|
|
317
|
-
periodStart: string;
|
|
318
|
-
/** End of the measurement period (ISO timestamp) */
|
|
319
|
-
periodEnd: string;
|
|
320
|
-
/**
|
|
321
|
-
* The computed signal value (e.g., 0.85 for 85% accuracy).
|
|
322
|
-
* This is the 'Y' in the regression analysis.
|
|
323
|
-
*
|
|
324
|
-
* Higher values indicate better learning outcomes.
|
|
325
|
-
*/
|
|
326
|
-
outcomeValue: number;
|
|
327
|
-
/**
|
|
328
|
-
* Snapshot of active deviations during this period.
|
|
329
|
-
* Maps strategyId -> deviation value used [-1.0, 1.0].
|
|
330
|
-
* This provides the 'X' values for regression analysis.
|
|
331
|
-
*/
|
|
332
|
-
deviations: Record<string, number>;
|
|
333
|
-
metadata: {
|
|
334
|
-
sessionsCount: number;
|
|
335
|
-
cardsSeen: number;
|
|
336
|
-
eloStart: number;
|
|
337
|
-
eloEnd: number;
|
|
338
|
-
/** The algorithm used to compute outcomeValue (e.g. "accuracy_in_zone") */
|
|
339
|
-
signalType: string;
|
|
340
|
-
};
|
|
341
|
-
}
|
|
342
|
-
|
|
343
|
-
/**
|
|
344
|
-
* Context for orchestration decisions during a session.
|
|
345
|
-
*
|
|
346
|
-
* Provides access to user/course data and helper methods for determining
|
|
347
|
-
* effective strategy weights based on the user's cohort assignment.
|
|
348
|
-
*/
|
|
349
|
-
interface OrchestrationContext {
|
|
350
|
-
user: UserDBInterface;
|
|
351
|
-
course: CourseDBInterface;
|
|
352
|
-
userId: string;
|
|
353
|
-
courseConfig: CourseConfig;
|
|
354
|
-
/**
|
|
355
|
-
* Calculate the effective weight for a strategy for this user.
|
|
356
|
-
*
|
|
357
|
-
* Applies deviation based on the user's cohort assignment (derived from
|
|
358
|
-
* userId, strategyId, and course salt).
|
|
359
|
-
*
|
|
360
|
-
* @param strategyId - Unique ID of the strategy
|
|
361
|
-
* @param learnable - The strategy's learning configuration
|
|
362
|
-
* @returns Effective weight multiplier (typically 0.1 - 3.0)
|
|
363
|
-
*/
|
|
364
|
-
getEffectiveWeight(strategyId: string, learnable: LearnableWeight): number;
|
|
365
|
-
/**
|
|
366
|
-
* Get the deviation factor for this user/strategy.
|
|
367
|
-
* Range [-1.0, 1.0].
|
|
368
|
-
*/
|
|
369
|
-
getDeviation(strategyId: string): number;
|
|
370
|
-
}
|
|
371
|
-
/**
|
|
372
|
-
* Compute a user's deviation for a specific strategy.
|
|
373
|
-
*
|
|
374
|
-
* Returns a value in [-1, 1] that is:
|
|
375
|
-
* 1. Deterministic for the same (user, strategy, salt) tuple
|
|
376
|
-
* 2. Uniformly distributed across users
|
|
377
|
-
* 3. Uncorrelated between different strategies (due to strategyId in hash)
|
|
378
|
-
* 4. Rotatable by changing the salt
|
|
379
|
-
*
|
|
380
|
-
* @param userId - ID of the user
|
|
381
|
-
* @param strategyId - ID of the strategy
|
|
382
|
-
* @param salt - Random seed from course config
|
|
383
|
-
* @returns Deviation factor between -1.0 and 1.0
|
|
384
|
-
*/
|
|
385
|
-
declare function computeDeviation(userId: string, strategyId: string, salt: string): number;
|
|
386
|
-
/**
|
|
387
|
-
* Compute the exploration spread based on confidence.
|
|
388
|
-
*
|
|
389
|
-
* - Low confidence (0.0) -> Max spread (Explore broadly)
|
|
390
|
-
* - High confidence (1.0) -> Min spread (Exploit known good weight)
|
|
391
|
-
*
|
|
392
|
-
* @param confidence - Confidence level 0-1
|
|
393
|
-
* @returns Spread magnitude (half-width of the distribution)
|
|
394
|
-
*/
|
|
395
|
-
declare function computeSpread(confidence: number): number;
|
|
396
|
-
/**
|
|
397
|
-
* Calculate the effective weight for a strategy instance.
|
|
398
|
-
*
|
|
399
|
-
* Combines the learnable weight (peak) with the user's deviation and the
|
|
400
|
-
* allowed spread (based on confidence).
|
|
401
|
-
*
|
|
402
|
-
* @param learnable - Strategy learning config
|
|
403
|
-
* @param userId - User ID
|
|
404
|
-
* @param strategyId - Strategy ID
|
|
405
|
-
* @param salt - Course salt
|
|
406
|
-
* @returns Effective weight multiplier
|
|
407
|
-
*/
|
|
408
|
-
declare function computeEffectiveWeight(learnable: LearnableWeight, userId: string, strategyId: string, salt: string): number;
|
|
409
|
-
/**
|
|
410
|
-
* Create an orchestration context for a study session.
|
|
411
|
-
*
|
|
412
|
-
* Fetches necessary configuration to enable deterministic weight calculation.
|
|
413
|
-
*
|
|
414
|
-
* @param user - User DB interface
|
|
415
|
-
* @param course - Course DB interface
|
|
416
|
-
* @returns Initialized orchestration context
|
|
417
|
-
*/
|
|
418
|
-
declare function createOrchestrationContext(user: UserDBInterface, course: CourseDBInterface): Promise<OrchestrationContext>;
|
|
419
|
-
|
|
420
|
-
/**
|
|
421
|
-
* A navigation pipeline that runs a generator and applies filters sequentially.
|
|
422
|
-
*
|
|
423
|
-
* Implements StudyContentSource for backward compatibility with SessionController.
|
|
424
|
-
*
|
|
425
|
-
* ## Usage
|
|
426
|
-
*
|
|
427
|
-
* ```typescript
|
|
428
|
-
* const pipeline = new Pipeline(
|
|
429
|
-
* compositeGenerator, // or single generator
|
|
430
|
-
* [eloDistanceFilter, interferenceFilter],
|
|
431
|
-
* user,
|
|
432
|
-
* course
|
|
433
|
-
* );
|
|
434
|
-
*
|
|
435
|
-
* const cards = await pipeline.getWeightedCards(20);
|
|
436
|
-
* ```
|
|
437
|
-
*/
|
|
438
|
-
/**
|
|
439
|
-
* Narrow capability surface for out-of-band, commit-free reads against a live
|
|
440
|
-
* pipeline (see {@link getActivePipeline}). Kept minimal on purpose — consumers
|
|
441
|
-
* get the forecast capability, not the whole `Pipeline` class.
|
|
442
|
-
*/
|
|
443
|
-
interface PipelineForecaster {
|
|
444
|
-
forecast(opts?: {
|
|
445
|
-
hints?: ReplanHints;
|
|
446
|
-
unseenOnly?: boolean;
|
|
447
|
-
threshold?: number;
|
|
448
|
-
limit?: number;
|
|
449
|
-
}): Promise<WeightedCard[]>;
|
|
450
|
-
}
|
|
451
|
-
/**
|
|
452
|
-
* Diagnosis of the full card space for the current user.
|
|
453
|
-
*/
|
|
454
|
-
interface CardSpaceDiagnosis {
|
|
455
|
-
totalCards: number;
|
|
456
|
-
threshold: number;
|
|
457
|
-
wellIndicated: number;
|
|
458
|
-
encountered: number;
|
|
459
|
-
wellIndicatedNew: number;
|
|
460
|
-
byType: Record<string, {
|
|
461
|
-
total: number;
|
|
462
|
-
wellIndicated: number;
|
|
463
|
-
new: number;
|
|
464
|
-
}>;
|
|
465
|
-
filterBreakdown: Array<{
|
|
466
|
-
name: string;
|
|
467
|
-
wellIndicated: number;
|
|
468
|
-
}>;
|
|
469
|
-
elapsedMs: number;
|
|
470
|
-
}
|
|
471
|
-
|
|
472
|
-
type RegulatorName = 'review-mass' | 'intake';
|
|
473
|
-
/** One regulator's reading for one pipeline run. Persisted on run summaries. */
|
|
474
|
-
interface RegulatorReading {
|
|
475
|
-
name: RegulatorName;
|
|
476
|
-
/** The class the multiplier applies to. */
|
|
477
|
-
class: 'review' | 'new';
|
|
478
|
-
/** The valve's urgency: review mass (card-equivalents) or intake hours. */
|
|
479
|
-
urgency: number;
|
|
480
|
-
multiplier: number;
|
|
481
|
-
/** Candidates the multiplier applied to. */
|
|
482
|
-
applied: number;
|
|
483
|
-
inputs: Record<string, number>;
|
|
484
|
-
}
|
|
485
|
-
interface RegulatorConfig {
|
|
486
|
-
reviewMass: {
|
|
487
|
-
/**
|
|
488
|
-
* Unit of mass for reviews without an SRS urgency (from another
|
|
489
|
-
* generator): a filtered score this high weighs 1.
|
|
490
|
-
*/
|
|
491
|
-
referenceScore: number;
|
|
492
|
-
/** Mass (card-equivalents) at or below which there's no pressure. */
|
|
493
|
-
healthyMass: number;
|
|
494
|
-
/** Multiplier growth per multiple of `healthyMass` in excess. */
|
|
495
|
-
rate: number;
|
|
496
|
-
};
|
|
497
|
-
intake: {
|
|
498
|
-
/** Multiplier growth per `scaleHours` without a new card. */
|
|
499
|
-
rate: number;
|
|
500
|
-
scaleHours: number;
|
|
501
|
-
};
|
|
502
|
-
}
|
|
503
|
-
/**
|
|
504
|
-
* Defaults. Review mass keeps the SRS generator's former healthy threshold and
|
|
505
|
-
* growth rate (20, ×2), now applied to mass instead of count. Intake doubles
|
|
506
|
-
* per day of servable time without a new card.
|
|
507
|
-
*/
|
|
508
|
-
declare const DEFAULT_REGULATOR_CONFIG: RegulatorConfig;
|
|
509
|
-
/**
|
|
510
|
-
* One due review's weight in the mass, in [0, 1]: its SRS urgency times the
|
|
511
|
-
* filters' net effect on it (filtered score ÷ the score it was generated
|
|
512
|
-
* with), so every course signal discounts it. A review without an urgency
|
|
513
|
-
* weighs its filtered score against the reference.
|
|
514
|
-
*/
|
|
515
|
-
declare function reviewWeight(card: WeightedCard, generatedScore: number | undefined, referenceScore: number): number;
|
|
516
|
-
/**
|
|
517
|
-
* @param reviews - Due reviews, after filters
|
|
518
|
-
* @param generatedScores - Each card's score as generated, before filters
|
|
519
|
-
*/
|
|
520
|
-
declare function reviewMassReading(reviews: WeightedCard[], generatedScores: ReadonlyMap<string, number>, config?: RegulatorConfig['reviewMass']): RegulatorReading;
|
|
521
|
-
/** The intake valve's clock, persisted per user and course (strategy state). */
|
|
522
|
-
interface IntakeClockState {
|
|
523
|
-
/** When a new card was last presented (ISO). */
|
|
524
|
-
lastNewAt: string;
|
|
525
|
-
/** Closed stretches since then during which no eligible new card existed (ms). */
|
|
526
|
-
frozenMs: number;
|
|
527
|
-
/** Start of the current stretch with no eligible new card (ISO), or null. */
|
|
528
|
-
unservableSince: string | null;
|
|
529
|
-
}
|
|
530
|
-
/** Strategy-state key for the intake clock. */
|
|
531
|
-
declare const INTAKE_CLOCK_KEY = "IntakeClock";
|
|
532
|
-
/** A fresh clock: a new card was just presented (or the clock is starting). */
|
|
533
|
-
declare function resetIntakeClock(nowMs: number): IntakeClockState;
|
|
534
|
-
/** Frozen time so far, including an open unservable stretch. */
|
|
535
|
-
declare function frozenMsAt(state: IntakeClockState, nowMs: number): number;
|
|
536
|
-
/** Servable hours since a new card was last presented. */
|
|
537
|
-
declare function intakeHours(state: IntakeClockState, nowMs: number): number;
|
|
538
|
-
/**
|
|
539
|
-
* Advance the clock's freeze bookkeeping for a run that found `eligibleNew`
|
|
540
|
-
* eligible new candidates. The clock freezes while there are none (exhaustion
|
|
541
|
-
* isn't starvation) and resumes when some appear. Returns the same object when
|
|
542
|
-
* nothing changed, so callers persist only on transitions.
|
|
543
|
-
*/
|
|
544
|
-
declare function stepIntakeClock(state: IntakeClockState, nowMs: number, eligibleNew: number): IntakeClockState;
|
|
545
|
-
declare function intakeReading(state: IntakeClockState, nowMs: number, counts: {
|
|
546
|
-
eligibleNew: number;
|
|
547
|
-
newCandidates: number;
|
|
548
|
-
}, config?: RegulatorConfig['intake']): RegulatorReading;
|
|
549
|
-
/** Multiply `cards` (in place) by a reading's multiplier, with a provenance entry when it changes them. */
|
|
550
|
-
declare function applyReading(cards: WeightedCard[], reading: RegulatorReading): void;
|
|
551
|
-
|
|
552
|
-
/**
|
|
553
|
-
* The most recently constructed pipeline for the current session, or null if
|
|
554
|
-
* none has been built yet. This is the supported, non-debug accessor for
|
|
555
|
-
* out-of-band reads against the live pipeline (e.g. a commit-free
|
|
556
|
-
* `forecast()`), replacing reach-ins through `window.skuilder.pipeline`.
|
|
557
|
-
*/
|
|
558
|
-
declare function getActivePipeline(): PipelineForecaster | null;
|
|
559
|
-
/**
|
|
560
|
-
* Summary of a single generator's contribution.
|
|
561
|
-
*/
|
|
562
|
-
interface GeneratorSummary {
|
|
563
|
-
name: string;
|
|
564
|
-
cardCount: number;
|
|
565
|
-
newCount: number;
|
|
566
|
-
reviewCount: number;
|
|
567
|
-
topScore: number;
|
|
568
|
-
}
|
|
569
|
-
/**
|
|
570
|
-
* Summary of a filter's impact on scores.
|
|
571
|
-
*/
|
|
572
|
-
interface FilterImpact {
|
|
573
|
-
name: string;
|
|
574
|
-
/** Effective kind: undeclared filters count as gates. Absent on runs before 0.2.29. */
|
|
575
|
-
kind?: FilterKind;
|
|
576
|
-
boosted: number;
|
|
577
|
-
penalized: number;
|
|
578
|
-
passed: number;
|
|
579
|
-
removed: number;
|
|
580
|
-
}
|
|
581
|
-
/** A run's version stamps. Either may be absent: no strategy hash, or no content version set. */
|
|
582
|
-
interface RunVersions {
|
|
583
|
-
strategies?: string;
|
|
584
|
-
content?: string;
|
|
585
|
-
}
|
|
586
|
-
/** One card as retained in a {@link PipelineRunReport}. */
|
|
587
|
-
interface RunReportCard {
|
|
588
|
-
cardId: string;
|
|
589
|
-
courseId: string;
|
|
590
|
-
/** `'review'`: a scheduled review. `'new'`: anything else. */
|
|
591
|
-
origin: 'new' | 'review';
|
|
592
|
-
/** The strategy that produced the card (first provenance entry). Absent if a hint injected it. */
|
|
593
|
-
generator?: string;
|
|
594
|
-
/** The hint that made the card mandatory, if one did. Its source, over `generator`. */
|
|
595
|
-
required?: string;
|
|
596
|
-
finalScore: number;
|
|
597
|
-
/** Card's ELO (parsed from ELO generator provenance, if available) */
|
|
598
|
-
cardElo?: number;
|
|
599
|
-
provenance: StrategyContribution[];
|
|
600
|
-
tags?: string[];
|
|
601
|
-
selected: boolean;
|
|
602
|
-
}
|
|
603
|
-
/**
|
|
604
|
-
* Complete record of a single pipeline execution.
|
|
605
|
-
*/
|
|
606
|
-
interface PipelineRunReport {
|
|
607
|
-
runId: string;
|
|
608
|
-
/** Absent for runs fired outside a session (forecasts, editor probes). */
|
|
609
|
-
sessionId?: string;
|
|
610
|
-
timestamp: Date;
|
|
611
|
-
courseId: string;
|
|
612
|
-
courseName?: string;
|
|
613
|
-
/** User's global ELO at the time of this pipeline run */
|
|
614
|
-
userElo?: number;
|
|
615
|
-
generatorName: string;
|
|
616
|
-
generators?: GeneratorSummary[];
|
|
617
|
-
generatedCount: number;
|
|
618
|
-
filters: FilterImpact[];
|
|
619
|
-
/** Ephemeral hints applied during this run */
|
|
620
|
-
hints?: ReplanHints;
|
|
621
|
-
finalCount: number;
|
|
622
|
-
reviewsSelected: number;
|
|
623
|
-
newSelected: number;
|
|
624
|
-
/**
|
|
625
|
-
* Card data for inspection.
|
|
626
|
-
*
|
|
627
|
-
* To keep the in-memory ring buffer small, this contains:
|
|
628
|
-
* - All selected cards (the actual session output).
|
|
629
|
-
* - The top-N highest-scoring non-selected cards (see DISCARDED_KEEP_TOP),
|
|
630
|
-
* useful for understanding "near misses" and filter behavior.
|
|
631
|
-
*
|
|
632
|
-
* The remaining low-score tail of the candidate pool (mostly ELO-window
|
|
633
|
-
* pull remnants that filters scored down) is summarized in `discardedTail`
|
|
634
|
-
* rather than retained verbatim — each retained card carries a multi-KB
|
|
635
|
-
* provenance trail, and the tail is typically hundreds of cards per run.
|
|
636
|
-
*/
|
|
637
|
-
cards: RunReportCard[];
|
|
638
|
-
/**
|
|
639
|
-
* The two unselected non-review cards most worth explaining when a run
|
|
640
|
-
* picks no new content. Non-review means no `reviewID`, so prescribed and
|
|
641
|
-
* required cards count.
|
|
642
|
-
*
|
|
643
|
-
* - `nextInLine`: highest final score. How close new content came.
|
|
644
|
-
* - `topGenerated`: highest generator score, zero-scored cards included.
|
|
645
|
-
* Its provenance shows which filter sank it. Omitted when it is the same
|
|
646
|
-
* card as `nextInLine`.
|
|
647
|
-
*/
|
|
648
|
-
unselectedNew?: {
|
|
649
|
-
nextInLine?: RunReportCard;
|
|
650
|
-
topGenerated?: RunReportCard;
|
|
651
|
-
};
|
|
652
|
-
/** The regulator stage's readings: each class's pressure and the multiplier it got. */
|
|
653
|
-
regulators?: RegulatorReading[];
|
|
654
|
-
/**
|
|
655
|
-
* What this run ran on (see versionStamps.ts): the hash of the strategy docs
|
|
656
|
-
* the pipeline was assembled from, and the course's content version.
|
|
657
|
-
*/
|
|
658
|
-
versions?: RunVersions;
|
|
659
|
-
/**
|
|
660
|
-
* Summary of the discarded tail of the candidate pool — cards that were
|
|
661
|
-
* generated and scored but neither selected nor retained in `cards`.
|
|
662
|
-
*
|
|
663
|
-
* Provides breadcrumbs for "where did card X go?" investigations without
|
|
664
|
-
* the memory cost of keeping every dropped candidate's provenance.
|
|
665
|
-
*
|
|
666
|
-
* Future: may carry a bloom filter of discarded cardIds so callers can
|
|
667
|
-
* ask "was X in this run's discard tail?" with bounded memory cost.
|
|
668
|
-
*/
|
|
669
|
-
discardedTail?: {
|
|
670
|
-
count: number;
|
|
671
|
-
/** [min, max] finalScore across the discarded tail. */
|
|
672
|
-
scoreRange?: [number, number];
|
|
673
|
-
/** [min, max] cardElo across the discarded tail (where parseable). */
|
|
674
|
-
eloRange?: [number, number];
|
|
675
|
-
/** Human-readable note for console display. */
|
|
676
|
-
note: string;
|
|
677
|
-
};
|
|
678
|
-
}
|
|
679
|
-
declare function setDebugSessionId(sessionId: string | undefined): void;
|
|
680
|
-
/** Take and clear the runs captured since the previous call, in execution order. */
|
|
681
|
-
declare function drainCapturedRuns(): PipelineRunReport[];
|
|
682
|
-
/**
|
|
683
|
-
* Runs for `sessionId`, oldest first. Bounded by {@link MAX_RUNS} — the
|
|
684
|
-
* complete record is `StudySessionDoc.runs`.
|
|
685
|
-
*/
|
|
686
|
-
declare function getRunsForSession(sessionId: string): PipelineRunReport[];
|
|
687
|
-
/**
|
|
688
|
-
* Console API object exposed on window.skuilder.pipeline
|
|
689
|
-
*/
|
|
690
|
-
declare const pipelineDebugAPI: {
|
|
691
|
-
/**
|
|
692
|
-
* Get raw run history for programmatic access.
|
|
693
|
-
*/
|
|
694
|
-
readonly runs: PipelineRunReport[];
|
|
695
|
-
/**
|
|
696
|
-
* Show summary of a specific pipeline run.
|
|
697
|
-
*/
|
|
698
|
-
showRun(idOrIndex?: string | number): void;
|
|
699
|
-
/**
|
|
700
|
-
* Show summary of the last pipeline run.
|
|
701
|
-
*/
|
|
702
|
-
showLastRun(): void;
|
|
703
|
-
/**
|
|
704
|
-
* Show detailed provenance for a specific card.
|
|
705
|
-
*/
|
|
706
|
-
showCard(cardId: string): void;
|
|
707
|
-
/**
|
|
708
|
-
* Explain why reviews may or may not have been selected.
|
|
709
|
-
*/
|
|
710
|
-
explainReviews(): void;
|
|
711
|
-
/**
|
|
712
|
-
* Show prescribed-related cards from the most recent run.
|
|
713
|
-
*
|
|
714
|
-
* Highlights:
|
|
715
|
-
* - cards directly generated by the prescribed strategy
|
|
716
|
-
* - blocked prescribed targets mentioned in provenance
|
|
717
|
-
* - support tags resolved for blocked targets
|
|
718
|
-
*
|
|
719
|
-
* @param groupId - Optional prescribed group ID filter (e.g. 'intro-core')
|
|
720
|
-
*/
|
|
721
|
-
showPrescribed(groupId?: string): void;
|
|
722
|
-
/**
|
|
723
|
-
* Show all runs in compact format.
|
|
724
|
-
*/
|
|
725
|
-
listRuns(): void;
|
|
726
|
-
/**
|
|
727
|
-
* Export run history as JSON for bug reports.
|
|
728
|
-
*/
|
|
729
|
-
export(): string;
|
|
730
|
-
/**
|
|
731
|
-
* Clear run history.
|
|
732
|
-
*/
|
|
733
|
-
clear(): void;
|
|
734
|
-
/**
|
|
735
|
-
* Show the navigator registry: all registered classes and their roles.
|
|
736
|
-
*
|
|
737
|
-
* Useful for verifying that consumer-defined navigators were registered
|
|
738
|
-
* before pipeline assembly.
|
|
739
|
-
*/
|
|
740
|
-
showRegistry(): void;
|
|
741
|
-
/**
|
|
742
|
-
* Show strategy documents from the last pipeline run and how they mapped
|
|
743
|
-
* to the registry.
|
|
744
|
-
*
|
|
745
|
-
* If no runs are captured yet, falls back to showing just the registry.
|
|
746
|
-
*/
|
|
747
|
-
showStrategies(): void;
|
|
748
|
-
/**
|
|
749
|
-
* Scan the full card space through the filter chain for the current user.
|
|
750
|
-
*
|
|
751
|
-
* Reports how many cards are well-indicated and how many are new.
|
|
752
|
-
* Use this to understand how the search space grows during onboarding.
|
|
753
|
-
*
|
|
754
|
-
* @param threshold - Score threshold for "well indicated" (default 0.10)
|
|
755
|
-
*/
|
|
756
|
-
diagnoseCardSpace(threshold?: number): Promise<CardSpaceDiagnosis | null>;
|
|
757
|
-
/**
|
|
758
|
-
* Show user's per-tag ELO data. Useful for diagnosing hierarchy gate status.
|
|
759
|
-
*
|
|
760
|
-
* @param tagFilter - Optional glob pattern(s) to filter tags.
|
|
761
|
-
* Examples: 'gpc:expose:*', 'gpc:intro:t-T', ['gpc:expose:t-*', 'gpc:intro:t-*']
|
|
762
|
-
*/
|
|
763
|
-
showTagElo(tagFilter?: string | string[]): Promise<void>;
|
|
764
|
-
/**
|
|
765
|
-
* Toggle the full-screen UI debugger.
|
|
766
|
-
*/
|
|
767
|
-
ui(): void;
|
|
768
|
-
/**
|
|
769
|
-
* Internal UI helpers
|
|
770
|
-
* @internal
|
|
771
|
-
*/
|
|
772
|
-
_selectRun(index: number): void;
|
|
773
|
-
/**
|
|
774
|
-
* Internal UI helpers
|
|
775
|
-
* @internal
|
|
776
|
-
*/
|
|
777
|
-
_setSearch(query: string): void;
|
|
778
|
-
/**
|
|
779
|
-
* Internal UI helpers
|
|
780
|
-
* @internal
|
|
781
|
-
*/
|
|
782
|
-
_copyConfig(runId: string, btn?: HTMLElement): void;
|
|
783
|
-
/**
|
|
784
|
-
* Internal UI helpers
|
|
785
|
-
* @internal
|
|
786
|
-
*
|
|
787
|
-
* Copies an "abridged" view of results: just the selected cards with their
|
|
788
|
-
* generator, origin, final score, and the top provenance reason. Designed
|
|
789
|
-
* for pasting into bug reports without flooding with full provenance.
|
|
790
|
-
*/
|
|
791
|
-
_copyResults(runId: string, btn?: HTMLElement): void;
|
|
792
|
-
/**
|
|
793
|
-
* Show help.
|
|
794
|
-
*/
|
|
795
|
-
help(): void;
|
|
796
|
-
};
|
|
797
|
-
/**
|
|
798
|
-
* Mount the debug API on window.skuilder.pipeline
|
|
799
|
-
*/
|
|
800
|
-
declare function mountPipelineDebugger(): void;
|
|
801
|
-
|
|
802
|
-
/**
|
|
803
|
-
* Durable per-sitting record. Join target for `CardRecord.sessionId`.
|
|
804
|
-
*
|
|
805
|
-
* Written twice: `open` at `prepareSession()`, overwritten at termination.
|
|
806
|
-
*/
|
|
807
|
-
interface StudySessionDoc {
|
|
808
|
-
/** `SESSION::{courseId}::{userId}::{sessionId}` */
|
|
809
|
-
_id: string;
|
|
810
|
-
_rev?: string;
|
|
811
|
-
docType: DocType.STUDY_SESSION;
|
|
812
|
-
sessionId: string;
|
|
813
|
-
courseId: string;
|
|
814
|
-
userId: string;
|
|
815
|
-
/** Session construction time, not first-card time. */
|
|
816
|
-
startTime: string;
|
|
817
|
-
endTime?: string;
|
|
818
|
-
/**
|
|
819
|
-
* `closed` — ran to natural termination.
|
|
820
|
-
* `abandoned` — host tore the study view down mid-session.
|
|
821
|
-
* `open` — never closed: tab closed, reload, crash. No tally or end state.
|
|
822
|
-
*/
|
|
823
|
-
status: 'open' | 'closed' | 'abandoned';
|
|
824
|
-
plannedSeconds: number;
|
|
825
|
-
config: {
|
|
826
|
-
defaultBatchLimit: number;
|
|
827
|
-
sourceCount: number;
|
|
828
|
-
initHints?: ReplanHints | null;
|
|
829
|
-
};
|
|
830
|
-
/**
|
|
831
|
-
* The code this session ran on: the framework's version (`'dev'` when run
|
|
832
|
-
* from source) and the host app's, if it reported one (`appVersion` in the
|
|
833
|
-
* data-layer config). Strategy and content versions are stamped per run.
|
|
834
|
-
* Absent on sessions recorded before this shipped.
|
|
835
|
-
*/
|
|
836
|
-
versions?: {
|
|
837
|
-
framework: string;
|
|
838
|
-
app?: string;
|
|
839
|
-
};
|
|
840
|
-
/** Queue depths after the bootstrap run, before the first draw. */
|
|
841
|
-
initialQueues: {
|
|
842
|
-
supplyQ: number;
|
|
843
|
-
failedQ: number;
|
|
844
|
-
};
|
|
845
|
-
tally?: {
|
|
846
|
-
/** Distinct cards; a re-presented failed card counts once. */
|
|
847
|
-
cardsPresented: number;
|
|
848
|
-
/** Total responses, including repeat attempts on one card. */
|
|
849
|
-
responses: number;
|
|
850
|
-
correct: number;
|
|
851
|
-
incorrect: number;
|
|
852
|
-
failedQRemaining: number;
|
|
853
|
-
secondsRemaining: number;
|
|
854
|
-
};
|
|
855
|
-
/** Bootstrap run plus every replan, in execution order. */
|
|
856
|
-
runs?: StudySessionRunSummary[];
|
|
857
|
-
/**
|
|
858
|
-
* Per-response ELO exchanges, in the order they resolved. One entry per
|
|
859
|
-
* ELO-updating response (first attempt of a presentation; retries don't
|
|
860
|
-
* move ELO). Flushed at close from an in-memory log — so `open`/`abandoned`
|
|
861
|
-
* sessions that never reached the close write carry none, and a same-card
|
|
862
|
-
* event still in flight at close may be missing. Absent on sessions
|
|
863
|
-
* recorded before this shipped.
|
|
864
|
-
*/
|
|
865
|
-
eloEvents?: SessionEloEvent[];
|
|
866
|
-
finalHints?: ReplanHints | null;
|
|
867
|
-
stateAtStart?: SessionStateSnapshot;
|
|
868
|
-
stateAtEnd?: SessionStateSnapshot;
|
|
869
|
-
}
|
|
870
|
-
interface StudySessionRunSummary {
|
|
871
|
-
/** Joins to `PipelineRunReport.runId` while that run is still in memory. */
|
|
872
|
-
runId: string;
|
|
873
|
-
at: string;
|
|
874
|
-
/** `'bootstrap'`, a replan's label, or `'(auto)'`. */
|
|
875
|
-
label: string;
|
|
876
|
-
mode?: string;
|
|
877
|
-
generatedCount: number;
|
|
878
|
-
finalCount: number;
|
|
879
|
-
reviewsSelected: number;
|
|
880
|
-
newSelected: number;
|
|
881
|
-
/** User's global ELO at the moment this run's pipeline executed. */
|
|
882
|
-
userElo?: number;
|
|
883
|
-
/** Per-generator contribution (name, card/new/review counts, top score). */
|
|
884
|
-
generators?: GeneratorSummary[];
|
|
885
|
-
/** Per-filter impact (boosted / penalized / passed / removed). */
|
|
886
|
-
filters?: FilterImpact[];
|
|
887
|
-
/** Ephemeral replan hints in force for this run (what the navigator was told). */
|
|
888
|
-
hints?: ReplanHints;
|
|
889
|
-
/** Compact summary of the scored-but-dropped candidate tail. */
|
|
890
|
-
discardedTail?: {
|
|
891
|
-
count: number;
|
|
892
|
-
scoreRange?: [number, number];
|
|
893
|
-
eloRange?: [number, number];
|
|
894
|
-
note: string;
|
|
895
|
-
};
|
|
896
|
-
/**
|
|
897
|
-
* The selected cards, then the top few unselected ones, each in score
|
|
898
|
-
* order. The lowest selected score against the first runner-up is this
|
|
899
|
-
* run's cutoff.
|
|
900
|
-
*/
|
|
901
|
-
cards?: StudySessionRunCard[];
|
|
902
|
-
/**
|
|
903
|
-
* The unselected non-review cards most worth explaining, with their
|
|
904
|
-
* score-changing provenance. See `PipelineRunReport.unselectedNew`.
|
|
905
|
-
*/
|
|
906
|
-
unselectedNew?: {
|
|
907
|
-
nextInLine?: StudySessionRunCardTrail;
|
|
908
|
-
topGenerated?: StudySessionRunCardTrail;
|
|
909
|
-
};
|
|
910
|
-
/** The regulator stage's readings: review mass and intake, each with its multiplier (0.2.29+). */
|
|
911
|
-
regulators?: RegulatorReading[];
|
|
912
|
-
/** What the run ran on: the strategy docs' hash and the course's content version. */
|
|
913
|
-
versions?: RunVersions;
|
|
914
|
-
}
|
|
915
|
-
/** A card as persisted on a run. `origin` is as counted in `newSelected`/`reviewsSelected`. */
|
|
916
|
-
interface StudySessionRunCard {
|
|
917
|
-
cardId: string;
|
|
918
|
-
/**
|
|
919
|
-
* `'review'`: a scheduled review. `'new'`: anything else. `'unknown'` only on
|
|
920
|
-
* older runs, which counted prescribed and hint-required cards as neither.
|
|
921
|
-
*/
|
|
922
|
-
origin: 'new' | 'review' | 'unknown';
|
|
923
|
-
/**
|
|
924
|
-
* The strategy that produced the card. Absent if a hint injected it (older
|
|
925
|
-
* runs name the hint here instead).
|
|
926
|
-
*/
|
|
927
|
-
generator?: string;
|
|
928
|
-
/** The hint that made the card mandatory, if one did. Its source, over `generator`. */
|
|
929
|
-
required?: string;
|
|
930
|
-
/** Final score; null for a mandatory (required) card, whose score is infinite. */
|
|
931
|
-
score: number | null;
|
|
932
|
-
selected: boolean;
|
|
933
|
-
}
|
|
934
|
-
/**
|
|
935
|
-
* A card plus the provenance entries that changed its score, in order.
|
|
936
|
-
* `'passed'` entries are dropped. Strategy ids are dropped (the name is kept).
|
|
937
|
-
*/
|
|
938
|
-
interface StudySessionRunCardTrail extends StudySessionRunCard {
|
|
939
|
-
trail: Array<{
|
|
940
|
-
strategyName: string;
|
|
941
|
-
action: StrategyContribution['action'];
|
|
942
|
-
score: number;
|
|
943
|
-
reason: string;
|
|
944
|
-
}>;
|
|
945
|
-
}
|
|
946
|
-
/**
|
|
947
|
-
* One learner↔card ELO exchange, captured at the moment it resolved so a
|
|
948
|
-
* session can be read as an ELO ledger (why did 88% accuracy net -1?). The
|
|
949
|
-
* exchange is otherwise write-once-and-discard: only the updated aggregates
|
|
950
|
-
* survive on the user/card docs, and ELO is path-dependent, so a response's
|
|
951
|
-
* move can't be reconstructed after the fact. Joins to a `CardRecord` by
|
|
952
|
-
* `cardId` + nearest `at`.
|
|
953
|
-
*/
|
|
954
|
-
interface SessionEloEvent {
|
|
955
|
-
/** Card this exchange was for. */
|
|
956
|
-
cardId: string;
|
|
957
|
-
/** ISO time the exchange resolved (fires just after the response record). */
|
|
958
|
-
at: string;
|
|
959
|
-
/**
|
|
960
|
-
* Global performance in [0,1] that drove the update. Note this is the ELO
|
|
961
|
-
* `userScore`, not raw correctness: the numeric path maps a correct answer
|
|
962
|
-
* to `0.5 + performance/2` (so a plain correct is 1.0, a graded-correct
|
|
963
|
-
* less) and a miss to 0; the tagged path uses `_global`.
|
|
964
|
-
*/
|
|
965
|
-
userScore: number;
|
|
966
|
-
/** Learner global ELO before → after this response. */
|
|
967
|
-
global: {
|
|
968
|
-
before: number;
|
|
969
|
-
after: number;
|
|
970
|
-
};
|
|
971
|
-
/** Card global ELO before → after (absent if the card ELO was unreadable). */
|
|
972
|
-
card?: {
|
|
973
|
-
before: number;
|
|
974
|
-
after: number;
|
|
975
|
-
};
|
|
976
|
-
/**
|
|
977
|
-
* Per-tag learner ELO before → after, for every tag the exchange touched.
|
|
978
|
-
* `score` is the per-tag performance applied, or null for a count-only
|
|
979
|
-
* exposure tag (`gpc:expose:*`) that increments count without moving ELO.
|
|
980
|
-
*/
|
|
981
|
-
tags?: Record<string, {
|
|
982
|
-
before: number;
|
|
983
|
-
after: number;
|
|
984
|
-
score: number | null;
|
|
985
|
-
}>;
|
|
986
|
-
}
|
|
987
|
-
/**
|
|
988
|
-
* Host-defined learner state at a session boundary. Keep it thin — this is
|
|
989
|
-
* written on every session, and the deltas between consecutive snapshots are
|
|
990
|
-
* what it's read for.
|
|
991
|
-
*/
|
|
992
|
-
type SessionStateSnapshot = Record<string, unknown>;
|
|
993
|
-
/**
|
|
994
|
-
* Invoked at session open and close. Errors and slow calls are absorbed by
|
|
995
|
-
* the controller.
|
|
996
|
-
*/
|
|
997
|
-
type SessionStateSnapshotProvider = (phase: 'start' | 'end') => SessionStateSnapshot | Promise<SessionStateSnapshot>;
|
|
998
|
-
/** Stable across the open and close writes, unlike a timestamp-keyed id. */
|
|
999
|
-
declare function makeStudySessionId(courseId: string, userId: string, sessionId: string): string;
|
|
1000
|
-
declare function newSessionId(): string;
|
|
1001
|
-
|
|
1002
|
-
/**
|
|
1003
|
-
* User database hydration.
|
|
1004
|
-
*
|
|
1005
|
-
* A logged-in user's data lives in a remote CouchDB `userdb-<hex>` and is
|
|
1006
|
-
* mirrored into a browser-local PouchDB. On a device that has never synced
|
|
1007
|
-
* that account, the local mirror starts EMPTY — and every local read
|
|
1008
|
-
* (`getStrategyState`, `getConfig`, `getCourseRegistrationsDoc`, ...) answers
|
|
1009
|
-
* "no such document", which is indistinguishable from "brand new user".
|
|
1010
|
-
*
|
|
1011
|
-
* Consumers acting on that answer render a new-user experience to an existing
|
|
1012
|
-
* user, and — worse — compute writes from empty state that then lose to the
|
|
1013
|
-
* real remote document at replication time. Hydration closes that window by
|
|
1014
|
-
* pulling the account's documents down BEFORE the user object is handed out.
|
|
1015
|
-
*/
|
|
1016
|
-
/**
|
|
1017
|
-
* Where a user's local database stands relative to its remote counterpart.
|
|
1018
|
-
*
|
|
1019
|
-
* Only `failed` is a blocking condition. `stale` explicitly is not: it means a
|
|
1020
|
-
* full pull completed on this device previously, so local data is real and
|
|
1021
|
-
* merely possibly-behind — live sync closes the gap in the background. That is
|
|
1022
|
-
* the ordinary offline case and it must keep working.
|
|
1023
|
-
*/
|
|
1024
|
-
type UserHydrationState =
|
|
1025
|
-
/** Guest, or a data layer with no remote. There is nothing to hydrate from. */
|
|
1026
|
-
'not-required'
|
|
1027
|
-
/** Initial pull in flight. */
|
|
1028
|
-
| 'hydrating'
|
|
1029
|
-
/** Initial pull completed this session. Local is a faithful mirror. */
|
|
1030
|
-
| 'hydrated'
|
|
1031
|
-
/**
|
|
1032
|
-
* A previous session completed a full pull on this device (recorded by the
|
|
1033
|
-
* `_local/hydration` marker). Local data is real; live sync is catching up.
|
|
1034
|
-
*/
|
|
1035
|
-
| 'stale'
|
|
1036
|
-
/**
|
|
1037
|
-
* No pull has ever completed on this device and one could not be completed
|
|
1038
|
-
* now. Local reads CANNOT be trusted to mean "no data" — callers must not
|
|
1039
|
-
* present a new-user experience or compute writes from what they read.
|
|
1040
|
-
*/
|
|
1041
|
-
| 'failed';
|
|
1042
|
-
/**
|
|
1043
|
-
* Hydration state plus observability detail.
|
|
1044
|
-
*
|
|
1045
|
-
* Shaped to mirror `CourseSyncStatus` in CourseSyncService, which solves the
|
|
1046
|
-
* same problem for course databases.
|
|
1047
|
-
*/
|
|
1048
|
-
interface UserHydrationStatus {
|
|
1049
|
-
state: UserHydrationState;
|
|
1050
|
-
/** Documents pulled by the initial replication (set when state is `hydrated`). */
|
|
1051
|
-
docsWritten?: number;
|
|
1052
|
-
/** Wall-clock duration of the initial pull attempt, successful or not. */
|
|
1053
|
-
durationMs?: number;
|
|
1054
|
-
/** Failure detail, set when state is `failed`. */
|
|
1055
|
-
error?: string;
|
|
1056
|
-
}
|
|
1057
|
-
/**
|
|
1058
|
-
* ID of the per-device marker recording that a full pull once completed.
|
|
1059
|
-
*
|
|
1060
|
-
* `_local/*` documents are deliberately excluded from replication by CouchDB
|
|
1061
|
-
* and PouchDB alike, which is exactly the semantics wanted here: the marker
|
|
1062
|
-
* describes THIS device's mirror, and must never travel to another one.
|
|
1063
|
-
*/
|
|
1064
|
-
declare const HYDRATION_MARKER_ID = "_local/hydration";
|
|
1065
|
-
/**
|
|
1066
|
-
* Payload of {@link HYDRATION_MARKER_ID}.
|
|
1067
|
-
*/
|
|
1068
|
-
interface HydrationMarker {
|
|
1069
|
-
_id: typeof HYDRATION_MARKER_ID;
|
|
1070
|
-
_rev?: string;
|
|
1071
|
-
/** Account the mirror was hydrated for — guards against a stale marker after an account switch. */
|
|
1072
|
-
username: string;
|
|
1073
|
-
/** ISO timestamp of the most recent successful full pull. */
|
|
1074
|
-
hydratedAt: string;
|
|
1075
|
-
}
|
|
1076
|
-
|
|
1077
|
-
type Update<T> = Partial<T> | ((x: T) => T);
|
|
1078
|
-
|
|
1079
|
-
interface DocumentUpdater {
|
|
1080
|
-
update<T extends PouchDB.Core.Document<object>>(id: string, update: Update<T>): Promise<T>;
|
|
1081
|
-
}
|
|
1082
|
-
/**
|
|
1083
|
-
* Returns the minimum number of seconds that should pass before a
|
|
1084
|
-
* card is redisplayed for review / practice.
|
|
1085
|
-
*
|
|
1086
|
-
* @param cardHistory The user's history working with the given card
|
|
1087
|
-
*/
|
|
1088
|
-
declare function newInterval(user: DocumentUpdater, cardHistory: CardHistory<CardRecord>): number;
|
|
1089
|
-
/**
|
|
1090
|
-
* Number of trailing consecutive correct records (retries within a single
|
|
1091
|
-
* presentation count as separate records). Exported so the persisted
|
|
1092
|
-
* `CardHistory.streak` can be kept in step with this derivation.
|
|
1093
|
-
*/
|
|
1094
|
-
declare function getStreak(records: QuestionRecord[]): number;
|
|
1095
|
-
/**
|
|
1096
|
-
* Total number of incorrect records on the card. Exported so the persisted
|
|
1097
|
-
* `CardHistory.lapses` can be kept in step with this derivation.
|
|
1098
|
-
*/
|
|
1099
|
-
declare function getLapses(records: QuestionRecord[]): number;
|
|
1100
|
-
|
|
1101
|
-
/**
|
|
1102
|
-
* Read-only user data operations
|
|
1103
|
-
*/
|
|
1104
|
-
interface UserDBReader {
|
|
1105
|
-
get<T>(id: string): Promise<T & PouchDB.Core.RevisionIdMeta>;
|
|
1106
|
-
getUsername(): string;
|
|
1107
|
-
isLoggedIn(): boolean;
|
|
1108
|
-
/**
|
|
1109
|
-
* How far this device's local mirror of the user's data can be trusted,
|
|
1110
|
-
* as of right now.
|
|
1111
|
-
*
|
|
1112
|
-
* Reads answer from the local mirror, so on a device that has never synced
|
|
1113
|
-
* this account "document not found" does not mean "no such data". Anything
|
|
1114
|
-
* that would otherwise interpret an empty read as a new user should check
|
|
1115
|
-
* for `failed` first. See {@link UserHydrationStatus}.
|
|
1116
|
-
*
|
|
1117
|
-
* Can return `hydrating`; use {@link awaitHydration} to decide on a settled
|
|
1118
|
-
* answer instead of a snapshot.
|
|
1119
|
-
*/
|
|
1120
|
-
hydrationStatus(): UserHydrationStatus;
|
|
1121
|
-
/**
|
|
1122
|
-
* The hydration status once settled — never `hydrating`.
|
|
1123
|
-
*
|
|
1124
|
-
* Resolves immediately unless a pull is in flight. Prefer this over
|
|
1125
|
-
* hydrationStatus() wherever the answer gates behaviour, such as a route
|
|
1126
|
-
* guard that may run while a login is still completing.
|
|
1127
|
-
*/
|
|
1128
|
-
awaitHydration(): Promise<UserHydrationStatus>;
|
|
1129
|
-
/**
|
|
1130
|
-
* Get user configuration
|
|
1131
|
-
*/
|
|
1132
|
-
getConfig(): Promise<UserConfig>;
|
|
1133
|
-
/**
|
|
1134
|
-
* Get cards that the user has seen
|
|
1135
|
-
*/
|
|
1136
|
-
getSeenCards(courseId?: string): Promise<string[]>;
|
|
1137
|
-
/**
|
|
1138
|
-
* Get cards that are actively scheduled for review
|
|
1139
|
-
*/
|
|
1140
|
-
getActiveCards(): Promise<QualifiedCardID[]>;
|
|
1141
|
-
/**
|
|
1142
|
-
* Get user's course registrations
|
|
1143
|
-
*/
|
|
1144
|
-
getCourseRegistrationsDoc(): Promise<CourseRegistrationDoc>;
|
|
1145
|
-
/**
|
|
1146
|
-
* Get the registration doc for a specific course.
|
|
1147
|
-
* @param courseId
|
|
1148
|
-
*/
|
|
1149
|
-
getCourseRegDoc(courseId: string): Promise<CourseRegistration>;
|
|
1150
|
-
/**
|
|
1151
|
-
* Get user's active courses
|
|
1152
|
-
*/
|
|
1153
|
-
getActiveCourses(): Promise<CourseRegistration[]>;
|
|
1154
|
-
/**
|
|
1155
|
-
* Get user's pending reviews
|
|
1156
|
-
*/
|
|
1157
|
-
getPendingReviews(courseId?: string): Promise<ScheduledCard[]>;
|
|
1158
|
-
/** Study-session records for a course, newest session-start first. */
|
|
1159
|
-
getStudySessions(courseId?: string): Promise<StudySessionDoc[]>;
|
|
1160
|
-
/**
|
|
1161
|
-
* Get all scheduled reviews due within the next `daysCount` days —
|
|
1162
|
-
* including ones not yet due. `getPendingReviews` is the `daysCount = 0`
|
|
1163
|
-
* special case: it returns only reviews already due, so a review scheduled
|
|
1164
|
-
* moments ago (necessarily in the future) will never appear in it.
|
|
1165
|
-
*/
|
|
1166
|
-
getReviewsForcast(daysCount: number, courseId?: string): Promise<ScheduledCard[]>;
|
|
1167
|
-
getActivityRecords(): Promise<ActivityRecord[]>;
|
|
1168
|
-
/**
|
|
1169
|
-
* Get strategy-specific state for a course.
|
|
1170
|
-
*
|
|
1171
|
-
* Strategies use this to persist preferences, learned patterns, or temporal
|
|
1172
|
-
* tracking data across sessions. Each strategy owns its own namespace.
|
|
1173
|
-
*
|
|
1174
|
-
* @deprecated Use `getCourseInterface(courseId).getStrategyState(strategyKey)` instead.
|
|
1175
|
-
* Direct use bypasses course-scoping safety — the courseId parameter is unguarded,
|
|
1176
|
-
* allowing accidental cross-course data access. The course-scoped interface binds
|
|
1177
|
-
* courseId once at construction.
|
|
1178
|
-
*
|
|
1179
|
-
* @param courseId - The course this state applies to
|
|
1180
|
-
* @param strategyKey - Unique key identifying the strategy (typically class name)
|
|
1181
|
-
* @returns The strategy's data payload, or null if no state exists
|
|
1182
|
-
*/
|
|
1183
|
-
getStrategyState<T>(courseId: string, strategyKey: string): Promise<T | null>;
|
|
1184
|
-
/**
|
|
1185
|
-
* Get user's classroom registrations
|
|
1186
|
-
*/
|
|
1187
|
-
getUserClassrooms(): Promise<ClassroomRegistrationDoc>;
|
|
1188
|
-
/**
|
|
1189
|
-
* Get user's active classes
|
|
1190
|
-
*/
|
|
1191
|
-
getActiveClasses(): Promise<string[]>;
|
|
1192
|
-
getCourseInterface(courseId: string): Promise<UsrCrsDataInterface>;
|
|
1193
|
-
}
|
|
1194
|
-
/**
|
|
1195
|
-
* User data mutation operations
|
|
1196
|
-
*/
|
|
1197
|
-
interface UserDBWriter extends DocumentUpdater {
|
|
1198
|
-
/**
|
|
1199
|
-
* Update user configuration
|
|
1200
|
-
*/
|
|
1201
|
-
setConfig(config: Partial<UserConfig>): Promise<void>;
|
|
1202
|
-
/**
|
|
1203
|
-
* Record a user's interaction with a card
|
|
1204
|
-
*/
|
|
1205
|
-
putCardRecord<T extends CardRecord>(record: T): Promise<CardHistory<CardRecord>>;
|
|
1206
|
-
/**
|
|
1207
|
-
* Register user for a course
|
|
1208
|
-
*/
|
|
1209
|
-
registerForCourse(courseId: string, previewMode?: boolean): Promise<PouchDB.Core.Response>;
|
|
1210
|
-
/**
|
|
1211
|
-
* Drop a course registration
|
|
1212
|
-
*/
|
|
1213
|
-
dropCourse(courseId: string, dropStatus?: string): Promise<PouchDB.Core.Response>;
|
|
1214
|
-
/**
|
|
1215
|
-
* Schedule a card for review
|
|
1216
|
-
*/
|
|
1217
|
-
scheduleCardReview(review: {
|
|
1218
|
-
user: string;
|
|
1219
|
-
course_id: string;
|
|
1220
|
-
card_id: string;
|
|
1221
|
-
time: Moment;
|
|
1222
|
-
scheduledFor: 'course' | 'classroom';
|
|
1223
|
-
schedulingAgentId: string;
|
|
1224
|
-
}): Promise<void>;
|
|
1225
|
-
/**
|
|
1226
|
-
* Remove a scheduled card review
|
|
1227
|
-
*/
|
|
1228
|
-
removeScheduledCardReview(reviewId: string): Promise<void>;
|
|
1229
|
-
/**
|
|
1230
|
-
* Register user for a classroom
|
|
1231
|
-
*/
|
|
1232
|
-
registerForClassroom(classId: string, registerAs: 'student' | 'teacher' | 'aide' | 'admin'): Promise<PouchDB.Core.Response>;
|
|
1233
|
-
/**
|
|
1234
|
-
* Drop user from classroom
|
|
1235
|
-
*/
|
|
1236
|
-
dropFromClassroom(classId: string): Promise<PouchDB.Core.Response>;
|
|
1237
|
-
/**
|
|
1238
|
-
* Update user's ELO rating for a course
|
|
1239
|
-
*/
|
|
1240
|
-
updateUserElo(courseId: string, elo: CourseElo): Promise<PouchDB.Core.Response>;
|
|
1241
|
-
/**
|
|
1242
|
-
* Reset all user data (progress, registrations, etc.) while preserving authentication
|
|
1243
|
-
*/
|
|
1244
|
-
resetUserData(): Promise<{
|
|
1245
|
-
status: Status;
|
|
1246
|
-
error?: string;
|
|
1247
|
-
}>;
|
|
1248
|
-
/**
|
|
1249
|
-
* Store strategy-specific state for a course.
|
|
1250
|
-
*
|
|
1251
|
-
* Strategies use this to persist preferences, learned patterns, or temporal
|
|
1252
|
-
* tracking data across sessions. Each strategy owns its own namespace.
|
|
1253
|
-
*
|
|
1254
|
-
* @deprecated Use `getCourseInterface(courseId).putStrategyState(strategyKey, data)` instead.
|
|
1255
|
-
* Direct use bypasses course-scoping safety — the courseId parameter is unguarded,
|
|
1256
|
-
* allowing accidental cross-course data writes. The course-scoped interface binds
|
|
1257
|
-
* courseId once at construction.
|
|
1258
|
-
*
|
|
1259
|
-
* @param courseId - The course this state applies to
|
|
1260
|
-
* @param strategyKey - Unique key identifying the strategy (typically class name)
|
|
1261
|
-
* @param data - The strategy's data payload to store
|
|
1262
|
-
*/
|
|
1263
|
-
putStrategyState<T>(courseId: string, strategyKey: string, data: T): Promise<void>;
|
|
1264
|
-
/**
|
|
1265
|
-
* Delete strategy-specific state for a course.
|
|
1266
|
-
*
|
|
1267
|
-
* @deprecated Use `getCourseInterface(courseId).deleteStrategyState(strategyKey)` instead.
|
|
1268
|
-
* Direct use bypasses course-scoping safety.
|
|
1269
|
-
*
|
|
1270
|
-
* @param courseId - The course this state applies to
|
|
1271
|
-
* @param strategyKey - Unique key identifying the strategy (typically class name)
|
|
1272
|
-
*/
|
|
1273
|
-
deleteStrategyState(courseId: string, strategyKey: string): Promise<void>;
|
|
1274
|
-
/**
|
|
1275
|
-
* Record a user learning outcome for evolutionary orchestration.
|
|
1276
|
-
*/
|
|
1277
|
-
putUserOutcome(record: UserOutcomeRecord): Promise<void>;
|
|
1278
|
-
/** Write or overwrite a study-session record. */
|
|
1279
|
-
putStudySession(doc: StudySessionDoc): Promise<void>;
|
|
1280
|
-
}
|
|
1281
|
-
/**
|
|
1282
|
-
* Authentication and account management operations
|
|
1283
|
-
*/
|
|
1284
|
-
interface UserDBAuthenticator {
|
|
1285
|
-
/**
|
|
1286
|
-
* Create a new user account
|
|
1287
|
-
*/
|
|
1288
|
-
createAccount(username: string, password: string): Promise<{
|
|
1289
|
-
status: Status;
|
|
1290
|
-
error: string;
|
|
1291
|
-
}>;
|
|
1292
|
-
/**
|
|
1293
|
-
* Log in as a user
|
|
1294
|
-
*/
|
|
1295
|
-
login(username: string, password: string): Promise<{
|
|
1296
|
-
ok: boolean;
|
|
1297
|
-
name?: string;
|
|
1298
|
-
roles?: string[];
|
|
1299
|
-
}>;
|
|
1300
|
-
/**
|
|
1301
|
-
* Log out the current user
|
|
1302
|
-
*/
|
|
1303
|
-
logout(): Promise<{
|
|
1304
|
-
ok: boolean;
|
|
1305
|
-
}>;
|
|
1306
|
-
/**
|
|
1307
|
-
* Adopt a session established outside this client (e.g. third-party
|
|
1308
|
-
* sign-in completed server-side), optionally migrating guest data.
|
|
1309
|
-
*/
|
|
1310
|
-
adoptSession(opts: {
|
|
1311
|
-
migrateGuestData: boolean;
|
|
1312
|
-
}): Promise<{
|
|
1313
|
-
ok: boolean;
|
|
1314
|
-
error?: string;
|
|
1315
|
-
username?: string;
|
|
1316
|
-
}>;
|
|
1317
|
-
}
|
|
1318
|
-
/**
|
|
1319
|
-
* Complete user database interface - combines all user operations
|
|
1320
|
-
* This maintains backward compatibility with existing code
|
|
1321
|
-
*/
|
|
1322
|
-
interface UserDBInterface extends UserDBReader, UserDBWriter, UserDBAuthenticator {
|
|
1323
|
-
}
|
|
1324
|
-
interface UserCourseSettings {
|
|
1325
|
-
[setting: string]: string | number | boolean;
|
|
1326
|
-
}
|
|
1327
|
-
interface UserCourseSetting {
|
|
1328
|
-
key: string;
|
|
1329
|
-
value: string | number | boolean;
|
|
1330
|
-
}
|
|
1331
|
-
interface UsrCrsDataInterface {
|
|
1332
|
-
getScheduledReviewCount(): Promise<number>;
|
|
1333
|
-
getCourseSettings(): Promise<UserCourseSettings>;
|
|
1334
|
-
updateCourseSettings(updates: UserCourseSetting[]): void;
|
|
1335
|
-
/**
|
|
1336
|
-
* Get strategy-specific state for this course.
|
|
1337
|
-
*
|
|
1338
|
-
* Course-scoped alternative to `UserDBInterface.getStrategyState()`.
|
|
1339
|
-
* The courseId is bound at construction via `getCourseInterface(courseId)`,
|
|
1340
|
-
* so callers cannot accidentally access another course's state.
|
|
1341
|
-
*
|
|
1342
|
-
* @param strategyKey - Unique key identifying the state document
|
|
1343
|
-
* @returns The state payload, or null if no state exists
|
|
1344
|
-
*/
|
|
1345
|
-
getStrategyState<T>(strategyKey: string): Promise<T | null>;
|
|
1346
|
-
/**
|
|
1347
|
-
* Store strategy-specific state for this course.
|
|
1348
|
-
*
|
|
1349
|
-
* Course-scoped alternative to `UserDBInterface.putStrategyState()`.
|
|
1350
|
-
*
|
|
1351
|
-
* @param strategyKey - Unique key identifying the state document
|
|
1352
|
-
* @param data - The state payload to store
|
|
1353
|
-
*/
|
|
1354
|
-
putStrategyState<T>(strategyKey: string, data: T): Promise<void>;
|
|
1355
|
-
/**
|
|
1356
|
-
* Delete strategy-specific state for this course.
|
|
1357
|
-
*
|
|
1358
|
-
* Course-scoped alternative to `UserDBInterface.deleteStrategyState()`.
|
|
1359
|
-
*
|
|
1360
|
-
* @param strategyKey - Unique key identifying the state document
|
|
1361
|
-
*/
|
|
1362
|
-
deleteStrategyState(strategyKey: string): Promise<void>;
|
|
1363
|
-
}
|
|
1364
|
-
type ClassroomRegistrationDesignation = 'student' | 'teacher' | 'aide' | 'admin';
|
|
1365
|
-
interface ClassroomRegistration {
|
|
1366
|
-
classID: string;
|
|
1367
|
-
registeredAs: ClassroomRegistrationDesignation;
|
|
1368
|
-
}
|
|
1369
|
-
interface ClassroomRegistrationDoc {
|
|
1370
|
-
registrations: ClassroomRegistration[];
|
|
1371
|
-
}
|
|
1372
|
-
|
|
1373
|
-
/**
|
|
1374
|
-
* Shared context available to all filters in a pipeline.
|
|
1375
|
-
*
|
|
1376
|
-
* Built once per getWeightedCards() call and passed to each filter.
|
|
1377
|
-
* This avoids repeated lookups for common data like user ELO.
|
|
1378
|
-
*/
|
|
1379
|
-
interface FilterContext {
|
|
1380
|
-
/** User database interface */
|
|
1381
|
-
user: UserDBInterface;
|
|
1382
|
-
/** Course database interface */
|
|
1383
|
-
course: CourseDBInterface;
|
|
1384
|
-
/** User's global ELO score for this course */
|
|
1385
|
-
userElo: number;
|
|
1386
|
-
/** User's full ELO for this course: global and per tag. Absent if it couldn't be read. */
|
|
1387
|
-
userCourseElo?: CourseElo;
|
|
1388
|
-
/** Orchestration context for evolutionary weighting */
|
|
1389
|
-
orchestration?: OrchestrationContext;
|
|
1390
|
-
}
|
|
1391
|
-
/**
|
|
1392
|
-
* A filter that transforms a list of weighted cards.
|
|
1393
|
-
*
|
|
1394
|
-
* Filters are pure transforms - they receive cards and context,
|
|
1395
|
-
* and return a modified list of cards. No delegate wrapping,
|
|
1396
|
-
* no side effects beyond provenance tracking.
|
|
1397
|
-
*
|
|
1398
|
-
* ## Implementation Guidelines
|
|
1399
|
-
*
|
|
1400
|
-
* 1. **Append provenance**: Every filter should add a StrategyContribution
|
|
1401
|
-
* entry documenting its decision for each card.
|
|
1402
|
-
*
|
|
1403
|
-
* 2. **Use multipliers**: Adjust scores by multiplying, not replacing.
|
|
1404
|
-
* This ensures filter order doesn't matter.
|
|
1405
|
-
*
|
|
1406
|
-
* 3. **Score 0 for exclusion**: To exclude a card, set score to 0.
|
|
1407
|
-
* Don't filter it out - let provenance show why it was excluded.
|
|
1408
|
-
*
|
|
1409
|
-
* 4. **Don't sort**: The Pipeline handles final sorting.
|
|
1410
|
-
* Filters just transform scores.
|
|
1411
|
-
*
|
|
1412
|
-
* ## Example Implementation
|
|
1413
|
-
*
|
|
1414
|
-
* ```typescript
|
|
1415
|
-
* const myFilter: CardFilter = {
|
|
1416
|
-
* name: 'My Filter',
|
|
1417
|
-
* async transform(cards, context) {
|
|
1418
|
-
* return cards.map(card => {
|
|
1419
|
-
* const multiplier = computeMultiplier(card, context);
|
|
1420
|
-
* const newScore = card.score * multiplier;
|
|
1421
|
-
* return {
|
|
1422
|
-
* ...card,
|
|
1423
|
-
* score: newScore,
|
|
1424
|
-
* provenance: [...card.provenance, {
|
|
1425
|
-
* strategy: 'myFilter',
|
|
1426
|
-
* strategyName: 'My Filter',
|
|
1427
|
-
* strategyId: 'MY_FILTER',
|
|
1428
|
-
* action: multiplier < 1 ? 'penalized' : 'passed',
|
|
1429
|
-
* score: newScore,
|
|
1430
|
-
* reason: 'Explanation of decision'
|
|
1431
|
-
* }]
|
|
1432
|
-
* };
|
|
1433
|
-
* });
|
|
1434
|
-
* }
|
|
1435
|
-
* };
|
|
1436
|
-
* ```
|
|
1437
|
-
*/
|
|
1438
|
-
/**
|
|
1439
|
-
* What a filter's penalties mean. A `gate` says a card isn't ready yet
|
|
1440
|
-
* (prerequisites, lessons, unlocks); a `signal` expresses preference
|
|
1441
|
-
* (priority, interference, ELO distance).
|
|
1442
|
-
*/
|
|
1443
|
-
type FilterKind = 'gate' | 'signal';
|
|
1444
|
-
interface CardFilter {
|
|
1445
|
-
/** Human-readable name for this filter */
|
|
1446
|
-
name: string;
|
|
1447
|
-
/**
|
|
1448
|
-
* Regulators lift only new cards that no gate penalized, so pressure can't
|
|
1449
|
-
* override "not ready". Undeclared filters count as gates: a penalty of
|
|
1450
|
-
* unknown meaning shouldn't be overridden by pressure.
|
|
1451
|
-
*/
|
|
1452
|
-
kind?: FilterKind;
|
|
1453
|
-
/**
|
|
1454
|
-
* Applies to live runs only. `forecast` and `diagnoseCardSpace` start every
|
|
1455
|
-
* card at 1.0 without a generator, and skip these filters.
|
|
1456
|
-
*/
|
|
1457
|
-
liveOnly?: boolean;
|
|
1458
|
-
/**
|
|
1459
|
-
* Transform a list of weighted cards.
|
|
1460
|
-
*
|
|
1461
|
-
* @param cards - Cards to transform (already scored by generator)
|
|
1462
|
-
* @param context - Shared context (user, course, userElo, etc.)
|
|
1463
|
-
* @returns Transformed cards with updated scores and provenance
|
|
1464
|
-
*/
|
|
1465
|
-
transform(cards: WeightedCard[], context: FilterContext): Promise<WeightedCard[]>;
|
|
1466
|
-
}
|
|
1467
|
-
/**
|
|
1468
|
-
* Factory function type for creating filters from configuration.
|
|
1469
|
-
*
|
|
1470
|
-
* Used by PipelineAssembler to instantiate filters from strategy documents.
|
|
1471
|
-
*/
|
|
1472
|
-
type CardFilterFactory<TConfig = unknown> = (config: TConfig) => CardFilter;
|
|
1473
|
-
|
|
1474
|
-
/**
|
|
1475
|
-
* Type for navigator constructor functions.
|
|
1476
|
-
*/
|
|
1477
|
-
type NavigatorConstructor = new (user: UserDBInterface, course: CourseDBInterface, strategyData: ContentNavigationStrategyData) => ContentNavigator;
|
|
1478
|
-
/**
|
|
1479
|
-
* Register a navigator implementation.
|
|
1480
|
-
*
|
|
1481
|
-
* Call this to make a navigator available for instantiation by
|
|
1482
|
-
* ContentNavigator.create() without relying on dynamic imports.
|
|
1483
|
-
*
|
|
1484
|
-
* Passing a `role` is optional for built-in navigators (whose roles are in
|
|
1485
|
-
* the hardcoded `NavigatorRoles` record), but **required** for consumer-
|
|
1486
|
-
* defined navigators that need to participate in pipeline assembly.
|
|
1487
|
-
*
|
|
1488
|
-
* @param implementingClass - The class name (e.g., 'elo', 'letterGatingFilter')
|
|
1489
|
-
* @param constructor - The navigator class constructor
|
|
1490
|
-
* @param role - Optional pipeline role (GENERATOR or FILTER)
|
|
1491
|
-
*/
|
|
1492
|
-
declare function registerNavigator(implementingClass: string, constructor: NavigatorConstructor, role?: NavigatorRole): void;
|
|
1493
|
-
/**
|
|
1494
|
-
* Get a navigator constructor from the registry.
|
|
1495
|
-
*
|
|
1496
|
-
* @param implementingClass - The class name to look up
|
|
1497
|
-
* @returns The constructor, or undefined if not registered
|
|
1498
|
-
*/
|
|
1499
|
-
declare function getRegisteredNavigator(implementingClass: string): NavigatorConstructor | undefined;
|
|
1500
|
-
/**
|
|
1501
|
-
* Check if a navigator is registered.
|
|
1502
|
-
*
|
|
1503
|
-
* @param implementingClass - The class name to check
|
|
1504
|
-
* @returns true if registered, false otherwise
|
|
1505
|
-
*/
|
|
1506
|
-
declare function hasRegisteredNavigator(implementingClass: string): boolean;
|
|
1507
|
-
/**
|
|
1508
|
-
* Get the registered role for a navigator, if one was provided at registration.
|
|
1509
|
-
*
|
|
1510
|
-
* @param implementingClass - The class name to look up
|
|
1511
|
-
* @returns The role, or undefined if not registered or no role was specified
|
|
1512
|
-
*/
|
|
1513
|
-
declare function getRegisteredNavigatorRole(implementingClass: string): NavigatorRole | undefined;
|
|
1514
|
-
/**
|
|
1515
|
-
* A registered filter's declared kind (see `CardFilter.kind`): the static
|
|
1516
|
-
* `kind` on its class. Undefined if unregistered or undeclared; undeclared
|
|
1517
|
-
* filters count as gates at run time.
|
|
1518
|
-
* @param implementingClass - The class name to look up
|
|
1519
|
-
*/
|
|
1520
|
-
declare function getRegisteredFilterKind(implementingClass: string): FilterKind | undefined;
|
|
1521
|
-
/**
|
|
1522
|
-
* Get all registered navigator names.
|
|
1523
|
-
* Useful for debugging and testing.
|
|
1524
|
-
*/
|
|
1525
|
-
declare function getRegisteredNavigatorNames(): string[];
|
|
1526
|
-
/**
|
|
1527
|
-
* Initialize the navigator registry with all built-in navigators.
|
|
1528
|
-
*
|
|
1529
|
-
* This function dynamically imports all standard navigator implementations
|
|
1530
|
-
* and registers them. Call this once at application startup to ensure
|
|
1531
|
-
* all navigators are available.
|
|
1532
|
-
*
|
|
1533
|
-
* In test environments, this may need to be called explicitly before
|
|
1534
|
-
* using ContentNavigator.create().
|
|
1535
|
-
*/
|
|
1536
|
-
declare function initializeNavigatorRegistry(): Promise<void>;
|
|
1537
|
-
/**
|
|
1538
|
-
* Tracks a single strategy's contribution to a card's final score.
|
|
1539
|
-
*
|
|
1540
|
-
* Each strategy in the pipeline adds a StrategyContribution entry to the
|
|
1541
|
-
* card's provenance array, creating an audit trail of scoring decisions.
|
|
1542
|
-
*/
|
|
1543
|
-
interface StrategyContribution {
|
|
1544
|
-
/**
|
|
1545
|
-
* Strategy type (implementing class name).
|
|
1546
|
-
* Examples: 'elo', 'hierarchyDefinition', 'interferenceMitigator'
|
|
1547
|
-
*/
|
|
1548
|
-
strategy: string;
|
|
1549
|
-
/**
|
|
1550
|
-
* Human-readable name identifying this specific strategy instance.
|
|
1551
|
-
* Extracted from ContentNavigationStrategyData.name.
|
|
1552
|
-
* Courses may have multiple instances of the same strategy type with
|
|
1553
|
-
* different configurations.
|
|
1554
|
-
*
|
|
1555
|
-
* Examples:
|
|
1556
|
-
* - "ELO (default)"
|
|
1557
|
-
* - "Interference: b/d/p confusion"
|
|
1558
|
-
* - "Interference: phonetic confusables"
|
|
1559
|
-
* - "Priority: Common letters first"
|
|
1560
|
-
*/
|
|
1561
|
-
strategyName: string;
|
|
1562
|
-
/**
|
|
1563
|
-
* Unique database document ID for this strategy instance.
|
|
1564
|
-
* Extracted from ContentNavigationStrategyData._id.
|
|
1565
|
-
* Use this to fetch the full strategy configuration document.
|
|
1566
|
-
*
|
|
1567
|
-
* Examples:
|
|
1568
|
-
* - "NAVIGATION_STRATEGY-ELO-default"
|
|
1569
|
-
* - "NAVIGATION_STRATEGY-interference-bdp"
|
|
1570
|
-
* - "NAVIGATION_STRATEGY-priority-common-letters"
|
|
1571
|
-
*/
|
|
1572
|
-
strategyId: string;
|
|
1573
|
-
/**
|
|
1574
|
-
* What the strategy did:
|
|
1575
|
-
* - 'generated': Strategy produced this card (generators only)
|
|
1576
|
-
* - 'passed': Strategy evaluated but didn't change score (transparent pass-through)
|
|
1577
|
-
* - 'boosted': Strategy increased the score
|
|
1578
|
-
* - 'penalized': Strategy decreased the score
|
|
1579
|
-
*/
|
|
1580
|
-
action: 'generated' | 'passed' | 'boosted' | 'penalized';
|
|
1581
|
-
/** Score after this strategy's processing */
|
|
1582
|
-
score: number;
|
|
1583
|
-
/**
|
|
1584
|
-
* The effective weight applied for this strategy instance.
|
|
1585
|
-
* If using evolutionary orchestration, this includes deviation.
|
|
1586
|
-
* If omitted, implies weight 1.0 (legacy behavior).
|
|
1587
|
-
*/
|
|
1588
|
-
effectiveWeight?: number;
|
|
1589
|
-
/**
|
|
1590
|
-
* The deviation factor applied to this user's cohort for this strategy.
|
|
1591
|
-
* Range [-1.0, 1.0].
|
|
1592
|
-
*/
|
|
1593
|
-
deviation?: number;
|
|
1594
|
-
/**
|
|
1595
|
-
* Human-readable explanation of the strategy's decision.
|
|
1596
|
-
*
|
|
1597
|
-
* Examples:
|
|
1598
|
-
* - "ELO distance 75, new card"
|
|
1599
|
-
* - "Prerequisites met: letter-sounds"
|
|
1600
|
-
* - "Interferes with immature tag 'd' (decay 0.8)"
|
|
1601
|
-
* - "High-priority tag 's' (0.95) → boost 1.15x"
|
|
1602
|
-
*
|
|
1603
|
-
* Required for transparency - silent adjusters are anti-patterns.
|
|
1604
|
-
*/
|
|
1605
|
-
reason: string;
|
|
1606
|
-
}
|
|
1607
|
-
/**
|
|
1608
|
-
* A card with a suitability score and provenance trail.
|
|
1609
|
-
*
|
|
1610
|
-
* Scores range from 0-1:
|
|
1611
|
-
* - 1.0 = fully suitable
|
|
1612
|
-
* - 0.0 = hard filter (e.g., prerequisite not met)
|
|
1613
|
-
* - 0.5 = neutral
|
|
1614
|
-
* - Intermediate values = soft preference
|
|
1615
|
-
*
|
|
1616
|
-
* Provenance tracks the scoring pipeline:
|
|
1617
|
-
* - First entry: Generator that produced the card
|
|
1618
|
-
* - Subsequent entries: Filters that transformed the score
|
|
1619
|
-
* - Each entry includes action and human-readable reason
|
|
1620
|
-
*/
|
|
1621
|
-
interface WeightedCard {
|
|
1622
|
-
cardId: string;
|
|
1623
|
-
courseId: string;
|
|
1624
|
-
/** Suitability score from 0-1 */
|
|
1625
|
-
score: number;
|
|
1626
|
-
/**
|
|
1627
|
-
* Audit trail of strategy contributions.
|
|
1628
|
-
* First entry is from the generator, subsequent entries from filters.
|
|
1629
|
-
*/
|
|
1630
|
-
provenance: StrategyContribution[];
|
|
1631
|
-
/**
|
|
1632
|
-
* Pre-fetched tags. Populated by Pipeline before filters run.
|
|
1633
|
-
* Filters should use this instead of querying getAppliedTags() individually.
|
|
1634
|
-
*/
|
|
1635
|
-
tags?: string[];
|
|
1636
|
-
/**
|
|
1637
|
-
* Review document ID (_id from ScheduledCard).
|
|
1638
|
-
* Present when this card originated from SRS review scheduling.
|
|
1639
|
-
* Used by SessionController to track review outcomes and maintain review state.
|
|
1640
|
-
*/
|
|
1641
|
-
reviewID?: string;
|
|
1642
|
-
/**
|
|
1643
|
-
* The card's global ELO, when the generator already knows it (the ELO
|
|
1644
|
-
* generator reads it during retrieval). Lets the ELO distance filter skip a
|
|
1645
|
-
* fetch.
|
|
1646
|
-
*/
|
|
1647
|
-
cardElo?: number;
|
|
1648
|
-
/**
|
|
1649
|
-
* A review's SRS urgency in [0, 1] (overdueness and interval recency), set by
|
|
1650
|
-
* the SRS generator. The review-mass regulator weighs the backlog by it.
|
|
1651
|
-
*/
|
|
1652
|
-
reviewUrgency?: number;
|
|
1653
|
-
}
|
|
1654
|
-
/**
|
|
1655
|
-
* Extract card origin from provenance trail.
|
|
1656
|
-
*
|
|
1657
|
-
* The first provenance entry (from the generator) indicates whether
|
|
1658
|
-
* this is a new card, review, or failed card. We parse the reason
|
|
1659
|
-
* string to extract this information.
|
|
1660
|
-
*
|
|
1661
|
-
* @param card - Card with provenance trail
|
|
1662
|
-
* @returns Card origin ('new', 'review', or 'failed')
|
|
1663
|
-
*/
|
|
1664
|
-
declare function getCardOrigin(card: WeightedCard): 'new' | 'review' | 'failed';
|
|
1665
|
-
declare enum Navigators {
|
|
1666
|
-
ELO = "elo",
|
|
1667
|
-
SRS = "srs",
|
|
1668
|
-
PRESCRIBED = "prescribed",
|
|
1669
|
-
HIERARCHY = "hierarchyDefinition",
|
|
1670
|
-
INTERFERENCE = "interferenceMitigator",
|
|
1671
|
-
RELATIVE_PRIORITY = "relativePriority",
|
|
1672
|
-
USER_TAG_PREFERENCE = "userTagPreference",
|
|
1673
|
-
ELO_DISTANCE = "eloDistance"
|
|
1674
|
-
}
|
|
1675
|
-
/**
|
|
1676
|
-
* Role classification for navigation strategies.
|
|
1677
|
-
*
|
|
1678
|
-
* - GENERATOR: Produces candidate cards with initial scores
|
|
1679
|
-
* - FILTER: Transforms cards with score multipliers
|
|
1680
|
-
*/
|
|
1681
|
-
declare enum NavigatorRole {
|
|
1682
|
-
GENERATOR = "generator",
|
|
1683
|
-
FILTER = "filter"
|
|
1684
|
-
}
|
|
1685
|
-
/**
|
|
1686
|
-
* Registry mapping navigator implementations to their roles.
|
|
1687
|
-
*/
|
|
1688
|
-
declare const NavigatorRoles: Record<Navigators, NavigatorRole>;
|
|
1689
|
-
/**
|
|
1690
|
-
* Check if a navigator implementation is a generator.
|
|
1691
|
-
*
|
|
1692
|
-
* @param impl - Navigator implementation name (e.g., 'elo', 'hierarchyDefinition')
|
|
1693
|
-
* @returns true if the navigator is a generator, false otherwise
|
|
1694
|
-
*/
|
|
1695
|
-
declare function isGenerator(impl: string): boolean;
|
|
1696
|
-
/**
|
|
1697
|
-
* Check if a navigator implementation is a filter.
|
|
1698
|
-
*
|
|
1699
|
-
* Checks the built-in NavigatorRoles enum first, then falls back to the
|
|
1700
|
-
* navigator registry for consumer-registered navigators.
|
|
1701
|
-
*
|
|
1702
|
-
* @param impl - Navigator implementation name (e.g., 'elo', 'letterGatingFilter')
|
|
1703
|
-
* @returns true if the navigator is a filter, false otherwise
|
|
1704
|
-
*/
|
|
1705
|
-
declare function isFilter(impl: string): boolean;
|
|
1706
|
-
/**
|
|
1707
|
-
* Abstract base class for navigation strategies.
|
|
1708
|
-
*
|
|
1709
|
-
* This class exists primarily for backward compatibility with legacy code.
|
|
1710
|
-
* New code should use CardGenerator or CardFilter interfaces directly.
|
|
1711
|
-
*
|
|
1712
|
-
* The class implements StudyContentSource for compatibility with SessionController.
|
|
1713
|
-
* Once SessionController migrates to use getWeightedCards() exclusively,
|
|
1714
|
-
* the legacy methods can be removed.
|
|
1715
|
-
*/
|
|
1716
|
-
declare abstract class ContentNavigator implements StudyContentSource {
|
|
1717
|
-
/** User interface for this navigation session */
|
|
1718
|
-
protected user: UserDBInterface;
|
|
1719
|
-
/** Course interface for this navigation session */
|
|
1720
|
-
protected course: CourseDBInterface;
|
|
1721
|
-
/** Human-readable name for this strategy instance (from ContentNavigationStrategyData.name) */
|
|
1722
|
-
protected strategyName?: string;
|
|
1723
|
-
/** Unique document ID for this strategy instance (from ContentNavigationStrategyData._id) */
|
|
1724
|
-
protected strategyId?: string;
|
|
1725
|
-
/** Evolutionary weighting configuration */
|
|
1726
|
-
learnable?: LearnableWeight;
|
|
1727
|
-
/** Whether to bypass deviation (manual/static weighting) */
|
|
1728
|
-
staticWeight?: boolean;
|
|
1729
|
-
/**
|
|
1730
|
-
* Constructor for standard navigators.
|
|
1731
|
-
* Call this from subclass constructors to initialize common fields.
|
|
1732
|
-
*
|
|
1733
|
-
* Note: CompositeGenerator and Pipeline call super() without args, then set
|
|
1734
|
-
* user/course fields directly if needed.
|
|
1735
|
-
*/
|
|
1736
|
-
constructor(user?: UserDBInterface, course?: CourseDBInterface, strategyData?: ContentNavigationStrategyData);
|
|
1737
|
-
/**
|
|
1738
|
-
* Unique key identifying this strategy for state storage.
|
|
1739
|
-
*
|
|
1740
|
-
* Defaults to the constructor name (e.g., "UserTagPreferenceFilter").
|
|
1741
|
-
* Override in subclasses if multiple instances of the same strategy type
|
|
1742
|
-
* need separate state storage.
|
|
1743
|
-
*/
|
|
1744
|
-
protected get strategyKey(): string;
|
|
1745
|
-
/**
|
|
1746
|
-
* Get this strategy's persisted state for the current course.
|
|
1747
|
-
*
|
|
1748
|
-
* @returns The strategy's data payload, or null if no state exists
|
|
1749
|
-
* @throws Error if user or course is not initialized
|
|
1750
|
-
*/
|
|
1751
|
-
protected getStrategyState<T>(): Promise<T | null>;
|
|
1752
|
-
/**
|
|
1753
|
-
* Persist this strategy's state for the current course.
|
|
1754
|
-
*
|
|
1755
|
-
* @param data - The strategy's data payload to store
|
|
1756
|
-
* @throws Error if user or course is not initialized
|
|
1757
|
-
*/
|
|
1758
|
-
protected putStrategyState<T>(data: T): Promise<void>;
|
|
1759
|
-
/**
|
|
1760
|
-
* Factory method to create navigator instances.
|
|
1761
|
-
*
|
|
1762
|
-
* First checks the navigator registry for a pre-registered constructor.
|
|
1763
|
-
* If not found, falls back to dynamic import (for custom navigators).
|
|
1764
|
-
*
|
|
1765
|
-
* For reliable operation in test environments, call initializeNavigatorRegistry()
|
|
1766
|
-
* before using this method.
|
|
1767
|
-
*
|
|
1768
|
-
* @param user - User interface
|
|
1769
|
-
* @param course - Course interface
|
|
1770
|
-
* @param strategyData - Strategy configuration document
|
|
1771
|
-
* @returns the runtime object used to steer a study session.
|
|
1772
|
-
*/
|
|
1773
|
-
static create(user: UserDBInterface, course: CourseDBInterface, strategyData: ContentNavigationStrategyData): Promise<ContentNavigator>;
|
|
1774
|
-
/**
|
|
1775
|
-
* Get cards with suitability scores and provenance trails.
|
|
1776
|
-
*
|
|
1777
|
-
* **This is the PRIMARY API for navigation strategies.**
|
|
1778
|
-
*
|
|
1779
|
-
* Returns cards ranked by suitability score (0-1). Higher scores indicate
|
|
1780
|
-
* better candidates for presentation. Each card includes a provenance trail
|
|
1781
|
-
* documenting how strategies contributed to the final score.
|
|
1782
|
-
*
|
|
1783
|
-
* ## Implementation Required
|
|
1784
|
-
* All navigation strategies MUST override this method. The base class does
|
|
1785
|
-
* not provide a default implementation.
|
|
1786
|
-
*
|
|
1787
|
-
* ## For Generators
|
|
1788
|
-
* Override this method to generate candidates and compute scores based on
|
|
1789
|
-
* your strategy's logic (e.g., ELO proximity, review urgency). Create the
|
|
1790
|
-
* initial provenance entry with action='generated'.
|
|
1791
|
-
*
|
|
1792
|
-
* ## For Filters
|
|
1793
|
-
* Filters should implement the CardFilter interface instead and be composed
|
|
1794
|
-
* via Pipeline. Filters do not directly implement getWeightedCards().
|
|
1795
|
-
*
|
|
1796
|
-
* @param limit - Maximum cards to return
|
|
1797
|
-
* @returns Cards sorted by score descending, with provenance trails
|
|
1798
|
-
*/
|
|
1799
|
-
getWeightedCards(_limit: number): Promise<GeneratorResult>;
|
|
1800
|
-
/**
|
|
1801
|
-
* Set ephemeral hints for the next pipeline run.
|
|
1802
|
-
* No-op for non-Pipeline navigators. Pipeline overrides this.
|
|
1803
|
-
*/
|
|
1804
|
-
setEphemeralHints(_hints: ReplanHints): void;
|
|
1805
|
-
}
|
|
1806
|
-
|
|
1807
|
-
/**
|
|
1808
|
-
* Typed ephemeral pipeline hints for a single run.
|
|
1809
|
-
* All fields are optional. Tag/card patterns support `*` wildcards.
|
|
1810
|
-
*/
|
|
1811
|
-
interface ReplanHints {
|
|
1812
|
-
/** Multiply scores for cards matching these tag patterns. */
|
|
1813
|
-
boostTags?: Record<string, number>;
|
|
1814
|
-
/** Multiply scores for these specific card IDs (glob patterns). */
|
|
1815
|
-
boostCards?: Record<string, number>;
|
|
1816
|
-
/** Cards matching these tag patterns MUST appear in results. */
|
|
1817
|
-
requireTags?: string[];
|
|
1818
|
-
/** These specific card IDs MUST appear in results. */
|
|
1819
|
-
requireCards?: string[];
|
|
1820
|
-
/** Remove cards matching these tag patterns from results. */
|
|
1821
|
-
excludeTags?: string[];
|
|
1822
|
-
/** Remove these specific card IDs from results. */
|
|
1823
|
-
excludeCards?: string[];
|
|
1824
|
-
/**
|
|
1825
|
-
* Debugging label threaded from the replan requester.
|
|
1826
|
-
* Prefixed with `_` to signal it's metadata, not a scoring hint.
|
|
1827
|
-
*/
|
|
1828
|
-
_label?: string;
|
|
1829
|
-
}
|
|
1830
|
-
/**
|
|
1831
|
-
* Context available to generators when producing candidates.
|
|
1832
|
-
*
|
|
1833
|
-
* Built once per getWeightedCards() call by the Pipeline.
|
|
1834
|
-
*/
|
|
1835
|
-
interface GeneratorContext {
|
|
1836
|
-
/** User database interface */
|
|
1837
|
-
user: UserDBInterface;
|
|
1838
|
-
/** Course database interface */
|
|
1839
|
-
course: CourseDBInterface;
|
|
1840
|
-
/** User's global ELO score for this course */
|
|
1841
|
-
userElo: number;
|
|
1842
|
-
/** Orchestration context for evolutionary weighting */
|
|
1843
|
-
orchestration?: OrchestrationContext;
|
|
1844
|
-
}
|
|
1845
|
-
/**
|
|
1846
|
-
* Structured generator result.
|
|
1847
|
-
*
|
|
1848
|
-
* Generators may optionally emit one-shot replan hints alongside their
|
|
1849
|
-
* candidate cards. This allows a generator to shape the broader pipeline
|
|
1850
|
-
* without having to enumerate every affected support card directly.
|
|
1851
|
-
*/
|
|
1852
|
-
interface GeneratorResult {
|
|
1853
|
-
/** Candidate cards produced by the generator */
|
|
1854
|
-
cards: WeightedCard[];
|
|
1855
|
-
/** Optional one-shot hints to apply after the filter chain */
|
|
1856
|
-
hints?: ReplanHints;
|
|
1857
|
-
}
|
|
1858
|
-
/**
|
|
1859
|
-
* A generator that produces candidate cards with initial scores.
|
|
1860
|
-
*
|
|
1861
|
-
* Generators are the "source" stage of a navigation pipeline.
|
|
1862
|
-
* They query the database for eligible cards and assign initial
|
|
1863
|
-
* suitability scores based on their strategy (ELO proximity,
|
|
1864
|
-
* review urgency, fixed order, etc.).
|
|
1865
|
-
*
|
|
1866
|
-
* ## Implementation Guidelines
|
|
1867
|
-
*
|
|
1868
|
-
* 1. **Create provenance**: Each card should have a provenance entry
|
|
1869
|
-
* with action='generated' documenting why it was selected.
|
|
1870
|
-
*
|
|
1871
|
-
* 2. **Score semantics**: Higher scores = more suitable for presentation.
|
|
1872
|
-
* Scores should be in [0, 1] range for composability.
|
|
1873
|
-
*
|
|
1874
|
-
* 3. **Limit handling**: Respect the limit parameter, but may over-fetch
|
|
1875
|
-
* internally if needed for scoring accuracy.
|
|
1876
|
-
*
|
|
1877
|
-
* 4. **Sort before returning**: Return cards sorted by score descending.
|
|
1878
|
-
*
|
|
1879
|
-
* 5. **Hints are optional**: Generators may return structured results with
|
|
1880
|
-
* `hints` when they need to apply pipeline-wide ephemeral pressure.
|
|
1881
|
-
*
|
|
1882
|
-
* ## Example Implementation
|
|
1883
|
-
*
|
|
1884
|
-
* ```typescript
|
|
1885
|
-
* const myGenerator: CardGenerator = {
|
|
1886
|
-
* name: 'My Generator',
|
|
1887
|
-
* async getWeightedCards(limit, context) {
|
|
1888
|
-
* const candidates = await fetchCandidates(context.course, limit);
|
|
1889
|
-
* return candidates.map(c => ({
|
|
1890
|
-
* cardId: c.id,
|
|
1891
|
-
* courseId: context.course.getCourseID(),
|
|
1892
|
-
* score: computeScore(c, context),
|
|
1893
|
-
* provenance: [{
|
|
1894
|
-
* strategy: 'myGenerator',
|
|
1895
|
-
* strategyName: 'My Generator',
|
|
1896
|
-
* strategyId: 'MY_GENERATOR',
|
|
1897
|
-
* action: 'generated',
|
|
1898
|
-
* score: computeScore(c, context),
|
|
1899
|
-
* reason: 'Explanation of selection'
|
|
1900
|
-
* }]
|
|
1901
|
-
* }));
|
|
1902
|
-
* }
|
|
1903
|
-
* };
|
|
1904
|
-
* ```
|
|
1905
|
-
*/
|
|
1906
|
-
interface CardGenerator {
|
|
1907
|
-
/** Human-readable name for this generator */
|
|
1908
|
-
name: string;
|
|
1909
|
-
/**
|
|
1910
|
-
* Produce candidate cards with initial scores.
|
|
1911
|
-
*
|
|
1912
|
-
* @param limit - Maximum number of cards to return
|
|
1913
|
-
* @param context - Shared context (user, course, userElo, etc.)
|
|
1914
|
-
* @returns Cards sorted by score descending, with provenance, optionally
|
|
1915
|
-
* accompanied by one-shot replan hints
|
|
1916
|
-
*/
|
|
1917
|
-
getWeightedCards(limit: number, context: GeneratorContext): Promise<GeneratorResult>;
|
|
1918
|
-
}
|
|
1919
|
-
/**
|
|
1920
|
-
* Factory function type for creating generators from configuration.
|
|
1921
|
-
*
|
|
1922
|
-
* Used by PipelineAssembler to instantiate generators from strategy documents.
|
|
1923
|
-
*/
|
|
1924
|
-
type CardGeneratorFactory<TConfig = unknown> = (config: TConfig) => CardGenerator;
|
|
1925
|
-
|
|
1926
|
-
type StudySessionFailedItem = StudySessionFailedNewItem | StudySessionFailedReviewItem;
|
|
1927
|
-
interface StudySessionFailedNewItem extends StudySessionItem {
|
|
1928
|
-
status: 'failed-new';
|
|
1929
|
-
}
|
|
1930
|
-
interface StudySessionFailedReviewItem extends StudySessionReviewItem {
|
|
1931
|
-
status: 'failed-review';
|
|
1932
|
-
}
|
|
1933
|
-
interface StudySessionNewItem extends StudySessionItem {
|
|
1934
|
-
status: 'new';
|
|
1935
|
-
}
|
|
1936
|
-
interface StudySessionReviewItem extends StudySessionItem {
|
|
1937
|
-
reviewID: string;
|
|
1938
|
-
status: 'review' | 'failed-review';
|
|
1939
|
-
}
|
|
1940
|
-
declare function isReview(item: StudySessionItem): item is StudySessionReviewItem;
|
|
1941
|
-
interface StudySessionItem {
|
|
1942
|
-
status: 'new' | 'review' | 'failed-new' | 'failed-review';
|
|
1943
|
-
contentSourceType: 'course' | 'classroom';
|
|
1944
|
-
contentSourceID: string;
|
|
1945
|
-
cardID: string;
|
|
1946
|
-
courseID: string;
|
|
1947
|
-
elo?: number;
|
|
1948
|
-
/**
|
|
1949
|
-
* Pipeline suitability score at queue-build time, carried for observability
|
|
1950
|
-
* (the debug overlay renders the now-load-bearing supply ranking). `+INF`
|
|
1951
|
-
* marks a mandatory required card. Not used for any draw decision — the
|
|
1952
|
-
* supplyQ is already ordered, so the controller draws front-to-back.
|
|
1953
|
-
*/
|
|
1954
|
-
score?: number;
|
|
1955
|
-
}
|
|
1956
|
-
interface ContentSourceID {
|
|
1957
|
-
type: 'course' | 'classroom';
|
|
1958
|
-
id: string;
|
|
1959
|
-
/**
|
|
1960
|
-
* Optional tag filter for scoped study sessions.
|
|
1961
|
-
* When present, creates a TagFilteredContentSource instead of a regular course source.
|
|
1962
|
-
*/
|
|
1963
|
-
tagFilter?: TagFilter;
|
|
1964
|
-
}
|
|
1965
|
-
/**
|
|
1966
|
-
* Interface for sources that provide study content to SessionController.
|
|
1967
|
-
*
|
|
1968
|
-
* Content sources return scored candidates via getWeightedCards(), which
|
|
1969
|
-
* SessionController uses to populate study queues.
|
|
1970
|
-
*
|
|
1971
|
-
* See: packages/db/docs/navigators-architecture.md
|
|
1972
|
-
*/
|
|
1973
|
-
interface StudyContentSource {
|
|
1974
|
-
/**
|
|
1975
|
-
* Get cards with suitability scores for presentation.
|
|
1976
|
-
*
|
|
1977
|
-
* Returns unified scored candidates that can be sorted and selected by SessionController.
|
|
1978
|
-
* The card origin ('new' | 'review' | 'failed') is determined by provenance metadata.
|
|
1979
|
-
*
|
|
1980
|
-
* @param limit - Maximum number of cards to return
|
|
1981
|
-
* @returns Cards sorted by score descending
|
|
1982
|
-
*/
|
|
1983
|
-
getWeightedCards(limit: number): Promise<GeneratorResult>;
|
|
1984
|
-
/**
|
|
1985
|
-
* Get the orchestration context for this source.
|
|
1986
|
-
* Used for recording learning outcomes.
|
|
1987
|
-
*/
|
|
1988
|
-
getOrchestrationContext?(): Promise<OrchestrationContext>;
|
|
1989
|
-
/**
|
|
1990
|
-
* Set ephemeral hints for the next pipeline run.
|
|
1991
|
-
* No-op for sources that don't support hints.
|
|
1992
|
-
*/
|
|
1993
|
-
setEphemeralHints?(hints: ReplanHints): void;
|
|
1994
|
-
/**
|
|
1995
|
-
* A card was just presented. `status` is the session item's (`'new'`,
|
|
1996
|
-
* `'review'`, `'failed-new'`, ...). Pipelines use a new card's first
|
|
1997
|
-
* presentation to restart their intake valve's clock.
|
|
1998
|
-
*/
|
|
1999
|
-
notePresented?(card: {
|
|
2000
|
-
cardId: string;
|
|
2001
|
-
courseId: string;
|
|
2002
|
-
status: string;
|
|
2003
|
-
}): void;
|
|
2004
|
-
}
|
|
2005
|
-
declare function getStudySource(source: ContentSourceID, user: UserDBInterface): Promise<StudyContentSource>;
|
|
2006
|
-
|
|
2007
|
-
export { type HydrationMarker as $, type UserDBWriter as A, type UserDBAuthenticator as B, type CourseDBInterface as C, type DataLayerResult as D, type UserCourseSettings as E, type FilterKind as F, type GeneratorResult as G, type UserCourseSetting as H, type UsrCrsDataInterface as I, type ClassroomRegistrationDesignation as J, type ClassroomRegistration as K, type ClassroomRegistrationDoc as L, type SessionTrackingData as M, NavigatorRole as N, type UserConfig as O, type ActivityRecord as P, type CourseRegistration as Q, type RegulatorReading as R, type StudySessionDoc as S, type UserOutcomeRecord as T, type UserDBInterface as U, makeStudySessionId as V, type WeightedCard as W, newSessionId as X, type UserHydrationState as Y, type UserHydrationStatus as Z, HYDRATION_MARKER_ID as _, type CoursesDBInterface as a, type NavigatorConstructor as a0, registerNavigator as a1, getRegisteredNavigator as a2, hasRegisteredNavigator as a3, getRegisteredNavigatorRole as a4, getRegisteredFilterKind as a5, getRegisteredNavigatorNames as a6, initializeNavigatorRegistry as a7, type StrategyContribution as a8, getCardOrigin as a9, createOrchestrationContext as aA, DEFAULT_REGULATOR_CONFIG as aB, reviewWeight as aC, reviewMassReading as aD, type IntakeClockState as aE, INTAKE_CLOCK_KEY as aF, resetIntakeClock as aG, frozenMsAt as aH, intakeHours as aI, stepIntakeClock as aJ, intakeReading as aK, applyReading as aL, type DocumentUpdater as aM, newInterval as aN, getStreak as aO, getLapses as aP, Navigators as aa, NavigatorRoles as ab, isGenerator as ac, isFilter as ad, type CardFilter as ae, type FilterContext as af, type CardFilterFactory as ag, type CardGenerator as ah, type GeneratorContext as ai, type CardGeneratorFactory as aj, pipelineDebugAPI as ak, mountPipelineDebugger as al, getActivePipeline as am, setDebugSessionId as an, getRunsForSession as ao, drainCapturedRuns as ap, type PipelineRunReport as aq, type RunReportCard as ar, type GeneratorSummary as as, type FilterImpact as at, type PipelineForecaster as au, type LearnableWeight as av, type OrchestrationContext as aw, computeDeviation as ax, computeSpread as ay, computeEffectiveWeight as az, type ContentNavigationStrategyData as b, type ScheduledCard as c, type CourseRegistrationDoc as d, type SessionStateSnapshot as e, type StudySessionRunSummary as f, type StudySessionRunCard as g, type RegulatorName as h, type SessionEloEvent as i, type StudySessionRunCardTrail as j, type CourseInfo as k, type StudySessionItem as l, ContentNavigator as m, type ReplanHints as n, type StudyContentSource as o, type StudySessionFailedItem as p, type StudySessionFailedNewItem as q, type StudySessionFailedReviewItem as r, type StudySessionNewItem as s, type StudySessionReviewItem as t, isReview as u, type ContentSourceID as v, getStudySource as w, type SessionStateSnapshotProvider as x, type RegulatorConfig as y, type UserDBReader as z };
|