@vue-skuilder/db 0.2.22 → 0.2.24
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-B1pqryv6.d.ts → contentSource-Z9lQOuu5.d.ts} +412 -79
- package/dist/{contentSource-CpTxVrFx.d.cts → contentSource-jBskhS2Y.d.cts} +412 -79
- package/dist/core/index.d.cts +84 -352
- package/dist/core/index.d.ts +84 -352
- package/dist/core/index.js.map +1 -1
- package/dist/core/index.mjs.map +1 -1
- package/dist/{dataLayerProvider-BZqH27f4.d.ts → dataLayerProvider-CvSh3KW-.d.ts} +1 -1
- package/dist/{dataLayerProvider-D4c7iUc_.d.cts → dataLayerProvider-DbA3d_Pd.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.map +1 -1
- 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.map +1 -1
- package/dist/impl/static/index.mjs.map +1 -1
- package/dist/{index-rmNIwnkV.d.ts → index-BkBJlGDX.d.ts} +1 -1
- package/dist/{index-DGApnUZ-.d.cts → index-D7WdMDAs.d.cts} +1 -1
- package/dist/index.d.cts +39 -14
- package/dist/index.d.ts +39 -14
- package/dist/index.js +179 -44
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +179 -44
- package/dist/index.mjs.map +1 -1
- package/dist/{types-r6fyuWP2.d.cts → types-DjiFOZxJ.d.cts} +1 -1
- package/dist/{types-legacy-BytY5eAR.d.cts → types-legacy-CrwyZIvI.d.cts} +1 -1
- package/dist/{types-legacy-BytY5eAR.d.ts → types-legacy-CrwyZIvI.d.ts} +1 -1
- package/dist/{types-B-Y3aoi5.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/types/studySession.ts +67 -0
- package/src/study/SessionController.ts +33 -1
- package/src/study/services/EloService.ts +78 -5
- package/src/study/services/ResponseProcessor.ts +79 -27
|
@@ -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,351 @@ 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
|
+
|
|
426
771
|
/**
|
|
427
772
|
* Durable per-sitting record. Join target for `CardRecord.sessionId`.
|
|
428
773
|
*
|
|
@@ -468,6 +813,15 @@ interface StudySessionDoc {
|
|
|
468
813
|
};
|
|
469
814
|
/** Bootstrap run plus every replan, in execution order. */
|
|
470
815
|
runs?: StudySessionRunSummary[];
|
|
816
|
+
/**
|
|
817
|
+
* Per-response ELO exchanges, in the order they resolved. One entry per
|
|
818
|
+
* ELO-updating response (first attempt of a presentation; retries don't
|
|
819
|
+
* move ELO). Flushed at close from an in-memory log — so `open`/`abandoned`
|
|
820
|
+
* sessions that never reached the close write carry none, and a same-card
|
|
821
|
+
* event still in flight at close may be missing. Absent on sessions
|
|
822
|
+
* recorded before this shipped.
|
|
823
|
+
*/
|
|
824
|
+
eloEvents?: SessionEloEvent[];
|
|
471
825
|
finalHints?: ReplanHints | null;
|
|
472
826
|
stateAtStart?: SessionStateSnapshot;
|
|
473
827
|
stateAtEnd?: SessionStateSnapshot;
|
|
@@ -483,6 +837,62 @@ interface StudySessionRunSummary {
|
|
|
483
837
|
finalCount: number;
|
|
484
838
|
reviewsSelected: number;
|
|
485
839
|
newSelected: number;
|
|
840
|
+
/** User's global ELO at the moment this run's pipeline executed. */
|
|
841
|
+
userElo?: number;
|
|
842
|
+
/** Per-generator contribution (name, card/new/review counts, top score). */
|
|
843
|
+
generators?: GeneratorSummary[];
|
|
844
|
+
/** Per-filter impact (boosted / penalized / passed / removed). */
|
|
845
|
+
filters?: FilterImpact[];
|
|
846
|
+
/** Ephemeral replan hints in force for this run (what the navigator was told). */
|
|
847
|
+
hints?: ReplanHints;
|
|
848
|
+
/** Compact summary of the scored-but-dropped candidate tail. */
|
|
849
|
+
discardedTail?: {
|
|
850
|
+
count: number;
|
|
851
|
+
scoreRange?: [number, number];
|
|
852
|
+
eloRange?: [number, number];
|
|
853
|
+
note: string;
|
|
854
|
+
};
|
|
855
|
+
}
|
|
856
|
+
/**
|
|
857
|
+
* One learner↔card ELO exchange, captured at the moment it resolved so a
|
|
858
|
+
* session can be read as an ELO ledger (why did 88% accuracy net -1?). The
|
|
859
|
+
* exchange is otherwise write-once-and-discard: only the updated aggregates
|
|
860
|
+
* survive on the user/card docs, and ELO is path-dependent, so a response's
|
|
861
|
+
* move can't be reconstructed after the fact. Joins to a `CardRecord` by
|
|
862
|
+
* `cardId` + nearest `at`.
|
|
863
|
+
*/
|
|
864
|
+
interface SessionEloEvent {
|
|
865
|
+
/** Card this exchange was for. */
|
|
866
|
+
cardId: string;
|
|
867
|
+
/** ISO time the exchange resolved (fires just after the response record). */
|
|
868
|
+
at: string;
|
|
869
|
+
/**
|
|
870
|
+
* Global performance in [0,1] that drove the update. Note this is the ELO
|
|
871
|
+
* `userScore`, not raw correctness: the numeric path maps a correct answer
|
|
872
|
+
* to `0.5 + performance/2` (so a plain correct is 1.0, a graded-correct
|
|
873
|
+
* less) and a miss to 0; the tagged path uses `_global`.
|
|
874
|
+
*/
|
|
875
|
+
userScore: number;
|
|
876
|
+
/** Learner global ELO before → after this response. */
|
|
877
|
+
global: {
|
|
878
|
+
before: number;
|
|
879
|
+
after: number;
|
|
880
|
+
};
|
|
881
|
+
/** Card global ELO before → after (absent if the card ELO was unreadable). */
|
|
882
|
+
card?: {
|
|
883
|
+
before: number;
|
|
884
|
+
after: number;
|
|
885
|
+
};
|
|
886
|
+
/**
|
|
887
|
+
* Per-tag learner ELO before → after, for every tag the exchange touched.
|
|
888
|
+
* `score` is the per-tag performance applied, or null for a count-only
|
|
889
|
+
* exposure tag (`gpc:expose:*`) that increments count without moving ELO.
|
|
890
|
+
*/
|
|
891
|
+
tags?: Record<string, {
|
|
892
|
+
before: number;
|
|
893
|
+
after: number;
|
|
894
|
+
score: number | null;
|
|
895
|
+
}>;
|
|
486
896
|
}
|
|
487
897
|
/**
|
|
488
898
|
* Host-defined learner state at a session boundary. Keep it thin — this is
|
|
@@ -848,83 +1258,6 @@ interface ClassroomRegistrationDoc {
|
|
|
848
1258
|
registrations: ClassroomRegistration[];
|
|
849
1259
|
}
|
|
850
1260
|
|
|
851
|
-
/**
|
|
852
|
-
* Context for orchestration decisions during a session.
|
|
853
|
-
*
|
|
854
|
-
* Provides access to user/course data and helper methods for determining
|
|
855
|
-
* effective strategy weights based on the user's cohort assignment.
|
|
856
|
-
*/
|
|
857
|
-
interface OrchestrationContext {
|
|
858
|
-
user: UserDBInterface;
|
|
859
|
-
course: CourseDBInterface;
|
|
860
|
-
userId: string;
|
|
861
|
-
courseConfig: CourseConfig;
|
|
862
|
-
/**
|
|
863
|
-
* Calculate the effective weight for a strategy for this user.
|
|
864
|
-
*
|
|
865
|
-
* Applies deviation based on the user's cohort assignment (derived from
|
|
866
|
-
* userId, strategyId, and course salt).
|
|
867
|
-
*
|
|
868
|
-
* @param strategyId - Unique ID of the strategy
|
|
869
|
-
* @param learnable - The strategy's learning configuration
|
|
870
|
-
* @returns Effective weight multiplier (typically 0.1 - 3.0)
|
|
871
|
-
*/
|
|
872
|
-
getEffectiveWeight(strategyId: string, learnable: LearnableWeight): number;
|
|
873
|
-
/**
|
|
874
|
-
* Get the deviation factor for this user/strategy.
|
|
875
|
-
* Range [-1.0, 1.0].
|
|
876
|
-
*/
|
|
877
|
-
getDeviation(strategyId: string): number;
|
|
878
|
-
}
|
|
879
|
-
/**
|
|
880
|
-
* Compute a user's deviation for a specific strategy.
|
|
881
|
-
*
|
|
882
|
-
* Returns a value in [-1, 1] that is:
|
|
883
|
-
* 1. Deterministic for the same (user, strategy, salt) tuple
|
|
884
|
-
* 2. Uniformly distributed across users
|
|
885
|
-
* 3. Uncorrelated between different strategies (due to strategyId in hash)
|
|
886
|
-
* 4. Rotatable by changing the salt
|
|
887
|
-
*
|
|
888
|
-
* @param userId - ID of the user
|
|
889
|
-
* @param strategyId - ID of the strategy
|
|
890
|
-
* @param salt - Random seed from course config
|
|
891
|
-
* @returns Deviation factor between -1.0 and 1.0
|
|
892
|
-
*/
|
|
893
|
-
declare function computeDeviation(userId: string, strategyId: string, salt: string): number;
|
|
894
|
-
/**
|
|
895
|
-
* Compute the exploration spread based on confidence.
|
|
896
|
-
*
|
|
897
|
-
* - Low confidence (0.0) -> Max spread (Explore broadly)
|
|
898
|
-
* - High confidence (1.0) -> Min spread (Exploit known good weight)
|
|
899
|
-
*
|
|
900
|
-
* @param confidence - Confidence level 0-1
|
|
901
|
-
* @returns Spread magnitude (half-width of the distribution)
|
|
902
|
-
*/
|
|
903
|
-
declare function computeSpread(confidence: number): number;
|
|
904
|
-
/**
|
|
905
|
-
* Calculate the effective weight for a strategy instance.
|
|
906
|
-
*
|
|
907
|
-
* Combines the learnable weight (peak) with the user's deviation and the
|
|
908
|
-
* allowed spread (based on confidence).
|
|
909
|
-
*
|
|
910
|
-
* @param learnable - Strategy learning config
|
|
911
|
-
* @param userId - User ID
|
|
912
|
-
* @param strategyId - Strategy ID
|
|
913
|
-
* @param salt - Course salt
|
|
914
|
-
* @returns Effective weight multiplier
|
|
915
|
-
*/
|
|
916
|
-
declare function computeEffectiveWeight(learnable: LearnableWeight, userId: string, strategyId: string, salt: string): number;
|
|
917
|
-
/**
|
|
918
|
-
* Create an orchestration context for a study session.
|
|
919
|
-
*
|
|
920
|
-
* Fetches necessary configuration to enable deterministic weight calculation.
|
|
921
|
-
*
|
|
922
|
-
* @param user - User DB interface
|
|
923
|
-
* @param course - Course DB interface
|
|
924
|
-
* @returns Initialized orchestration context
|
|
925
|
-
*/
|
|
926
|
-
declare function createOrchestrationContext(user: UserDBInterface, course: CourseDBInterface): Promise<OrchestrationContext>;
|
|
927
|
-
|
|
928
1261
|
/**
|
|
929
1262
|
* Type for navigator constructor functions.
|
|
930
1263
|
*/
|
|
@@ -1429,4 +1762,4 @@ interface StudyContentSource {
|
|
|
1429
1762
|
}
|
|
1430
1763
|
declare function getStudySource(source: ContentSourceID, user: UserDBInterface): Promise<StudyContentSource>;
|
|
1431
1764
|
|
|
1432
|
-
export {
|
|
1765
|
+
export { HYDRATION_MARKER_ID as $, type AdminDBInterface as A, type UserCourseSettings as B, type CourseDBInterface as C, type DataLayerResult as D, type UserCourseSetting as E, type UsrCrsDataInterface as F, type GeneratorResult as G, type ClassroomRegistrationDesignation as H, type ClassroomRegistration as I, type ClassroomRegistrationDoc as J, type SessionTrackingData as K, type UserConfig as L, type ActivityRecord as M, type CourseRegistration as N, type UserOutcomeRecord as O, type StudySessionDoc as P, type StudySessionRunSummary as Q, type ReplanHints as R, type StudySessionItem as S, type TeacherClassroomDBInterface as T, type UserDBInterface as U, type SessionStateSnapshot as V, type WeightedCard as W, makeStudySessionId as X, newSessionId as Y, type UserHydrationState as Z, type UserHydrationStatus as _, type UserDBReader as a, type HydrationMarker as a0, type NavigatorConstructor as a1, registerNavigator as a2, getRegisteredNavigator as a3, hasRegisteredNavigator as a4, getRegisteredNavigatorRole as a5, getRegisteredNavigatorNames as a6, initializeNavigatorRegistry as a7, type StrategyContribution as a8, getCardOrigin as a9, Navigators as aa, NavigatorRole as ab, NavigatorRoles as ac, isGenerator as ad, isFilter as ae, type CardGenerator as af, type GeneratorContext as ag, type CardGeneratorFactory as ah, pipelineDebugAPI as ai, mountPipelineDebugger as aj, getActivePipeline as ak, setDebugSessionId as al, getRunsForSession as am, drainCapturedRuns as an, type PipelineRunReport as ao, type GeneratorSummary as ap, type FilterImpact as aq, type PipelineForecaster as ar, type LearnableWeight as as, type OrchestrationContext as at, computeDeviation as au, computeSpread as av, computeEffectiveWeight as aw, createOrchestrationContext as ax, type DocumentUpdater as ay, newInterval as az, 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 SessionEloEvent as t, type SessionStateSnapshotProvider as u, type AssignedTag as v, type AssignedCourse as w, type AssignedCard as x, type UserDBWriter as y, type UserDBAuthenticator as z };
|