@vue-skuilder/db 0.2.21 → 0.2.23

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 (48) hide show
  1. package/dist/{contentSource-BMxsujRu.d.cts → contentSource-BvOpKUeU.d.ts} +442 -79
  2. package/dist/{contentSource-Bazgkf4C.d.ts → contentSource-DT9NaX69.d.cts} +442 -79
  3. package/dist/core/index.d.cts +84 -342
  4. package/dist/core/index.d.ts +84 -342
  5. package/dist/core/index.js +79 -4
  6. package/dist/core/index.js.map +1 -1
  7. package/dist/core/index.mjs +74 -4
  8. package/dist/core/index.mjs.map +1 -1
  9. package/dist/{dataLayerProvider-Bt-D6xas.d.ts → dataLayerProvider-CY2B2lyW.d.ts} +1 -1
  10. package/dist/{dataLayerProvider-DifVCcIS.d.cts → dataLayerProvider-wY6s_4x9.d.cts} +1 -1
  11. package/dist/impl/couch/index.d.cts +3 -3
  12. package/dist/impl/couch/index.d.ts +3 -3
  13. package/dist/impl/couch/index.js +63 -4
  14. package/dist/impl/couch/index.js.map +1 -1
  15. package/dist/impl/couch/index.mjs +63 -4
  16. package/dist/impl/couch/index.mjs.map +1 -1
  17. package/dist/impl/static/index.d.cts +4 -4
  18. package/dist/impl/static/index.d.ts +4 -4
  19. package/dist/impl/static/index.js +63 -4
  20. package/dist/impl/static/index.js.map +1 -1
  21. package/dist/impl/static/index.mjs +63 -4
  22. package/dist/impl/static/index.mjs.map +1 -1
  23. package/dist/{index-BLLT5BYE.d.ts → index-BkBJlGDX.d.ts} +1 -1
  24. package/dist/{index-k9NFHpS1.d.cts → index-D7WdMDAs.d.cts} +1 -1
  25. package/dist/index.d.cts +51 -14
  26. package/dist/index.d.ts +51 -14
  27. package/dist/index.js +240 -12
  28. package/dist/index.js.map +1 -1
  29. package/dist/index.mjs +235 -12
  30. package/dist/index.mjs.map +1 -1
  31. package/dist/{types-BFUa1pa3.d.cts → types-DjiFOZxJ.d.cts} +1 -1
  32. package/dist/{types-legacy-4tlwHnXo.d.cts → types-legacy-CrwyZIvI.d.cts} +10 -2
  33. package/dist/{types-legacy-4tlwHnXo.d.ts → types-legacy-CrwyZIvI.d.ts} +10 -2
  34. package/dist/{types-CHgpWQAY.d.ts → types-uJ2Xn3_X.d.ts} +1 -1
  35. package/dist/util/packer/index.d.cts +3 -3
  36. package/dist/util/packer/index.d.ts +3 -3
  37. package/package.json +3 -3
  38. package/src/core/index.ts +1 -0
  39. package/src/core/interfaces/userDB.ts +7 -0
  40. package/src/core/navigators/PipelineDebugger.ts +41 -1
  41. package/src/core/navigators/index.ts +3 -0
  42. package/src/core/types/studySession.ts +125 -0
  43. package/src/core/types/types-legacy.ts +8 -0
  44. package/src/impl/common/BaseUserDB.ts +36 -0
  45. package/src/study/SessionController.ts +188 -2
  46. package/src/study/SessionDebugger.ts +4 -3
  47. package/src/study/SessionOverlay.ts +1 -0
  48. package/src/study/services/ResponseProcessor.ts +32 -4
