@vue-skuilder/db 0.2.27 → 0.2.29

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 (82) 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-B6FrSihy.d.cts} +282 -99
  4. package/dist/{contentSource-D3c1fMAk.d.cts → contentSource-CqJmbOZN.d.ts} +282 -99
  5. package/dist/core/index.d.cts +16 -92
  6. package/dist/core/index.d.ts +16 -92
  7. package/dist/core/index.js +607 -179
  8. package/dist/core/index.js.map +1 -1
  9. package/dist/core/index.mjs +606 -179
  10. package/dist/core/index.mjs.map +1 -1
  11. package/dist/{dataLayerProvider-DaAootVV.d.ts → dataLayerProvider-B9_UCvkR.d.ts} +2 -8
  12. package/dist/{dataLayerProvider-CeLiFbHv.d.cts → dataLayerProvider-DUxDqMtZ.d.cts} +2 -8
  13. package/dist/diagnostics/index.d.cts +443 -0
  14. package/dist/diagnostics/index.d.ts +443 -0
  15. package/dist/diagnostics/index.js +932 -0
  16. package/dist/diagnostics/index.js.map +1 -0
  17. package/dist/diagnostics/index.mjs +881 -0
  18. package/dist/diagnostics/index.mjs.map +1 -0
  19. package/dist/impl/couch/index.d.cts +13 -3
  20. package/dist/impl/couch/index.d.ts +13 -3
  21. package/dist/impl/couch/index.js +605 -179
  22. package/dist/impl/couch/index.js.map +1 -1
  23. package/dist/impl/couch/index.mjs +605 -179
  24. package/dist/impl/couch/index.mjs.map +1 -1
  25. package/dist/impl/static/index.d.cts +11 -5
  26. package/dist/impl/static/index.d.ts +11 -5
  27. package/dist/impl/static/index.js +602 -185
  28. package/dist/impl/static/index.js.map +1 -1
  29. package/dist/impl/static/index.mjs +602 -185
  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 +73 -11
  34. package/dist/index.d.ts +73 -11
  35. package/dist/index.js +696 -200
  36. package/dist/index.js.map +1 -1
  37. package/dist/index.mjs +683 -200
  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/contentSource.ts +7 -0
  47. package/src/core/interfaces/dataLayerProvider.ts +3 -8
  48. package/src/core/navigators/Pipeline.ts +149 -14
  49. package/src/core/navigators/PipelineAssembler.ts +19 -40
  50. package/src/core/navigators/PipelineDebugger.ts +74 -17
  51. package/src/core/navigators/SrsDebugger.ts +37 -12
  52. package/src/core/navigators/defaults.ts +29 -5
  53. package/src/core/navigators/filters/WeightedFilter.ts +5 -1
  54. package/src/core/navigators/filters/eloDistance.ts +261 -76
  55. package/src/core/navigators/filters/hierarchyDefinition.ts +5 -1
  56. package/src/core/navigators/filters/index.ts +2 -2
  57. package/src/core/navigators/filters/interferenceMitigator.ts +5 -1
  58. package/src/core/navigators/filters/relativePriority.ts +5 -1
  59. package/src/core/navigators/filters/types.ts +24 -1
  60. package/src/core/navigators/filters/userTagPreference.ts +5 -1
  61. package/src/core/navigators/generators/elo.ts +23 -53
  62. package/src/core/navigators/generators/srs.ts +27 -124
  63. package/src/core/navigators/index.ts +32 -5
  64. package/src/core/navigators/pipelinePlan.ts +245 -0
  65. package/src/core/navigators/regulators.ts +230 -0
  66. package/src/core/types/studySession.ts +40 -0
  67. package/src/diagnostics/dataset.ts +242 -0
  68. package/src/diagnostics/derive.ts +555 -0
  69. package/src/diagnostics/index.ts +27 -0
  70. package/src/diagnostics/loader.ts +194 -0
  71. package/src/diagnostics/pipeline.ts +236 -0
  72. package/src/diagnostics/text.ts +265 -0
  73. package/src/impl/couch/PouchDataLayerProvider.ts +0 -23
  74. package/src/impl/couch/courseDB.ts +13 -0
  75. package/src/impl/static/StaticDataLayerProvider.ts +0 -11
  76. package/src/impl/static/courseDB.ts +9 -0
  77. package/src/index.ts +4 -0
  78. package/src/study/SessionController.ts +76 -2
  79. package/src/study/SessionOverlay.ts +7 -4
  80. package/tests/core/navigators/PipelineAssembler.test.ts +20 -5
  81. package/tests/core/navigators/eloDistanceFilter.test.ts +9 -9
  82. 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-CqJmbOZN.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-B6FrSihy.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,443 @@
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 { b as ContentNavigationStrategyData, S as StudySessionDoc, c as ScheduledCard, d as CourseRegistrationDoc, e as SessionStateSnapshot, f as StudySessionRunSummary, R as RegulatorReading, F as FilterKind, g as RegulatorName } from '../contentSource-B6FrSihy.cjs';
3
+ export { h as SessionEloEvent, i as StudySessionRunCard, j as StudySessionRunCardTrail } from '../contentSource-B6FrSihy.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. Later v1 dumps also carry `course.strategies` (optional).
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
+ * The course's NAVIGATION_STRATEGY docs, as they stood when the dump was
65
+ * taken (current state, not as of any session). Absent in older dumps.
66
+ */
67
+ strategies?: ContentNavigationStrategyData[];
68
+ }
69
+ /** A card-history record with an ISO `timeStamp`. Question fields exist on question records only. */
70
+ type DatasetRecord = Omit<CardRecord, 'timeStamp'> & Partial<Omit<QuestionRecord, keyof CardRecord>> & {
71
+ timeStamp: string;
72
+ };
73
+ /** A `CardHistory` whose records carry ISO timestamps. */
74
+ type DatasetCardHistory = Omit<CardHistory<CardRecord>, 'records'> & {
75
+ records: DatasetRecord[];
76
+ };
77
+ /** What a view or detector needs to know about a card, joined from the course slice. */
78
+ interface CardSummary {
79
+ cardId: string;
80
+ /** The question type's name, from `id_view` ("Course.question.Spelling.SpellingView" → "Spelling"). */
81
+ questionType?: string;
82
+ elo?: CardData['elo'];
83
+ /** Applied tags, from the course's TAG docs. */
84
+ tags: string[];
85
+ /** The card's displayable-data fields by name (the word, the answer, etc). */
86
+ data: Record<string, unknown>;
87
+ }
88
+ /** One learner in one course, indexed for reading. Built from a {@link LearnerDump} by {@link fromDump}. */
89
+ interface LearnerDataset {
90
+ username: string;
91
+ courseId: string;
92
+ /** When the records were read. Derivations take "now" from here, never the wall clock. */
93
+ asOf: string;
94
+ /** Oldest first. */
95
+ sessions: StudySessionDoc[];
96
+ /** Records oldest first, timestamps normalized to ISO. */
97
+ cardHistories: DatasetCardHistory[];
98
+ /** Pending reviews, soonest first. */
99
+ scheduled: ScheduledCard[];
100
+ registration?: CourseRegistrationDoc;
101
+ /** `STRATEGY_STATE` docs' `data`, by strategy key. */
102
+ strategyState: Record<string, unknown>;
103
+ tombstones: Array<{
104
+ id: string;
105
+ seq: number;
106
+ }>;
107
+ /** Absent when the dump carried no course slice. */
108
+ cards?: Map<string, CardSummary>;
109
+ /** The course's strategy docs at dump time. Absent when the dump didn't carry them. */
110
+ strategies?: ContentNavigationStrategyData[];
111
+ }
112
+ /**
113
+ * Normalize a stored timestamp to ISO. Card-history `timeStamp`s persist as
114
+ * `Moment.toString()` ("Sat Jul 18 2026 23:26:16 GMT+0000"), which sorts by
115
+ * weekday name, not time. Returns the input unchanged if it doesn't parse.
116
+ */
117
+ declare function toIsoTimestamp(value: unknown): string;
118
+ /** `userdb-<username>-2026-09-30T1412Z.json`: sortable and filename-safe. */
119
+ declare function dumpFileName(dump: Pick<LearnerDump, 'username' | 'fetchedAt'>): string;
120
+ /** Parse and minimally validate a dump file's text. */
121
+ declare function parseLearnerDump(text: string): LearnerDump;
122
+ /**
123
+ * Index a dump for one course. Records for other courses in the same user DB
124
+ * (retired or sibling courses) are left out.
125
+ */
126
+ declare function fromDump(dump: LearnerDump, courseId?: string): LearnerDataset;
127
+
128
+ type CouchAuth = {
129
+ kind: 'basic';
130
+ username: string;
131
+ password: string;
132
+ }
133
+ /** Browser: the signed-in admin's couch session cookie. */
134
+ | {
135
+ kind: 'cookie';
136
+ };
137
+ interface FetchLearnerDumpOptions {
138
+ /** Couch base URL, e.g. `https://example.com/couch`. */
139
+ couchUrl: string;
140
+ username: string;
141
+ courseId: string;
142
+ auth: CouchAuth;
143
+ /** Course-DB slice to include. Default `touched`. */
144
+ cards?: 'touched' | 'all' | 'none';
145
+ /** Inline user-DB attachments as base64. Default false. */
146
+ attachments?: boolean;
147
+ /** Defaults to the global `fetch`. */
148
+ fetchImpl?: typeof fetch;
149
+ }
150
+ /** couch_peruser convention: `userdb-` + lowercase hex of the username's UTF-8 bytes. */
151
+ declare function userDbName(username: string): string;
152
+ /**
153
+ * Read one learner's records for one course into a {@link LearnerDump}: the
154
+ * whole user DB, its tombstones, and (by default) the course cards the user
155
+ * has touched, with their displayable data and tags, plus the course's strategy
156
+ * docs. Needs admin rights on the couch, via basic auth or the browser's
157
+ * session cookie.
158
+ */
159
+ declare function fetchLearnerDump(opts: FetchLearnerDumpOptions): Promise<LearnerDump>;
160
+
161
+ /**
162
+ * Derivations over a `LearnerDataset`: pure functions that views, text
163
+ * exports, and (later) detectors share. Ported from LettersPractice's admin
164
+ * service, with LP's domain knowledge moved behind `DiagnosticsInterpreters`.
165
+ *
166
+ * "Now" is always `dataset.asOf`, never the wall clock, so a dump reads the
167
+ * same tomorrow as today.
168
+ */
169
+
170
+ /**
171
+ * Course-supplied meaning for the generic views. Every member is optional and
172
+ * has a neutral default.
173
+ */
174
+ interface DiagnosticsInterpreters {
175
+ /** Tags that name what a card exercises: shown inline and sorted first. Default: none. */
176
+ isSkillTag?(tag: string): boolean;
177
+ /** Compact display form of a tag. Default: unchanged. */
178
+ shortTag?(tag: string): string;
179
+ /**
180
+ * Numbers to read off a session's state snapshot, by display label.
181
+ * Default: every numeric field up to two levels deep, labelled by its path.
182
+ */
183
+ snapshotMetrics?(snapshot: SessionStateSnapshot): Record<string, number>;
184
+ /** Which `snapshotMetrics` labels count as progress (for `stalled`). Default: none. */
185
+ progressMetrics?: string[];
186
+ }
187
+ declare const isSkillTag: (i: DiagnosticsInterpreters | undefined, tag: string) => boolean;
188
+ declare const shortTag: (i: DiagnosticsInterpreters | undefined, tag: string) => string;
189
+ /**
190
+ * Ways a session failed to do its job. `out-of-content` is LP's `starved`,
191
+ * renamed so it isn't confused with intake starvation (no new cards chosen).
192
+ */
193
+ type SessionFlag = 'churned' | 'out-of-content' | 'walked' | 'stalled' | 'grinding';
194
+ declare const SESSION_FLAGS: Record<SessionFlag, {
195
+ label: string;
196
+ help: string;
197
+ }>;
198
+ /** First guesses, not measurements: nothing yet records whether a flag was right. */
199
+ declare const SESSION_FLAG_THRESHOLDS: {
200
+ /** Runs per card above which a session counts as churned. */
201
+ churnRunsPerCard: number;
202
+ /** Minimum cards before churn is meaningful. */
203
+ churnMinCards: number;
204
+ /** Leftover clock (s) that counts as running out of content. */
205
+ outOfContentSeconds: number;
206
+ /** Cards below which an abandon reads as a mis-click, not a walk-out. */
207
+ walkMinCards: number;
208
+ /** |ELO change| below which movement is flat. */
209
+ stallEloEpsilon: number;
210
+ /** Accuracy below which a session is grinding. */
211
+ grindAccuracy: number;
212
+ };
213
+ interface SessionStateRow {
214
+ label: string;
215
+ from: number | null;
216
+ to: number | null;
217
+ delta: number | null;
218
+ }
219
+ interface SessionSummary {
220
+ doc: StudySessionDoc;
221
+ /** Null while a session is `open`. */
222
+ durationSeconds: number | null;
223
+ accuracy: number | null;
224
+ /** Net learner global-ELO change over the session's ELO events. Null when it has none. */
225
+ eloNet: number | null;
226
+ /** Snapshot metrics at start and end. */
227
+ state: SessionStateRow[];
228
+ flags: SessionFlag[];
229
+ }
230
+ declare function summarizeSession(doc: StudySessionDoc, interp?: DiagnosticsInterpreters): SessionSummary;
231
+ /** Every session in the dataset, newest first. */
232
+ declare function summarizeSessions(ds: LearnerDataset, interp?: DiagnosticsInterpreters): SessionSummary[];
233
+ /** A `SessionEloEvent` reshaped for one response row: deltas precomputed, tags as a sorted array. */
234
+ interface ResponseEloDelta {
235
+ userScore: number;
236
+ global: {
237
+ before: number;
238
+ after: number;
239
+ delta: number;
240
+ };
241
+ card?: {
242
+ before: number;
243
+ after: number;
244
+ delta: number;
245
+ };
246
+ /** `score: null` is a count-only exposure that moves count, not ELO. */
247
+ tags: Array<{
248
+ tag: string;
249
+ before: number;
250
+ after: number;
251
+ delta: number;
252
+ score: number | null;
253
+ }>;
254
+ }
255
+ interface TimelineResponse {
256
+ kind: 'response';
257
+ at: string;
258
+ cardId: string;
259
+ /** Absent when the dataset has no course slice. */
260
+ card?: CardSummary;
261
+ tags: string[];
262
+ questionType?: string;
263
+ isCorrect: boolean | null;
264
+ timeSpentMs: number;
265
+ priorAttempts: number | null;
266
+ userAnswer: unknown;
267
+ /**
268
+ * The ELO exchange this response produced, joined from `eloEvents` by card
269
+ * and nearest time. Absent on retries (only first attempts move ELO), on
270
+ * events in flight at close, and on sessions predating ELO events.
271
+ */
272
+ elo?: ResponseEloDelta;
273
+ }
274
+ interface TimelineRun {
275
+ kind: 'run';
276
+ at: string;
277
+ run: StudySessionRunSummary;
278
+ }
279
+ /**
280
+ * Responses and pipeline runs in one time-ordered stream: a replan firing
281
+ * between two failures is the thing worth seeing, and a per-card pivot can't
282
+ * show sequence.
283
+ */
284
+ type TimelineEntry = TimelineResponse | TimelineRun;
285
+ interface SessionDetail {
286
+ summary: SessionSummary;
287
+ timeline: TimelineEntry[];
288
+ /** The tally claims more responses than records stamped with this session were found. */
289
+ responsesMissing: boolean;
290
+ }
291
+ /** One session's summary and interleaved timeline, or null if the dataset has no such session. */
292
+ declare function sessionDetail(ds: LearnerDataset, sessionId: string, interp?: DiagnosticsInterpreters): SessionDetail | null;
293
+ /** Per-tag rollup of what a session served. */
294
+ interface ServedTagStat {
295
+ tag: string;
296
+ /** Responses carrying this tag (a response with several tags counts toward each). */
297
+ responses: number;
298
+ correct: number;
299
+ incorrect: number;
300
+ /** correct / graded; null when nothing gradeable was served. */
301
+ accuracy: number | null;
302
+ totalTimeMs: number;
303
+ /** Distinct cards carrying this tag. */
304
+ cards: number;
305
+ }
306
+ /** Skill tags first, then most-served. */
307
+ declare function servedTags(timeline: TimelineEntry[], interp?: DiagnosticsInterpreters): ServedTagStat[];
308
+ /**
309
+ * A session's net global-ELO move split into wins and losses, so an
310
+ * accuracy/ELO mismatch (many small wins, a few big losses) is legible.
311
+ */
312
+ interface EloLedger {
313
+ count: number;
314
+ net: number;
315
+ gained: number;
316
+ lost: number;
317
+ wins: number;
318
+ losses: number;
319
+ }
320
+ declare function eloLedger(timeline: TimelineEntry[]): EloLedger | null;
321
+ /** Everything recorded about one card for one learner. */
322
+ interface CardDossier {
323
+ cardId: string;
324
+ /** Absent when the dataset has no course slice. */
325
+ card?: CardSummary;
326
+ records: DatasetRecord[];
327
+ lapses: number;
328
+ streak: number;
329
+ bestIntervalSeconds: number;
330
+ attempts: number;
331
+ fails: number;
332
+ firstSeen: string | null;
333
+ lastSeen: string | null;
334
+ totalTimeMs: number;
335
+ /** Earliest pending review; `overdue` is as of `dataset.asOf`. */
336
+ pendingReview: {
337
+ reviewTime: string;
338
+ overdue: boolean;
339
+ } | null;
340
+ cardElo: number | null;
341
+ cardEloCount: number | null;
342
+ /** Failed, and holding an overdue review. */
343
+ stuck: boolean;
344
+ /** Failed repeatedly, yet the card's ELO has fewer updates than failures. */
345
+ frozenElo: boolean;
346
+ /** Time sunk × (fails + 1): grind-heavy, low-payoff cards first. For sorting only. */
347
+ painScore: number;
348
+ }
349
+ /** One dossier per card the learner has history with, most painful first. */
350
+ declare function cardDossiers(ds: LearnerDataset): CardDossier[];
351
+ /** A record's global performance, whether stored as a number or a per-tag map. */
352
+ declare function recordPerformance(r: DatasetRecord): number | null;
353
+
354
+ /**
355
+ * Plain-text renderings of derivations, for pasting into an LLM or a note.
356
+ * Every admin view that shows something should be able to hand it out as
357
+ * text; these are those texts. Also the shared number formatting.
358
+ */
359
+
360
+ /** Signed, at most one decimal; `—` for null. */
361
+ declare function fmtDelta(d: number | null): string;
362
+ /** 45s, 3m20s, 1.5h. */
363
+ declare function fmtDuration(seconds: number): string;
364
+ declare function fmtAnswer(a: unknown, max?: number): string;
365
+ /** One regulator reading as a line: its urgency, inputs, and multiplier. */
366
+ declare function regulatorText(r: RegulatorReading): string;
367
+ /** One run as a compact text block. */
368
+ declare function runText(run: StudySessionRunSummary): string;
369
+ /** Per-tag ELO deltas worth showing inline: scored, non-zero, at most four. */
370
+ declare function scoredTagDeltas(elo: ResponseEloDelta): ResponseEloDelta['tags'];
371
+ /**
372
+ * A whole session as plain text, led by a legend so the numbers read without
373
+ * the UI.
374
+ */
375
+ declare function sessionText(username: string, detail: SessionDetail, extras?: {
376
+ servedTags?: ServedTagStat[];
377
+ eloLedger?: EloLedger | null;
378
+ }, interp?: DiagnosticsInterpreters): string;
379
+
380
+ /** One generator across persisted runs. */
381
+ interface GeneratorRunStat {
382
+ /** The name runs report it under (its strategy doc's name). */
383
+ name: string;
384
+ /** Runs it emitted at least one candidate in. */
385
+ runs: number;
386
+ /** Mean candidates per run, over the runs it appeared in. */
387
+ meanCards: number;
388
+ meanNew: number;
389
+ meanReview: number;
390
+ topScoreMax: number;
391
+ /** Top score in the most recent run it appeared in. */
392
+ topScoreLast: number;
393
+ /** Selected cards it originated (first provenance entry), over runs that persist selection. */
394
+ selected: number;
395
+ /** First attempts at those cards in the same session. */
396
+ firstAttempts: number;
397
+ firstAttemptsCorrect: number;
398
+ }
399
+ /** One filter across persisted runs: candidate counts summed over runs. */
400
+ interface FilterRunStat {
401
+ name: string;
402
+ /** As recorded by the most recent run that recorded it (0.2.29+). */
403
+ kind?: FilterKind;
404
+ runs: number;
405
+ boosted: number;
406
+ penalized: number;
407
+ passed: number;
408
+ removed: number;
409
+ }
410
+ /** One regulator across persisted runs (0.2.29+). */
411
+ interface RegulatorRunStat {
412
+ name: RegulatorName;
413
+ class: RegulatorReading['class'];
414
+ runs: number;
415
+ meanMultiplier: number;
416
+ maxMultiplier: number;
417
+ /** Runs where the multiplier was above 1. */
418
+ runsActive: number;
419
+ /** The most recent reading. */
420
+ last: RegulatorReading;
421
+ }
422
+ interface PipelineRunStats {
423
+ sessions: number;
424
+ runs: number;
425
+ /** Runs that persist their selected cards. Selection and outcome counts cover only these. */
426
+ runsWithSelection: number;
427
+ firstRunAt?: string;
428
+ lastRunAt?: string;
429
+ /** Busiest first. */
430
+ generators: GeneratorRunStat[];
431
+ /** By name. */
432
+ filters: FilterRunStat[];
433
+ /** Empty before 0.2.29. */
434
+ regulators: RegulatorRunStat[];
435
+ /** Selected cards with no originating generator: cards forced in by `requireCards`. */
436
+ selectedUnattributed: number;
437
+ }
438
+ /** Aggregate a learner's persisted pipeline runs, optionally only sessions started at or after `since` (ISO). */
439
+ declare function pipelineRunStats(ds: LearnerDataset, opts?: {
440
+ since?: string;
441
+ }): PipelineRunStats;
442
+
443
+ export { type CardDossier, type CardSummary, type CouchAuth, type CourseSlice, type DatasetCardHistory, type DatasetRecord, type DiagnosticsInterpreters, type EloLedger, type FetchLearnerDumpOptions, FilterKind, type FilterRunStat, type GeneratorRunStat, type LearnerDataset, type LearnerDump, type PipelineRunStats, RegulatorName, RegulatorReading, type RegulatorRunStat, 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, pipelineRunStats, recordPerformance, regulatorText, runText, scoredTagDeltas, servedTags, sessionDetail, sessionText, shortTag, summarizeSession, summarizeSessions, toIsoTimestamp, userDbName };