@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.
- package/dist/{contentSource-BMxsujRu.d.cts → contentSource-BvOpKUeU.d.ts} +442 -79
- package/dist/{contentSource-Bazgkf4C.d.ts → contentSource-DT9NaX69.d.cts} +442 -79
- package/dist/core/index.d.cts +84 -342
- package/dist/core/index.d.ts +84 -342
- package/dist/core/index.js +79 -4
- package/dist/core/index.js.map +1 -1
- package/dist/core/index.mjs +74 -4
- package/dist/core/index.mjs.map +1 -1
- package/dist/{dataLayerProvider-Bt-D6xas.d.ts → dataLayerProvider-CY2B2lyW.d.ts} +1 -1
- package/dist/{dataLayerProvider-DifVCcIS.d.cts → dataLayerProvider-wY6s_4x9.d.cts} +1 -1
- package/dist/impl/couch/index.d.cts +3 -3
- package/dist/impl/couch/index.d.ts +3 -3
- package/dist/impl/couch/index.js +63 -4
- package/dist/impl/couch/index.js.map +1 -1
- package/dist/impl/couch/index.mjs +63 -4
- package/dist/impl/couch/index.mjs.map +1 -1
- package/dist/impl/static/index.d.cts +4 -4
- package/dist/impl/static/index.d.ts +4 -4
- package/dist/impl/static/index.js +63 -4
- package/dist/impl/static/index.js.map +1 -1
- package/dist/impl/static/index.mjs +63 -4
- package/dist/impl/static/index.mjs.map +1 -1
- package/dist/{index-BLLT5BYE.d.ts → index-BkBJlGDX.d.ts} +1 -1
- package/dist/{index-k9NFHpS1.d.cts → index-D7WdMDAs.d.cts} +1 -1
- package/dist/index.d.cts +51 -14
- package/dist/index.d.ts +51 -14
- package/dist/index.js +240 -12
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +235 -12
- package/dist/index.mjs.map +1 -1
- package/dist/{types-BFUa1pa3.d.cts → types-DjiFOZxJ.d.cts} +1 -1
- package/dist/{types-legacy-4tlwHnXo.d.cts → types-legacy-CrwyZIvI.d.cts} +10 -2
- package/dist/{types-legacy-4tlwHnXo.d.ts → types-legacy-CrwyZIvI.d.ts} +10 -2
- package/dist/{types-CHgpWQAY.d.ts → types-uJ2Xn3_X.d.ts} +1 -1
- package/dist/util/packer/index.d.cts +3 -3
- package/dist/util/packer/index.d.ts +3 -3
- package/package.json +3 -3
- package/src/core/index.ts +1 -0
- package/src/core/interfaces/userDB.ts +7 -0
- package/src/core/navigators/PipelineDebugger.ts +41 -1
- package/src/core/navigators/index.ts +3 -0
- package/src/core/types/studySession.ts +125 -0
- package/src/core/types/types-legacy.ts +8 -0
- package/src/impl/common/BaseUserDB.ts +36 -0
- package/src/study/SessionController.ts +188 -2
- package/src/study/SessionDebugger.ts +4 -3
- package/src/study/SessionOverlay.ts +1 -0
- package/src/study/services/ResponseProcessor.ts +32 -4
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { CourseConfig, ClassroomConfig, Status, SkuilderCourseData as SkuilderCourseData$1, CourseElo, DataShape, TagFilter } from '@vue-skuilder/common';
|
|
2
2
|
import { Moment } from 'moment';
|
|
3
|
-
import { S as SkuilderCourseData,
|
|
3
|
+
import { S as SkuilderCourseData, i as DocTypePrefixes, D as DocType, Q as QualifiedCardID, T as TagStub, a as Tag, C as CardHistory, b as CardRecord } from './types-legacy-CrwyZIvI.js';
|
|
4
4
|
|
|
5
5
|
/**
|
|
6
6
|
* Admin functionality
|
|
@@ -423,6 +423,442 @@ interface UserOutcomeRecord {
|
|
|
423
423
|
};
|
|
424
424
|
}
|
|
425
425
|
|
|
426
|
+
/**
|
|
427
|
+
* Context for orchestration decisions during a session.
|
|
428
|
+
*
|
|
429
|
+
* Provides access to user/course data and helper methods for determining
|
|
430
|
+
* effective strategy weights based on the user's cohort assignment.
|
|
431
|
+
*/
|
|
432
|
+
interface OrchestrationContext {
|
|
433
|
+
user: UserDBInterface;
|
|
434
|
+
course: CourseDBInterface;
|
|
435
|
+
userId: string;
|
|
436
|
+
courseConfig: CourseConfig;
|
|
437
|
+
/**
|
|
438
|
+
* Calculate the effective weight for a strategy for this user.
|
|
439
|
+
*
|
|
440
|
+
* Applies deviation based on the user's cohort assignment (derived from
|
|
441
|
+
* userId, strategyId, and course salt).
|
|
442
|
+
*
|
|
443
|
+
* @param strategyId - Unique ID of the strategy
|
|
444
|
+
* @param learnable - The strategy's learning configuration
|
|
445
|
+
* @returns Effective weight multiplier (typically 0.1 - 3.0)
|
|
446
|
+
*/
|
|
447
|
+
getEffectiveWeight(strategyId: string, learnable: LearnableWeight): number;
|
|
448
|
+
/**
|
|
449
|
+
* Get the deviation factor for this user/strategy.
|
|
450
|
+
* Range [-1.0, 1.0].
|
|
451
|
+
*/
|
|
452
|
+
getDeviation(strategyId: string): number;
|
|
453
|
+
}
|
|
454
|
+
/**
|
|
455
|
+
* Compute a user's deviation for a specific strategy.
|
|
456
|
+
*
|
|
457
|
+
* Returns a value in [-1, 1] that is:
|
|
458
|
+
* 1. Deterministic for the same (user, strategy, salt) tuple
|
|
459
|
+
* 2. Uniformly distributed across users
|
|
460
|
+
* 3. Uncorrelated between different strategies (due to strategyId in hash)
|
|
461
|
+
* 4. Rotatable by changing the salt
|
|
462
|
+
*
|
|
463
|
+
* @param userId - ID of the user
|
|
464
|
+
* @param strategyId - ID of the strategy
|
|
465
|
+
* @param salt - Random seed from course config
|
|
466
|
+
* @returns Deviation factor between -1.0 and 1.0
|
|
467
|
+
*/
|
|
468
|
+
declare function computeDeviation(userId: string, strategyId: string, salt: string): number;
|
|
469
|
+
/**
|
|
470
|
+
* Compute the exploration spread based on confidence.
|
|
471
|
+
*
|
|
472
|
+
* - Low confidence (0.0) -> Max spread (Explore broadly)
|
|
473
|
+
* - High confidence (1.0) -> Min spread (Exploit known good weight)
|
|
474
|
+
*
|
|
475
|
+
* @param confidence - Confidence level 0-1
|
|
476
|
+
* @returns Spread magnitude (half-width of the distribution)
|
|
477
|
+
*/
|
|
478
|
+
declare function computeSpread(confidence: number): number;
|
|
479
|
+
/**
|
|
480
|
+
* Calculate the effective weight for a strategy instance.
|
|
481
|
+
*
|
|
482
|
+
* Combines the learnable weight (peak) with the user's deviation and the
|
|
483
|
+
* allowed spread (based on confidence).
|
|
484
|
+
*
|
|
485
|
+
* @param learnable - Strategy learning config
|
|
486
|
+
* @param userId - User ID
|
|
487
|
+
* @param strategyId - Strategy ID
|
|
488
|
+
* @param salt - Course salt
|
|
489
|
+
* @returns Effective weight multiplier
|
|
490
|
+
*/
|
|
491
|
+
declare function computeEffectiveWeight(learnable: LearnableWeight, userId: string, strategyId: string, salt: string): number;
|
|
492
|
+
/**
|
|
493
|
+
* Create an orchestration context for a study session.
|
|
494
|
+
*
|
|
495
|
+
* Fetches necessary configuration to enable deterministic weight calculation.
|
|
496
|
+
*
|
|
497
|
+
* @param user - User DB interface
|
|
498
|
+
* @param course - Course DB interface
|
|
499
|
+
* @returns Initialized orchestration context
|
|
500
|
+
*/
|
|
501
|
+
declare function createOrchestrationContext(user: UserDBInterface, course: CourseDBInterface): Promise<OrchestrationContext>;
|
|
502
|
+
|
|
503
|
+
/**
|
|
504
|
+
* A navigation pipeline that runs a generator and applies filters sequentially.
|
|
505
|
+
*
|
|
506
|
+
* Implements StudyContentSource for backward compatibility with SessionController.
|
|
507
|
+
*
|
|
508
|
+
* ## Usage
|
|
509
|
+
*
|
|
510
|
+
* ```typescript
|
|
511
|
+
* const pipeline = new Pipeline(
|
|
512
|
+
* compositeGenerator, // or single generator
|
|
513
|
+
* [eloDistanceFilter, interferenceFilter],
|
|
514
|
+
* user,
|
|
515
|
+
* course
|
|
516
|
+
* );
|
|
517
|
+
*
|
|
518
|
+
* const cards = await pipeline.getWeightedCards(20);
|
|
519
|
+
* ```
|
|
520
|
+
*/
|
|
521
|
+
/**
|
|
522
|
+
* Narrow capability surface for out-of-band, commit-free reads against a live
|
|
523
|
+
* pipeline (see {@link getActivePipeline}). Kept minimal on purpose — consumers
|
|
524
|
+
* get the forecast capability, not the whole `Pipeline` class.
|
|
525
|
+
*/
|
|
526
|
+
interface PipelineForecaster {
|
|
527
|
+
forecast(opts?: {
|
|
528
|
+
hints?: ReplanHints;
|
|
529
|
+
unseenOnly?: boolean;
|
|
530
|
+
threshold?: number;
|
|
531
|
+
limit?: number;
|
|
532
|
+
}): Promise<WeightedCard[]>;
|
|
533
|
+
}
|
|
534
|
+
/**
|
|
535
|
+
* Diagnosis of the full card space for the current user.
|
|
536
|
+
*/
|
|
537
|
+
interface CardSpaceDiagnosis {
|
|
538
|
+
totalCards: number;
|
|
539
|
+
threshold: number;
|
|
540
|
+
wellIndicated: number;
|
|
541
|
+
encountered: number;
|
|
542
|
+
wellIndicatedNew: number;
|
|
543
|
+
byType: Record<string, {
|
|
544
|
+
total: number;
|
|
545
|
+
wellIndicated: number;
|
|
546
|
+
new: number;
|
|
547
|
+
}>;
|
|
548
|
+
filterBreakdown: Array<{
|
|
549
|
+
name: string;
|
|
550
|
+
wellIndicated: number;
|
|
551
|
+
}>;
|
|
552
|
+
elapsedMs: number;
|
|
553
|
+
}
|
|
554
|
+
|
|
555
|
+
/**
|
|
556
|
+
* The most recently constructed pipeline for the current session, or null if
|
|
557
|
+
* none has been built yet. This is the supported, non-debug accessor for
|
|
558
|
+
* out-of-band reads against the live pipeline (e.g. a commit-free
|
|
559
|
+
* `forecast()`), replacing reach-ins through `window.skuilder.pipeline`.
|
|
560
|
+
*/
|
|
561
|
+
declare function getActivePipeline(): PipelineForecaster | null;
|
|
562
|
+
/**
|
|
563
|
+
* Summary of a single generator's contribution.
|
|
564
|
+
*/
|
|
565
|
+
interface GeneratorSummary {
|
|
566
|
+
name: string;
|
|
567
|
+
cardCount: number;
|
|
568
|
+
newCount: number;
|
|
569
|
+
reviewCount: number;
|
|
570
|
+
topScore: number;
|
|
571
|
+
}
|
|
572
|
+
/**
|
|
573
|
+
* Summary of a filter's impact on scores.
|
|
574
|
+
*/
|
|
575
|
+
interface FilterImpact {
|
|
576
|
+
name: string;
|
|
577
|
+
boosted: number;
|
|
578
|
+
penalized: number;
|
|
579
|
+
passed: number;
|
|
580
|
+
removed: number;
|
|
581
|
+
}
|
|
582
|
+
/**
|
|
583
|
+
* Complete record of a single pipeline execution.
|
|
584
|
+
*/
|
|
585
|
+
interface PipelineRunReport {
|
|
586
|
+
runId: string;
|
|
587
|
+
/** Absent for runs fired outside a session (forecasts, editor probes). */
|
|
588
|
+
sessionId?: string;
|
|
589
|
+
timestamp: Date;
|
|
590
|
+
courseId: string;
|
|
591
|
+
courseName?: string;
|
|
592
|
+
/** User's global ELO at the time of this pipeline run */
|
|
593
|
+
userElo?: number;
|
|
594
|
+
generatorName: string;
|
|
595
|
+
generators?: GeneratorSummary[];
|
|
596
|
+
generatedCount: number;
|
|
597
|
+
filters: FilterImpact[];
|
|
598
|
+
/** Ephemeral hints applied during this run */
|
|
599
|
+
hints?: ReplanHints;
|
|
600
|
+
finalCount: number;
|
|
601
|
+
reviewsSelected: number;
|
|
602
|
+
newSelected: number;
|
|
603
|
+
/**
|
|
604
|
+
* Card data for inspection.
|
|
605
|
+
*
|
|
606
|
+
* To keep the in-memory ring buffer small, this contains:
|
|
607
|
+
* - All selected cards (the actual session output).
|
|
608
|
+
* - The top-N highest-scoring non-selected cards (see DISCARDED_KEEP_TOP),
|
|
609
|
+
* useful for understanding "near misses" and filter behavior.
|
|
610
|
+
*
|
|
611
|
+
* The remaining low-score tail of the candidate pool (mostly ELO-window
|
|
612
|
+
* pull remnants that filters scored down) is summarized in `discardedTail`
|
|
613
|
+
* rather than retained verbatim — each retained card carries a multi-KB
|
|
614
|
+
* provenance trail, and the tail is typically hundreds of cards per run.
|
|
615
|
+
*/
|
|
616
|
+
cards: Array<{
|
|
617
|
+
cardId: string;
|
|
618
|
+
courseId: string;
|
|
619
|
+
origin: 'new' | 'review' | 'unknown';
|
|
620
|
+
generator?: string;
|
|
621
|
+
finalScore: number;
|
|
622
|
+
/** Card's ELO (parsed from ELO generator provenance, if available) */
|
|
623
|
+
cardElo?: number;
|
|
624
|
+
provenance: StrategyContribution[];
|
|
625
|
+
tags?: string[];
|
|
626
|
+
selected: boolean;
|
|
627
|
+
}>;
|
|
628
|
+
/**
|
|
629
|
+
* Summary of the discarded tail of the candidate pool — cards that were
|
|
630
|
+
* generated and scored but neither selected nor retained in `cards`.
|
|
631
|
+
*
|
|
632
|
+
* Provides breadcrumbs for "where did card X go?" investigations without
|
|
633
|
+
* the memory cost of keeping every dropped candidate's provenance.
|
|
634
|
+
*
|
|
635
|
+
* Future: may carry a bloom filter of discarded cardIds so callers can
|
|
636
|
+
* ask "was X in this run's discard tail?" with bounded memory cost.
|
|
637
|
+
*/
|
|
638
|
+
discardedTail?: {
|
|
639
|
+
count: number;
|
|
640
|
+
/** [min, max] finalScore across the discarded tail. */
|
|
641
|
+
scoreRange?: [number, number];
|
|
642
|
+
/** [min, max] cardElo across the discarded tail (where parseable). */
|
|
643
|
+
eloRange?: [number, number];
|
|
644
|
+
/** Human-readable note for console display. */
|
|
645
|
+
note: string;
|
|
646
|
+
};
|
|
647
|
+
}
|
|
648
|
+
declare function setDebugSessionId(sessionId: string | undefined): void;
|
|
649
|
+
/** Take and clear the runs captured since the previous call, in execution order. */
|
|
650
|
+
declare function drainCapturedRuns(): PipelineRunReport[];
|
|
651
|
+
/**
|
|
652
|
+
* Runs for `sessionId`, oldest first. Bounded by {@link MAX_RUNS} — the
|
|
653
|
+
* complete record is `StudySessionDoc.runs`.
|
|
654
|
+
*/
|
|
655
|
+
declare function getRunsForSession(sessionId: string): PipelineRunReport[];
|
|
656
|
+
/**
|
|
657
|
+
* Console API object exposed on window.skuilder.pipeline
|
|
658
|
+
*/
|
|
659
|
+
declare const pipelineDebugAPI: {
|
|
660
|
+
/**
|
|
661
|
+
* Get raw run history for programmatic access.
|
|
662
|
+
*/
|
|
663
|
+
readonly runs: PipelineRunReport[];
|
|
664
|
+
/**
|
|
665
|
+
* Show summary of a specific pipeline run.
|
|
666
|
+
*/
|
|
667
|
+
showRun(idOrIndex?: string | number): void;
|
|
668
|
+
/**
|
|
669
|
+
* Show summary of the last pipeline run.
|
|
670
|
+
*/
|
|
671
|
+
showLastRun(): void;
|
|
672
|
+
/**
|
|
673
|
+
* Show detailed provenance for a specific card.
|
|
674
|
+
*/
|
|
675
|
+
showCard(cardId: string): void;
|
|
676
|
+
/**
|
|
677
|
+
* Explain why reviews may or may not have been selected.
|
|
678
|
+
*/
|
|
679
|
+
explainReviews(): void;
|
|
680
|
+
/**
|
|
681
|
+
* Show prescribed-related cards from the most recent run.
|
|
682
|
+
*
|
|
683
|
+
* Highlights:
|
|
684
|
+
* - cards directly generated by the prescribed strategy
|
|
685
|
+
* - blocked prescribed targets mentioned in provenance
|
|
686
|
+
* - support tags resolved for blocked targets
|
|
687
|
+
*
|
|
688
|
+
* @param groupId - Optional prescribed group ID filter (e.g. 'intro-core')
|
|
689
|
+
*/
|
|
690
|
+
showPrescribed(groupId?: string): void;
|
|
691
|
+
/**
|
|
692
|
+
* Show all runs in compact format.
|
|
693
|
+
*/
|
|
694
|
+
listRuns(): void;
|
|
695
|
+
/**
|
|
696
|
+
* Export run history as JSON for bug reports.
|
|
697
|
+
*/
|
|
698
|
+
export(): string;
|
|
699
|
+
/**
|
|
700
|
+
* Clear run history.
|
|
701
|
+
*/
|
|
702
|
+
clear(): void;
|
|
703
|
+
/**
|
|
704
|
+
* Show the navigator registry: all registered classes and their roles.
|
|
705
|
+
*
|
|
706
|
+
* Useful for verifying that consumer-defined navigators were registered
|
|
707
|
+
* before pipeline assembly.
|
|
708
|
+
*/
|
|
709
|
+
showRegistry(): void;
|
|
710
|
+
/**
|
|
711
|
+
* Show strategy documents from the last pipeline run and how they mapped
|
|
712
|
+
* to the registry.
|
|
713
|
+
*
|
|
714
|
+
* If no runs are captured yet, falls back to showing just the registry.
|
|
715
|
+
*/
|
|
716
|
+
showStrategies(): void;
|
|
717
|
+
/**
|
|
718
|
+
* Scan the full card space through the filter chain for the current user.
|
|
719
|
+
*
|
|
720
|
+
* Reports how many cards are well-indicated and how many are new.
|
|
721
|
+
* Use this to understand how the search space grows during onboarding.
|
|
722
|
+
*
|
|
723
|
+
* @param threshold - Score threshold for "well indicated" (default 0.10)
|
|
724
|
+
*/
|
|
725
|
+
diagnoseCardSpace(threshold?: number): Promise<CardSpaceDiagnosis | null>;
|
|
726
|
+
/**
|
|
727
|
+
* Show user's per-tag ELO data. Useful for diagnosing hierarchy gate status.
|
|
728
|
+
*
|
|
729
|
+
* @param tagFilter - Optional glob pattern(s) to filter tags.
|
|
730
|
+
* Examples: 'gpc:expose:*', 'gpc:intro:t-T', ['gpc:expose:t-*', 'gpc:intro:t-*']
|
|
731
|
+
*/
|
|
732
|
+
showTagElo(tagFilter?: string | string[]): Promise<void>;
|
|
733
|
+
/**
|
|
734
|
+
* Toggle the full-screen UI debugger.
|
|
735
|
+
*/
|
|
736
|
+
ui(): void;
|
|
737
|
+
/**
|
|
738
|
+
* Internal UI helpers
|
|
739
|
+
* @internal
|
|
740
|
+
*/
|
|
741
|
+
_selectRun(index: number): void;
|
|
742
|
+
/**
|
|
743
|
+
* Internal UI helpers
|
|
744
|
+
* @internal
|
|
745
|
+
*/
|
|
746
|
+
_setSearch(query: string): void;
|
|
747
|
+
/**
|
|
748
|
+
* Internal UI helpers
|
|
749
|
+
* @internal
|
|
750
|
+
*/
|
|
751
|
+
_copyConfig(runId: string, btn?: HTMLElement): void;
|
|
752
|
+
/**
|
|
753
|
+
* Internal UI helpers
|
|
754
|
+
* @internal
|
|
755
|
+
*
|
|
756
|
+
* Copies an "abridged" view of results: just the selected cards with their
|
|
757
|
+
* generator, origin, final score, and the top provenance reason. Designed
|
|
758
|
+
* for pasting into bug reports without flooding with full provenance.
|
|
759
|
+
*/
|
|
760
|
+
_copyResults(runId: string, btn?: HTMLElement): void;
|
|
761
|
+
/**
|
|
762
|
+
* Show help.
|
|
763
|
+
*/
|
|
764
|
+
help(): void;
|
|
765
|
+
};
|
|
766
|
+
/**
|
|
767
|
+
* Mount the debug API on window.skuilder.pipeline
|
|
768
|
+
*/
|
|
769
|
+
declare function mountPipelineDebugger(): void;
|
|
770
|
+
|
|
771
|
+
/**
|
|
772
|
+
* Durable per-sitting record. Join target for `CardRecord.sessionId`.
|
|
773
|
+
*
|
|
774
|
+
* Written twice: `open` at `prepareSession()`, overwritten at termination.
|
|
775
|
+
*/
|
|
776
|
+
interface StudySessionDoc {
|
|
777
|
+
/** `SESSION::{courseId}::{userId}::{sessionId}` */
|
|
778
|
+
_id: string;
|
|
779
|
+
_rev?: string;
|
|
780
|
+
docType: DocType.STUDY_SESSION;
|
|
781
|
+
sessionId: string;
|
|
782
|
+
courseId: string;
|
|
783
|
+
userId: string;
|
|
784
|
+
/** Session construction time, not first-card time. */
|
|
785
|
+
startTime: string;
|
|
786
|
+
endTime?: string;
|
|
787
|
+
/**
|
|
788
|
+
* `closed` — ran to natural termination.
|
|
789
|
+
* `abandoned` — host tore the study view down mid-session.
|
|
790
|
+
* `open` — never closed: tab closed, reload, crash. No tally or end state.
|
|
791
|
+
*/
|
|
792
|
+
status: 'open' | 'closed' | 'abandoned';
|
|
793
|
+
plannedSeconds: number;
|
|
794
|
+
config: {
|
|
795
|
+
defaultBatchLimit: number;
|
|
796
|
+
sourceCount: number;
|
|
797
|
+
initHints?: ReplanHints | null;
|
|
798
|
+
};
|
|
799
|
+
/** Queue depths after the bootstrap run, before the first draw. */
|
|
800
|
+
initialQueues: {
|
|
801
|
+
supplyQ: number;
|
|
802
|
+
failedQ: number;
|
|
803
|
+
};
|
|
804
|
+
tally?: {
|
|
805
|
+
/** Distinct cards; a re-presented failed card counts once. */
|
|
806
|
+
cardsPresented: number;
|
|
807
|
+
/** Total responses, including repeat attempts on one card. */
|
|
808
|
+
responses: number;
|
|
809
|
+
correct: number;
|
|
810
|
+
incorrect: number;
|
|
811
|
+
failedQRemaining: number;
|
|
812
|
+
secondsRemaining: number;
|
|
813
|
+
};
|
|
814
|
+
/** Bootstrap run plus every replan, in execution order. */
|
|
815
|
+
runs?: StudySessionRunSummary[];
|
|
816
|
+
finalHints?: ReplanHints | null;
|
|
817
|
+
stateAtStart?: SessionStateSnapshot;
|
|
818
|
+
stateAtEnd?: SessionStateSnapshot;
|
|
819
|
+
}
|
|
820
|
+
interface StudySessionRunSummary {
|
|
821
|
+
/** Joins to `PipelineRunReport.runId` while that run is still in memory. */
|
|
822
|
+
runId: string;
|
|
823
|
+
at: string;
|
|
824
|
+
/** `'bootstrap'`, a replan's label, or `'(auto)'`. */
|
|
825
|
+
label: string;
|
|
826
|
+
mode?: string;
|
|
827
|
+
generatedCount: number;
|
|
828
|
+
finalCount: number;
|
|
829
|
+
reviewsSelected: number;
|
|
830
|
+
newSelected: number;
|
|
831
|
+
/** User's global ELO at the moment this run's pipeline executed. */
|
|
832
|
+
userElo?: number;
|
|
833
|
+
/** Per-generator contribution (name, card/new/review counts, top score). */
|
|
834
|
+
generators?: GeneratorSummary[];
|
|
835
|
+
/** Per-filter impact (boosted / penalized / passed / removed). */
|
|
836
|
+
filters?: FilterImpact[];
|
|
837
|
+
/** Ephemeral replan hints in force for this run (what the navigator was told). */
|
|
838
|
+
hints?: ReplanHints;
|
|
839
|
+
/** Compact summary of the scored-but-dropped candidate tail. */
|
|
840
|
+
discardedTail?: {
|
|
841
|
+
count: number;
|
|
842
|
+
scoreRange?: [number, number];
|
|
843
|
+
eloRange?: [number, number];
|
|
844
|
+
note: string;
|
|
845
|
+
};
|
|
846
|
+
}
|
|
847
|
+
/**
|
|
848
|
+
* Host-defined learner state at a session boundary. Keep it thin — this is
|
|
849
|
+
* written on every session, and the deltas between consecutive snapshots are
|
|
850
|
+
* what it's read for.
|
|
851
|
+
*/
|
|
852
|
+
type SessionStateSnapshot = Record<string, unknown>;
|
|
853
|
+
/**
|
|
854
|
+
* Invoked at session open and close. Errors and slow calls are absorbed by
|
|
855
|
+
* the controller.
|
|
856
|
+
*/
|
|
857
|
+
type SessionStateSnapshotProvider = (phase: 'start' | 'end') => SessionStateSnapshot | Promise<SessionStateSnapshot>;
|
|
858
|
+
/** Stable across the open and close writes, unlike a timestamp-keyed id. */
|
|
859
|
+
declare function makeStudySessionId(courseId: string, userId: string, sessionId: string): string;
|
|
860
|
+
declare function newSessionId(): string;
|
|
861
|
+
|
|
426
862
|
/**
|
|
427
863
|
* User database hydration.
|
|
428
864
|
*
|
|
@@ -568,6 +1004,8 @@ interface UserDBReader {
|
|
|
568
1004
|
* Get user's pending reviews
|
|
569
1005
|
*/
|
|
570
1006
|
getPendingReviews(courseId?: string): Promise<ScheduledCard[]>;
|
|
1007
|
+
/** Study-session records for a course, newest session-start first. */
|
|
1008
|
+
getStudySessions(courseId?: string): Promise<StudySessionDoc[]>;
|
|
571
1009
|
/**
|
|
572
1010
|
* Get all scheduled reviews due within the next `daysCount` days —
|
|
573
1011
|
* including ones not yet due. `getPendingReviews` is the `daysCount = 0`
|
|
@@ -686,6 +1124,8 @@ interface UserDBWriter extends DocumentUpdater {
|
|
|
686
1124
|
* Record a user learning outcome for evolutionary orchestration.
|
|
687
1125
|
*/
|
|
688
1126
|
putUserOutcome(record: UserOutcomeRecord): Promise<void>;
|
|
1127
|
+
/** Write or overwrite a study-session record. */
|
|
1128
|
+
putStudySession(doc: StudySessionDoc): Promise<void>;
|
|
689
1129
|
}
|
|
690
1130
|
/**
|
|
691
1131
|
* Authentication and account management operations
|
|
@@ -768,83 +1208,6 @@ interface ClassroomRegistrationDoc {
|
|
|
768
1208
|
registrations: ClassroomRegistration[];
|
|
769
1209
|
}
|
|
770
1210
|
|
|
771
|
-
/**
|
|
772
|
-
* Context for orchestration decisions during a session.
|
|
773
|
-
*
|
|
774
|
-
* Provides access to user/course data and helper methods for determining
|
|
775
|
-
* effective strategy weights based on the user's cohort assignment.
|
|
776
|
-
*/
|
|
777
|
-
interface OrchestrationContext {
|
|
778
|
-
user: UserDBInterface;
|
|
779
|
-
course: CourseDBInterface;
|
|
780
|
-
userId: string;
|
|
781
|
-
courseConfig: CourseConfig;
|
|
782
|
-
/**
|
|
783
|
-
* Calculate the effective weight for a strategy for this user.
|
|
784
|
-
*
|
|
785
|
-
* Applies deviation based on the user's cohort assignment (derived from
|
|
786
|
-
* userId, strategyId, and course salt).
|
|
787
|
-
*
|
|
788
|
-
* @param strategyId - Unique ID of the strategy
|
|
789
|
-
* @param learnable - The strategy's learning configuration
|
|
790
|
-
* @returns Effective weight multiplier (typically 0.1 - 3.0)
|
|
791
|
-
*/
|
|
792
|
-
getEffectiveWeight(strategyId: string, learnable: LearnableWeight): number;
|
|
793
|
-
/**
|
|
794
|
-
* Get the deviation factor for this user/strategy.
|
|
795
|
-
* Range [-1.0, 1.0].
|
|
796
|
-
*/
|
|
797
|
-
getDeviation(strategyId: string): number;
|
|
798
|
-
}
|
|
799
|
-
/**
|
|
800
|
-
* Compute a user's deviation for a specific strategy.
|
|
801
|
-
*
|
|
802
|
-
* Returns a value in [-1, 1] that is:
|
|
803
|
-
* 1. Deterministic for the same (user, strategy, salt) tuple
|
|
804
|
-
* 2. Uniformly distributed across users
|
|
805
|
-
* 3. Uncorrelated between different strategies (due to strategyId in hash)
|
|
806
|
-
* 4. Rotatable by changing the salt
|
|
807
|
-
*
|
|
808
|
-
* @param userId - ID of the user
|
|
809
|
-
* @param strategyId - ID of the strategy
|
|
810
|
-
* @param salt - Random seed from course config
|
|
811
|
-
* @returns Deviation factor between -1.0 and 1.0
|
|
812
|
-
*/
|
|
813
|
-
declare function computeDeviation(userId: string, strategyId: string, salt: string): number;
|
|
814
|
-
/**
|
|
815
|
-
* Compute the exploration spread based on confidence.
|
|
816
|
-
*
|
|
817
|
-
* - Low confidence (0.0) -> Max spread (Explore broadly)
|
|
818
|
-
* - High confidence (1.0) -> Min spread (Exploit known good weight)
|
|
819
|
-
*
|
|
820
|
-
* @param confidence - Confidence level 0-1
|
|
821
|
-
* @returns Spread magnitude (half-width of the distribution)
|
|
822
|
-
*/
|
|
823
|
-
declare function computeSpread(confidence: number): number;
|
|
824
|
-
/**
|
|
825
|
-
* Calculate the effective weight for a strategy instance.
|
|
826
|
-
*
|
|
827
|
-
* Combines the learnable weight (peak) with the user's deviation and the
|
|
828
|
-
* allowed spread (based on confidence).
|
|
829
|
-
*
|
|
830
|
-
* @param learnable - Strategy learning config
|
|
831
|
-
* @param userId - User ID
|
|
832
|
-
* @param strategyId - Strategy ID
|
|
833
|
-
* @param salt - Course salt
|
|
834
|
-
* @returns Effective weight multiplier
|
|
835
|
-
*/
|
|
836
|
-
declare function computeEffectiveWeight(learnable: LearnableWeight, userId: string, strategyId: string, salt: string): number;
|
|
837
|
-
/**
|
|
838
|
-
* Create an orchestration context for a study session.
|
|
839
|
-
*
|
|
840
|
-
* Fetches necessary configuration to enable deterministic weight calculation.
|
|
841
|
-
*
|
|
842
|
-
* @param user - User DB interface
|
|
843
|
-
* @param course - Course DB interface
|
|
844
|
-
* @returns Initialized orchestration context
|
|
845
|
-
*/
|
|
846
|
-
declare function createOrchestrationContext(user: UserDBInterface, course: CourseDBInterface): Promise<OrchestrationContext>;
|
|
847
|
-
|
|
848
1211
|
/**
|
|
849
1212
|
* Type for navigator constructor functions.
|
|
850
1213
|
*/
|
|
@@ -1349,4 +1712,4 @@ interface StudyContentSource {
|
|
|
1349
1712
|
}
|
|
1350
1713
|
declare function getStudySource(source: ContentSourceID, user: UserDBInterface): Promise<StudyContentSource>;
|
|
1351
1714
|
|
|
1352
|
-
export {
|
|
1715
|
+
export { type HydrationMarker as $, type AdminDBInterface as A, type UserCourseSetting as B, type CourseDBInterface as C, type DataLayerResult as D, type UsrCrsDataInterface as E, type ClassroomRegistrationDesignation as F, type GeneratorResult as G, type ClassroomRegistration as H, type ClassroomRegistrationDoc as I, type SessionTrackingData as J, type UserConfig as K, type ActivityRecord as L, type CourseRegistration as M, type UserOutcomeRecord as N, type StudySessionDoc as O, type StudySessionRunSummary as P, type SessionStateSnapshot as Q, type ReplanHints as R, type StudySessionItem as S, type TeacherClassroomDBInterface 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 UserDBReader as a, type NavigatorConstructor as a0, registerNavigator as a1, getRegisteredNavigator as a2, hasRegisteredNavigator as a3, getRegisteredNavigatorRole as a4, getRegisteredNavigatorNames as a5, initializeNavigatorRegistry as a6, type StrategyContribution as a7, getCardOrigin as a8, Navigators as a9, NavigatorRole as aa, NavigatorRoles as ab, isGenerator as ac, isFilter as ad, type CardGenerator as ae, type GeneratorContext as af, type CardGeneratorFactory as ag, pipelineDebugAPI as ah, mountPipelineDebugger as ai, getActivePipeline as aj, setDebugSessionId as ak, getRunsForSession as al, drainCapturedRuns as am, type PipelineRunReport as an, type GeneratorSummary as ao, type FilterImpact as ap, type PipelineForecaster as aq, type LearnableWeight as ar, type OrchestrationContext as as, computeDeviation as at, computeSpread as au, computeEffectiveWeight as av, createOrchestrationContext as aw, type DocumentUpdater as ax, newInterval as ay, type CoursesDBInterface as b, type ClassroomDBInterface as c, type CourseInfo as d, type ContentNavigationStrategyData as e, ContentNavigator as f, type AssignedContent as g, type StudyContentSource as h, type StudentClassroomDBInterface as i, type ScheduledCard as j, type StudySessionFailedItem as k, type StudySessionFailedNewItem as l, type StudySessionFailedReviewItem as m, type StudySessionNewItem as n, type StudySessionReviewItem as o, isReview as p, type ContentSourceID as q, getStudySource as r, type CourseRegistrationDoc as s, type SessionStateSnapshotProvider as t, type AssignedTag as u, type AssignedCourse as v, type AssignedCard as w, type UserDBWriter as x, type UserDBAuthenticator as y, type UserCourseSettings as z };
|