@@ -1,89 +1,11 @@
1
- import { ab as LearnableWeight, M as UserOutcomeRecord, ac as OrchestrationContext, W as WeightedCard, U as UserDBInterface, C as CourseDBInterface, R as ReplanHints, a1 as StrategyContribution } from '../contentSource-Bazgkf4C.js';
2
- export { K as ActivityRecord, A as AdminDBInterface, v as AssignedCard, g as AssignedContent, u as AssignedCourse, t as AssignedTag, a8 as CardGenerator, aa as CardGeneratorFactory, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, H as ClassroomRegistrationDoc, e as ContentNavigationStrategyData, f as ContentNavigator, q as ContentSourceID, d as CourseInfo, L as CourseRegistration, s as CourseRegistrationDoc, b as CoursesDBInterface, a9 as GeneratorContext, G as GeneratorResult, P as HYDRATION_MARKER_ID, Q as HydrationMarker, V as NavigatorConstructor, a4 as NavigatorRole, a5 as NavigatorRoles, a3 as Navigators, j as ScheduledCard, I as SessionTrackingData, i as StudentClassroomDBInterface, h as StudyContentSource, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, S as StudySessionItem, n as StudySessionNewItem, o as StudySessionReviewItem, T as TeacherClassroomDBInterface, J as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, N as UserHydrationState, O as UserHydrationStatus, B as UsrCrsDataInterface, ad as computeDeviation, af as computeEffectiveWeight, ae as computeSpread, ag as createOrchestrationContext, a2 as getCardOrigin, Y as getRegisteredNavigator, $ as getRegisteredNavigatorNames, _ as getRegisteredNavigatorRole, r as getStudySource, Z as hasRegisteredNavigator, a0 as initializeNavigatorRegistry, a7 as isFilter, a6 as isGenerator, p as isReview, X as registerNavigator } from '../contentSource-Bazgkf4C.js';
3
- export { D as DataLayerProvider } from '../dataLayerProvider-Bt-D6xas.js';
4
- import { D as DocType, d as QuestionRecord, b as DocTypePrefixes, C as CardHistory, c as CardRecord } from '../types-legacy-4tlwHnXo.js';
5
- export { e as CardData, f as CourseListData, h as DataShapeData, g as DisplayableData, F as Field, G as GuestUsername, Q as QualifiedCardID, i as QuestionData, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from '../types-legacy-4tlwHnXo.js';
1
+ import { ar as LearnableWeight, N as UserOutcomeRecord, as as OrchestrationContext, W as WeightedCard, U as UserDBInterface, C as CourseDBInterface } from '../contentSource-BvOpKUeU.js';
2
+ export { L as ActivityRecord, A as AdminDBInterface, w as AssignedCard, g as AssignedContent, v as AssignedCourse, u as AssignedTag, ae as CardGenerator, ag as CardGeneratorFactory, c as ClassroomDBInterface, H as ClassroomRegistration, F as ClassroomRegistrationDesignation, I as ClassroomRegistrationDoc, e as ContentNavigationStrategyData, f as ContentNavigator, q as ContentSourceID, d as CourseInfo, M as CourseRegistration, s as CourseRegistrationDoc, b as CoursesDBInterface, ap as FilterImpact, af as GeneratorContext, G as GeneratorResult, ao as GeneratorSummary, _ as HYDRATION_MARKER_ID, $ as HydrationMarker, a0 as NavigatorConstructor, aa as NavigatorRole, ab as NavigatorRoles, a9 as Navigators, aq as PipelineForecaster, an as PipelineRunReport, R as ReplanHints, j as ScheduledCard, Q as SessionStateSnapshot, t as SessionStateSnapshotProvider, J as SessionTrackingData, a7 as StrategyContribution, i as StudentClassroomDBInterface, h as StudyContentSource, O as StudySessionDoc, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, S as StudySessionItem, n as StudySessionNewItem, o as StudySessionReviewItem, P as StudySessionRunSummary, T as TeacherClassroomDBInterface, K as UserConfig, B as UserCourseSetting, z as UserCourseSettings, y as UserDBAuthenticator, a as UserDBReader, x as UserDBWriter, Y as UserHydrationState, Z as UserHydrationStatus, E as UsrCrsDataInterface, at as computeDeviation, av as computeEffectiveWeight, au as computeSpread, aw as createOrchestrationContext, am as drainCapturedRuns, aj as getActivePipeline, a8 as getCardOrigin, a2 as getRegisteredNavigator, a5 as getRegisteredNavigatorNames, a4 as getRegisteredNavigatorRole, al as getRunsForSession, r as getStudySource, a3 as hasRegisteredNavigator, a6 as initializeNavigatorRegistry, ad as isFilter, ac as isGenerator, p as isReview, V as makeStudySessionId, ai as mountPipelineDebugger, X as newSessionId, ah as pipelineDebugAPI, a1 as registerNavigator, ak as setDebugSessionId } from '../contentSource-BvOpKUeU.js';
3
+ export { D as DataLayerProvider } from '../dataLayerProvider-CY2B2lyW.js';
4
+ import { D as DocType, c as QuestionRecord, i as DocTypePrefixes, C as CardHistory, b as CardRecord } from '../types-legacy-CrwyZIvI.js';
5
+ export { d as CardData, e as CourseListData, g as DataShapeData, f as DisplayableData, F as Field, G as GuestUsername, Q as QualifiedCardID, h as QuestionData, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from '../types-legacy-CrwyZIvI.js';
6
6
  import { DataShape, ParsedCard } from '@vue-skuilder/common';
7
7
  import 'moment';
8
8
 
9
- declare abstract class Loggable {
10
- protected abstract readonly _className: string;
11
- protected log(...args: unknown[]): void;
12
- protected error(...args: unknown[]): void;
13
- }
14
-
15
- /** Per-course snapshot of SRS backlog state, captured on each SRS generator run. */
16
- interface SrsBacklogDebug {
17
- courseId: string;
18
- /** Total reviews scheduled for this course (due + not-yet-due). */
19
- scheduledTotal: number;
20
- /** Reviews eligible (due) right now. */
21
- dueNow: number;
22
- /** Healthy backlog threshold; multiplier is ×1.0 at or below this. */
23
- healthyBacklog: number;
24
- /** Global multiplier applied to every due review's urgency this run (>= 1.0, unbounded). */
25
- backlogMultiplier: number;
26
- /** Exponential growth-rate base the multiplier climbs by per multiple of healthyBacklog excess. */
27
- backlogGrowthRate: number;
28
- /** Highest review score produced this run (post-multiplier; can exceed 1.0); null if none due. */
29
- topReviewScore: number | null;
30
- /** Human-readable time until the next review comes due, or null if some are due now. */
31
- nextDueIn: string | null;
32
- /** Epoch ms of capture. */
33
- timestamp: number;
34
- }
35
- /** Current backlog snapshot for every course seen, newest-first. */
36
- declare function getSrsBacklogDebug(): SrsBacklogDebug[];
37
- /** Drop all captured snapshots (called on session start, alongside pipeline history). */
38
- declare function clearSrsBacklogDebug(): void;
39
-
40
- /**
41
- * A single named pressure reading. The common shape across strategies: a
42
- * multiplier that climbs under some accumulated condition (staleness, debt,
43
- * blockage), optionally clamped at a cap.
44
- */
45
- interface PressureGaugeDebug {
46
- /** Stable identifier within the source (e.g. 'group:intro-core:target'). */
47
- id: string;
48
- /** Short display label (e.g. 'intro-core targets'). */
49
- label: string;
50
- /** Current pressure multiplier (×1.0 = no pressure). */
51
- multiplier: number;
52
- /** Clamp ceiling, if the multiplier is capped. Omit for unbounded. */
53
- max?: number;
54
- /** One-line context for the reading (counts, mode, staleness). */
55
- detail?: string;
56
- /** Expandable rows (blocked target ids, per-tag debt ages, ...). */
57
- items?: Array<{
58
- label: string;
59
- value?: string;
60
- }>;
61
- }
62
- /** One strategy's pressure snapshot for one course, captured once per run. */
63
- interface StrategyPressureDebug {
64
- /** Producer identity — implementingClass name (e.g. 'prescribed'). */
65
- source: string;
66
- courseId: string;
67
- gauges: PressureGaugeDebug[];
68
- /**
69
- * Highest score this strategy emitted into the candidate pool this run;
70
- * null if it emitted nothing. Compare against the supplyQ head score to
71
- * read how the pressure is competing for slots (same crossover read as the
72
- * SRS panel's `top review`).
73
- */
74
- topScore?: number | null;
75
- /** Label of any one-shot hints emitted alongside the cards this run. */
76
- hintsLabel?: string;
77
- /** Epoch ms of capture. */
78
- timestamp: number;
79
- }
80
- /** Called by a strategy once per run. Latest snapshot per (source, course) wins. */
81
- declare function captureStrategyPressure(snapshot: StrategyPressureDebug): void;
82
- /** Current pressure snapshot for every source seen, newest-first. */
83
- declare function getStrategyPressureDebug(): StrategyPressureDebug[];
84
- /** Drop all captured snapshots (called on session start, alongside pipeline history). */
85
- declare function clearStrategyPressureDebug(): void;
86
-
87
9
  /**
88
10
  * Snapshot of the learning state for a strategy.
89
11
  *
@@ -294,6 +216,84 @@ declare function scoreAccuracyInZone(accuracy: number, target: number, tolerance
294
216
  */
295
217
  declare function recordUserOutcome(context: OrchestrationContext, periodStart: string, periodEnd: string, records: QuestionRecord[], activeStrategyIds: string[], eloStart?: number, eloEnd?: number, config?: SignalConfig): Promise<void>;
296
218
 
219
+ declare abstract class Loggable {
220
+ protected abstract readonly _className: string;
221
+ protected log(...args: unknown[]): void;
222
+ protected error(...args: unknown[]): void;
223
+ }
224
+
225
+ /** Per-course snapshot of SRS backlog state, captured on each SRS generator run. */
226
+ interface SrsBacklogDebug {
227
+ courseId: string;
228
+ /** Total reviews scheduled for this course (due + not-yet-due). */
229
+ scheduledTotal: number;
230
+ /** Reviews eligible (due) right now. */
231
+ dueNow: number;
232
+ /** Healthy backlog threshold; multiplier is ×1.0 at or below this. */
233
+ healthyBacklog: number;
234
+ /** Global multiplier applied to every due review's urgency this run (>= 1.0, unbounded). */
235
+ backlogMultiplier: number;
236
+ /** Exponential growth-rate base the multiplier climbs by per multiple of healthyBacklog excess. */
237
+ backlogGrowthRate: number;
238
+ /** Highest review score produced this run (post-multiplier; can exceed 1.0); null if none due. */
239
+ topReviewScore: number | null;
240
+ /** Human-readable time until the next review comes due, or null if some are due now. */
241
+ nextDueIn: string | null;
242
+ /** Epoch ms of capture. */
243
+ timestamp: number;
244
+ }
245
+ /** Current backlog snapshot for every course seen, newest-first. */
246
+ declare function getSrsBacklogDebug(): SrsBacklogDebug[];
247
+ /** Drop all captured snapshots (called on session start, alongside pipeline history). */
248
+ declare function clearSrsBacklogDebug(): void;
249
+
250
+ /**
251
+ * A single named pressure reading. The common shape across strategies: a
252
+ * multiplier that climbs under some accumulated condition (staleness, debt,
253
+ * blockage), optionally clamped at a cap.
254
+ */
255
+ interface PressureGaugeDebug {
256
+ /** Stable identifier within the source (e.g. 'group:intro-core:target'). */
257
+ id: string;
258
+ /** Short display label (e.g. 'intro-core targets'). */
259
+ label: string;
260
+ /** Current pressure multiplier (×1.0 = no pressure). */
261
+ multiplier: number;
262
+ /** Clamp ceiling, if the multiplier is capped. Omit for unbounded. */
263
+ max?: number;
264
+ /** One-line context for the reading (counts, mode, staleness). */
265
+ detail?: string;
266
+ /** Expandable rows (blocked target ids, per-tag debt ages, ...). */
267
+ items?: Array<{
268
+ label: string;
269
+ value?: string;
270
+ }>;
271
+ }
272
+ /** One strategy's pressure snapshot for one course, captured once per run. */
273
+ interface StrategyPressureDebug {
274
+ /** Producer identity — implementingClass name (e.g. 'prescribed'). */
275
+ source: string;
276
+ courseId: string;
277
+ gauges: PressureGaugeDebug[];
278
+ /**
279
+ * Highest score this strategy emitted into the candidate pool this run;
280
+ * null if it emitted nothing. Compare against the supplyQ head score to
281
+ * read how the pressure is competing for slots (same crossover read as the
282
+ * SRS panel's `top review`).
283
+ */
284
+ topScore?: number | null;
285
+ /** Label of any one-shot hints emitted alongside the cards this run. */
286
+ hintsLabel?: string;
287
+ /** Epoch ms of capture. */
288
+ timestamp: number;
289
+ }
290
+ /** Called by a strategy once per run. Latest snapshot per (source, course) wins. */
291
+ declare function captureStrategyPressure(snapshot: StrategyPressureDebug): void;
292
+ /** Current pressure snapshot for every source seen, newest-first. */
293
+ declare function getStrategyPressureDebug(): StrategyPressureDebug[];
294
+ /** Drop all captured snapshots (called on session start, alongside pipeline history). */
295
+ declare function clearStrategyPressureDebug(): void;
296
+
297
297
  /**
298
298
  * Shared context available to all filters in a pipeline.
299
299
  *
@@ -412,264 +412,6 @@ declare const DIVERSITY_FLOOR = 0.3;
412
412
  */
413
413
  declare function diversityRerank(cards: WeightedCard[], opts?: DiversityRerankOptions): WeightedCard[];
414
414
 
415
- /**
416
- * A navigation pipeline that runs a generator and applies filters sequentially.
417
- *
418
- * Implements StudyContentSource for backward compatibility with SessionController.
419
- *
420
- * ## Usage
421
- *
422
- * ```typescript
423
- * const pipeline = new Pipeline(
424
- * compositeGenerator, // or single generator
425
- * [eloDistanceFilter, interferenceFilter],
426
- * user,
427
- * course
428
- * );
429
- *
430
- * const cards = await pipeline.getWeightedCards(20);
431
- * ```
432
- */
433
- /**
434
- * Narrow capability surface for out-of-band, commit-free reads against a live
435
- * pipeline (see {@link getActivePipeline}). Kept minimal on purpose — consumers
436
- * get the forecast capability, not the whole `Pipeline` class.
437
- */
438
- interface PipelineForecaster {
439
- forecast(opts?: {
440
- hints?: ReplanHints;
441
- unseenOnly?: boolean;
442
- threshold?: number;
443
- limit?: number;
444
- }): Promise<WeightedCard[]>;
445
- }
446
- /**
447
- * Diagnosis of the full card space for the current user.
448
- */
449
- interface CardSpaceDiagnosis {
450
- totalCards: number;
451
- threshold: number;
452
- wellIndicated: number;
453
- encountered: number;
454
- wellIndicatedNew: number;
455
- byType: Record<string, {
456
- total: number;
457
- wellIndicated: number;
458
- new: number;
459
- }>;
460
- filterBreakdown: Array<{
461
- name: string;
462
- wellIndicated: number;
463
- }>;
464
- elapsedMs: number;
465
- }
466
-
467
- /**
468
- * The most recently constructed pipeline for the current session, or null if
469
- * none has been built yet. This is the supported, non-debug accessor for
470
- * out-of-band reads against the live pipeline (e.g. a commit-free
471
- * `forecast()`), replacing reach-ins through `window.skuilder.pipeline`.
472
- */
473
- declare function getActivePipeline(): PipelineForecaster | null;
474
- /**
475
- * Summary of a single generator's contribution.
476
- */
477
- interface GeneratorSummary {
478
- name: string;
479
- cardCount: number;
480
- newCount: number;
481
- reviewCount: number;
482
- topScore: number;
483
- }
484
- /**
485
- * Summary of a filter's impact on scores.
486
- */
487
- interface FilterImpact {
488
- name: string;
489
- boosted: number;
490
- penalized: number;
491
- passed: number;
492
- removed: number;
493
- }
494
- /**
495
- * Complete record of a single pipeline execution.
496
- */
497
- interface PipelineRunReport {
498
- runId: string;
499
- timestamp: Date;
500
- courseId: string;
501
- courseName?: string;
502
- /** User's global ELO at the time of this pipeline run */
503
- userElo?: number;
504
- generatorName: string;
505
- generators?: GeneratorSummary[];
506
- generatedCount: number;
507
- filters: FilterImpact[];
508
- /** Ephemeral hints applied during this run */
509
- hints?: ReplanHints;
510
- finalCount: number;
511
- reviewsSelected: number;
512
- newSelected: number;
513
- /**
514
- * Card data for inspection.
515
- *
516
- * To keep the in-memory ring buffer small, this contains:
517
- * - All selected cards (the actual session output).
518
- * - The top-N highest-scoring non-selected cards (see DISCARDED_KEEP_TOP),
519
- * useful for understanding "near misses" and filter behavior.
520
- *
521
- * The remaining low-score tail of the candidate pool (mostly ELO-window
522
- * pull remnants that filters scored down) is summarized in `discardedTail`
523
- * rather than retained verbatim — each retained card carries a multi-KB
524
- * provenance trail, and the tail is typically hundreds of cards per run.
525
- */
526
- cards: Array<{
527
- cardId: string;
528
- courseId: string;
529
- origin: 'new' | 'review' | 'unknown';
530
- generator?: string;
531
- finalScore: number;
532
- /** Card's ELO (parsed from ELO generator provenance, if available) */
533
- cardElo?: number;
534
- provenance: StrategyContribution[];
535
- tags?: string[];
536
- selected: boolean;
537
- }>;
538
- /**
539
- * Summary of the discarded tail of the candidate pool — cards that were
540
- * generated and scored but neither selected nor retained in `cards`.
541
- *
542
- * Provides breadcrumbs for "where did card X go?" investigations without
543
- * the memory cost of keeping every dropped candidate's provenance.
544
- *
545
- * Future: may carry a bloom filter of discarded cardIds so callers can
546
- * ask "was X in this run's discard tail?" with bounded memory cost.
547
- */
548
- discardedTail?: {
549
- count: number;
550
- /** [min, max] finalScore across the discarded tail. */
551
- scoreRange?: [number, number];
552
- /** [min, max] cardElo across the discarded tail (where parseable). */
553
- eloRange?: [number, number];
554
- /** Human-readable note for console display. */
555
- note: string;
556
- };
557
- }
558
- /**
559
- * Console API object exposed on window.skuilder.pipeline
560
- */
561
- declare const pipelineDebugAPI: {
562
- /**
563
- * Get raw run history for programmatic access.
564
- */
565
- readonly runs: PipelineRunReport[];
566
- /**
567
- * Show summary of a specific pipeline run.
568
- */
569
- showRun(idOrIndex?: string | number): void;
570
- /**
571
- * Show summary of the last pipeline run.
572
- */
573
- showLastRun(): void;
574
- /**
575
- * Show detailed provenance for a specific card.
576
- */
577
- showCard(cardId: string): void;
578
- /**
579
- * Explain why reviews may or may not have been selected.
580
- */
581
- explainReviews(): void;
582
- /**
583
- * Show prescribed-related cards from the most recent run.
584
- *
585
- * Highlights:
586
- * - cards directly generated by the prescribed strategy
587
- * - blocked prescribed targets mentioned in provenance
588
- * - support tags resolved for blocked targets
589
- *
590
- * @param groupId - Optional prescribed group ID filter (e.g. 'intro-core')
591
- */
592
- showPrescribed(groupId?: string): void;
593
- /**
594
- * Show all runs in compact format.
595
- */
596
- listRuns(): void;
597
- /**
598
- * Export run history as JSON for bug reports.
599
- */
600
- export(): string;
601
- /**
602
- * Clear run history.
603
- */
604
- clear(): void;
605
- /**
606
- * Show the navigator registry: all registered classes and their roles.
607
- *
608
- * Useful for verifying that consumer-defined navigators were registered
609
- * before pipeline assembly.
610
- */
611
- showRegistry(): void;
612
- /**
613
- * Show strategy documents from the last pipeline run and how they mapped
614
- * to the registry.
615
- *
616
- * If no runs are captured yet, falls back to showing just the registry.
617
- */
618
- showStrategies(): void;
619
- /**
620
- * Scan the full card space through the filter chain for the current user.
621
- *
622
- * Reports how many cards are well-indicated and how many are new.
623
- * Use this to understand how the search space grows during onboarding.
624
- *
625
- * @param threshold - Score threshold for "well indicated" (default 0.10)
626
- */
627
- diagnoseCardSpace(threshold?: number): Promise<CardSpaceDiagnosis | null>;
628
- /**
629
- * Show user's per-tag ELO data. Useful for diagnosing hierarchy gate status.
630
- *
631
- * @param tagFilter - Optional glob pattern(s) to filter tags.
632
- * Examples: 'gpc:expose:*', 'gpc:intro:t-T', ['gpc:expose:t-*', 'gpc:intro:t-*']
633
- */
634
- showTagElo(tagFilter?: string | string[]): Promise<void>;
635
- /**
636
- * Toggle the full-screen UI debugger.
637
- */
638
- ui(): void;
639
- /**
640
- * Internal UI helpers
641
- * @internal
642
- */
643
- _selectRun(index: number): void;
644
- /**
645
- * Internal UI helpers
646
- * @internal
647
- */
648
- _setSearch(query: string): void;
649
- /**
650
- * Internal UI helpers
651
- * @internal
652
- */
653
- _copyConfig(runId: string, btn?: HTMLElement): void;
654
- /**
655
- * Internal UI helpers
656
- * @internal
657
- *
658
- * Copies an "abridged" view of results: just the selected cards with their
659
- * generator, origin, final score, and the top provenance reason. Designed
660
- * for pasting into bug reports without flooding with full provenance.
661
- */
662
- _copyResults(runId: string, btn?: HTMLElement): void;
663
- /**
664
- * Show help.
665
- */
666
- help(): void;
667
- };
668
- /**
669
- * Mount the debug API on window.skuilder.pipeline
670
- */
671
- declare function mountPipelineDebugger(): void;
672
-
673
415
  /**
674
416
  * Template literal type for strategy state document IDs.
675
417
  *
@@ -852,4 +594,4 @@ declare const userDBDebugAPI: {
852
594
  */
853
595
  declare function mountUserDBDebugger(): void;
854
596
 
855
- export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, CardHistory, CardRecord, CourseDBInterface, DIVERSITY_FLOOR, DIVERSITY_STRENGTH, type DiversityRerankOptions, DocType, DocTypePrefixes, type FilterContext, type FilterImpact, type GeneratorSummary, type GradientObservation, type GradientResult, type ImportResult, LearnableWeight, Loggable, OrchestrationContext, type PeriodUpdateInput, type PeriodUpdateResult, type PipelineForecaster, type PipelineRunReport, type PressureGaugeDebug, QuestionRecord, ReplanHints, type SignalConfig, type SrsBacklogDebug, StrategyContribution, type StrategyLearningState, type StrategyPressureDebug, type StrategyStateDoc, type StrategyStateId, UserDBInterface, UserOutcomeRecord, WeightedCard, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, captureStrategyPressure, clearSrsBacklogDebug, clearStrategyPressureDebug, computeOutcomeSignal, computeStrategyGradient, diversityRerank, docIsDeleted, getActivePipeline, getCardHistoryID, getDefaultLearnableWeight, getSrsBacklogDebug, getStrategyPressureDebug, importParsedCards, isQuestionRecord, mountPipelineDebugger, mountUserDBDebugger, parseCardHistoryID, pipelineDebugAPI, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, userDBDebugAPI, validateProcessorConfig };
597
+ export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, CardHistory, CardRecord, CourseDBInterface, DIVERSITY_FLOOR, DIVERSITY_STRENGTH, type DiversityRerankOptions, DocType, DocTypePrefixes, type FilterContext, type GradientObservation, type GradientResult, type ImportResult, LearnableWeight, Loggable, OrchestrationContext, type PeriodUpdateInput, type PeriodUpdateResult, type PressureGaugeDebug, QuestionRecord, type SignalConfig, type SrsBacklogDebug, type StrategyLearningState, type StrategyPressureDebug, type StrategyStateDoc, type StrategyStateId, UserDBInterface, UserOutcomeRecord, WeightedCard, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, captureStrategyPressure, clearSrsBacklogDebug, clearStrategyPressureDebug, computeOutcomeSignal, computeStrategyGradient, diversityRerank, docIsDeleted, getCardHistoryID, getDefaultLearnableWeight, getSrsBacklogDebug, getStrategyPressureDebug, importParsedCards, isQuestionRecord, mountUserDBDebugger, parseCardHistoryID, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, userDBDebugAPI, validateProcessorConfig };
@@ -125,6 +125,7 @@ var init_types_legacy = __esm({
125
125
  DocType2["STRATEGY_STATE"] = "STRATEGY_STATE";
126
126
  DocType2["USER_OUTCOME"] = "USER_OUTCOME";
127
127
  DocType2["STRATEGY_LEARNING_STATE"] = "STRATEGY_LEARNING_STATE";
128
+ DocType2["STUDY_SESSION"] = "STUDY_SESSION";
128
129
  return DocType2;
129
130
  })(DocType || {});
