@vue-skuilder/db 0.2.27 → 0.2.28

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. package/dist/classroomDB-DLTtLZct.d.cts +86 -0
  2. package/dist/classroomDB-DLTtLZct.d.ts +86 -0
  3. package/dist/{contentSource-LPf044hY.d.ts → contentSource-BoFBwvYa.d.ts} +65 -98
  4. package/dist/{contentSource-D3c1fMAk.d.cts → contentSource-DpQqTG3m.d.cts} +65 -98
  5. package/dist/core/index.d.cts +6 -5
  6. package/dist/core/index.d.ts +6 -5
  7. package/dist/core/index.js +22 -2
  8. package/dist/core/index.js.map +1 -1
  9. package/dist/core/index.mjs +22 -2
  10. package/dist/core/index.mjs.map +1 -1
  11. package/dist/{dataLayerProvider-DaAootVV.d.ts → dataLayerProvider-D_LJT3F4.d.ts} +2 -8
  12. package/dist/{dataLayerProvider-CeLiFbHv.d.cts → dataLayerProvider-Dl3cAAvQ.d.cts} +2 -8
  13. package/dist/diagnostics/index.d.cts +370 -0
  14. package/dist/diagnostics/index.d.ts +370 -0
  15. package/dist/diagnostics/index.js +778 -0
  16. package/dist/diagnostics/index.js.map +1 -0
  17. package/dist/diagnostics/index.mjs +729 -0
  18. package/dist/diagnostics/index.mjs.map +1 -0
  19. package/dist/impl/couch/index.d.cts +4 -3
  20. package/dist/impl/couch/index.d.ts +4 -3
  21. package/dist/impl/couch/index.js +22 -2
  22. package/dist/impl/couch/index.js.map +1 -1
  23. package/dist/impl/couch/index.mjs +22 -2
  24. package/dist/impl/couch/index.mjs.map +1 -1
  25. package/dist/impl/static/index.d.cts +5 -5
  26. package/dist/impl/static/index.d.ts +5 -5
  27. package/dist/impl/static/index.js +22 -8
  28. package/dist/impl/static/index.js.map +1 -1
  29. package/dist/impl/static/index.mjs +22 -8
  30. package/dist/impl/static/index.mjs.map +1 -1
  31. package/dist/{index-BkBJlGDX.d.ts → index-CVGehe_t.d.ts} +1 -1
  32. package/dist/{index-D7WdMDAs.d.cts → index-Ktg72jKb.d.cts} +1 -1
  33. package/dist/index.d.cts +10 -9
  34. package/dist/index.d.ts +10 -9
  35. package/dist/index.js +64 -23
  36. package/dist/index.js.map +1 -1
  37. package/dist/index.mjs +64 -23
  38. package/dist/index.mjs.map +1 -1
  39. package/dist/{types-DjiFOZxJ.d.cts → types-D0oQeJAi.d.cts} +1 -1
  40. package/dist/{types-uJ2Xn3_X.d.ts → types-dXWfyz9B.d.ts} +1 -1
  41. package/dist/{types-legacy-CrwyZIvI.d.cts → types-legacy-BkOYOR6U.d.cts} +1 -1
  42. package/dist/{types-legacy-CrwyZIvI.d.ts → types-legacy-BkOYOR6U.d.ts} +1 -1
  43. package/dist/util/packer/index.d.cts +3 -3
  44. package/dist/util/packer/index.d.ts +3 -3
  45. package/package.json +15 -3
  46. package/src/core/interfaces/dataLayerProvider.ts +3 -8
  47. package/src/core/navigators/Pipeline.ts +5 -2
  48. package/src/core/navigators/PipelineDebugger.ts +64 -16
  49. package/src/core/navigators/index.ts +1 -0
  50. package/src/core/types/studySession.ts +37 -0
  51. package/src/diagnostics/dataset.ts +231 -0
  52. package/src/diagnostics/derive.ts +555 -0
  53. package/src/diagnostics/index.ts +24 -0
  54. package/src/diagnostics/loader.ts +191 -0
  55. package/src/diagnostics/text.ts +242 -0
  56. package/src/impl/couch/PouchDataLayerProvider.ts +0 -23
  57. package/src/impl/static/StaticDataLayerProvider.ts +0 -11
  58. package/src/study/SessionController.ts +56 -2
  59. package/tsup.config.ts +1 -0
@@ -1,4 +1,5 @@
1
- import { U as UserDBInterface, a as UserDBReader, C as CourseDBInterface, b as CoursesDBInterface, c as ClassroomDBInterface, A as AdminDBInterface } from './contentSource-LPf044hY.js';
1
+ import { U as UserDBInterface, C as CourseDBInterface, a as CoursesDBInterface } from './contentSource-BoFBwvYa.js';
2
+ import { C as ClassroomDBInterface, A as AdminDBInterface } from './classroomDB-DLTtLZct.js';
2
3
 
3
4
  /**
4
5
  * Main factory interface for data access
@@ -8,13 +9,6 @@ interface DataLayerProvider {
8
9
  * Get the user database interface
9
10
  */
10
11
  getUserDB(): UserDBInterface;
11
- /**
12
- * Create a UserDBReader for a specific user (admin access required)
13
- * Uses session authentication to verify requesting user is admin
14
- * @param targetUsername - The username to create a reader for
15
- * @throws Error if requesting user is not 'admin'
16
- */
17
- createUserReaderForUser(targetUsername: string): Promise<UserDBReader>;
18
12
  /**
19
13
  * Get a course database interface
20
14
  */
@@ -1,4 +1,5 @@
1
- import { U as UserDBInterface, a as UserDBReader, C as CourseDBInterface, b as CoursesDBInterface, c as ClassroomDBInterface, A as AdminDBInterface } from './contentSource-D3c1fMAk.cjs';
1
+ import { U as UserDBInterface, C as CourseDBInterface, a as CoursesDBInterface } from './contentSource-DpQqTG3m.cjs';
2
+ import { C as ClassroomDBInterface, A as AdminDBInterface } from './classroomDB-DLTtLZct.cjs';
2
3
 
3
4
  /**
4
5
  * Main factory interface for data access
@@ -8,13 +9,6 @@ interface DataLayerProvider {
8
9
  * Get the user database interface
9
10
  */
10
11
  getUserDB(): UserDBInterface;
11
- /**
12
- * Create a UserDBReader for a specific user (admin access required)
13
- * Uses session authentication to verify requesting user is admin
14
- * @param targetUsername - The username to create a reader for
15
- * @throws Error if requesting user is not 'admin'
16
- */
17
- createUserReaderForUser(targetUsername: string): Promise<UserDBReader>;
18
12
  /**
19
13
  * Get a course database interface
20
14
  */