130
131
  DocTypePrefixes = {
@@ -141,7 +142,8 @@ var init_types_legacy = __esm({
141
142
  ["NAVIGATION_STRATEGY" /* NAVIGATION_STRATEGY */]: "NAVIGATION_STRATEGY",
142
143
  ["STRATEGY_STATE" /* STRATEGY_STATE */]: "STRATEGY_STATE",
143
144
  ["USER_OUTCOME" /* USER_OUTCOME */]: "USER_OUTCOME",
144
- ["STRATEGY_LEARNING_STATE" /* STRATEGY_LEARNING_STATE */]: "STRATEGY_LEARNING_STATE"
145
+ ["STRATEGY_LEARNING_STATE" /* STRATEGY_LEARNING_STATE */]: "STRATEGY_LEARNING_STATE",
146
+ ["STUDY_SESSION" /* STUDY_SESSION */]: "SESSION"
145
147
  };
146
148
  }
147
149
  });
@@ -817,10 +819,13 @@ __export(PipelineDebugger_exports, {
817
819
  buildRunReport: () => buildRunReport,
818
820
  captureRun: () => captureRun,
819
821
  clearRunHistory: () => clearRunHistory,
822
+ drainCapturedRuns: () => drainCapturedRuns,
820
823
  getActivePipeline: () => getActivePipeline,
824
+ getRunsForSession: () => getRunsForSession,
821
825
  mountPipelineDebugger: () => mountPipelineDebugger,
822
826
  pipelineDebugAPI: () => pipelineDebugAPI,
823
- registerPipelineForDebug: () => registerPipelineForDebug
827
+ registerPipelineForDebug: () => registerPipelineForDebug,
828
+ setDebugSessionId: () => setDebugSessionId
824
829
  });