@@ -0,0 +1,370 @@
1
+ import { C as CardData, a as DisplayableData, T as Tag, b as CardRecord, Q as QuestionRecord, c as CardHistory } from '../types-legacy-BkOYOR6U.cjs';
2
+ import { S as StudySessionDoc, b as ScheduledCard, c as CourseRegistrationDoc, d as SessionStateSnapshot, e as StudySessionRunSummary } from '../contentSource-DpQqTG3m.cjs';
3
+ export { f as SessionEloEvent, g as StudySessionRunCard, h as StudySessionRunCardTrail } from '../contentSource-DpQqTG3m.cjs';
4
+ import '@vue-skuilder/common';
5
+ import 'moment';
6
+
7
+ type RawDoc = {
8
+ _id: string;
9
+ [key: string]: unknown;
10
+ };
11
+ /**
12
+ * A learner's raw records, as fetched. This is the on-disk dump format: the
13
+ * `dump-user` CLI writes it, an admin UI can load it from a file, and every
14
+ * loader produces it. Readers must tolerate every past version.
15
+ *
16
+ * - v0 (LP `scripts/dump-user-db.ts` before 2026-09-30): no `formatVersion`,
17
+ * `courseId`, `tombstones`, or `course`.
18
+ * - v1: adds all four.
19
+ */
20
+ interface LearnerDump {
21
+ formatVersion?: 1;
22
+ username: string;
23
+ dbName: string;
24
+ /** The couch base URL the records came from. */
25
+ source: string;
26
+ fetchedAt: string;
27
+ courseId?: string;
28
+ /** The couch `GET /{db}` response. */
29
+ info?: unknown;
30
+ /** Every user-DB doc, raw (`_id`/`_rev` kept, `_design` docs included). */
31
+ docs: RawDoc[];
32
+ /**
33
+ * Deleted user-DB docs. Completed reviews are deleted, so deleted
34
+ * `card_review_<reviewTime>` ids are the only record of past due times.
35
+ * `seq` is the numeric prefix of the couch seq: order, not time.
36
+ */
37
+ tombstones?: Array<{
38
+ id: string;
39
+ rev?: string;
40
+ seq: number;
41
+ }>;
42
+ course?: CourseSlice;
43
+ }
44
+ interface CourseSlice {
45
+ courseId: string;
46
+ source?: string;
47
+ /** `touched`: cards the user has history, schedule, or ELO events for. `all`: every card. */
48
+ scope: 'touched' | 'all';
49
+ cards: Array<CardData & {
50
+ _id: string;
51
+ }>;
52
+ displayableData: Array<DisplayableData & {
53
+ _id: string;
54
+ }>;
55
+ /**
56
+ * TAG docs. Under `touched`, `taggedCards` is narrowed to the included cards
57
+ * and `taggedCount` keeps the full length.
58
+ */
59
+ tags: Array<Tag & {
60
+ _id: string;
61
+ taggedCount: number;
62
+ }>;
63
+ }
64
+ /** A card-history record with an ISO `timeStamp`. Question fields exist on question records only. */
65
+ type DatasetRecord = Omit<CardRecord, 'timeStamp'> & Partial<Omit<QuestionRecord, keyof CardRecord>> & {
66
+ timeStamp: string;
67
+ };
68
+ /** A `CardHistory` whose records carry ISO timestamps. */
69
+ type DatasetCardHistory = Omit<CardHistory<CardRecord>, 'records'> & {
70
+ records: DatasetRecord[];
71
+ };
72
+ /** What a view or detector needs to know about a card, joined from the course slice. */
73
+ interface CardSummary {
74
+ cardId: string;
75
+ /** The question type's name, from `id_view` ("Course.question.Spelling.SpellingView" → "Spelling"). */
76
+ questionType?: string;
77
+ elo?: CardData['elo'];
78
+ /** Applied tags, from the course's TAG docs. */
79
+ tags: string[];
80
+ /** The card's displayable-data fields by name (the word, the answer, etc). */
81
+ data: Record<string, unknown>;
82
+ }
83
+ /** One learner in one course, indexed for reading. Built from a {@link LearnerDump} by {@link fromDump}. */
84
+ interface LearnerDataset {
85
+ username: string;
86
+ courseId: string;
87
+ /** When the records were read. Derivations take "now" from here, never the wall clock. */
88
+ asOf: string;
89
+ /** Oldest first. */
90
+ sessions: StudySessionDoc[];
91
+ /** Records oldest first, timestamps normalized to ISO. */
92
+ cardHistories: DatasetCardHistory[];
93
+ /** Pending reviews, soonest first. */
94
+ scheduled: ScheduledCard[];
95
+ registration?: CourseRegistrationDoc;
96
+ /** `STRATEGY_STATE` docs' `data`, by strategy key. */
97
+ strategyState: Record<string, unknown>;
98
+ tombstones: Array<{
99
+ id: string;
100
+ seq: number;
101
+ }>;
102
+ /** Absent when the dump carried no course slice. */
103
+ cards?: Map<string, CardSummary>;
104
+ }
105
+ /**
106
+ * Normalize a stored timestamp to ISO. Card-history `timeStamp`s persist as
107
+ * `Moment.toString()` ("Sat Jul 18 2026 23:26:16 GMT+0000"), which sorts by
108
+ * weekday name, not time. Returns the input unchanged if it doesn't parse.
109
+ */
110
+ declare function toIsoTimestamp(value: unknown): string;
111
+ /** `userdb-<username>-2026-09-30T1412Z.json`: sortable and filename-safe. */
112
+ declare function dumpFileName(dump: Pick<LearnerDump, 'username' | 'fetchedAt'>): string;
113
+ /** Parse and minimally validate a dump file's text. */
114
+ declare function parseLearnerDump(text: string): LearnerDump;
115
+ /**
116
+ * Index a dump for one course. Records for other courses in the same user DB
117
+ * (retired or sibling courses) are left out.
118
+ */
119
+ declare function fromDump(dump: LearnerDump, courseId?: string): LearnerDataset;
120
+
121
+ type CouchAuth = {
122
+ kind: 'basic';
123
+ username: string;
124
+ password: string;
125
+ }
126
+ /** Browser: the signed-in admin's couch session cookie. */
127
+ | {
128
+ kind: 'cookie';
129
+ };
130
+ interface FetchLearnerDumpOptions {
131
+ /** Couch base URL, e.g. `https://example.com/couch`. */
132
+ couchUrl: string;
133
+ username: string;
134
+ courseId: string;
135
+ auth: CouchAuth;
136
+ /** Course-DB slice to include. Default `touched`. */
137
+ cards?: 'touched' | 'all' | 'none';
138
+ /** Inline user-DB attachments as base64. Default false. */
139
+ attachments?: boolean;
140
+ /** Defaults to the global `fetch`. */
141
+ fetchImpl?: typeof fetch;
142
+ }
143
+ /** couch_peruser convention: `userdb-` + lowercase hex of the username's UTF-8 bytes. */
144
+ declare function userDbName(username: string): string;
145
+ /**
146
+ * Read one learner's records for one course into a {@link LearnerDump}: the
147
+ * whole user DB, its tombstones, and (by default) the course cards the user
148
+ * has touched, with their displayable data and tags. Needs admin rights on
149
+ * the couch, via basic auth or the browser's session cookie.
150
+ */
151
+ declare function fetchLearnerDump(opts: FetchLearnerDumpOptions): Promise<LearnerDump>;
152
+
153
+ /**
154
+ * Derivations over a `LearnerDataset`: pure functions that views, text
155
+ * exports, and (later) detectors share. Ported from LettersPractice's admin
156
+ * service, with LP's domain knowledge moved behind `DiagnosticsInterpreters`.
157
+ *
158
+ * "Now" is always `dataset.asOf`, never the wall clock, so a dump reads the
159
+ * same tomorrow as today.
160
+ */
161
+
162
+ /**
163
+ * Course-supplied meaning for the generic views. Every member is optional and
164
+ * has a neutral default.
165
+ */
166
+ interface DiagnosticsInterpreters {
167
+ /** Tags that name what a card exercises: shown inline and sorted first. Default: none. */
168
+ isSkillTag?(tag: string): boolean;
169
+ /** Compact display form of a tag. Default: unchanged. */
170
+ shortTag?(tag: string): string;
171
+ /**
172
+ * Numbers to read off a session's state snapshot, by display label.
173
+ * Default: every numeric field up to two levels deep, labelled by its path.
174
+ */
175
+ snapshotMetrics?(snapshot: SessionStateSnapshot): Record<string, number>;
176
+ /** Which `snapshotMetrics` labels count as progress (for `stalled`). Default: none. */
177
+ progressMetrics?: string[];
178
+ }
179
+ declare const isSkillTag: (i: DiagnosticsInterpreters | undefined, tag: string) => boolean;
180
+ declare const shortTag: (i: DiagnosticsInterpreters | undefined, tag: string) => string;
181
+ /**
182
+ * Ways a session failed to do its job. `out-of-content` is LP's `starved`,
183
+ * renamed so it isn't confused with intake starvation (no new cards chosen).
184
+ */
185
+ type SessionFlag = 'churned' | 'out-of-content' | 'walked' | 'stalled' | 'grinding';
186
+ declare const SESSION_FLAGS: Record<SessionFlag, {
187
+ label: string;
188
+ help: string;
189
+ }>;
190
+ /** First guesses, not measurements: nothing yet records whether a flag was right. */
191
+ declare const SESSION_FLAG_THRESHOLDS: {
192
+ /** Runs per card above which a session counts as churned. */
193
+ churnRunsPerCard: number;
194
+ /** Minimum cards before churn is meaningful. */
195
+ churnMinCards: number;
196
+ /** Leftover clock (s) that counts as running out of content. */
197
+ outOfContentSeconds: number;
198
+ /** Cards below which an abandon reads as a mis-click, not a walk-out. */
199
+ walkMinCards: number;
200
+ /** |ELO change| below which movement is flat. */
201
+ stallEloEpsilon: number;
202
+ /** Accuracy below which a session is grinding. */
203
+ grindAccuracy: number;
204
+ };
205
+ interface SessionStateRow {
206
+ label: string;
207
+ from: number | null;
208
+ to: number | null;
209
+ delta: number | null;
210
+ }
211
+ interface SessionSummary {
212
+ doc: StudySessionDoc;
213
+ /** Null while a session is `open`. */
214
+ durationSeconds: number | null;
215
+ accuracy: number | null;
216
+ /** Net learner global-ELO change over the session's ELO events. Null when it has none. */
217
+ eloNet: number | null;
218
+ /** Snapshot metrics at start and end. */
219
+ state: SessionStateRow[];
220
+ flags: SessionFlag[];
221
+ }
222
+ declare function summarizeSession(doc: StudySessionDoc, interp?: DiagnosticsInterpreters): SessionSummary;
223
+ /** Every session in the dataset, newest first. */
224
+ declare function summarizeSessions(ds: LearnerDataset, interp?: DiagnosticsInterpreters): SessionSummary[];
225
+ /** A `SessionEloEvent` reshaped for one response row: deltas precomputed, tags as a sorted array. */
226
+ interface ResponseEloDelta {
227
+ userScore: number;
228
+ global: {
229
+ before: number;
230
+ after: number;
231
+ delta: number;
232
+ };
233
+ card?: {
234
+ before: number;
235
+ after: number;
236
+ delta: number;
237
+ };
238
+ /** `score: null` is a count-only exposure that moves count, not ELO. */
239
+ tags: Array<{
240
+ tag: string;
241
+ before: number;
242
+ after: number;
243
+ delta: number;
244
+ score: number | null;
245
+ }>;
246
+ }
247
+ interface TimelineResponse {
248
+ kind: 'response';
249
+ at: string;
250
+ cardId: string;
251
+ /** Absent when the dataset has no course slice. */
252
+ card?: CardSummary;
253
+ tags: string[];
254
+ questionType?: string;
255
+ isCorrect: boolean | null;
256
+ timeSpentMs: number;
257
+ priorAttempts: number | null;
258
+ userAnswer: unknown;
259
+ /**
260
+ * The ELO exchange this response produced, joined from `eloEvents` by card
261
+ * and nearest time. Absent on retries (only first attempts move ELO), on
262
+ * events in flight at close, and on sessions predating ELO events.
263
+ */
264
+ elo?: ResponseEloDelta;
265
+ }
266
+ interface TimelineRun {
267
+ kind: 'run';
268
+ at: string;
269
+ run: StudySessionRunSummary;
270
+ }
271
+ /**
272
+ * Responses and pipeline runs in one time-ordered stream: a replan firing
273
+ * between two failures is the thing worth seeing, and a per-card pivot can't
274
+ * show sequence.
275
+ */
276
+ type TimelineEntry = TimelineResponse | TimelineRun;
277
+ interface SessionDetail {
278
+ summary: SessionSummary;
279
+ timeline: TimelineEntry[];
280
+ /** The tally claims more responses than records stamped with this session were found. */
281
+ responsesMissing: boolean;
282
+ }
283
+ /** One session's summary and interleaved timeline, or null if the dataset has no such session. */
284
+ declare function sessionDetail(ds: LearnerDataset, sessionId: string, interp?: DiagnosticsInterpreters): SessionDetail | null;
285
+ /** Per-tag rollup of what a session served. */
286
+ interface ServedTagStat {
287
+ tag: string;
288
+ /** Responses carrying this tag (a response with several tags counts toward each). */
289
+ responses: number;
290
+ correct: number;
291
+ incorrect: number;
292
+ /** correct / graded; null when nothing gradeable was served. */
293
+ accuracy: number | null;
294
+ totalTimeMs: number;
295
+ /** Distinct cards carrying this tag. */
296
+ cards: number;
297
+ }
298
+ /** Skill tags first, then most-served. */
299
+ declare function servedTags(timeline: TimelineEntry[], interp?: DiagnosticsInterpreters): ServedTagStat[];
300
+ /**
301
+ * A session's net global-ELO move split into wins and losses, so an
302
+ * accuracy/ELO mismatch (many small wins, a few big losses) is legible.
303
+ */
304
+ interface EloLedger {
305
+ count: number;
306
+ net: number;
307
+ gained: number;
308
+ lost: number;
309
+ wins: number;
310
+ losses: number;
311
+ }
312
+ declare function eloLedger(timeline: TimelineEntry[]): EloLedger | null;
313
+ /** Everything recorded about one card for one learner. */
314
+ interface CardDossier {
315
+ cardId: string;
316
+ /** Absent when the dataset has no course slice. */
317
+ card?: CardSummary;
318
+ records: DatasetRecord[];
319
+ lapses: number;
320
+ streak: number;
321
+ bestIntervalSeconds: number;
322
+ attempts: number;
323
+ fails: number;
324
+ firstSeen: string | null;
325
+ lastSeen: string | null;
326
+ totalTimeMs: number;
327
+ /** Earliest pending review; `overdue` is as of `dataset.asOf`. */
328
+ pendingReview: {
329
+ reviewTime: string;
330
+ overdue: boolean;
331
+ } | null;
332
+ cardElo: number | null;
333
+ cardEloCount: number | null;
334
+ /** Failed, and holding an overdue review. */
335
+ stuck: boolean;
336
+ /** Failed repeatedly, yet the card's ELO has fewer updates than failures. */
337
+ frozenElo: boolean;
338
+ /** Time sunk × (fails + 1): grind-heavy, low-payoff cards first. For sorting only. */
339
+ painScore: number;
340
+ }
341
+ /** One dossier per card the learner has history with, most painful first. */
342
+ declare function cardDossiers(ds: LearnerDataset): CardDossier[];
343
+ /** A record's global performance, whether stored as a number or a per-tag map. */
344
+ declare function recordPerformance(r: DatasetRecord): number | null;
345
+
346
+ /**
347
+ * Plain-text renderings of derivations, for pasting into an LLM or a note.
348
+ * Every admin view that shows something should be able to hand it out as
349
+ * text; these are those texts. Also the shared number formatting.
350
+ */
351
+
352
+ /** Signed, at most one decimal; `—` for null. */
353
+ declare function fmtDelta(d: number | null): string;
354
+ /** 45s, 3m20s, 1.5h. */
355
+ declare function fmtDuration(seconds: number): string;
356
+ declare function fmtAnswer(a: unknown, max?: number): string;
357
+ /** One run as a compact text block. */
358
+ declare function runText(run: StudySessionRunSummary): string;
359
+ /** Per-tag ELO deltas worth showing inline: scored, non-zero, at most four. */
360
+ declare function scoredTagDeltas(elo: ResponseEloDelta): ResponseEloDelta['tags'];
361
+ /**
362
+ * A whole session as plain text, led by a legend so the numbers read without
363
+ * the UI.
364
+ */
365
+ declare function sessionText(username: string, detail: SessionDetail, extras?: {
366
+ servedTags?: ServedTagStat[];
367
+ eloLedger?: EloLedger | null;
368
+ }, interp?: DiagnosticsInterpreters): string;
369
+
370
+ export { type CardDossier, type CardSummary, type CouchAuth, type CourseSlice, type DatasetCardHistory, type DatasetRecord, type DiagnosticsInterpreters, type EloLedger, type FetchLearnerDumpOptions, type LearnerDataset, type LearnerDump, type ResponseEloDelta, SESSION_FLAGS, SESSION_FLAG_THRESHOLDS, type ServedTagStat, type SessionDetail, type SessionFlag, type SessionStateRow, SessionStateSnapshot, type SessionSummary, StudySessionDoc, StudySessionRunSummary, type TimelineEntry, type TimelineResponse, type TimelineRun, cardDossiers, dumpFileName, eloLedger, fetchLearnerDump, fmtAnswer, fmtDelta, fmtDuration, fromDump, isSkillTag, parseLearnerDump, recordPerformance, runText, scoredTagDeltas, servedTags, sessionDetail, sessionText, shortTag, summarizeSession, summarizeSessions, toIsoTimestamp, userDbName };