825
830
  function registerPipelineForDebug(pipeline) {
826
831
  _activePipeline = pipeline;
@@ -828,8 +833,20 @@ function registerPipelineForDebug(pipeline) {
828
833
  function getActivePipeline() {
829
834
  return _activePipeline;
830
835
  }
836
+ function setDebugSessionId(sessionId) {
837
+ _currentSessionId = sessionId;
838
+ }
839
+ function drainCapturedRuns() {
840
+ const drained = _pendingRuns;
841
+ _pendingRuns = [];
842
+ return drained;
843
+ }
844
+ function getRunsForSession(sessionId) {
845
+ return runHistory.filter((r) => r.sessionId === sessionId).reverse();
846
+ }
831
847
  function clearRunHistory() {
832
848
  runHistory.length = 0;
849
+ _pendingRuns = [];
833
850
  }
834
851
  function getOrigin(card) {
835
852
  const firstEntry = card.provenance[0];
@@ -844,12 +861,15 @@ function captureRun(report) {
844
861
  const fullReport = {
845
862
  ...report,
846
863
  runId: `run-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
864
+ sessionId: _currentSessionId,
847
865
  timestamp: /* @__PURE__ */ new Date()
848
866
  };
849
867
  runHistory.unshift(fullReport);
850
868
  if (runHistory.length > MAX_RUNS) {
851
869
  runHistory.pop();
852
870
  }
871
+ _pendingRuns.push(fullReport);
872
+ return fullReport;
853
873
  }
854
874
  function parseCardElo(provenance) {
855
875
  const eloEntry = provenance.find((p) => p.strategy === "elo");
@@ -1177,7 +1197,7 @@ function mountPipelineDebugger() {
1177
1197
  win.skuilder = win.skuilder || {};
1178
1198
  win.skuilder.pipeline = pipelineDebugAPI;
1179
1199
  }
1180
- var _activePipeline, MAX_RUNS, runHistory, DISCARDED_KEEP_TOP, _uiContainer, _selectedRunIndex, _cardSearchQuery, pipelineDebugAPI;
1200
+ var _activePipeline, MAX_RUNS, runHistory, _currentSessionId, _pendingRuns, DISCARDED_KEEP_TOP, _uiContainer, _selectedRunIndex, _cardSearchQuery, pipelineDebugAPI;
1181
1201
  var init_PipelineDebugger = __esm({
1182
1202
  "src/core/navigators/PipelineDebugger.ts"() {
1183
1203
  "use strict";
@@ -1186,6 +1206,7 @@ var init_PipelineDebugger = __esm({
1186
1206
  _activePipeline = null;
1187
1207
  MAX_RUNS = 10;
1188
1208
  runHistory = [];
1209
+ _pendingRuns = [];
1189
1210
  DISCARDED_KEEP_TOP = 25;
1190
1211
  _uiContainer = null;
1191
1212
  _selectedRunIndex = null;
@@ -5409,11 +5430,13 @@ __export(navigators_exports, {
5409
5430
  clearSrsBacklogDebug: () => clearSrsBacklogDebug,
5410
5431
  clearStrategyPressureDebug: () => clearStrategyPressureDebug,
5411
5432
  diversityRerank: () => diversityRerank,
5433
+ drainCapturedRuns: () => drainCapturedRuns,
5412
5434
  getActivePipeline: () => getActivePipeline,
5413
5435
  getCardOrigin: () => getCardOrigin,
5414
5436
  getRegisteredNavigator: () => getRegisteredNavigator,
5415
5437
  getRegisteredNavigatorNames: () => getRegisteredNavigatorNames,
5416
5438
  getRegisteredNavigatorRole: () => getRegisteredNavigatorRole,
5439
+ getRunsForSession: () => getRunsForSession,
5417
5440
  getSrsBacklogDebug: () => getSrsBacklogDebug,
5418
5441
  getStrategyPressureDebug: () => getStrategyPressureDebug,
5419
5442
  hasRegisteredNavigator: () => hasRegisteredNavigator,
@@ -5422,7 +5445,8 @@ __export(navigators_exports, {
5422
5445
  isGenerator: () => isGenerator,
5423
5446
  mountPipelineDebugger: () => mountPipelineDebugger,
5424
5447
  pipelineDebugAPI: () => pipelineDebugAPI,
5425
- registerNavigator: () => registerNavigator
5448
+ registerNavigator: () => registerNavigator,
5449
+ setDebugSessionId: () => setDebugSessionId
5426
5450
  });
5427
5451
  function registerNavigator(implementingClass, constructor, role) {
5428
5452
  navigatorRegistry.set(implementingClass, { constructor, role });
@@ -7880,6 +7904,32 @@ Currently logged-in as ${this._username}.`
7880
7904
  };
7881
7905
  await this.localDB.put(doc);
7882
7906
  }
7907
+ /**
7908
+ * Open and close write the same `_id`, so the 409 path is the expected
7909
+ * route for the second write, not an error case.
7910
+ */
7911
+ async putStudySession(doc) {
7912
+ try {
7913
+ await this.localDB.put(doc);
7914
+ } catch (err) {
7915
+ if (err.status === 409) {
7916
+ const existing = await this.localDB.get(doc._id);
7917
+ await this.localDB.put({ ...doc, _rev: existing._rev });
7918
+ } else {
7919
+ throw err;
7920
+ }
7921
+ }
7922
+ }
7923
+ async getStudySessions(courseId) {
7924
+ const prefix = courseId ? `${DocTypePrefixes["STUDY_SESSION" /* STUDY_SESSION */]}::${courseId}::` : `${DocTypePrefixes["STUDY_SESSION" /* STUDY_SESSION */]}::`;
7925
+ const keys = getStartAndEndKeys(prefix);
7926
+ const res = await this.localDB.allDocs({
7927
+ startkey: keys.startkey,
7928
+ endkey: keys.endkey,
7929
+ include_docs: true
7930
+ });
7931
+ return res.rows.map((r) => r.doc).filter((d) => !!d).sort((a, b) => b.startTime.localeCompare(a.startTime));
7932
+ }
7883
7933
  async putUserOutcome(record) {
7884
7934
  try {
7885
7935
  await this.localDB.put(record);
@@ -8200,6 +8250,20 @@ var init_userOutcome = __esm({
8200
8250
  }
8201
8251
  });
8202
8252
 
8253
+ // src/core/types/studySession.ts
8254
+ function makeStudySessionId(courseId, userId, sessionId) {
8255
+ return `${DocTypePrefixes["STUDY_SESSION" /* STUDY_SESSION */]}::${courseId}::${userId}::${sessionId}`;
8256
+ }
8257
+ function newSessionId() {
8258
+ return `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
8259
+ }
8260
+ var init_studySession = __esm({
8261
+ "src/core/types/studySession.ts"() {
8262
+ "use strict";
8263
+ init_types_legacy();
8264
+ }
8265
+ });
8266
+
8203
8267
  // src/core/types/hydration.ts
8204
8268
  var HYDRATION_MARKER_ID;
8205
8269
  var init_hydration = __esm({
@@ -8708,6 +8772,7 @@ __export(core_exports, {
8708
8772
  createOrchestrationContext: () => createOrchestrationContext,
8709
8773
  diversityRerank: () => diversityRerank,
8710
8774
  docIsDeleted: () => docIsDeleted,
8775
+ drainCapturedRuns: () => drainCapturedRuns,
8711
8776
  getActivePipeline: () => getActivePipeline,
8712
8777
  getCardHistoryID: () => getCardHistoryID,
8713
8778
  getCardOrigin: () => getCardOrigin,
@@ -8715,6 +8780,7 @@ __export(core_exports, {
8715
8780
  getRegisteredNavigator: () => getRegisteredNavigator,
8716
8781
  getRegisteredNavigatorNames: () => getRegisteredNavigatorNames,
8717
8782
  getRegisteredNavigatorRole: () => getRegisteredNavigatorRole,
8783
+ getRunsForSession: () => getRunsForSession,
8718
8784
  getSrsBacklogDebug: () => getSrsBacklogDebug,
8719
8785
  getStrategyPressureDebug: () => getStrategyPressureDebug,
8720
8786
  getStudySource: () => getStudySource,
@@ -8726,14 +8792,17 @@ __export(core_exports, {
8726
8792
  isQuestionRecord: () => isQuestionRecord,
8727
8793
  isReview: () => isReview,
8728
8794
  log: () => log,
8795
+ makeStudySessionId: () => makeStudySessionId,
8729
8796
  mountPipelineDebugger: () => mountPipelineDebugger,
8730
8797
  mountUserDBDebugger: () => mountUserDBDebugger,
8798
+ newSessionId: () => newSessionId,
8731
8799
  parseCardHistoryID: () => parseCardHistoryID,
8732
8800
  pipelineDebugAPI: () => pipelineDebugAPI,
8733
8801
  recordUserOutcome: () => recordUserOutcome,
8734
8802
  registerNavigator: () => registerNavigator,
8735
8803
  runPeriodUpdate: () => runPeriodUpdate,
8736
8804
  scoreAccuracyInZone: () => scoreAccuracyInZone,
8805
+ setDebugSessionId: () => setDebugSessionId,
8737
8806
  updateLearningState: () => updateLearningState,
8738
8807
  updateStrategyWeight: () => updateStrategyWeight,
8739
8808
  userDBDebugAPI: () => userDBDebugAPI,
@@ -8747,6 +8816,7 @@ var init_core = __esm({
8747
8816
  init_user();
8748
8817
  init_strategyState();
8749
8818
  init_userOutcome();
8819
+ init_studySession();
8750
8820
  init_hydration();
8751
8821
  init_Loggable();
8752
8822
  init_util();
@@ -8784,6 +8854,7 @@ init_core();
8784
8854
  createOrchestrationContext,
8785
8855
  diversityRerank,
8786
8856
  docIsDeleted,
8857
+ drainCapturedRuns,
8787
8858
  getActivePipeline,
8788
8859
  getCardHistoryID,
8789
8860
  getCardOrigin,
@@ -8791,6 +8862,7 @@ init_core();
8791
8862
  getRegisteredNavigator,
8792
8863
  getRegisteredNavigatorNames,
8793
8864
  getRegisteredNavigatorRole,
8865
+ getRunsForSession,
8794
8866
  getSrsBacklogDebug,
8795
8867
  getStrategyPressureDebug,
8796
8868
  getStudySource,
@@ -8802,14 +8874,17 @@ init_core();
8802
8874
  isQuestionRecord,
8803
8875
  isReview,
8804
8876
  log,
8877
+ makeStudySessionId,
8805
8878
  mountPipelineDebugger,
8806
8879
  mountUserDBDebugger,
8880
+ newSessionId,
8807
8881
  parseCardHistoryID,
8808
8882
  pipelineDebugAPI,
8809
8883
  recordUserOutcome,
8810
8884
  registerNavigator,
8811
8885
  runPeriodUpdate,
8812
8886
  scoreAccuracyInZone,
8887
+ setDebugSessionId,
8813
8888
  updateLearningState,
8814
8889
  updateStrategyWeight,
8815
8890
  userDBDebugAPI,